NAME

Mail::Box::Maildir - handle Maildir folders

CLASS INHERITANCE

Mail::Box::Maildir is a Mail::Box::Dir is a Mail::Box is a Mail::Reporter

SYNOPSIS

 use Mail::Box::Maildir;
 my $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;

DESCRIPTION

This documentation describes how Maildir mailboxes work, and what you can do with the Maildir folder object Mail::Box::Maildir. Please read Mail::Box-Overview and Mail::Box::Dir first.

Maildir is not supported for Windows, because it create filenames which are not accepted by the Windows system. The internal organization and details are found at the bottom of this manual-page.

METHODS

Initiation

new OPTIONS

 OPTION               DEFAULT
 access               'r'
 body_delayed_type    'Mail::Message::Body::Delayed'
 body_type            'Mail::Message::Body::Lines'
 coerce_options       []
 create               <false>
 extract              10240
 field_type           undef
 folder               $ENV{MAIL}
 folderdir            $ENV{HOME}/.maildir
 head_delayed_type    'Mail::Message::Head::Delayed'
 head_type            'Mail::Message::Head::Complete'
 keep_dups            <false>
 lock_file            <not used>
 lock_timeout         <not used>
 lock_type            'NONE' (constant)
 lock_wait            <not used>
 locker               undef
 log                  'WARNINGS'
 manager              undef
 message_type         'Mail::Box::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 remove_when_empty    <true>
 save_on_exit         <true>
 trace                'WARNINGS'
 trusted              <depends on folder location>

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::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_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)
trace => LEVEL: See Mail::Reporter::new(trace)
trusted => BOOLEAN: See Mail::Box::new(trusted)

Opening folders

clone OPTIONS: See Mail::Box::clone()
create FOLDERNAME, OPTIONS: See Mail::Box::create()
folderdir [DIRECTORY]: See Mail::Box::folderdir()
foundIn [FOLDERNAME], OPTIONS: See Mail::Box::foundIn()

On open folders

addMessage MESSAGE: See Mail::Box::addMessage()
addMessages MESSAGE [, MESSAGE, ...]: See Mail::Box::addMessages()
copyTo FOLDER, OPTIONS: See Mail::Box::copyTo()
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: See Mail::Box::listSubFolders()
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()
createDirs FOLDERDIR: (Instance or class method) The FOLDERDIR contains the absolute path of the location where the messages are kept. Maildir folders contain a tmp, new, and cur sub-directory within that folder directory as well. This method will ensure that all directories exist. Returns false on failure.
determineBodyType MESSAGE, HEAD: See Mail::Box::determineBodyType()
directory: See Mail::Box::Dir::directory()
folderIsEmpty FOLDERDIR: (Instance or class method) Checks whether the folder whose directory is specified as absolute FOLDERDIR is empty or not. A folder is empty when the tmp, new, and cur subdirectories are empty and some files which are left there by application programs. The maildir spec explicitly states: .qmail, bulletintime, bulletinlock and seriallock. If any other files are found, the directory is considered not-empty.
folderToDirectory FOLDERNAME, FOLDERDIR: See Mail::Box::Dir::folderToDirectory()
lineSeparator [STRING|'CR'|'LF'|'CRLF']: See Mail::Box::lineSeparator()
locker: See Mail::Box::locker()
read OPTIONS: See Mail::Box::read()
readMessageFilenames DIRECTORY: See Mail::Box::Dir::readMessageFilenames()
readMessages OPTIONS: See Mail::Box::readMessages()
storeMessage MESSAGE: See Mail::Box::storeMessage()
updateMessages OPTIONS: See Mail::Box::updateMessages()
write OPTIONS: See Mail::Box::write()
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

The explanation is complicated, but for normal use you should bother yourself with all details.

How Maildir-folders work

Maildir-type folders use a directory to store the messages of one folder. Each message is stored in a separate file. This seems useful, because changes in a folder change only a few of these small files, in contrast with file-based folders where changes in a folder cause rewrites of huge folder-files.

However, Maildir based folders perform very bad if you need header information of all messages. For instance, if you want to have full knowledge about all message-threads (see Mail::Box::Thread::Manager) in the folder, it requires to read all header lines in all message files. And usually, reading your messages as threads is desired. Maildir maintains a tiny amount of info visible in the filename, which may make it perform just a little bit faster than MH.

The following information was found at http://cr.yp.to/proto/maildir.html. Each message is written in a separate file. The filename is constructed from the time-of-arrival, a unique component, hostname, a syntax marker, and flags. For example 1014220791.meteor.42:2,DF. The filename must match:

 my ($time, $unique, $hostname, $info)
    = $filename =~ m!^(\d+)\.(.*)\.(\w+)(\:.*)?$!;
 my ($semantics, $flags)
    = $info =~ m!([12])\,([RSTDF]+)$!;
 my @flags = split //, $flags;

The @flags are sorted alphabetically, with the following meanings:

 D = draft, to be sent later
 F = flagged for user-defined purpose
 R = has been replied
 S = seen / (partially) read by the user
 T = trashed, flagged to be deleted later

Labels

The filename contains flags, and those flags are translated into labels when the folder is opened. Labels can be changed by the application using the labels method.

Changes will directly reflect in a filename change. The Status and X-Status lines in the header, which are used by Mbox kind of folders, are ignored except when a new message is received in the new directory. In case a message has to be written to file for some reason, the status header lines are updated as well.

AUTHOR

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

VERSION

This code is beta, version 2.026.

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)