
=head1 NAME


Mail::Box - manage a message-folder.

=head1 CLASS INHERITANCE

Mail::Box
   is a Mail::Reporter

Mail::Box is extended by
   Mail::Box::Dir
   Mail::Box::Mbox
   Mail::Box::Net

=head1 SYNOPSIS


 use Mail::Box::Manager;
 my $mgr    = Mail::Box::Manager->new;
 my $folder = $mgr->open(folder => $ENV{MAIL}, ...);
 print $folder->name;

 # Get the first message.
 print $folder->message(0);

 # Delete the third message
 $folder->message(3)->delete;

 # Get the number of messages in scalar context.
 my $emails = $folder->messages;

 # Iterate over the messages.
 foreach ($folder->messages) {...}     # all messages
 foreach (@$folder) {...}              # all messages

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

Tied-interface:   (See Mail::Box::Tie)

 tie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox;
 $inbox[3]->print        # same as $folder->message(3)->print

 tie my(%inbox), 'Mail::Box::Tie::HASH', $inbox;
 $inbox{$msgid}->print   # same as $folder->messageId($msgid)->print

=head1 DESCRIPTION


A Mail::Box::Manager creates Mail::Box objects.  But you already
knew, because you started with the Mail::Box-Overview manual page.
That page is obligatory reading, sorry!

Mail::Box is the base class for accessing various types of mail folder
organizational structures in a uniform way.  The various folder types vary
on how they store their messages. For example, a folder may store many
messages in a single file, or store each message in a separate file in a
directory. Similarly, there may be different techniques for locking the
folders.

No object will be of type Mail::Box: it is only used as base class
for the real folder types.  Mail::Box is extended by

=over 4

=item * Mail::Box::Mbox

A folder type in which all related messages are stored in one file.  This
is very common folder type for UNIX.

=item * Mail::Box::MH

This folder creates a directory for each folder, and a message is one
file inside that directory.  The message files are numbered.

=item * Mail::Box::Maildir

This folder creates a directory for each folder.  A folder directory
contains a C<tmp>, C<new>, and C<cur> subdirectory.  New messages are
first stored in C<new>, and later moved to C<cur>.  Each message is one
file with a name starting with timestamp.

=back

The Mail::Box is used to get Mail::Box::Message objects from the
mailbox.  Applications then usually use information or add information to the
message object. For instance, the application can set a label which indicates
whether a message has been replied to or not.

=head1 METHODS

=head2 Initiation

=over 4

=item B<new> OPTIONS X<new>

(Class method) Open a new folder. OPTIONS is a list of labeled parameters
defining options for the mailboxes. Some options pertain to Mail::Box, and
others are added by sub-classes. The list below describes all the options
provided by Mail::Box and the various sub-classes distributed with it. Those
provided by the Mail::Box class are described in detail here. For a
description of the other options, see the documentation for the respective
sub-class.

To control delay-loading of messages, as well the headers as the bodies,
a set of C<*_type> options are available. C<extract> determines whether
we want delay-loading.

 OPTION               DEFAULT
 access               'r'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            <folder specific>
 coerce_options       []
 create               <false>
 extract              10240
 field_type           undef
 folder               $ENV{MAIL}
 folderdir            undef
 head_delayed_type    'Mail::Message::Head::Delayed'
 head_type            'Mail::Message::Head::Complete'
 head_wrap            72
 keep_dups            <false>
 lock_file            undef
 lock_timeout         1 hour
 lock_type            'Mail::Box::Locker::DotLock'
 lock_wait            10 seconds
 locker               undef
 log                  'WARNINGS'
 manager              undef
 message_type         'Mail::Box::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 remove_when_empty    <true>
 save_on_exit         <true>
 trace                'WARNINGS'
 trusted              <depends on folder location>

=over 4

=item B<access> =E<gt> MODE X<new(access)>

Access-rights to the folder. MODE can be read-only (C<"r">), append (C<"a">),
and read-write (C<"rw">).  Folders are opened for read-only (C<"r">) by
default.

These modes have nothing in common with the modes actually used to open the
folder-files within this module.  For instance, if you specify C<"rw">, and
open the folder, only read-permission on the folder-file is required.  Writing
to a folder will always create a new file to replace the old one.

