The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mail-Box-2.038
River stage one • 8 direct dependents • 8 total dependents
16 ++
/ Mail::Box::Mbox

NAME

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

CLASS INHERITANCE

 Mail::Box::Mbox
   is a Mail::Box::File
   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

(Class method)

 OPTION               DEFAULT
 access               'r'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            <see description>
 coerce_options       []
 create               <false>
 extract              10240
 field_type           undef
 fix_headers          <false>
 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

See Mail::Box::File::new(body_type)

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)

fix_headers => BOOLEAN

See Mail::Box::new(fix_headers)

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

See Mail::Box::File::new(lock_extension)

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

Mbox folders do not support sub-folders. 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

See Mail::Box::File::new(write_policy)

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

If a directory is found on the location of the folder to be created, this STRING is used to extend that directory name with. This will cause the directory to be seen as sub-folder for the created folder. This argument is passed to dirToSubfolder().

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

See Mail::Box::File::filename()

isModified

See Mail::Box::isModified()

modified [BOOLEAN]

See Mail::Box::modified()

name

See Mail::Box::name()

organization

See Mail::Box::organization()

type

See Mail::Box::type()

update OPTIONS

See Mail::Box::update()

url

See Mail::Box::url()

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

When the method is called on an open folder, the extension defined by it is used to detect sub-folders by default. Otherwise, '.d' is taken.

nameOfSubfolder NAME

See Mail::Box::nameOfSubfolder()

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::File::appendMessages()

coerce MESSAGE

See Mail::Box::coerce()

determineBodyType MESSAGE, HEAD

See Mail::Box::determineBodyType()

dirToSubfolder DIRECTORY, EXTENSION

The DIRECTORY is renamed by appending the EXTENSION, which defaults to ".d", to make place for a folder file on that specific location. false is returned if this failed.

folderToFilename FOLDERNAME, FOLDERDIR, [EXTENSION]

(Class or Instance method) Translate a folder name into a filename, using the FOLDERDIR value to replace a leading =. If no EXTENSION is specified and this method is called as instance method, new(subfolder_extension) is used. Otherwise, the extension default to '.d'.

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

See Mail::Box::lineSeparator()

locker

See Mail::Box::locker()

parser

See Mail::Box::File::parser()

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

See Mail::Box::File::write()

writeMessages OPTIONS

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. 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 respect must be noted that the format of the MBOX files is not strictly defined. The exact content of the separator lines differ between Mail User Agents (MUA's). Besides, some MUAs (like mutt) forget to encode the From lines within message bodies, breaking other parsers....

Simulation of sub-folders

MBOX folders do not have a sub-folder concept as directory based folders do, but this MBOX 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.

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

Written by Mark Overmeer (mark@overmeer.net) with the help of many. See the ChangeLog for details.

VERSION

This code is beta, version 2.038.

Copyright (c) 2001-2003 by the authors. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.