NAME

Mail::Folder::Mbox - A Unix mbox interface for Mail::Folder.

WARNING: This code is in alpha release. Expect the interface to change.

SYNOPSIS

use Mail::Folder::Mbox;

DESCRIPTION

This module provides an interface to unix mbox folders.

The mbox folder format is the standard monolithic folder structure prevalent on Unix. A single folder is contained within a single file. Each message starts with a line matching /^From / and ends with a blank line.

The folder architecture does not provide any persistantly stored current message variable, so the current message in this folder interface defaults to 1 and is not retained between opens of a folder.

If the Timeout option is specified when the object is created, that value will be used to determine the timeout for attempting to aquire a folder lock. The default is 10 seconds.

If the DotLock option is specified when the object is created, that value will be used to determine whether or not to use '.lock' style folder locking. The default value is 1.

If the Flock option is specified when the object is created, that value will be used to determined whether or not to use flock style folder locking. By default, the option is not set.

If the NFSLock option is specified when the object is created, that value will be used to determine whether or not special measures are taken when doing DotLocking. These special measures consist of constructing the lock file in a special manner that is more immune to atomicity problems with NFS when creating a folder lock file. By default, the option is not set. This option necessitates the ability to use long filenames.

It is currently a fatal error to have both DotLock and Flock disabled.

**NOTE** flock locking is currently disabled until I can sift out the 'right way'. **NOTE**

METHODS

open($folder_name)

• Call the superclass open method.

• Check to see if it is a valid mbox folder.

• Mark it as readonly if the folder is not writable.

• Lock the folder.

• Split the folder into individual messages in a temporary working directory.

• Unlock the folder.

• Cache all the headers.

• Update the appropriate labels with information in the Status fields.

• Set current_message to 1.

close

Deletes the internal working copy of the folder and calls the superclass close method.

sync

• Call the superclass sync method.

• Lock the folder.

• Extract into the temporary working directory any new messages that have been appended to the folder since the last time the folder was either opened or synced.

• Create a new copy of the folder and populate it with the messages in the working copy that are not flagged for deletion and update the Status fields appropriately.

• Move the original folder to a temp location

• Move the new folder into place

• Delete the old original folder

• Unlock the folder

pack

Calls the superclass pack method.

Renames the message list to that there are no gaps in the numbering sequence.

It also tweaks the current_message accordingly.

get_message ($msg_number)

Calls the superclass get_message method.

Retrieves the given mail message file into a Mail::Internet object reference, sets the 'seen' label, and returns the reference.

If the 'Content-Length' option is not set, then get_message will unescape 'From ' lines in the body of the message.

get_message_file ($msg_number)

Calls the superclass get_message_file method.

Retrieves the given mail message file and returns the name of the file.

Returns undef on failure.

This method does NOT currently do any 'From ' unescaping.

get_header($msg_number)

If the particular header has never been retrieved then get_header loads (in a manner similar to get_message) the header of the given mail message into $self->{Messages}{$msg_number}{Header} and returns the object reference.

If the header for the given mail message has already been retrieved in a prior call to get_header, then the cached entry is returned.

It also calls the superclass get_header method.

append_message($mref)

Calls the superclass append_message method.

Creates a new mail message file, in the temporary working directory, with the contents of the mail message contained in $mref. It will synthesize a 'From ' line if one is not present in $mref.

If the 'Content-Length' option is not set, then get_message will escape 'From ' lines in the body of the message.

update_message($msg_number, $mref)

Calls the superclass update_message method.

Replaces the message pointed to by $msg_number with the contents of the Mail::Internet object reference $mref.

It will synthesize a 'From ' line if one is not present in $mref.

If the 'Content-Length' option is not set, then get_message will escape 'From ' lines in the body of the message.

init

Initializes various items specific to Mbox.

• Determines an appropriate temporary directory. If the TMPDIR environment variable is set, it uses that, otherwise it uses /tmp. The working directory will be a subdirectory in that directory.

• Bumps a sequence number used for unique temporary filenames.

• Initializes $self->{WorkingDir} to the name of a directory that will be used to hold the working copies of the messages in the folder.

is_valid_folder_format($foldername)

Returns 1 if the folder is a plain file and starts with the string 'From ', otherwise it returns 0.

Returns 1 if the folder is a zero-length file and the $Mail::Format::DefaultEmptyFileFormat class variable is set to 'mbox'.

Otherwise it returns 0.

create($foldername)

Creates a new folder named $foldername. Returns 0 if the folder already exists, otherwise returns 1.

AUTHOR

Kevin Johnson <kjj@pobox.com>

COPYRIGHT

Copyright (c) 1996-1998 Kevin Johnson <kjj@pobox.com>.

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Mail::Folder

perl -MCPAN -e shell
install Mail::Folder