NAME

Mail::Folder - A folder-independant interface to email folders.

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

SYNOPSIS

use Mail::Folder;

DESCRIPTION

This base class, and it's subclasses provide an object-oriented interface to email folders independant of the underlying folder implementation.

There are currently two folder interfaces provided with this package:

Mail::Folder::Emaul
Mail::Folder::Mbox

Here's a snippet of code that retrieves the third message from a mythical emaul folder and outputs it to stdout:

use Mail::Folder::Emaul;

$folder = new Mail::Folder('emaul', "mythicalfolder");
$message = $folder->get_message(3);
$message->print(\*STDOUT);
$folder->close;

METHODS

new([%options])

new($folder_name [, %options])

Create a new, empty Mail::Folder object. If $folder_name is specified, then the open method will be automatically called with that argument.

Options are specified as hash items using key and value pairs. Currently, the only builtin option is Create, which is used by open.

open($folder_name)

Open the given folder and populate internal data structures with information about the messages in the folder. If the Create option is set, then the folder will be created if it does not already exist.

The readonly attribute will be set if the underlying folder interface determines that the folder is readonly.

close

Perform any housecleaning to affect a 'closing' of the folder. It does not perform an implicit sync. Make sure you do a sync before the close if you want the pending deletes, appends, updates, and the like to be performed on the folder.

sync

Synchronize the folder with the internal data structures. The folder interface will process deletes, updates, appends, refiles, and dups. It also reads in any new messages that have arrived in the folder since the last time it was either opened or synced.

pack

For folder formats that may have holes in the message number sequence (like mh) this will rename the files in the folder so that there are no gaps in the message number sequence. For folder formats that won't have these holes (like mbox) it does nothing.

get_message($msg_number)

Retrieve a message. Returns a reference to a Mail::Internet object.

get_header($msg_number)

Retrieve a message header. Returns a reference to a Mail::Internet object.

append_message($message_ref)

Add a message to a folder. Given a reference to a Mail::Internet object, append it to the end of the folder. The result is not committed to the original folder until a sync is performed.

update_message($msg_number, $message_ref)

Replaces the message identified by $msg_number with the contents of the message in reference to a Mail::Internet object $message_ref. The result is not committed to the original folder until a sync is performed.

refile($msg_number, $folder_ref)

Moves a message from one folder to another. Note that this method uses delete_message and append_message so the changes will show up in the folder objects, but will need a syncs performed in order for the changes to show up in the actual folders.

dup($msg_number, $folder_ref)

Copies a message to a folder. Works like refile, but doesn't delete the original message. Note that this method uses append_message so the change will show up in the folder object, but will need a sync performed in order for the change to show up in the actual folder.

init

This is a stub entry called by new. The primary purpose is to provide a method for subclasses to override for initialization to be performed at constructor time. It is called after the object members variables have been initialized and before the optional call to open. The new method will return undef if the init method returns 0.

delete_message($msg_number)

Mark a message for deletion. The actual deletion will be done by the sync method. The actual delete in the original folder is not performed until a sync is performed.

message_list

Returns a list of the message numbers in the folder.

first_message

Returns the message number of the first message in the folder.

last_message

Returns the message number of the last message in the folder.

next_message($msg_number)

Returns the message number of the next message in the folder relative to $msg_number. It returns 0 is there is no next message (ie. at the end of the folder).

prev_message($msg_number)

Returns the message number of the previous message in the folder relative to $msg_number. It returns 0 is there is no previous message (ie. at the beginning of the folder).

first_labeled_message($label)

Returns the message number of the first message in the folder that has the label $label associated with it. Returns 0 is there are no messages with the given label.

first_labeled_message($label)

Returns the message number of the last message in the folder that has the label $label associated with it. Returns 0 if there are no messages with the given label.

next_labeled_message($msg_number, $label)

Returns the message number of the next message (relative to $msg_number) in the folder that has the label $label associated with it. It returns 0 is there is no next message with the given label.

prev_labeled_message($msg_number, $label)

Returns the message number of the previous message (relative to $msg_number) in the folder that has the label $label associated with it. It returns 0 is there is no previous message with the given label.

current_message

current_message($msg_number)

When called with no arguments returns the message number of the current message in the folder. When called with an argument set the current message number for the folder to the value of the argument.

For folder mechanisms that provide persistant storage of the current message, the underlying folder interface will update that storage. For those that don't changes to current_message will be affect while the folder is open.

sort($func_ref)

Returns a sorted list of messages. It works conceptually similar to the regular perl sort. The $func_ref that is passed to sort must be a reference to a function. The function will be passed two Mail::Internet message references containing only the headers and it must return an integer less than, equal to, or greater than 0, depending on how the elements of the array are to be ordered.

select($func_ref)

Returns a list of message numbers that match a set of criteria. The method is passed a reference to a function that is used to determine the match criteria. The function will be passed a reference to a Mail::Internet message object containing only a header.

add_label($msg_number, $label)

Associates $label with $msg_number. The label must have a length > 0 and should be a printable string, although there are currently no requirements for this.

add_label will return 0 if $label is of zero length, otherwise it returns 1.

The persistant storage of labels is dependant on the underlying folder interface. Some folder interfaces may not support arbitrary labels. In this case, the labels will not exist when the folder is reopened.

There are a few standard labels that have implied meaning. Unless stated, these labels are not actually acted on my the module interface, rather represent a standard set of labels for MUAs to use.