=item B<body_delayed_type> =E<gt> CLASS X<new(body_delayed_type)>

The bodies which are delayed: which will be read from file when it
is needed, but not before.

=item B<body_type> =E<gt> CLASS|CODE X<new(body_type)>

When messages are read from a folder-file, the headers will be stored in
a C<head_type>-object.  For the body, however, there is a range of
choices about type, which are all described in the Mail::Message::Body
manual page.

Specify a CODE-reference which produces the body-type to be created, or
a CLASS of the body which is used when the body is not a multipart.  In case
of a code, the header-structure is passed as first argument to the routine.

Do I<not> return a delayed body-type (like C<::Delayed>), because that is
determined by the C<extract()> method.  Do always check for multipart
messages, otherwise your parts (I<attachments>) will not be split-up.

For instance:

 $mgr->open('InBox', body_type => \&which_body);

 sub which_body($) {
     my $head = shift;
     my $size = $head->guessBodySize || 0;
     my $type = $size > 100000 ? 'File' : 'Lines';
     "Mail::Message::Body::$type";
 }

The default depends on the mail-folder type, although the general default
is Mail::Message::Body::Lines.  Please check the applicable
manual pages.

=item B<coerce_options> =E<gt> ARRAY X<new(coerce_options)>

Keep configuration information for messages which are coerced into the
specified folder type, starting with a different folder type (or even
no folder at all).
Messages which are coerced are always fully read, so this kind of information
does not need to be kept here.

=item B<create> =E<gt> BOOLEAN X<new(create)>

Automatically create the folder when it does not exist yet.  This will only
work when access is granted for writing or appending to the folder.  Be
careful: you may create a different folder type than you expect unless you
ensure the C<type> (See Mail::Box::Manager::open()).

=item B<extract> =E<gt> INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS' X<new(extract)>

When the header of a message is read, you may want to postpone the
reading of the body.  Header information is more often needed than
the body data, so why parse it always together?  The cost of delaying
is not too high.

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 necessary.

If 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 with the following arguments:

 $code->(FOLDER, HEAD)

where FOLDER is a reference to the folder we are reading.  HEAD refers to a
Mail::Message::Head.  The routine must return a true value (extract now)
or a false value (be lazy, do not parse yet).  Think about using the
guessBodySize() and guessTimestamp() on the header to determine
your choice.

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

 FOLDER->NAME(HEAD)

Where each parameter has the same meaning as described above.

The fourth way to use this parameter involves constants: with C<'LAZY'>
all messages will be delayed. With C<'ALWAYS'> you force unconditional
loading.

Examples:

 $folder->new(extract => 'LAZY');
 $folder->new(extract => 10000);
 $folder->new(extract => sub
    { my ($f, $head) = @_;
      my $size = $head->guessBodySize;
      defined $size ? $size < 10000 : 1
    }); #same

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

=item B<field_type> =E<gt> CLASS X<new(field_type)>

The type of the fields to be used in a header. Must extend
Mail::Message::Field.

=item B<folder> =E<gt> FOLDERNAME X<new(folder)>

Which folder to open (for reading or writing). When used for reading (the
C<access> option set to C<"r"> or C<"a">) the mailbox should already exist
and be readable. The file or directory of the mailbox need not exist if it
is opened for reading and writing (C<"rw">).  Write-permission is checked when
opening an existing mailbox.

=item B<folderdir> =E<gt> DIRECTORY X<new(folderdir)>

Where are folders written by default?  You can specify a folder-name
preceded by C<=> to explicitly state that the folder is located below
this directory.  For example: if C<folderdir =E<gt> '/tmp'> and
C<folder =E<gt> '=abc'>, then the name of the folder-file is C<'/tmp/abc'>.

=item B<head_delayed_type> =E<gt> CLASS X<new(head_delayed_type)>

The headers which are delayed: which will be read from file when it
is needed, but not before.

=item B<head_type> =E<gt> CLASS X<new(head_type)>

The type of header which contains all header information.  Must extend
Mail::Message::Head::Complete.

=item B<head_wrap> =E<gt> INTEGER X<new(head_wrap)>

