NAME¶
Mail::IMAPClient::MessageSet - ranges of message sequence numbers
SYNOPSIS¶
my @msgs = $imap->search("SUBJECT","Virus"); # returns 1,3,4,5,6,9,10
my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
print $msgset; # prints "1,3:6,9:10"
# add message 14 to the set:
$msgset += 14;
print $msgset; # prints "1,3:6,9:10,14"
# add messages 16,17,18,19, and 20 to the set:
$msgset .= "16,17,18:20";
print $msgset; # prints "1,3:6,9:10,14,16:20"
# Hey, I didn't really want message 17 in there; let's take it out:
$msgset -= 17;
print $msgset; # prints "1,3:6,9:10,14,16,18:20"
# Now let's iterate over each message:
for my $msg (@$msgset)
{ print "$msg\n"; # Prints: "1\n3\n4\n5\n6..16\n18\n19\n20\n"
}
print join("\n", @$msgset)."\n"; # same simpler
local $" = "\n"; print "@$msgset\n"; # even more simple
DESCRIPTION¶
The
Mail::IMAPClient::MessageSet module is designed to make life easier
for programmers who need to manipulate potentially large sets of IMAP message
UID's or sequence numbers.
This module presents an object-oriented interface into handling your message
sets. The object reference returned by the new method is an overloaded
reference to a scalar variable that contains the message set's compact RFC2060
representation. The object is overloaded so that using it like a string
returns this compact message set representation. You can also add messages to
the set (using either a '.=' operator or a '+=' operator) or remove messages
(with the '-=' operator). And if you use it as an array reference, it will
humor you and act like one by calling unfold for you.
RFC2060 specifies that multiple messages can be provided to certain IMAP
commands by separating them with commas. For example, "1,2,3,4,5"
would specify messages 1, 2, 3, 4, and (you guessed it!) 5. However, if you
are performing an operation on lots of messages, this string can get quite
long. So long that it may slow down your transaction, and perhaps even cause
the server to reject it. So RFC2060 also permits you to specify a range of
messages, so that messages 1, 2, 3, 4 and 5 can also be specified as
"1:5".
This is where
Mail::IMAPClient::MessageSet comes in. It will convert your
message set into the shortest correct syntax. This could potentially save you
tons of network I/O, as in the case where you want to fetch the flags for all
messages in a 10000 message folder, where the messages are all numbered
sequentially. Delimited as commas, and making the best-case assumption that
the first message is message "1", it would take 48893 bytes to
specify the whole message set using the comma-delimited method. To specify it
as a range, it takes just seven bytes (1:10000).
Note that the Mail::IMAPClient
Range method can be used as a short-cut to
specifying "Mail::IMAPClient::MessageSet->new(@etc)".)
CLASS METHODS¶
The only class method you need to worry about is
new. And if you create
your
Mail::IMAPClient::MessageSet objects via Mail::IMAPClient's
Range method then you don't even need to worry about
new.
new¶
Example:
my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
The
new method requires at least one argument. That argument can be
either a message, a comma-separated list of messages, a colon-separated range
of messages, or a combination of comma-separated messages and colon-separated
ranges. It can also be a reference to an array of messages, comma-separated
message lists, and colon separated ranges.
If more then one argument is supplied to
new, then those arguments should
be more message numbers, lists, and ranges (or references to arrays of them)
just as in the first argument.
The message numbers passed to
new can really be any kind of number at all
but to be useful in a Mail::IMAPClient session they should be either message
UID's (if your
Uid parameter is true) or message sequence numbers.
The
new method will return a reference to a
Mail::IMAPClient::MessageSet object. That object, when double quoted,
will act just like a string whose value is the message set expressed in the
shortest possible way, with the message numbers sorted in ascending order and
with duplicates removed.
OBJECT METHODS¶
The only object method currently available to a
Mail::IMAPClient::MessageSet object is the unfold method.
unfold¶
Example:
my $msgset = $imap->Range( $imap->messages ) ;
my @all_messages = $msgset->unfold;
The
unfold method returns an array of messages that belong to the message
set. If called in a scalar context it returns a reference to the array
instead.
OVERRIDDEN OPERATIONS¶
Mail::IMAPClient::MessageSet overrides a number of operators in order to
make manipulating your message sets easier. The overridden operations are:
stringify¶
Attempts to stringify a
Mail::IMAPClient::MessageSet object will result
in the compact message specification being returned, which is almost certainly
what you will want.
Auto-increment¶
Attempts to autoincrement a
Mail::IMAPClient::MessageSet object will
result in a message (or messages) being added to the object's message set.
Example:
$msgset += 34;
# Message #34 is now in the message set
Concatenate¶
Attempts to concatenate to a
Mail::IMAPClient::MessageSet object will
result in a message (or messages) being added to the object's message set.
Example:
$msgset .= "34,35,36,40:45";
# Messages 34,35,36,40,41,42,43,44,and 45 are now in the message set
The ".=" operator and the "+=" operator can be used
interchangeably, but as you can see by looking at the examples there are times
when use of one has an aesthetic advantage over use of the other.
Autodecrement¶
Attempts to autodecrement a
Mail::IMAPClient::MessageSet object will
result in a message being removed from the object's message set.
Examples:
$msgset -= 34;
# Message #34 is no longer in the message set
$msgset -= "1:10";
# Messages 1 through 10 are no longer in the message set
If you attempt to remove a message that was not in the original message set then
your resulting message set will be the same as the original, only more
expensive. However, if you attempt to remove several messages from the message
set and some of those messages were in the message set and some were not, the
additional overhead of checking for the messages that were not there is
negligible. In either case you get back the message set you want regardless of
whether it was already like that or not.
AUTHOR¶
David J. Kernen
The Kernen Consulting Group, Inc
COPYRIGHT¶
Copyright 1999, 2000, 2001, 2002 The Kernen Group, Inc.
All rights reserved.
This program is free software; you can redistribute it and/or modify it under
the terms of either:
- a) the "Artistic License" which comes with this Kit, or
- b) the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See either the GNU General Public License or the
Artistic License for more details. All your base are belong to us.