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.

Handle file-based folders, where many messages are stored in one file.

A File-based folder is a plain text-file where the start of a message is detected by scanning for the word From . Lines which do accedentally start with a From are in the file preceeded by `>', however, this is stripped when reading.

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.

PUBLIC INTERFACE

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'
dummy_type        Mail::Box::Threads 'Mail::Box::Message::Dummy'
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::Message::NotParsed'
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          <specify everything you need>
<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 whether 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.

appendMessages LIST-OF-OPTIONS

(Class method) Append one or more messages to this folder. See the manual-page of Mail::Box for explantion of the options. The folder will not be opened. Returns the list of written messages on success.

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;

folderToFilename FOLDERNAME ,FOLDERDIR

(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

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

listFolders [OPTIONS]

List the folders in a certain directory.

• folderdir => DIRECTORY

• check => BOOL

• skip_empty => BOOL

subFolders [OPTIONS]

Returns the subfolders to a folder. Although file-type folders do not have a natural form of sub-folders, we can simulate them. The subfolder_extention option of the constructor (new()) defines how sub-folders can be recognized.

• check => BOOL

• skip_empty => BOOL

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');

Mail::Box::Mbox::Message::Runtime

This object contains methods which are part of as well delay-loaded (not-parsed) as loaded messages, but not general for all folders.

PUBLIC INTERFACE

new ARGS

Messages in file-based folders use the following extra options for creation:

• from LINE

  The line which precedes each message in the file. Some people detest this line, but this is just how things were invented...

fromLine [LINE]

Many people detest file-style folders because they store messages all in one file, where a line starting with From leads the header. If we receive a message from a file-based folder, we store that line. If we write to such a file, but there is no such line stored, then we try to produce one.

When you pass a LINE, that this is stored.

print TO

Write one message to a file-handle. Unmodified messages are taken from the folder-file where they were stored in. Modified messages are written as in memory. Specify a file-handle to write TO (defaults to STDOUT).

Mail::Box::Mbox::Message

This object extends a Mail::Box::Message with extra tools and facts on what is special to messages in file-based folders, with respect to messages in other types of folders.

PUBLIC INTERFACE

coerce MESSAGE

(Class method) Coerce a message into a Mail::Box::Mbox::Message. When any message is offered to be stored in the mailbox, it first should have all fields which are specific for Mbox-folders (especially the special From line.

Example: my $mh = Mail::Box::MH::Message->new(...); my $Mbox = Mail::Box::Mbox::Message->coerce($mh);

Mail::Box::Mbox::Message::NotParsed

Not parsed messages stay in the file until the message is used. Because this folder structure uses many messages in the same file, the byte-locations are remembered.

PUBLIC INTERFACE

load

This method is called by the autoloader then the data of the message is required. If you specified REAL for the take_headers option for new(), you did have a MIME::Head in your hands, however this will be destroyed when the whole message is loaded.

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

cpanm Mail::Box

perl -MCPAN -e shell
install Mail::Box