Fold the structured headers to the specified length.
Folding is disabled when C<0> is specified.

=item B<keep_dups> =E<gt> BOOLEAN X<new(keep_dups)>

Indicates whether or not duplicate messages within the folder should          
be retained.  A message is considered to be a duplicate if its message-id      
is the same as a previously parsed message within the folder. If this         
option is false (the default) such messages are automatically deleted,
because it is useless to store the same message twice.

=item B<lock_file> =E<gt> FILENAME X<new(lock_file)>

The name of the file which is used to lock.  This must be specified when
locking is to be used.

=item B<lock_timeout> =E<gt> SECONDS X<new(lock_timeout)>

When the lock file is older than the specified number of SECONDS, it is
considered a mistake.  The original lock is released, and accepted for
this folder.

=item B<lock_type> =E<gt> CLASS|STRING X<new(lock_type)>

The type of the locker object.  This may be the full name of a CLASS
which extends Mail::Box::Locker, or one of the known locker types
C<'DotLock'>, C<'File'>, C<'MULTI'>, C<'NFS'>, C<'POSIX'>, or C<'NONE'>.

=item B<lock_wait> =E<gt> SECONDS X<new(lock_wait)>

SECONDS to wait before failing on opening this folder.

=item B<locker> =E<gt> OBJECT X<new(locker)>

An OBJECT which extends Mail::Box::Locker, and will handle
folder locking replacing the default lock behavior.

=item B<log> =E<gt> LEVEL

See Mail::Reporter::new(log)

=item B<manager> =E<gt> MANAGER X<new(manager)>

A reference to the object which manages this folder -- typically an
Mail::Box::Manager instance.

=item B<message_type> =E<gt> CLASS X<new(message_type)>

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

=item B<multipart_type> =E<gt> CLASS X<new(multipart_type)>

The default type of objects which are to be created for multipart message
bodies.

=item B<remove_when_empty> =E<gt> BOOLEAN X<new(remove_when_empty)>

Determines whether or not to remove the folder file or directory
automatically when the write would result in a folder without sub-folders
or messages. This option is dependent on the type of folder.

=item B<save_on_exit> =E<gt> BOOLEAN X<new(save_on_exit)>

Sets the policy for saving the folder when it is closed. (See close())
A folder can be closed manually or via a number of
implicit methods (including when the program is terminated).

=item B<trace> =E<gt> LEVEL

See Mail::Reporter::new(trace)

=item B<trusted> =E<gt> BOOLEAN X<new(trusted)>

Flags whether to trust the data in the folder or not.  Folders which
reside in your C<folderdir> will be trusted by default, but folders
which are outside it will need some extra checking.

If you do not check encodings of received messages, you may print
text messages with binary data to the screen.  This is a security risk.

=back

=back

=head2 Opening folders

=over 4

=item B<clone> OPTIONS X<clone>

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.

Examples:

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

=item B<create> FOLDERNAME, OPTIONS X<create>

(Class method) Create a folder.  If the folder already exists, it will
be left unchanged.  As options, you may specify:

 OPTION               DEFAULT
 folderdir            undef

=over 4

=item B<folderdir> =E<gt> DIRECTORY X<create(folderdir)>

When the foldername is preceded by a C<=>, the C<folderdir> directory
will be searched for the named folder.

=back

=item B<folderdir> [DIRECTORY] X<folderdir>

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

Examples:

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

=item B<foundIn> [FOLDERNAME], OPTIONS X<foundIn>

(class method) Determine if the specified folder is of the type handled by the
folder class. This method is extended by each folder sub-type.

The FOLDERNAME specifies the name of the folder, as is specified by the
application.  You need to specified the C<folder> option when you skip
this first argument.

OPTIONS is a list of extra information for the request.  Read
the documentation for each type of folder for folder-specific options, but
each folder class will at least support the C<folderdir> option:

 OPTION               DEFAULT
 folderdir            undef

=over 4

=item B<folderdir> =E<gt> DIRECTORY X<foundIn(folderdir)>

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

=back

Examples:

 Mail::Box::Mbox->foundIn('=markov', folderdir => "$ENV{HOME}/Mail");
 Mail::Box::MH->foundIn(folder => '=markov');

