NAME

$obj->addMessages(MESSAGE [, MESSAGE, ...])

Mail::Box::File->appendMessages(OPTIONS)

Appending messages to a file based folder which is not opened is a little risky. In practice, this is often done without locking the folder. So, an other application may write to the folder at the same time... :( Hopefully, all goes fast enough that the chance on collition is small.

All OPTIONS of Mail::Box::Mbox::new() can be supplied.

Option   --Defined in     --Default
folder     Mail::Box        <required>
lock_type                   NONE
message    Mail::Box        undef
messages   Mail::Box        undef
share      Mail::Box        <false>

. folder => FOLDERNAME

. lock_type => ...

See Mail::Box::new(lock_type) for possible values.

. message => MESSAGE

. messages => ARRAY-OF-MESSAGES

. share => BOOLEAN

$obj->close(OPTIONS)

$obj->copyTo(FOLDER, OPTIONS)

$obj->delete(OPTIONS)

$obj->filename

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

example:

print $folder->filename;

$obj->folderdir([DIRECTORY])

$obj->name

$obj->organization

$obj->size

$obj->type

$obj->update(OPTIONS)

$obj->url

Folder flags

$obj->access

$obj->isModified

$obj->modified([BOOLEAN])

$obj->writable

The messages

$obj->current([NUMBER|MESSAGE|MESSAGE-ID])

$obj->find(MESSAGE-ID)

$obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])

$obj->message(INDEX [,MESSAGE])

$obj->messageId(MESSAGE-ID [,MESSAGE])

$obj->messageIds

$obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])

$obj->nrMessages(OPTIONS)

$obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)

Sub-folders

$obj->listSubFolders(OPTIONS)

Mail::Box::File->listSubFolders(OPTIONS)

$obj->nameOfSubFolder(SUBNAME, [PARENTNAME])

Mail::Box::File->nameOfSubFolder(SUBNAME, [PARENTNAME])

$obj->openRelatedFolder(OPTIONS)

$obj->openSubFolder(SUBNAME, OPTIONS)

$obj->topFolderWithMessages

Mail::Box::File->topFolderWithMessages

Internals

$obj->coerce(MESSAGE, OPTIONS)

$obj->create(FOLDERNAME, OPTIONS)

Mail::Box::File->create(FOLDERNAME, OPTIONS)

Option   --Defined in--Default
folderdir  Mail::Box   undef

. folderdir => DIRECTORY

$obj->determineBodyType(MESSAGE, HEAD)

$obj->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])

Mail::Box::File->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])

Translate a folder name into a filename, using the FOLDERDIR value to replace a leading =. SUBEXT is only used for MBOX folders.

Mail::Box::File->foundIn([FOLDERNAME], OPTIONS)

$obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])

$obj->locker

$obj->messageCreateOptions([TYPE, CONFIG])

Returns a key-value list of options to be used each time a new message is read from a file. The list is preceeded by the TYPE of message which has to be created.

This data is used by readMessages() and updateMessages(). With TYPE and CONFIG, a new configuration is set.

$obj->moveAwaySubFolder(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.

$obj->parser

Create a parser for this mailbox. The parser stays alive as long as the folder is open.

$obj->read(OPTIONS)

$obj->readMessages(OPTIONS)

$obj->storeMessage(MESSAGE)

$obj->toBeThreaded(MESSAGES)

$obj->toBeUnthreaded(MESSAGES)

$obj->updateMessages(OPTIONS)

For file based folders, the file handle stays open until the folder is closed. Update is therefore rather simple: move to the end of the last known message, and continue reading...

$obj->write(OPTIONS)

Option      --Defined in     --Default
force         Mail::Box        <false>
policy                         undef
save_deleted  Mail::Box        <false>

. force => BOOLEAN

. policy => 'REPLACE'|'INPLACE'|undef

In what way will the mail folder be updated. If not specified during the write, the value of the new(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.

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 (at least available for recent versions of Linux, Solaris, Tru64, HPUX). 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

$obj->writeMessages(OPTIONS)

File based folders

File based folders maintain a folder (a set of messages) in one single file. The advantage is that your folder has only one single name, which speeds-up access to all messages at once.

The disadvantage over directory based folder (see Mail::Box::Dir) is that you have to construct some means to keep all message apart, for instance by adding a message separator, and this will cause problems. Where access to all messages at once is faster in file based folders, access to a single message is (much) slower, because the whole folder must be read.

File based folders

File based folders maintain a folder (a set of messages) in one single file. The advantage is that your folder has only one single name, which speeds-up access to all messages at once.

Other methods

$obj->timespan2seconds(TIME)

Mail::Box::File->timespan2seconds(TIME)

See "Other methods" in Mail::Box

Error handling

$obj->AUTOLOAD

$obj->addReport(OBJECT)

$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

Mail::Box::File->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])

$obj->errors

$obj->log([LEVEL [,STRINGS]])

Mail::Box::File->log([LEVEL [,STRINGS]])

$obj->logPriority(LEVEL)

Mail::Box::File->logPriority(LEVEL)

$obj->logSettings

$obj->notImplemented

$obj->report([LEVEL])

$obj->reportAll([LEVEL])

$obj->trace([LEVEL])

$obj->warnings