NAME

Mail::Box - Manage a message-folder.

SYNOPSIS

use Mail::Box;
my $folder = new Mail::Box file => $ENV{MAIL}, ...;
print $folder->message(0)->subject;      # See Mail::Box::Message
$folder->message(3)->deleted(1);
my $emails = $folder->messages;          # amount

$folder->addMessage(new Mail::Box::Message(...));

foreach (@{$folder->messages}) {...}     # the messages
foreach (@$folder) {...}                 # same

Tied-interface:

use Mail::Box;
tie my @inbox, 'Mail::Box', file => $ENV{MAIL};
# See Mail::Box::Tied

DESCRIPTION

Read Mail::Box::Manager first. Mail::Box is the base-class for accessing various types of mail-folder organizational structures in a uniformal way.

This class extends:

• Mail::Box::Threads

  implements thread detection and simplified access to the threads found.

• Mail::Box::Locker

  implements various locking algorithms

• Mail::Box::Tie

  provides simple array-based access to the folder.

You need to read their manual-pages too, to find-out what a folder is capable of.

The various folder-types do vary on how they store their messages (a folder with many messages in a single file or a folder as a directory with each message in a single file) Furthermore, different types of folders have different ways to be locked.

Applications usually add information to the messages in the folders, for instance whether you have replied to a message or not. The base-class for messages in a folder is Mail::Box::Message (an extention of MIME::Entity). It presents message-facts in an application-independent way. Each application needs to extend Mail::Box::Message with their own practices.

PUBLIC INTERFACE

new ARGS

(Class method) Create a new folder. The ARGS is a list of labeled parameters defining what to do. Each sub-class of Mail::Box will add different options to this method. See their manual-pages.

All possible options are: (for detail description of the Mail::Box specific options see below, for the other options their respective manual-pages)

access            Mail::Box          'r'
dummy_type        Mail::Box::Threads 'Mail::Box::Message::Dummy'
folder            Mail::Box          $ENV{MAIL}
folderdir         Mail::Box          <no default>
lazy_extract      Mail::Box          10kb
lockfile          Mail::Box::Locker  foldername.'.lock'
lock_method       Mail::Box::Locker  'dotlock'
lock_timeout      Mail::Box::Locker  1 hour
lock_wait         Mail::Box::Locker  10 seconds
manager           Mail::Box          undef
message_type      Mail::Box          'Mail::Box::Message'
notreadhead_type  Mail::Box          'Mail::Box::Message::NotReadHead'
notread_type      Mail::Box          'Mail::Box::Message::NotParsed'
realhead_type     Mail::Box          'MIME::Head'
remove_when_empty Mail::Box          1
save_on_exit      Mail::Box          1
take_headers      Mail::Box          <specify everything you need>
<none>            Mail::Box::Tie

The options added by Mail::Box

• folder => FOLDERNAME

  Which folder to open (for read or write). When used for reading (the access option set to "r") the mailbox should already exist. When opened for "rw", we do not care, although write-permission is checked on opening.

• access => MODE

  Access-rights to the folder. MODE can be read-only ("r"), append ("a"), and read-write ("rw"). These modes have nothing in common with the modes actually used to open the folder-files within this module.

  Folders are opened for read-only ("r") by default.

• folderdir => DIRECTORY

  Where are folders written by default? You can specify a folder-name preceeded by = to explicitly state that the folder is located below this directory.

• message_type => CLASS

  What kind of message-objects are stored in this type of folder. The default is Mail::Box::Message (which is a sub-class of MIME::Entity). The class you offer must be an extention of Mail::Box::Message.