=back

=head2 On open folders

=over 4

=item B<addMessage> MESSAGE X<addMessage>

=item B<addMessages> MESSAGE [, MESSAGE, ...] X<addMessages>

Add a message to the folder.  A message is usually a Mail::Box::Message
object or a sub-class thereof.  The message shall not be in an other folder,
when you use this method.  In case it is, use moveMessage() or
copyMessage() via the manager.

Messages with id's which already exist in this folder are not added.

Examples:

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

=item B<copyTo> FOLDER, OPTIONS X<copyTo>

Copy the folder's messages to a new folder.  The new folder may be of
a different type.

 OPTION               DEFAULT
 delete_copied        <false>
 select               'ACTIVE'
 subfolders           <folder type dependent>

=over 4

=item B<delete_copied> =E<gt> BOOLEAN X<copyTo(delete_copied)>

Flag the messages from the source folder to be deleted, just after it
was copied.  The deletion will only take effect when the originating
folder is closed.

=item B<select> =E<gt> 'ACTIVE'|'DELETED'|'ALL'|LABEL|!LABEL|FILTER X<copyTo(select)>

Which messages are to be copied. See the description of the option
for the messages() method about how this works.

=item B<subfolders> =E<gt> BOOLEAN|'FLATTEN'|'RECURSE' X<copyTo(subfolders)>

How to handle sub-folders.  When false (0 or C<undef>), sub-folders
are simply ignored.  With 'FLATTEN', messages from sub-folders are
included in the main copy.  'RECURSE' recursively copies the
sub-folders as well.  By default, when the destination folder
supports sub-folders 'RECURSE' is used, otherwise 'FLATTEN'.  A value
of true will select the default.

=back

Examples:

 my $mgr  = Mail::Box::Manager->new;
 my $imap = $mgr->open(type => 'imap', host => ...);
 my $mh   = $mgr->open(type => 'mh', folder => '/tmp/mh',
     create => 1, access => 'w');

 $imap->copyTo($mh, delete_copied => 1);
 $mh->close; $imap->close;

=item B<modified> [BOOLEAN] X<modified>

C<modified> checks if the folder is modified, optionally after setting the
flag.   A folder is modified when any of the messages is to be deleted, any
of the messages has changed, or messages are added after the folder was
read from file.

=item B<name>  X<name>

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

Examples:

 print $folder->name;

=item B<organization>  X<organization>

Returns whether a folder is organized as one 'FILE' with many messages or
a 'DIRECTORY' with one message per file.

=item B<update> OPTIONS X<update>

Read new messages from the folder, which where received after opening
it.  This is quite dangerous and shouldn't be possible: folders which
are open are locked.  However, some applications do not use locks or
the wrong kind of locks.  This method reads the changes (not always
failsafe) and incorporates them in the open folder administration.

The OPTIONS are extra values which are passed to the
updateMessages() method which is doing the actual work here.

=item B<writable>  X<writable>

Checks whether the current folder is writable.

Examples:

 $folder->addMessage($msg) if $folder->writable;

=back

=head2 Closing the folder

=over 4

=item B<DESTROY>  X<DESTROY>

This method is called by Perl when an folder-object is no longer accessible
by the rest of the program.

=item B<close> OPTIONS X<close>

lose the folder, optionally writing it. C<close> takes the same options as
write(), as well as a few others:

WARNING: When moving messages from one folder to another, be sure to write the
destination folder before writing and closing the source folder.  Otherwise
you may lose data if the system crashes or if there are software problems.

 OPTION               DEFAULT
 force                <false>
 write                'MODIFIED'

=over 4

=item B<force> =E<gt> BOOLEAN X<close(force)>

Override the C<access> setting specified when the folder was opened. This
option only has an effect if its value is TRUE. NOTE: Writing to the folder
may not be permitted by the operating system, in which case even C<force> will
not help.

=item B<write> =E<gt> 'ALWAYS'|'NEVER'|'MODIFIED' X<close(write)>

Specifies whether the folder should be written.  As could be expected,
C<'ALWAYS'> means always (even if there are no changes), C<'NEVER'> means that
changes to the folder will be lost, and C<'MODIFIED'>
only saves the folder if there are any changes.

