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

NAME

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

CLASS INHERITANCE

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.

METHODS

Initiation

new OPTIONS 
OPTION               DEFAULT
access               'r'
body_delayed_type    'Mail::Message::Body::Delayed'
body_type            <see description>
coerce_options       []
create               <false>
extract              10240
field_type           undef
folder               $ENV{MAIL}
folderdir            $ENV{HOME}.'/Mail'
head_delayed_type    'Mail::Message::Head::Delayed'
head_type            'Mail::Message::Head::Complete'
keep_dups            <false>
lock_extension       '.lock'
lock_file            foldername.lock-extension
lock_timeout         1 hour
lock_type            'Mail::Box::Locker::DotLock'
lock_wait            10 seconds
locker               undef
log                  'WARNINGS'
manager              undef
message_type         'Mail::Box::Mbox::Message'
multipart_type       'Mail::Message::Body::Multipart'
remove_when_empty    <true>
save_on_exit         <true>
subfolder_extension  '.d'
trace                'WARNINGS'
trusted              <depends on folder location>
write_policy         undef
access => MODE

See Mail::Box::new(access)

body_delayed_type => CLASS

See Mail::Box::new(body_delayed_type)

body_type => CLASS|CODE

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.

coerce_options => ARRAY

See Mail::Box::new(coerce_options)

create => BOOLEAN

See Mail::Box::new(create)

extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'

See Mail::Box::new(extract)

field_type => CLASS

See Mail::Box::new(field_type)

folder => FOLDERNAME

See Mail::Box::new(folder)

folderdir => DIRECTORY

See Mail::Box::new(folderdir)

head_delayed_type => CLASS

See Mail::Box::new(head_delayed_type)

head_type => CLASS

See Mail::Box::new(head_type)

keep_dups => BOOLEAN

See Mail::Box::new(keep_dups)

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 (preceded by a dot). So valid examples are:

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

See Mail::Box::new(lock_file)

lock_timeout => SECONDS

See Mail::Box::new(lock_timeout)

lock_type => CLASS|STRING

See Mail::Box::new(lock_type)

lock_wait => SECONDS

See Mail::Box::new(lock_wait)

locker => OBJECT

See Mail::Box::new(locker)

log => LEVEL

See Mail::Reporter::new(log)

manager => MANAGER

See Mail::Box::new(manager)

message_type => CLASS

See Mail::Box::new(message_type)

multipart_type => CLASS

See Mail::Box::new(multipart_type)

remove_when_empty => BOOLEAN

See Mail::Box::new(remove_when_empty)

save_on_exit => BOOLEAN

See Mail::Box::new(save_on_exit)

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.

trace => LEVEL

See Mail::Reporter::new(trace)

trusted => BOOLEAN

See Mail::Box::new(trusted)

write_policy => 'REPLACE'|'INPLACE'|undef

Sets the default write policy. See the policy option to write().

Opening folders

clone OPTIONS

See Mail::Box::clone()

create FOLDERNAME, OPTIONS 
OPTION               DEFAULT
folderdir            undef
subfolder_extension  undef
folderdir => DIRECTORY

See Mail::Box::create(folderdir)

subfolder_extension => STRING
folderdir [DIRECTORY]

See Mail::Box::folderdir()

foundIn [FOLDERNAME] [,OPTIONS]

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

OPTION               DEFAULT
folder               undef
folderdir            undef
subfolder_extension  <from object>
folder => FOLDERNAME
folderdir => DIRECTORY

See Mail::Box::foundIn(folderdir)

subfolder_extension => STRING

On open folders

addMessage MESSAGE

See Mail::Box::addMessage()

addMessages MESSAGE [, MESSAGE, ...]

See Mail::Box::addMessages()

copyTo FOLDER, OPTIONS

See Mail::Box::copyTo()

filename

Returns the filename for this folder.

Examples:

print $folder->filename;
modified [BOOLEAN]

See Mail::Box::modified()

name

See Mail::Box::name()

organization

See Mail::Box::organization()

update OPTIONS

See Mail::Box::update()

writable

See Mail::Box::writable()

Closing the folder

DESTROY

See Mail::Box::DESTROY()

close OPTIONS

See Mail::Box::close()

delete

See Mail::Box::delete()

The messages

current [NUMBER|MESSAGE|MESSAGE-ID]

See Mail::Box::current()

find MESSAGE-ID

See Mail::Box::find()

message INDEX [,MESSAGE]

See Mail::Box::message()

messageId MESSAGE-ID [,MESSAGE]

See Mail::Box::messageId()

messageIds

See Mail::Box::messageIds()

messages ['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER]

See Mail::Box::messages()

scanForMessages MESSAGE, MESSAGE-IDS, TIMESTAMP, WINDOW

See Mail::Box::scanForMessages()

Sub-folders

listSubFolders OPTIONS 
OPTION               DEFAULT
check                <false>
folder               <obligatory>
folderdir            <from folder>
skip_empty           <false>
subfolder_extension  <from object>
check => BOOLEAN

See Mail::Box::listSubFolders(check)

folder => FOLDERNAME

See Mail::Box::listSubFolders(folder)

folderdir => DIRECTORY

See Mail::Box::listSubFolders(folderdir)

skip_empty => BOOL

See Mail::Box::listSubFolders(skip_empty)

subfolder_extension => STRING
openRelatedFolder OPTIONS

See Mail::Box::openRelatedFolder()

openSubFolder NAME, OPTIONS

See Mail::Box::openSubFolder()

Message threads [internals]

toBeThreaded MESSAGES

See Mail::Box::toBeThreaded()

toBeUnthreaded MESSAGES

See Mail::Box::toBeUnthreaded()

Reading and Writing [internals]

appendMessages OPTIONS

See Mail::Box::appendMessages()

coerce MESSAGE

See Mail::Box::coerce()

determineBodyType MESSAGE, HEAD

See Mail::Box::determineBodyType()

folderToFilename FOLDERNAME, FOLDERDIR, EXTENSION

(Class method) Translate a folder name into a filename, using the FOLDERDIR value to replace a leading =.

lineSeparator [STRING|'CR'|'LF'|'CRLF']

See Mail::Box::lineSeparator()

locker

See Mail::Box::locker()

parser

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

parserClose

Destroy the parser explicilty. This will free various data-structures, and close open file-handles.

read OPTIONS

See Mail::Box::read()

readMessages OPTIONS

See Mail::Box::readMessages()

storeMessage MESSAGE

See Mail::Box::storeMessage()

updateMessages OPTIONS

See Mail::Box::updateMessages()

write OPTIONS 
OPTION               DEFAULT
force                <false>
keep_deleted         <false>
policy               undef
save_deleted         <false>
force => BOOLEAN

See Mail::Box::write(force)

keep_deleted => BOOLEAN

See Mail::Box::write(keep_deleted)

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.

save_deleted => BOOLEAN

See Mail::Box::write(save_deleted)

writeMessages

See Mail::Box::writeMessages()

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

timespan2seconds TIME

See Mail::Box::timespan2seconds()

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, preceded 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 precede the foldername by =, which means that it is relative to new(folderdir).

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.

SEE ALSO

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

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.023.

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.