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
- create FOLDERNAME, OPTIONS
-
(Class method)
OPTION DEFAULT folderdir undef
- 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::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 tosub 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)
- 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
-
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()
- 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;
- 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
-
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
-
(Class method)
OPTION DEFAULT folder <obligatory> message undef messages undef
- 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, firstREPLACE
mode is tried. Only when that fails, anINPLACE
update is performed.
INPLACE
will be much faster thanREPLACE
when applied on large folders, however requires thetruncate
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, theroot
andmail
users can, but if you want to use this Perl module with permission of a normal user, you can only get it to work inINPLACE
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).
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.039.
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.