/ 
Mail-Box-1.317
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Mbox

NAME

Mail::Box::Mbox - Handle folders with many messages per file.

SYNOPSIS

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

DESCRIPTION

This manual-page describes Mail::Box::Mbox and Mail::Box::Mbox::* packages. Read Mail::Box::Manager and Mail::Box first.

How Mbox-folders work

Mbox folders store many messages in one file (let's call this a `file-based' folder, in contrary to a `directory-based' foldertype like MH).

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

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 as specified at new.

Simulation of sub-folders

File-based folders do not really have a sub-folder idea, as directory-based folders have, 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 as in the first example and you want to put messages in that empty folder, the directory is automatically renamed, such that the second situation is reached.

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

METHODS

new ARGS

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

access            Mail::Box          'r'
create            Mail::Box          0
folder            Mail::Box          $ENV{MAIL}
folderdir         Mail::Box          $ENV{HOME}.'/Mail'
lazy_extract      Mail::Box          10kb
lockfile          Mail::Box::Locker  foldername.lock-extention
lock_extention    Mail::Box::Mbox    '.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::Mbox::Message'
notreadhead_type  Mail::Box          'Mail::Box::Message::NotReadHead'
notread_type      Mail::Box          'Mail::Box::Mbox::NotParsed'
organization      Mail::Box          'FILE'
realhead_type     Mail::Box          'MIME::Head'
remove_when_empty Mail::Box          1
save_on_exit      Mail::Box          1
subfolder_extention Mail::Box::Mbox  '.d'
take_headers      Mail::Box          <quite some>
<none>            Mail::Box::Tie

Mbox specific options:

  • lock_extention => 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 as the folder-file itself, followed by .lock.

    You may specify an absolute filename, a relative (to the folder's directory) name, or an extention (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_extention => STRING

    Mail folders which store their messages in files do usually not support sub-folders, as known by mail folders which store messages in a directory.

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

fileOpen
fileIsOpen
fileClose

Open/close the file which keeps the folder. If the folder is already open, it will not be opened again. This method will maintain exclusive locking. Of course, fileIsOpen only checks if the file is opened or not.

Example:

my $file = $folder->fileOpen or die;
$folder->fileClose;
readMessages

Read all messages from the folder. This method is called at instantiation of the folder, so do not call it yourself unless you have a very good reason.

write

Write all messages to the folder-file. Returns the folder when this was successful. If you want to write to a different file, you first create a new folder, then move the messages, and then write that file. As options you may specify (see Mail::Box for explanation)

  • keep_deleted => BOOL

  • save_deleted => BOOL

  • remove_when_empty => BOOL

appendMessages OPTIONS

(Class method) Append one or more messages to a folder. The folder will not be read, but messages are just appended to the folder-file. This also means that double messages can exist in a folder.

If the folder does not exist, undef (or FALSE) is returned.

  • folder => FOLDERNAME

  • message => MESSAGE

  • messages => ARRAY-OF-MESSAGES

Example:

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

Returns the filename related to this folder.

Example:

print $folder->filename;
filehandle

Returns the filehandle related to this folder.

Example:

print $folder->filehandle;
folderToFilename FOLDERNAME, FOLDERDIR, EXTENTION

(class method) Translate a foldername into a filename, with use of the FOLDERDIR to replace a leading =.

folder management methods

Read the Mail::Box manual for more details and more options on each method.

foundIn FOLDERNAME [,OPTIONS]

Autodetect if there is a Mail::Box::Mbox folder specified here. The FOLDERNAME specifies the name of the folder, as is specified by the application. ARGS is a reference to a hash with extra information on the request. For this class, we use (if defined):

  • folderdir => DIRECTORY

  • subfolder_extention => STRING

Example:

Mail::Box::Mbox->foundIn
   ( '=markov'
   , folderdir => "$ENV{HOME}/Mail"
   );
create FOLDERNAME [, OPTIONS]

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

  • folderdir => DIRECTORY

listFolders [OPTIONS]

(Class OR Instance method) List the folders in a certain directory. This method can be called on the class, in which case you specify the base folder where the sub-folders must be retreived from as name. When used on an instance, the sub-folders of the instance are returned.

Folders will not start with a dot. When a directory without the sub-folder extention is found, then an empty folder is presumed.

  • folder => FOLDERNAME

  • folderdir => DIRECTORY

  • check => BOOL

  • skip_empty => BOOL

  • subfolder_extention => STRING

openSubFolder NAME [,OPTIONS]

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

Example:

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

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 beta, version 1.317