=back

=item B<delete>  X<delete>

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

WARNING: When moving messages from one folder to another, be sure to write the
destination folder before deleting the source folder.  Otherwise you may lose
data if the system crashes or if there are software problems.

Examples:

 my $folder = Mail::Box::Mbox->new(folder => 'InBox');
 $folder->delete;

=back

=head2 The messages

=over 4

=item B<current> [NUMBER|MESSAGE|MESSAGE-ID] X<current>

Some mail-readers keep the I<current> message, which represents the last
used message.  This method returns [after setting] the current message.
You may specify a NUMBER, to specify that that message number is to be
selected as current, or a MESSAGE/MESSAGE-ID (as long as you are sure that the
header is already loaded, otherwise they are not recognized).

Examples:

 $folder->current(0);
 $folder->current($message);

=item B<find> MESSAGE-ID X<find>

Like messageId(), this method searches for a message with the
MESSAGE-ID, returning the corresponding message object.  However, C<find>
will cause unparsed message in the folder to be parsed until the message-id
is found.  The folder will be scanned back to front.

=item B<message> INDEX [,MESSAGE] X<message>

Get or set a message with on a certain index.  Messages which are flagged
for deletion are counted.  Negative indexes start at the end of the folder.

Examples:

 my $msg = $folder->message(3);
 $folder->message(3)->delete;   # status changes to `deleted'
 $folder->message(3, $msg);
 print $folder->message(-1);    # last message.

=item B<messageId> MESSAGE-ID [,MESSAGE] X<messageId>

With one argument, returns the message in the folder with the specified
MESSAGE-ID. If a reference to a message object is passed as the optional
second argument, the message is first stored in the folder, replacing any
existing message whose message ID is MESSAGE-ID. (The message ID of MESSAGE
need not match MESSAGE-ID.)

The MESSAGE-ID may still be in angles, which will be stripped.  In that
case blanks (which origin from header line folding) are removed too.  Other
info around the angles will be removed too.

WARNING: when the message headers are delay-parsed, the message might be in
the folder but not yet parsed into memory. In this case, use the find()
method instead of C<messageId> if you really need a thorough search.

Examples:

 my $msg = $folder->messageId('<complex-message.id>');
 $folder->messageId("<complex-message\n.id>", $msg);
 my $msg = $folder->messageId('complex-message.id');
 my $msg = $folder->messageId('garbage <complex-message.id> trash');

=item B<messageIds>  X<messageIds>

Returns a list of I<all> message-ids in the folder, including
those of messages which are to be deleted.

For some folder-types (like MH), this method may cause all message-files
to be read.  See their respective manual pages.

Examples:

 foreach my $id ($folder->messageIds) {
    $folder->messageId($id)->print;
 }

=item B<messages> ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER] X<messages>

Returns multiple messages from the folder.  The default is 'ALL'
which will return (as expected maybe) all the messages in the
folder.  The 'ACTIVE' flag will return the messages not flagged for
deletion.  This is the opposite of 'DELETED', which returns all
messages from the folder which will be deleted when the folder is
closed.

You may also specify a RANGE: two numbers specifying begin and end
index in the array of messages.  Negative indexes count from the
end of the folder.  When an index is out-of-range, the returned
list will be shorter without complaints.

Everything else than the predefined names is seen as labels.  The messages
which have that label set will be returned.  When the sequence starts
with an exclamation mark (!), the search result is reversed.

For more complex searches, you can specify a FILTER, which is
simply a code reference.  The message is passed as only argument.

Examples:

 foreach my $message ($folder->messages) {...}
 foreach my $message (@$folder) {...}
 my @messages   = $folder->messages;
 my @messages   = $folder->messages('ALL');    # same

 my $subset     = $folder->messages(10,-8);

 my @not_deleted= grep {not $_->deleted} $folder->messages;
 my @not_deleted= $folder->messages('ACTIVE'); # same

 my $nr_of_msgs = $folder->messages;           # scalar context
 $folder->[2];                  # third message, via overloading

 $mgr->moveMessages($spamfolder, $inbox->message('spam'));
 $mgr->moveMessages($archive, $inbox->message('seen'));

