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

The documentation for each of these modules provides more detailed into on their operation.

ABSTRACT METHODS

These are the methods that a folder interface will override to perform it's work on a folder. The corresponding subclass methods should call these methods if the call fails.

new()

new($folder_name)

Create a new, empty Mail::Folder object. If $folder_name is included, then the open method is also called with that argument.

open($folder_name)

Open the given folder and populate internal data structures with information about the messages in the folder.

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 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.

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 reutrn undef if the init method returns 0.

Class Methods

These methods are provided by the base class and probably don't need to be overridden by a folder interface.

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()

next_message($msg_number)

Returns the message number of the next message in the folder. If $msg_number is not specified it is relative to the current message, otherwise it is relative to $msg_number. It returns -1 is there is no next message (ie. at the end of the folder).

prev_message()

Returns the message number of the previous message in the folder. If $msg_number is not specified it is relative to the current message, otherwise it is relative to $msg_number. It returns -1 is there is no previous message (ie. at the beginning of the folder).

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.

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.

foldername()

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

list_deletes()

Returns a list of the message numbers that are marked for deletion.

clear_deletes()

Zero out the list of pending deletes.

Misc Routines

register_folder_type($class, $type)

Register a folder interface with Mail::Folder.

Folder Interface Methods

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

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

Copyright (c) 1996 Kevin Johnson <kjj@primenet.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