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               MR log [LEVEL [,STRINGS]]
MB addMessages MESSAGE [, MESS...    MB message INDEX [,MESSAGE]
MB allMessageIds                     MB messageId MESSAGE-ID [,MESS...
MB close OPTIONS                     MB messages
   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

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

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 some data from the folder still has to be parsed, and may be revived when the information is to be written to a new file (or to update the folder).

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

How Mbox folders work

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.

Labels

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.

Simulation of sub-folders

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.

AUTHOR

VERSION

This code is beta, version 2.015.

To install Mail::Box, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Box

CPAN shell

perl -MCPAN -e shell
install Mail::Box

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

CLASS HIERARCHY

SYNOPSIS

DESCRIPTION

METHOD INDEX

METHODS

METHODS for extension writers

IMPLEMENTATION

How Mbox folders work

Labels

Simulation of sub-folders

SEE ALSO

AUTHOR

VERSION

Module Install Instructions