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 open
s 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 DotLock
ing. 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
to1
.
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
open
ed orsync
ed.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.
3 POD Errors
The following errors were encountered while parsing the POD:
- Around line 339:
'=item' outside of any '=over'
- Around line 395:
You forgot a '=back' before '=head2'
- Around line 477:
You forgot a '=back' before '=head2'