=item B<scanForMessages> MESSAGE, MESSAGE-IDS, TIMESTAMP, WINDOW X<scanForMessages>

The MESSAGE which is known contains references to messages before
it which are not found yet.  But those messages can be in the same
folder.  Scan back in this folder for the MESSAGE-IDS (which may be
one string or a reference to an array of strings).  The TIMESTAMP
and WINDOW (see options in new()) limit the search.

=back

=head2 Sub-folders

=over 4

=item B<listSubFolders> OPTIONS X<listSubFolders>

(Class and Instance method)
List the names of all sub-folders to this folder.  Use these names
in openSubFolder(), to open these folders on a mailbox type way.
For Mbox-folders, sub-folders are simulated.

 OPTION               DEFAULT
 check                <false>
 folder               <obligatory>
 folderdir            <from folder>
 skip_empty           <false>

=over 4

=item B<check> =E<gt> BOOLEAN X<listSubFolders(check)>

Specifies whether empty folders (folders which currently do not contain any
messages) should be included. It may not be useful to open empty folders, but 
saving to them is useful.

=item B<folder> =E<gt> FOLDERNAME X<listSubFolders(folder)>

The folder whose sub-folders should be listed.

=item B<folderdir> =E<gt> DIRECTORY X<listSubFolders(folderdir)>

=item B<skip_empty> =E<gt> BOOL X<listSubFolders(skip_empty)>

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.

=back

Examples:

 my $folder = $mgr->open('=in/new');
 my @subs = $folder->listSubFolders;

 my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');
 my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.

=item B<openRelatedFolder> OPTIONS X<openRelatedFolder>

Open a folder (usually a sub-folder) with the same options as this one.  If
there is a folder manager in use, it will be informed about this new folder.
OPTIONS overrule the options which where used for the folder this method
is called upon.

=item B<openSubFolder> NAME, OPTIONS X<openSubFolder>

Open (or create, if it does not exist yet) a new subfolder in an
existing folder.

Examples:

 my $folder = Mail::Box::Mbox->new(folder => '=Inbox');
 my $sub    = $folder->openSubFolder('read');

=back

=head2 Message threads [internals]

=over 4

=item B<toBeThreaded> MESSAGES X<toBeThreaded>

=item B<toBeUnthreaded> MESSAGES X<toBeUnthreaded>

The specified message is ready to be included in (or remove from) a thread.
This will be passed on to the mail-manager, which keeps an overview on
which thread-detection objects are floating around.

=back

=head2 Reading and Writing [internals]

=over 4

=item B<appendMessages> OPTIONS X<appendMessages>

