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.

For a specific example of adding a folder interface see Mail::Folder::Emaul. More detailed documentation on the subject is forthcoming.

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 so a sync before the close if you want deletes and the like to be reflected in the folder.

sync()

Synchronize the folder with the internal data structures. The folder interface will process deletes and read in any new messages that have arrived in the folder since the last time it was either opened or synced.

pack()

For folder formats like mh this will rename the files in the folder so that there are no gaps in the message number sequence. For other folder formats (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. Please note that this operation takes place immediately, not during a sync.

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. Please note that this operation takes place immediately, not during a sync.

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.

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

Based on the current message number, returns the message number of the next message in the folder.

prev_message()

Based on the current message number, returns the message number of the previous message in 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.

sort($func_ref)

Returns a sorted list of messages. The method is passed a reference to a function that will accept two Mail::Internet message references containing only the headers and will 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.

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.

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