NAME
Mail::Pegasus - read Pegasus Mail folders and messages.
SYNOPSIS
This is a Perl Module to provide read only access to messsages in a Pegasus
Mailbox folder.
CONSTRUCTOR
The following method contructs a new Mail::Pegasus
object:
- new ( Directory => $directory, [ OPTIONS ] )
-
Directory
is a required argument in the form of a key-value pair, jusr like a hash table. It will identify the mailbox heirarchy for the Pegasus mail folder.OPTIONS
is a list of options given in the form of key-value pairs, just like a hash table. Valid options are- Debug
-
The value of this option should be a
1
or a0
. When set to 1 extensive debug information is sent to STDERR - Heirarch
-
The value of this option should be the name of the HEIRARCHY.PM file in the target Pegasus mail folder. The default for this option is 'HEIRARCHY.PM' (all upper case).
A HEIRARCHY.PM file is expected and required in the directory supplied to the constructor.
METHODS
- init ( )
-
Will read the heirarchy file reinitialising the folder list.
- print_folders ( )
-
Will provide a text list of folder names prefixed with a numeric folder identifier. The identifier may then be used to select a folder using the
select_by_id
method. - select_by_id ( FOLDER-ID )
-
Will mark a folder as selected and will initialise the message list for that folder. The argument must be a number that identifies a valid folder. WARNING: Everytime
init()
is called the folder identifiers may be changed. - select ( FOLDER-NAME )
-
Will mark a folder as selected and will initialise the message list for that folder. The argument must be the folder name as found in the
print_folders()
- list_folders ( )
-
Will return a reference to an array which will contain a list of all Pegasus Mail folders found.
- get_message ( MSG-ID )
-
Will return the entire message indexed by the MSG-ID in the currently selected folder.
- get_message_status ( MSG-ID )
-
Will return a flag indicating whether the message has been read or not. A return of
1
indicates the message has been read,0
that the message has not been read, and undef if the status headers are not found. - messages ( )
-
Will return the number of messages in the currently selected folder.
- list_messages ( )
-
Will return a visual list of messsages in the currently selected folder. The format of the returned list is:
ID: # Date: message date Subject: <message subject>
The ID number can be used with
get_message()
andget_message_status()
to retrieve the message from the folder. - message ( MSG-ID )
-
Will return a
Mail::Internet
object for the message specified by MSG-ID in the currently selected folder. - head ( MSG-ID )
-
Will return a
Mail::Header
object for the message specified by MSG-ID in the currently selected folder. - body ( MSG-ID )
-
Will return a body of the message. This is a reference to an array. Each entry in the array represents a single line in the message.
EXAMPLE
This example will show the Data and Subject of every folder of a user, then it will show the first message of the INBOX for the same user and finally it will return the status of the first message in the INBOX.
my $mailbox = Mail::Pegasus->new(Directory => "$ENV{USER}/pmail");
foreach my $mailFolder (@{$mailbox->list_folders()})
{
$mailbox->select($mailFolder);
print "Selected $mailFolder [" . $mailbox->messages() . " messages]\n";
$mailbox->list_messages();
}
$mailbox->select("INBOX");
print $mailbox->get_message("1");
my $status = $mailbox->get_message_status("1");
if (defined($status))
{
print "Message has " . ($status ? "" : "not ") . "been read!\n";
} else {
print "Unable to determine the message status!\n";
}
exit;
BUGS
Known issues are:
Drives and Paths in the heirarchy file will cause the folder
not to be read.
If present a seperate folder called INBOX will not be accessable.
Duplicate folder names render the first read folders with the
same name inaccessable.
SEE ALSO
AUTHOR
Matthew Sullivan <sorbs@cpan.org>
COPYRIGHT
Copyright (c) 2004 Matthew Sullivan & Rodney McDuff. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.