1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
=head1 NAME
Mail::Box::Tie::ARRAY - access an existing message folder as array
=head1 SYNOPSIS
use Mail::Box::Manager;
my $mgr = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => 'inbox');
use Mail::Box::Tie::ARRAY;
tie my(@inbox), 'Mail::Box::Tie::ARRAY', $folder;
# deprecated, but works too
use Mail::Box::Tie;
tie my(@inbox), 'Mail::Box::Tie', $folder;
foreach (@inbox) {print $_->short}
print $_->print foreach @inbox;
my $emails = @inbox;
print $inbox[3];
print scalar @inbox;
push @inbox, Mail::Box::Message->new(...);
delete $inbox[6];
print $inbox[0]->head->get('status');
my $folder = tied @inbox;
untie @inbox;
=head1 DESCRIPTION
Certainly when you look at a folder as a list of messages, it is logical to
access the folder through an array.
Not all operations on arrays are supported. Actually, most functions which
would reduce the size of the array are modified instead to mark messages for
deletion.
Examples what you I<cannot> do:
shift/unshift/pop/splice @inbox;
=head1 METHODS
=head2 Constructors
B<TIEARRAY>('Mail::Box::Tie::ARRAY', FOLDER)
=over 4
Create the tie on an existing folder.
I<Example:> tie an array to a folder
my $mgr = Mail::Box::Manager->new;
my $inbox = $mgr->new(folder => $ENV{MAIL});
tie my(@inbox), 'Mail::Box::Tie::Array', ref $inbox, $inbox;
=back
=head2 Tied Interface
$obj-E<gt>B<DELETE>
=over 4
Flag a message to be removed. Be warned that the message stays in
the folder, and is not removed before the folder is written.
I<Example:>
delete $inbox[5];
$inbox[5]->delete; #same
=back
$obj-E<gt>B<FETCH>(INDEX)
=over 4
Get the message which is at the indicated location in the list of
messages contained in this folder. Deleted messages will be returned
as C<undef>.
I<Example:>
print $inbox[3]; # 4th message in the folder
print @inbox[3,0]; # 4th and first of the folder
print $inbox[-1]; # last message
=back
$obj-E<gt>B<FETCHSIZE>
=over 4
Return the total number of messages in a folder. This is called when
the folder-array is used in scalar context, for instance.
I<Example:>
if(@inbox > 10) # contains more than 10 messages?
my $nrmsgs = @inbox;
=back
$obj-E<gt>B<PUSH>(MESSAGES)
=over 4
Add MESSAGES to the end of the folder.
I<Example:>
push @inbox, $newmsg;
=back
$obj-E<gt>B<STORE>(INDEX, MESSAGE)
=over 4
Random message replacement is not permitted --doing so would disturb threads
etc. An error occurs if you try to do this. The only thing which is allowed
is to store a message at the first free index at the end of the folder (which
is also achievable with L<PUSH()|Mail::Box::Tie::ARRAY/"Tied Interface">).
I<Example:>
$inbox[8] = $add;
$inbox[-1] = $add;
push @inbox, $add;
=back
$obj-E<gt>B<STORESIZE>(LENGTH)
=over 4
Sets all messages behind from LENGTH to the end of folder to be deleted.
=back
=head1 DETAILS
=head2 Folder tied as array
=head3 Limitations
This module implements C<TIEARRAY>, C<FETCH>, C<STORE>, C<FETCHSIZE>,
C<STORESIZE>, C<DELETE>, C<PUSH>, and C<DESTROY>.
This module does not implement all other methods as described in
the Tie::Array documentation, because the real array of messages
is not permitted to shrink or be mutilated.
=head1 REFERENCES
See the MailBox website at L<http://perl.overmeer.net/mailbox/> for more details.
=head1 COPYRIGHTS
Distribution version 2.068.
Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for
other contributors.
Copyright (c) 2001-2006 by the author(s). All rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
|
