Box::Mbox(3)

NAME
Mail::Box::Mbox - handle folders in Mbox format

CLASS HIERARCHY
 Mail::Box::Mbox
 is a Mail::Box
 is a Mail::Reporter

SYNOPSIS
 use Mail::Box::Mbox;
 my $folder = Mail::Box::Mbox->new(folder => $ENV{MAIL}, ...);

DESCRIPTION
This documentation describes how Mbox mailboxes work, and also describes what you can do with the Mbox folder object "Mail::Box::Mbox". Please read "Mail::Box-Overview" and "Mail::Box" first.

The internal organization and details are found at the bottom of this manual-page. The working of Mbox-messages are described in Mail::Box::Mbox::Message.

METHOD INDEX
Methods prefixed with an abbreviation are described in Mail::Box (MB), Mail::Reporter (MR).

The general methods for "Mail::Box::Mbox" objects:

   MB addMessage  MESSAGE               MB message INDEX [,MESSAGE]
   MB addMessages MESSAGE [, MESS...    MB messageId MESSAGE-ID [,MESS...
   MB close OPTIONS                     MB messageIds
   MB copyTo FOLDER, OPTIONS            MB messages ['ALL',RANGE,'ACTI...
      create FOLDERNAME, ARGS           MB modified [BOOLEAN]
   MB current [NUMBER|MESSAGE|MES...    MB name
   MB delete                               new OPTIONS
   MR errors                            MB openSubFolder NAME [,OPTIONS]
      filename                          MR report [LEVEL]
   MB find MESSAGE-ID                   MR reportAll [LEVEL]
      listSubFolders [OPTIONS]          MR trace [LEVEL]
   MB locker                            MR warnings
   MR log [LEVEL [,STRINGS]]            MB writable

The extra methods for extension writers:

   MR AUTOLOAD                          MB organization
   MB DESTROY                              parser
   MB appendMessages OPTIONS            MB read OPTIONS
   MB clone OPTIONS                     MB readMessages OPTIONS
   MB coerce MESSAGE                    MB scanForMessages MESSAGE, ME...
   MB determineBodyType MESSAGE, ...    MB sort PREPARE, COMPARE, LIST
      folderToFilename FOLDERNAME...    MB storeMessage MESSAGE
   MB folderdir [DIR]                   MB timespan2seconds TIME
      foundIn [FOLDERNAME] [,OPTI...    MB toBeThreaded MESSAGES
   MR inGlobalDestruction               MB toBeUnthreaded MESSAGES
   MB lineSeparator [STRING|'CR'|...    MB update OPTIONS
   MR logPriority LEVEL                 MB updateMessages OPTIONS
   MR logSettings                          write OPTIONS
   MR notImplemented                    MB writeMessages
   MB openRelatedFolder OPTIONS

METHODS

new OPTIONS
    Create a new folder. Many options are taken from object-classes to which "Mail::Box::Mbox" is an extension. Read below for a detailed description of Mbox specific options.

     OPTION              DESCRIBED IN       DEFAULT
     access              Mail::Box          'r'
     create              Mail::Box          0
     folder              Mail::Box          $ENV{MAIL}
     folderdir           Mail::Box          $ENV{HOME}.'/Mail'
     head_wrap           Mail::Box          72
     extract             Mail::Box          10kb
     keep_dups           Mail::Box          0
     lock_file           Mail::Box          foldername.lock-extension
     lock_extension      Mail::Box::Mbox    '.lock'
     lock_timeout        Mail::Box          1 hour
     lock_wait           Mail::Box          10 seconds
     log                 Mail::Reporter     'WARNINGS'
     write_policy        Mail::Box::Mbox    undef
     remove_when_empty   Mail::Box          1
     save_on_exit        Mail::Box          1
     subfolder_extension Mail::Box::Mbox    '.d'
     trace               Mail::Reporter     'WARNINGS'
     trusted             Mail::Box          <depends on folder location>

    Only useful to write extension to "Mail::Box::Mbox". Common users of folders you will not specify these:

     OPTION              DEFINED BY         DEFAULT
     body_type           Mail::Box::Mbox    <see below>
     body_delayed_type   Mail::Box          'Mail::Message::Body::Delayed'
     coerce_options      Mail::Box          []
     field_type          Mail::Box          undef
     head_type           Mail::Box          'Mail::Message::Head::Complete'
     head_delayed_type   Mail::Box          'Mail::Message::Head::Delayed'
     locker              Mail::Box          undef
     lock_type           Mail::Box          'DOTLOCK'
     multipart_type      Mail::Box          'Mail::Message::Body::Multipart'
     manager             Mail::Box          undef
     message_type        Mail::Box          'Mail::Box::Mbox::Message'

    Mbox specific options:

    * lock_extension => FILENAME|STRING
        When the dotlock locking mechanism is used, the lock is created by the creation of a file. For "Mail::Box::Mbox" type of folders, this file is by default named the same as the folder-file itself, followed by ".lock".

        You may specify an absolute filename, a relative (to the folder's directory) filename, or an extension (preceeded by a dot). So valid examples are:

            .lock                  # append to filename
            my_own_lockfile.test   # full filename, same dir
            /etc/passwd            # somewhere else

    * subfolder_extension => STRING
        Mail folders which store their messages in files usually do not support sub-folders, as do mail folders which store messages in a directory.

        However, this module can simulate sub-directories if the user wants it to. When a subfolder of folder "xyz" is created, we create a directory which is called "xyz.d" to contain them. This extension ".d" can be changed using this option.

    * write_policy => 'REPLACE' || 'INPLACE'
        Sets the default write policy. See the "policy" option to the "write()" method.

    The "body_type" option for Mbox folders defaults to

       sub determine_body_type($$)
       {   my $head = shift;
           my $size = shift || 0;
           'Mail::Message::Body::' . ($size > 10000 ? 'File' : 'Lines');
       }

    which will cause messages larger than 10kB to be stored in files, and smaller files in memory.

filename
    Returns the filename for this folder.

    Example:

        print $folder->filename;

create FOLDERNAME, ARGS
     OPTION              DEFINED BY         DEFAULT
     folderdir           Mail::Box          <from object>
     subfolder_extension Mail::Box::Mbox    <from object>

    Mbox specific options:

    * subfolder_extension => STRING
listSubFolders [OPTIONS]
     OPTION              DEFINED BY         DEFAULT
     folder              Mail::Box          <obligatory>
     folderdir           Mail::Box          <from object>
     check               Mail::Box          <false>
     skip_empty          Mail::Box          <false>
     subfolder_extension Mail::Box::Mbox    <from object>

    Mbox specific options:

    * subfolder_extension => STRING

METHODS for extension writers
parser
    Create a parser for this mailbox. The parser stays alive as long as the folder is open.

write OPTIONS
     OPTION            DEFINED BY         DEFAULT
     force             Mail::Box          <true>
     head_wrap         Mail::Box          72
     keep_deleted      Mail::Box          <false>
     save_deleted      Mail::Box          <false>
     policy            Mail::Box::Mbox    'REPLACE'|'INPLACE'

    policy => 'REPLACE'|'INPLACE'|undef
        In what way will the mail folder be updated. If not specified during the write, the value of the "write_policy" at folder creation is taken.

        Valid values:

        * "REPLACE"
            First a new folder is written in the same directory as the folder which has to be updated, and then a call to move will throw away the old immediately replacing it by the new. The name of the folder's temporary file is produced in "tmpNewFolder".

            Writing in "REPLACE" module is slightly optimized: messages which are not modified are copied from file to file, byte by byte. This is much faster than printing the data which is will be done for modified messages.

        * "INPLACE"
            The original folder file will be opened read/write. All message which where not changed will be left untouched, until the first deleted or modified message is detected. All further messages are printed again.

        * "undef"
            As default, or when "undef" is explicitly specified, first "REPLACE" mode is tried. Only when that fails, an "INPLACE" update is performed.

        "INPLACE" will be much faster than "REPLACE" when applied on large folders, however requires the "truncate" function to be implemented on your operating system. It is also dangerous: when the program is interrupted during the update process, the folder is corrupted. Data may be lost.

        However, in some cases it is not possible to write the folder with "REPLACE". For instance, the usual incoming mail folder on UNIX is stored in a directory where a user can not write. Of course, the "root" and "mail" users can, but if you want to use this Perl module with permission of a normal user, you can only get it to work in "INPLACE" mode. Be warned that in this case folder locking via a lockfile is not possible as well.

foundIn [FOLDERNAME] [,OPTIONS]
     OPTION              DEFINED BY         DEFAULT
     folder              Mail::Box::Mbox    undef
     folderdir           Mail::Box          <from object>
     subfolder_extension Mail::Box::Mbox    <from object>

    If no FOLDERNAME is specified, then the "folder" option is taken.

    Mbox specific options:

    * folder => FOLDERNAME
    * subfolder_extension => STRING
folderToFilename FOLDERNAME, FOLDERDIR, EXTENSION
    (Class method) Translate a folder name into a filename, using the FOLDERDIR value to replace a leading "=".

IMPLEMENTATION
Mbox folders store many messages in one file (let's call this a `file-based' folder, in comparison to a `directory-based' folder types like MH and Maildir).

In file-based folders, each message begins with a line which starts with the string "From ". Lines inside a message which accidentally start with "From" are, in the file, preceeded by `>'. This character is stripped when the message is read.

In this module, the name of a folder may be an absolute or relative path. You can also preceed the foldername by "=", which means that it is relative to the folderdir option specified for the "new" method. Message labels (flags which tell about user-actions on the message) are stored in "Status" and "X-Status" fields. Each time a label is changed (using the "label()" method) these lines are updated immediately. File-based folders do not really have a sub-folder concept as directory-based folders do, but this module tries to simulate them. In this implementation a directory like

   Mail/subject1/

is taken as an empty folder "Mail/subject1", with the folders in that directory as sub-folders for it. You may also use

   Mail/subject1
   Mail/subject1.d/

where "Mail/subject1" is the folder, and the folders in the "Mail/subject1.d" directory are used as sub-folders. If your situation is similar to the first example and you want to put messages in that empty folder, the directory is automatically (and transparently) renamed, so that the second situation is reached.

Because of these simulated sub-folders, the folder manager does not need to distinguish between file- and directory-based folders in this respect.

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@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 beta, version 2.018.

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.