NAME

Mail::Box::File - handle file-based folders

CLASS INHERITANCE

Mail::Box::File is a Mail::Box is a Mail::Reporter

Mail::Box::File is extended by Mail::Box::Mbox

SYNOPSIS

DESCRIPTION

Mail::Box::File is the base-class for all file-based folders: folders which bundle multiple messages into one single file. Usually, these messages are separated by a special line which indicates the start of the next one.

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::File::Message'
 multipart_type       'Mail::Message::Body::Multipart'
 remove_when_empty    <true>
 save_on_exit         <true>
 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 File 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 with a hardlink to the folder file. For Mail::Box::File type of folders, this file is by default named as the folder-file itself followed by .lock. For example: the Mail/inbox folder file will have a hardlink made as Mail/inbox.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                  # appended to the folder's filename
 my_own_lockfile.test   # full filename, same dir
 /etc/passwd            # somewhere else

When the program runs with less priviledges (as normal user), often the default inbox folder can not be locked with the lockfile name which is produced by default.

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)

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

Sets the default write policy (see write(policy)). With undef, the best policy is autodetected.

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()

filename

Returns the filename for this folder, which may be an absolute or relative path to the file.

Examples:

 print $folder->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: See Mail::Box::listSubFolders()
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()

folderToFilename FOLDERNAME, FOLDERDIR, [SUBEXT]

(Class or instance method) Translate a folder name into a filename, using the FOLDERDIR value to replace a leading =. SUBEXT is only used for MBOX folders.

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.

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>
 policy               undef
 save_deleted         <false>

force => BOOLEAN

See Mail::Box::write(force)

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 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 file-based folders work

File-based 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).

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.035.

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)