(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
folder type is checked.

This method takes a list of labeled parameters, which may contain
any option which can be used when a folder is opened (most importantly
C<folderdir>).

 OPTION               DEFAULT
 folder               <obligatory>
 message              undef
 messages             undef

=over 4

=item B<folder> =E<gt> FOLDERNAME X<appendMessages(folder)>

The name of the folder to which the messages are to be appended.  The folder
implementation will avoid opening the folder when possible, because this is
resource consuming.

=item B<message> =E<gt> MESSAGE X<appendMessages(message)>

=item B<messages> =E<gt> ARRAY-OF-MESSAGES X<appendMessages(messages)>

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

=back

Examples:

 my $message = Mail::Message->new(...);
 Mail::Box::Mbox->appendMessages
  ( folder    => '=xyz'
  , message   => $message
  , folderdir => $ENV{FOLDERS}
  );

better:

 my Mail::Box::Manager $mgr;
 $mgr->appendMessages($message, folder => '=xyz');

=item B<coerce> MESSAGE X<coerce>

Coerce the MESSAGE to be of the correct type to be placed in the
folder.  You are not may specify Mail::Internet and MIME::Entity
here: they will be translated into Mail::Message messages first.

=item B<determineBodyType> MESSAGE, HEAD X<determineBodyType>

Determine which kind of body will be created for this message when
reading the folder initially.

=item B<lineSeparator> [STRING|'CR'|'LF'|'CRLF'] X<lineSeparator>

Returns the character or characters used to separate lines in the folder
file, optionally after setting it to STRING, or one of the constants.
The first line of the folder sets the default.

UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF.  Each
separator will be represented by a "\n" within your program.  However,
when processing platform foreign folders, complications appear.  Think about
the C<Size> field in the header.

When the separator is changed, the whole folder me be rewritten.  Although,
that may not be required.

=item B<locker>  X<locker>

Returns the locking object.

=item B<read> OPTIONS X<read>

Read messages from the folder into memory.  The OPTIONS are folder
specific.  Do not call C<read> yourself: it will be called for you
when you open the folder via the manager or instantiate a folder
object directly.

NOTE: if you are copying messages from one folder to another, use
addMessages() instead of C<read>.

Examples:

 my $mgr = Mail::Box::Manager->new;
 my $folder = $mgr->open('InBox');             # implies read
 my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same

=item B<readMessages> OPTIONS X<readMessages>

Called by read() to actually read the messages from one specific
folder type.  The read() organizes the general activities.

The OPTIONS are C<trusted>, C<head_wrap>, C<head_type>, C<field_type>,
C<message_type>, C<body_delayed_type>, and C<head_delayed_type> as
defined by the folder at hand.  The defaults are the constructor
defaults (see new()).

=item B<storeMessage> MESSAGE X<storeMessage>

Store the message in the folder without the checks as performed by
addMessage().

=item B<updateMessages> OPTIONS X<updateMessages>

Called by update() to read messages which arrived in the folder
after it was opened.  Sometimes, external applications dump messages
in a folder without locking (or using a different lock than your
application does).

Although this is quite a dangerous, it only fails when a folder is
updated (reordered or message removed) at exactly the same time as
new messages arrive.  These collisions are sparse.

The options are the same as for readMessages().

=item B<write> OPTIONS X<write>

Write the data to disk.  The folder is returned if successful. To write to a
different file, you must first create a new folder, then move the messages,
and then write the folder.

WARNING: When moving messages from one folder to another, be sure to write the
destination folder before writing and closing the source folder.  Otherwise
you may lose data if the system crashes or if there are software problems.

 OPTION               DEFAULT
 force                <false>
 head_wrap            72
 keep_deleted         <false>
 save_deleted         <false>

=over 4

=item B<force> =E<gt> BOOLEAN X<write(force)>

Override write-protection by the C<access> option while opening the folder
(whenever possible, it may still be blocked by the operating system).

=item B<head_wrap> =E<gt> INTEGER X<write(head_wrap)>

=item B<keep_deleted> =E<gt> BOOLEAN X<write(keep_deleted)>

Do not remove messages which were flagged to be deleted from the folder
from memory, but do remove them from disk.

=item B<save_deleted> =E<gt> BOOLEAN X<write(save_deleted)>

Do also write messages which where flagged to be deleted to their folder.  The
flag is conserved (when possible), which means that the next write may
remove them for real.

=back

=item B<writeMessages>  X<writeMessages>

Called by write() to actually write the messages from one specific
folder type.  The C<write> organizes the general activities.

=back

=head2 Logging and Tracing

=over 4

=item B<errors> 

See Mail::Reporter::errors()

=item B<log> [LEVEL [,STRINGS]]

See Mail::Reporter::log()

=item B<report> [LEVEL]

See Mail::Reporter::report()

=item B<reportAll> [LEVEL]

See Mail::Reporter::reportAll()

=item B<trace> [LEVEL]

See Mail::Reporter::trace()

=item B<warnings> 

See Mail::Reporter::warnings()

=back

=head2 Other Methods

=over 4

=item B<AUTOLOAD> 

See Mail::Reporter::AUTOLOAD()

=item B<inGlobalDestruction> 

See Mail::Reporter::inGlobalDestruction()

=item B<logPriority> LEVEL

See Mail::Reporter::logPriority()

=item B<logSettings> 

See Mail::Reporter::logSettings()

=item B<notImplemented> 

See Mail::Reporter::notImplemented()

=item B<timespan2seconds> TIME X<timespan2seconds>

TIME is a string, which starts with a float, and then one of the
words 'hour', 'hours', 'day', 'days', 'week', or 'weeks'.  For instance:
'1 hour' or '4 weeks'.

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>) with the help of many.

=head1 VERSION

This code is beta, version 2.019.

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