1MessageSet(3) User Contributed Perl Documentation MessageSet(3)
2
6 Mail::IMAPClient::MessageSet -- an extension to Mail::IMAPClient that
7 expresses lists of message sequence numbers or message UID's in the
8 shortest way permissable by RFC2060.
9 DESCRIPTION
11 The Mail::IMAPClient::MessageSet module is designed to make life easier
13 for programmers who need to manipulate potentially large sets of IMAP
14 message UID's or sequence numbers.
15 This module presents an object-oriented interface into handling your
17 message sets. The object reference returned by the new method is an
18 overloaded reference to a scalar variable that contains the message
19 set's compact RFC2060 representation. The object is overloaded so that
20 using it like a string returns this compact message set representation.
21 You can also add messages to the set (using either a '.=' operator or a
22 '+=' operator) or remove messages (with the '-=' operator). And if you
23 use it as an array reference, it will humor you and act like one by
24 calling unfold for you. (But you need perl 5.6 or above to do this.)
25 RFC2060 specifies that multiple messages can be provided to certain
27 IMAP commands by separating them with commas. For example, "1,2,3,4,5"
28 would specify messages 1, 2, 3, 4, and (you guessed it!) 5. However, if
29 you are performing an operation on lots of messages, this string can
30 get quite long. So long that it may slow down your transaction, and
31 perhaps even cause the server to reject it. So RFC2060 also permits you
32 to specifiy a range of messages, so that messages 1, 2, 3, 4 and 5 can
33 also be specified as "1:5".
34 This is where Mail::IMAPClient::MessageSet comes in. It will convert
36 your message set into the shortest correct syntax. This could poten‐
37 tially save you tons of network I/O, as in the case where you want to
38 fetch the flags for all messages in a 10000 message folder, where the
39 messages are all numbered sequentially. Delimited as commas, and making
40 the best-case assumption that the first message is message "1", it
41 would take 48893 bytes to specify the whole message set using the
42 comma-delimited method. To specify it as a range, it takes just seven
43 bytes (1:10000).
44 SYNOPSIS
46 To illustrate, let's take the trivial example of a search that returns
48 these message uids: 1,3,4,5,6,9,10, as follows:
49 @msgs = $imap->search("SUBJECT","Virus"); # returns 1,3,4,5,6,9,10
51 my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
52 print "$msgset\n"; # prints "1,3:6,9:10\n"
53 # add message 14 to the set:
54 $msgset += 14;
55 print "$msgset\n"; # prints "1,3:6,9:10,14\n"
56 # add messages 16,17,18,19, and 20 to the set:
57 $msgset .= "16,17,18:20";
58 print "$msgset\n"; # prints "1,3:6,9:10,14,16:20\n"
59 # Hey, I didn't really want message 17 in there; let's take it out:
60 $msgset -= 17;
61 print "$msgset\n"; # prints "1,3:6,9:10,14,16,18:20\n"
62 # Now let's iterate over each message:
63 for my $msg (@$msgset) {
64 print "$msg\n";
65 } # Prints: "1\n3\n4\n5\n6\n9\n10\n14\n16\n18\n19\n20"
66 (Note that the Mail::IMAPClient Range method can be used as a short-cut
68 to specifying "Mail::IMAPClient::MessageSet->new(@etc)".)
69
71 The only class method you need to worry about is new. And if you create
72 your Mail::IMAPClient::MessageSet objects via Mail::IMAPClient's Range
73 method then you don't even need to worry about new.
74 new
76 Example:
78 my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
80 The new method requires at least one argument. That argument can be
82 either a message, a comma-separated list of messages, a colon-separated
83 range of messages, or a combination of comma-separated messages and
84 colon-separated ranges. It can also be a reference to an array of mes‐
85 sages, comma-separated message lists, and colon separated ranges.
86 If more then one argument is supplied to new, then those arguments
88 should be more message numbers, lists, and ranges (or references to
89 arrays of them) just as in the first argument.
90 The message numbers passed to new can really be any kind of number at
92 all but to be useful in a Mail::IMAPClient session they should be
93 either message UID's (if your Uid parameter is true) or message
94 sequence numbers.
95 The new method will return a reference to a Mail::IMAPClient::Message‐
97 Set object. That object, when double quoted, will act just like a
98 string whose value is the message set expressed in the shortest possi‐
99 ble way, with the message numbers sorted in ascending order and with
100 duplicates removed.
101
103 The only object method currently available to a Mail::IMAPClient::Mes‐
104 sageSet object is the unfold method.
105 unfold
107 Example:
109 my $msgset = $imap->Range( $imap->messages ) ;
111 my @all_messages = $msgset->unfold;
112 The unfold method returns an array of messages that belong to the mes‐
114 sage set. If called in a scalar context it returns a reference to the
115 array instead.
116
118 Mail::IMAPClient::MessageSet overrides a number of operators in order
119 to make manipulating your message sets easier. The overridden opera‐
120 tions are:
121 stringify
123 Attempts to stringify a Mail::IMAPClient::MessageSet object will result
125 in the compact message specification being returned, which is almost
126 certainly what you will want.
127 Auto-increment
129 Attempts to autoincrement a Mail::IMAPClient::MessageSet object will
131 result in a message (or messages) being added to the object's message
132 set.
133 Example:
135 $msgset += 34;
137 # Message #34 is now in the message set
138 Concatenate
140 Attempts to concatenate to a Mail::IMAPClient::MessageSet object will
142 result in a message (or messages) being added to the object's message
143 set.
144 Example:
146 $msgset .= "34,35,36,40:45";
148 # Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set
149 The ".=" operator and the "+=" operator can be used interchangeably,
151 but as you can see by looking at the examples there are times when use
152 of one has an aesthetic advantage over use of the other.
153 Autodecrement
155 Attempts to autodecrement a Mail::IMAPClient::MessageSet object will
157 result in a message being removed from the object's message set.
158 Examples:
160 $msgset -= 34;
162 # Message #34 is no longer in the message set
163 $msgset -= "1:10";
164 # Messages 1 through 10 are no longer in the message set
165 If you attempt to remove a message that was not in the original message
167 set then your resulting message set will be the same as the original,
168 only more expensive. However, if you attempt to remove several messages
169 from the message set and some of those messages were in the message set
170 and some were not, the additional overhead of checking for the messages
171 that were not there is negligable. In either case you get back the mes‐
172 sage set you want regardless of whether it was already like that or
173 not.
174
176 Please feel free to e-mail the author at "bug-Mail-IMAP‐
177 Client@rt.cpan.org" if you encounter any strange behaviors. Don't worry
178 about hurting my feelings or sounding like a whiner or anything like
179 that; if there's a problem with this module you'll be doing me a favor
180 by reporting it. However, I probably won't be able to do much about it
181 if you don't include enough information, so please read and follow
182 these instructions carefully.
183 When reporting a bug, please be sure to include the following:
185 - As much information about your environment as possible. I especially
187 need to know which version of Mail::IMAPClient you are running and the
188 type/version of IMAP server to which you are connecting. Your OS and
189 perl verions would be helpful too.
190 - As detailed a description of the problem as possible. (What are you
192 doing? What happens? Have you found a work-around?)
193 - An example script that demonstrates the problem (preferably with as
195 few lines of code as possible!) and which calls the Mail::IMAPClient's
196 new method with the Debug parameter set to "1". (If this generates a
197 ridiculous amount of output and you're sure you know where the problem
198 is, you can create your object with debugging turned off and then turn
199 it on later, just before you issue the commands that recreate the prob‐
200 lem. On the other hand, if you can do this you can probably also reduce
201 the program rather than reducing the output, and this would be the best
202 way to go under most circumstances.)
203 - Output from the example script when it's running with the Debug
205 parameter turned on. You can edit the output to remove (or preferably
206 to "X" out) sensitive data, such as hostnames, user names, and pass‐
207 words, but PLEASE do not remove the text that identifies the TYPE of
208 IMAP server to which you are connecting. Note that in most versions of
209 Mail::IMAPClient, debugging does not print out the user or password
210 from the login command line. However, if you use some other means of
211 authenticating then you may need to edit the debugging output with an
212 eye to security.
213 - If something worked in a previous release and doesn't work now,
215 please tell me which release did work. You don't have to test every
216 intervening release; just let me know it worked in version x but
217 doesn't work in version (x+n) or whatever.
218 - Don't be surprised if I come back asking for a trace of the problem.
220 To provide this, you should create a file called .perldb in your cur‐
221 rent working directory and include the following line of text in that
222 file:
223 "&parse_options("NonStop=1 LineInfo=mail_imapclient_db.out");"
225 For your debugging convenience, a sample .perldb file, which was ran‐
227 domly assigned the name sample.perldb, is provided in the distribution.
228 Next, without changing your working directory, debug the example script
230 like this: "perl -d example_script.pl [ args ]"
231 Note that in these examples, the script that demonstrates your problem
233 is named "example_script.pl" and the trace output will be saved in
234 "mail_imapclient_db.out". You should either change these values to suit
235 your needs, or change your needs to suit these values.
236 Bug reports should be mailed to:
238 bug-Mail-IMAPClient@rt.cpan.org
240 Please remember to place a SHORT description of the problem in the sub‐
242 ject of the message. Please try to be a bit specific; things like "Bug
243 in Mail::IMAPClient" or "Computer Problem" won't exactly expedite
244 things on my end.
245
247 If you have suggestions for extending this functionality of this mod‐
248 ule, or if you have a question and you can't find an answer in any of
249 the documentation (including the RFC's, which are included in this dis‐
250 tribution for a reason), then you can e-mail me at the following
251 address:
252 comment-Mail-IMAPClient@rt.cpan.org
254 Please note that this address is for questions, suggestions, and other
256 comments about Mail::IMAPClient. It's not for reporting bugs, it's not
257 for general correspondence, and it's especially not for selling porn,
258 mortgages, Viagra, or anything else.
259
261 David J. Kernen
262 The Kernen Consulting Group, Inc
263 DJKERNEN@cpan.org
264
266 Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
267 All rights reserved.
268 This program is free software; you can redistribute it and/or modify it
270 under the terms of either:
271 a) the "Artistic License" which comes with this Kit, or
273 b) the GNU General Public License as published by the Free Software
274 Foundation; either version 1, or (at your option) any later version.
275 This program is distributed in the hope that it will be useful, but
277 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
278 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU
279 General Public License or the Artistic License for more details. All
280 your base are belong to us.
281perl v5.8.8 2003-06-24 MessageSet(3)