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
-
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
-
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)
- 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 calledxyz.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>
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()
- 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::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.034.
Copyright (c) 2001-2002 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.