deleted

This is used by the delete_message and sync to process the deletion of messages. These will not be reflected in any persistant storage of message labels.
edited

This tag is added by update_message to reflect that the message has been altered. This behaviour may go away.
seen

This means that the message has been viewed by the user. This should only be set by MUAs that present the entire message body to the user.
filed
replied
forwarded
printed

delete_label($msg_number, $label)

Deletes the association of $label with $msg_number.

Returns 0 if the label $label wasn't associated with $msg_number, otherwise returns a 1.

clear_label($label)

Deletes the association of $label for all of the messages in the folder.

Returns the quantity of messages that were associated with the label before they were cleared.

label_exists($msg_number, $label)

Returns 1 if the label $label is associated with $msg_number otherwise returns 0.

list_labels($msg_number)

Returns a list of the labels that are associated with $msg_number.

list_all_labels

Returns a list of all the labels that are associated with the messages in the folder.

select_label($label)

Returns a list of message numbers that have the given label $label associated with them.

foldername

Returns the name of the folder that the object has open.

message_exists($msg_number)

Returns 1 if the folder object contains a reference for $msg_number, otherwise returns 0.

set_readonly

Sets the readonly attribute for the folder. This will cause the sync command to not perform any updates to the actual folder.

is_readonly

Returns 1 if the readonly attribute for the folder is set, otherwise returns 0.

get_option($option)

Returns the setting for the given option. Returns undef if the option does not exist.

set_option($option, $value)

Set $option to $value.

WRITING A FOLDER INTERFACE

The start of a new folder interface module should start with something along the lines of the following chunk of code:

    package Mail::Folder::YOUR_FOLDER_TYPE;
    @ISA = qw(Mail::Folder);
    use Mail::Folder;

    Mail::Folder::register_folder_type(Mail::Folder::YOUR_FOLDER_TYPE,
				       'your_folder_type_name');

In general, writing a folder interface consists of writing a set of methods that overload some of the native ones in Mail::Folder. Below is a list of the methods and specific tasks that each must perform. See the code of the folder interfaces provides with the package for specific examples.

If you go about writing a folder interface and find that something is missing from this documentation, please let me know.

open

Call the superclass new method.
Call set_readonly if folder isn't writable.
Call remember_message for each message in the folder.
Call sort_message_list.
Initialize current_message.
Initialize any message labels from the folder's persistant storage.

close

Call the superclass close method.

sync

Call the superclass sync method.
Lock the folder.
Absorb any new messages
Perform any pending deletes and updates.
Update the folder's persistant storage of current message.
Update the folder's persistant storage of message labels.
Unlock the folder.

pack

Call the superclass pack method.
Perform the guts of the pack
Renumber the Messages member of $self.
Call sort_message_list
Don't forget to reset current_message based on the renumbering.

get_header

Call the superclass get_header method.
Return the cached entry if it exists.
Extract the header into a Mail::Internet object.
Cache it.

get_message

Call the superclass get_message method.
Extract the message into a Mail::Internet object.

update_message

Call the superclass update_message method.
Replace the specified message in the working copy of the folder.

create

Create a folder in a manner specific to the folder interface.

init

This isn't really a method that needs to be overloaded. It is a method that is called by new to perform any initialization specific to the folder interface. For example of a typical use, see the init routine in Mail::Folder::Mbox.

FOLDER INTERFACE METHODS

These routines are intended for use by implementers of finder interfaces.

register_folder_type($class, $type)

Registers a folder interface with Mail::Folder.

sort_message_list

This is used to resort the internal sorted list of messages. It needs to be called whenever the list of messages is changed. It's a separate routine to allow large updates to the list of messages (like during an open) with only one trailing call to sort_message_list.

cache_header($msg_number, $header_ref)

Associates $header_ref with $msg_number in the object's internal header cache.

invalidate_header($msg_number)

Clobbers the header cache entry for $msg_number.

AUTHOR

Kevin Johnson <kjj@primenet.com>

COPYRIGHT

To install Mail::Folder, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Mail::Folder

CPAN shell

perl -MCPAN -e shell
install Mail::Folder

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)

NAME

SYNOPSIS

DESCRIPTION

METHODS

new([%options])

new($folder_name [, %options])

open($folder_name)

close

sync

pack

get_message($msg_number)

get_header($msg_number)

append_message($message_ref)

update_message($msg_number, $message_ref)

refile($msg_number, $folder_ref)

dup($msg_number, $folder_ref)

init

delete_message($msg_number)

message_list

first_message

last_message

next_message($msg_number)

prev_message($msg_number)

first_labeled_message($label)

first_labeled_message($label)

next_labeled_message($msg_number, $label)

prev_labeled_message($msg_number, $label)

current_message

current_message($msg_number)

sort($func_ref)

select($func_ref)

add_label($msg_number, $label)

delete_label($msg_number, $label)

clear_label($label)

label_exists($msg_number, $label)

list_labels($msg_number)

list_all_labels

select_label($label)

foldername

message_exists($msg_number)

set_readonly

is_readonly

get_option($option)

set_option($option, $value)

WRITING A FOLDER INTERFACE

open

close

sync

pack

get_header

get_message

update_message

create

init

FOLDER INTERFACE METHODS

register_folder_type($class, $type)

sort_message_list

cache_header($msg_number, $header_ref)

invalidate_header($msg_number)

AUTHOR

COPYRIGHT

Module Install Instructions