• save_on_exit => BOOL

  Sets the default on what to do when the folder is closed (see the close() method. When the program is terminated, or any other reason when the folder is automatically close, this flag determines what to do. By default, this is TRUE;

• remove_when_empty => BOOL

  Remove the folder-file or directory (dependent on the type of folder) automatically when the write would result in a folder without sub-folders and messages. This is true by default.

• manager => MANAGER

  The object which manages this folder. Typically a (sub-class of) Mail::Box::Manager.

Some folder-types have the following options. You can find this in their specific manual-pages. Folders which do not support these fields will not complain.

• notread_type => CLASS

• notreadhead_type => CLASS

• realhead_type => CLASS

  Three classes of objects which are usually hidden for users of this module, but especially useful if you plan to extent modules. These classes all contain parts of an incompletely read message.

• lazy_extract => INTEGER

• lazy_extract => CODE

• lazy_extract => METHOD

• lazy_extract => 'NEVER'|'ALWAYS'

  If you supply a number to this option, bodies of those messages with a total size less than that number will be extracted from the folder only when nessesary. Headers will always be extracted, even from the larger messages. This reduces the memory-footprint of the program, with only little cost.

  When you supply a code-reference, that subroutine is called every time that the extraction mechanism wants to determine whether to parse the body or not. The subroutine is called:

  $code->(FOLDER, HEADER, BODY, BYTES)

  where FOLDER is a reference to the folder we are reading. HEADER refers an array of header-lines, or a MIME::Header, but may also be undef. You have to handle all three situations. BODY refers to the array lines which form the body of the message (including message-parts), but may also be undef, dependent on the folder-type. BYTES is the size of the message in bytes including the header-lines, and always defined. This may be the best way to make a selection.

  The routine must return true (be lazy: delay extract) or false (extract now).

  The third possibility is to specify the NAME of a method. In that case, for each message is called:

  FOLDER->NAME(HEADER, BODY, BYTES)

  Where each field has the same meaning as described above.

  The fourth way to use this parameter involves constants: with 'NEVER' you can disable delayed loading. With 'ALWAYS' you force unconditional delayed-loading.

  Examples: $folder->new(lazy_extract => 'NEVER'); $folder->new(lazy_extract => 10000); $folder->new(lazy_extract => sub {$_[3] >= 10000 }); #same

  $folder->new(lazy_extract => 'sent_by_me');
  sub Mail::Box::send_by_me($$$)
  {   my ($self, $header, $lines, $bytes) = @_;
      $header->get('from') =~ m/\bmy\@example.com\b/i;
  }

  The Mail::Box::Message manual-page has more on this subject.

• take_headers => REF-ARRAY-OF-REGEXPS|REGEXPS|'ALL'|'REAL'

  When messages are not parsed (as controlled by the lazy_extract parameter), and hence stay in their respective files, some header-lines are still to be taken: for instance you still want access to the subject-field to be able to print an index.

  If you know your application needs some header-fields frequently, you add them to the default list of fields which are already taken by the folder-implementation. No problem if you specify the same name twice.

  You can specify a regular expression, although you cannot use parentheses in them which do count. The expressions will be matched always on the whole field. So X-.* will only match lines starting with X-. You can not used X-(ab|cd).*, but may say X-(?:ab|cd).*.

  If you specify too few fields, then all messages will get parsed to get the field you missed when you scanned the folder first. When you specify too many fields, your program will consume more memory.

  There are two special constants. With ALL you get all header-lines from the message (same as pattern .*) and REAL will cause headers to be read into a real MIME::Header structure (to be more precise: the type you specify with realhead_type.)

  Examples: $folder->new( take_headers => 'ALL'); $folder->new( take_headers => 'Subject'); $folder->new( take_headers => [ 'X-Mutt-.*', 'X-Folder-.*' ]); $folder->new( take_headers => 'REAL' , realhead_type => 'MIME::Head' ); =back

• clone [OPTIONS]

  Create a new folder, with the same settings as this folder. One of the specified options must be new folder to be opened. Other options overrule those of the folder where this is a clone from.

  Example: my $folder2 = $folder->clone(folder => '=jan');

• registerHeaders REGEXP [,REGEXP, ...]

• registeredHeaders

  See the take_header option of new(). The registerHeaders method can be used to specify more header-lines to be taken when scanning through a folder. Its counterpart registeredHeaders returns:

  • 'ALL' to indicate that all headers should be taken.

  • 'REAL' to indicated that all headers should be taken and translated into a real MIME::Header.

  • a list over lowercased regular expressions which sprecify the header-line to be taken.

• unfoldHeaders REF-ARRAY

  E-mail headers may span a few lines (folded fields). The first line has the name of the field, and is followed by one or more lines which start with some blanks.

  This method receives an array, and modifies it such that folder lines are rejoined with their field-name. Don't forget to fold back again when printing to file.

• read OPTIONS

  Read messages from the folder into the folder-structure. If there are already messages in this structure, the new ones are added.

  When to want to add messages from a different foldertype to this folder, you need to join folders, as shown in the following example.

  Example read folder into folder: my $folder = Mail::Box::File->new(folder => 'InBox'); my $old = Mail::Box::MH->new(folder => 'Received'); $folder->addMessages(@$old); $folder->write; $old->delete;

• write

  Write the data to its folder. If this returns false, then it failed.

• close OPTIONS

  Close the folder. It depends on the OPTIONS whether the folder is to be written or not. Futhermore, you may specify options which are passed to write, as descibed above.

  Options specific to close are:

  write => 'ALWAYS'|'NEVER'|'MODIFIED'

  When must the folder be written. As could be expected, 'ALWAYS' means always (even if there are no changes), 'NEVER' means that changes to the folder will be lost, and 'MODIFIED' (which is the default) only saves the folder if there are any changes.

  force => BOOL

  Overrule the setting of access when the folder was opened. This only contributes to your program when you give it a TRUE value. However: writing to the folder not be permitted by the file-system, in which case even force will not help.

• synchronize

  Write the messages to disk, and then read it back again. This will create a new folder structure, so you have to catch the result.

  Examples: $folder = $folder->synchronize; $folder = $folder->synchronize->lintThreads;

• delete

  Remove the specified folder-file or folder-directory (dependent on the type of folder) from disk. Of course, THIS IS DANGEROUS: you "may" lose data.

  When you first copied this folder's information into an other folder, then be sure that that folder is written to disk first! Otherwise you may loose data in case of a system-crash or software problems.

  Examples of instance call: my $folder = Mail::Box::File->new(folder => 'InBox'); $folder->delete;

• name

  Returns the name of this folder. What the name represents depends on the actual type of mailboxes used.

  Example: print $folder->name;

• writeable

• readable

  Checks whether the current folder is writeable respectively readable.

  Example: $folder->addMessage($msg) if $folder->writeable;

• modified

• modifications INCR

  modified checks if the folder is modified, where modifications is used to tell the folder how many changes are made in messages. The INCR value can be negative to undo effects.

• lazyExtract HEADER, BODY, BYTES

  Calls the subroutine which will perform the chech whether a message's body should be extracted or stay in the folder until used. This method calls the routine defined by the `lazy_extract' option at creation of the folder.

• message INDEX

  Get or set a message with on a certain index.

  Examples: my $msg = $folder->message(3); $folder->message(3)->delete; # status changes to `deleted' $folder->message(3) = $msg;

• messages

  Returns all messages which are not scheduled to be deleted. In scalar context, it provides you with the number of undeleted messages in this folder. Dereferencing a folder to an array is overloaded to call this method.

  Examples: foreach ($folder->messages) {...} foreach (@$folder) my $remaining_size = $folder->messages;

• activeMessage INDEX

  Returns the message indicated by INDEX from the list of non-deleted messages. This is useful for the tied-folder interface, where we only see the non-deleted messages, but not for other purposes.

• allMessages

  Returns a list of all messages in the folder, including those which are to be deleted.

  Examples: foreach ($folder->allMessages) {...} my $total_size = $folder->allMessages;

• addMessage MESSAGE

• addMessages MESSAGE [, MESSAGE, ...]

  Add a message to the folder. A message is usually a Mail::Box::Message object or a sub-class of that.

  Messages with id's which allready exist in this folder are neglected.

  Examples: $folder->addMessage($msg); $folder->addMessages($msg1, $msg2, ...);

• appendMessages LIST-OF-OPTIONS

  (Class method) Append one or more messages to an unopened folder. Usually, this method is called by the Mail::Box::Manager (its method appendMessage()), in which case the correctness of the foldertype is checked.

  This method gets a list of labeled parameters, which may contain any flag which can be used when a folder is opened (most importantly folderdir). Next to these, two parameters shall be specified:

  • folder => FOLDERNAME

    The name of the folder where the messages are to be appended. When possible, the folder-implementation will avoid to open the folder for real, because that is resource consuming.

  • message => MESSAGE

  • messages => ARRAY-OF-MESSAGES

    One reference to a MESSAGE or a reference to an ARRAY of MESSAGEs, which may be of any type. The messages will first be coerced into the correct message-type to fit in the folder, and then be added to it.

• coerce MESSAGE

  Coerce the message to be of the correct type to be placed in the folder.

• messageDeleted MESSAGE|MESSAGE-ID, BOOL

  Signals to the folder that a message has been deleted. This method is called automatically when you call the delete method on a MESSAGE. If the BOOL is true, the message got deleted, otherwise it got undeleted.

• folderdir [DIR]

  Get or set the directory which is used to store mail-folders by default.

  Examples: print $folder->folderdir; $folder->folderdir("$ENV{HOME}/nsmail");

• DESTROY

  This method is called by Perl when an folder-object is not accessible anymore by the rest of the program. However... This is not accomplished automatically because (unparsed) messages reference back to their folder: there is a two-way reference which is not resolved by the perl-memory cleanup.

  The two ways to clean-up the folder information is

  • by explicitly call for a close on a folder,

    in which case the data may be preserved (when the save_on_exit flag was selected), or

  • by terminating the program

    which will cause changes to be lost. In this condition, the two-way reference will cause Perl to call the DESTROY of the folder and its messages in undefined order. It is not possible to write messages which are already removed...

folder management methods

The following class methods are used to test and list folders. The do share the folderdir option, where you can specify which is the default location for the folder-files.

foundIn FOLDERNAME [,OPTIONS]

(class method) Autodetect if there is a folder of a certain type specified here. This method is extended for each type of folder.

The FOLDERNAME specifies the name of the folder, as is specified by the application. OPTIONS is a list of extra information on the request. Read the manual-page for each type of folder for more options, but at least each type will support

• folderdir => DIRECTORY

  The location where the folders of this class are stored by default. If the user specifies a name starting with a =, that symbolizes that the name is to be found is this default DIRECTORY.

listFolders [OPTIONS]

(class method) List all folders which belong to a certain class of folders. Each class should extent this method.

At least the following options are supported, but refer to the manpage of the various folder-classes to see more options.

• folderdir => DIRECTORY

• check => BOOL

  Specifies whether to do a very thorrow job on selecting folders. Performing a check on each file or directory (depends on the type of folder) to see if it really contains a folder can be time-consuming, so the default is off.

• skip_empty => BOOL

  Shall empty folders (folders which currently do not contain any messages) be included? Empty folders are not useful to open, but may be useful to save to.

subFolders [OPTIONS]

Returns a list with sub-folder names for the specified folder. Some folder-types do not have real sub-folders, but that can be simulated.

Different folder-types may carry different OPTIONS, but the following are commonly known:

• check => 1

  Check all returned folder-names thorrowly. This will cost some performance.

Example: my @subfolders = $folder->subFolders(check => 1); if($folder->subFolders) { ... }

AUTHOR

Mark Overmeer (Mark@Overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is alpha, version 0.4