Mail::IMAPClient::MessageSet -- an extension to Mail::IMAPClient that expresses lists of message sequence numbers or message UID's in the shortest way permissable by RFC2060.

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. (But you need perl 5.6 or above to do this.)

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 specifiy 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).

To illustrate, let's take the trivial example of a search that returns these message uids: 1,3,4,5,6,9,10, as follows:

        @msgs = $imap->search("SUBJECT","Virus"); # returns 1,3,4,5,6,9,10
        my $msgset = Mail::IMAPClient::MessageSet->new(@msgs);
        print "$msgset\n";  # prints "1,3:6,9:10\n"
        # add message 14 to the set:
        $msgset += 14;  
        print "$msgset\n";  # prints "1,3:6,9:10,14\n"
        # add messages 16,17,18,19, and 20 to the set:
        $msgset .= "16,17,18:20";       
        print "$msgset\n";  # prints "1,3:6,9:10,14,16:20\n"
        # Hey, I didn't really want message 17 in there; let's take it out:
        $msgset -= 17;
        print "$msgset\n";  # prints "1,3:6,9:10,14,16,18:20\n"
        # Now let's iterate over each message:
        for my $msg (@$msgset) {
                print "$msg\n";
        }       # Prints: "1\n3\n4\n5\n6\n9\n10\n14\n16\n18\n19\n20"

(Note that the Mail::IMAPClient Range method can be used as a short-cut to specifying CWMail::IMAPClient::MessageSet->new(@etc).)

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.

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.

The only object method currently available to a Mail::IMAPClient::MessageSet object is the unfold method.

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.

Mail::IMAPClient::MessageSet overrides a number of operators in order to make manipulating your message sets easier. The overridden operations are:

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.

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

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 CW.= operator and the CW+= 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.

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 negligable. In either case you get back the message set you want regardless of whether it was already like that or not.

Please feel free to e-mail the author at CWbug-Mail-IMAPClient@rt.cpan.org if you encounter any strange behaviors. Don't worry about hurting my feelings or sounding like a whiner or anything like that; if there's a problem with this module you'll be doing me a favor by reporting it. However, I probably won't be able to do much about it if you don't include enough information, so please read and follow these instructions carefully.

When reporting a bug, please be sure to include the following:

- As much information about your environment as possible. I especially need to know which version of Mail::IMAPClient you are running and the type/version of IMAP server to which you are connecting. Your OS and perl verions would be helpful too.

- As detailed a description of the problem as possible. (What are you doing? What happens? Have you found a work-around?)

- An example script that demonstrates the problem (preferably with as few lines of code as possible!) and which calls the Mail::IMAPClient's new method with the Debug parameter set to 1. (If this generates a ridiculous amount of output and you're sure you know where the problem is, you can create your object with debugging turned off and then turn it on later, just before you issue the commands that recreate the problem. On the other hand, if you can do this you can probably also reduce the program rather than reducing the output, and this would be the best way to go under most circumstances.)

- Output from the example script when it's running with the Debug parameter turned on. You can edit the output to remove (or preferably to X out) sensitive data, such as hostnames, user names, and passwords, but PLEASE do not remove the text that identifies the TYPE of IMAP server to which you are connecting. Note that in most versions of Mail::IMAPClient, debugging does not print out the user or password from the login command line. However, if you use some other means of authenticating then you may need to edit the debugging output with an eye to security.

- If something worked in a previous release and doesn't work now, please tell me which release did work. You don't have to test every intervening release; just let me know it worked in version x but doesn't work in version (x+n) or whatever.

- Don't be surprised if I come back asking for a trace of the problem. To provide this, you should create a file called .perldb in your current working directory and include the following line of text in that file:

CW&parse_options("NonStop=1 LineInfo=mail_imapclient_db.out");

For your debugging convenience, a sample .perldb file, which was randomly assigned the name sample.perldb, is provided in the distribution.

Next, without changing your working directory, debug the example script like this: CWperl -d example_script.pl [ args ]

Note that in these examples, the script that demonstrates your problem is named example_script.pl and the trace output will be saved in mail_imapclient_db.out. You should either change these values to suit your needs, or change your needs to suit these values.

Bug reports should be mailed to:

        bug-Mail-IMAPClient@rt.cpan.org

Please remember to place a SHORT description of the problem in the subject of the message. Please try to be a bit specific; things like Bug in Mail::IMAPClient or Computer Problem won't exactly expedite things on my end.

If you have suggestions for extending this functionality of this module, or if you have a question and you can't find an answer in any of the documentation (including the RFC's, which are included in this distribution for a reason), then you can e-mail me at the following address:

        comment-Mail-IMAPClient@rt.cpan.org

Please note that this address is for questions, suggestions, and other comments about Mail::IMAPClient. It's not for reporting bugs, it's not for general correspondence, and it's especially not for selling porn, mortgages, Viagra, or anything else.

        David J. Kernen
        The Kernen Consulting Group, Inc
        DJKERNEN@cpan.org

          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:

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.