(stringification) The folder objects stringify to their name. This simplifies especially print statements and sorting a lot.
# Three lines with overloading: resp. cmp, @{}, and "" foreach my $folder (sort @folders) { my $msgcount = @$folder; print "$folder contains $msgcount messages\n"; }
When the folder is used as if it is a reference to an array, it will show the messages, like messages() and message() would do.
my $msg = $folder->[3]; my $msg = $folder->message(3); # same foreach my $msg (@$folder) ... foreach my $msg ($folder->messages) ... # same
(string comparison) folders are compared based on their name. The sort
rules are those of the build-in cmp
.
See METHODS in Mail::Reporter
Open a new folder. A list of labeled OPTIONS for the mailbox can be supplied. Some options pertain to Mail::Box, and others are added by sub-classes.
To control delay-loading of messages, as well the headers as the bodies,
a set of *_type
options are available. extract
determines whether
we want delay-loading.
Option | Defined in | Default |
---|---|---|
access |
| |
body_delayed_type | ||
body_type | <folder specific> | |
coerce_options |
| |
create | <false> | |
extract |
| |
field_type | undef | |
fix_headers | <false> | |
folder |
| |
folderdir | undef | |
head_delayed_type | ||
head_type | ||
keep_dups | <false> | |
lock_file | undef | |
lock_timeout | 1 hour | |
lock_type | ||
lock_wait | 10 seconds | |
locker | undef | |
log | Mail::Reporter |
|
manager | undef | |
message_type | ||
multipart_type | ||
remove_when_empty | <true> | |
save_on_exit | <true> | |
trace | Mail::Reporter |
|
trusted | <depends on folder location> |
You did not specify the name of a folder to be opened. Use the
new(folder) option or set the MAIL
environment variable.
Add a message to the folder. A message is usually a Mail::Box::Message object or a sub-class thereof. The message shall not be in an other folder, when you use this method. In case it is, use Mail::Box::Manager::moveMessage() or Mail::Box::Manager::copyMessage() via the manager.
Messages with id's which already exist in this folder are not added.
Option | Default |
---|---|
share | <not used> |
$folder->addMessage($msg); $folder->addMessages($msg1, $msg2, ...);
Adds a set of MESSAGE objects to the open folder at once. For some folder types this may be faster than adding them one at a time.
$folder->addMessages($msg1, $msg2, ...);
Append one or more messages to an unopened folder. Usually, this method is called by the Mail::Box::Manager::appendMessage(), in which case the correctness of the folder type is checked.
For some folder types it is required to open the folder before it can be used for appending. This can be fast, but this can also be very slow (depends on the implementation). All OPTIONS passed will also be used to open the folder, if needed.
Option | Default |
---|---|
folder | <required> |
message | undef |
messages | undef |
share | <false> |
my $message = Mail::Message->new(...); Mail::Box::Mbox->appendMessages ( folder => '=xyz' , message => $message , folderdir => $ENV{FOLDERS} );
better:
my Mail::Box::Manager $mgr; $mgr->appendMessages($message, folder => '=xyz');
Close the folder, which usually implies writing the changes. This will
return false
when writing is required but fails. Please do check this
result.
WARNING: When moving messages from one folder to another, be sure to write the destination folder before writing and closing the source folder. Otherwise you may lose data if the system crashes or if there are software problems.
Option | Default |
---|---|
force | <false> |
save_deleted |
|
write |
|
my $f = $mgr->open('spam', access => 'rw') or die "Cannot open spam: $!\n"; $f->message(0)->delete if $f->messages; $f->close or die "Couldn't write $f: $!\n";
You have opened the folder read-only --which is the default set
by new(access)--, made modifications, and now want to close it.
Set close(force) if you want to overrule the access mode, or close
the folder with close(write) set to NEVER
.
Copy the folder's messages to a new folder. The new folder may be of a different type.
Option | Default |
---|---|
delete_copied | <false> |
select | 'ACTIVE' |
share | <not used> |
subfolders | <folder type dependent> |
my $mgr = Mail::Box::Manager->new; my $imap = $mgr->open(type => 'imap', host => ...); my $mh = $mgr->open(type => 'mh', folder => '/tmp/mh', create => 1, access => 'w'); $imap->copyTo($mh, delete_copied => 1); $mh->close; $imap->close;
For some reason, for instance disc full, removed by external process, or read-protection, it is impossible to copy one of the messages. Copying will proceed for the other messages.
The folder where the messages are copied to is not opened with write access (see new(access)). This has no relation with write permission to the folder which is controled by your operating system.
The copy includes the subfolders, but for some reason it was not possible to copy one of these. Copying will proceed for all other sub-folders.
Remove the specified folder file or folder directory (depending on
the type of folder) from disk. Of course, THIS IS DANGEROUS: you "may"
lose data. Returns a true
value on success.
WARNING: When moving messages from one folder to another, be sure to write the destination folder before deleting the source folder. Otherwise you may lose data if the system crashes or if there are software problems.
Option | Default |
---|---|
recursive | 1 |
my $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw'); ... some other code ... $folder->delete;
my $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd'); $folder->delete;
The folder must be opened with write access via new(access), otherwise
removing it will be refused. So, you may have write-access according to
the operating system, but that will not automatically mean that this
delete
method permits you to. The reverse remark is valid as well.
Returns how the folder is organized: as one FILE
with many messages,
a DIRECTORY
with one message per file, or by a REMOTE
server.
Returns the size of the folder in bytes, not counting in the deleted messages. The error in the presented result may be as large as 10%, because the in-memory representation of messages is not always the same as the size when they are written.
Returns a name for the type of mail box. This can be mbox
, mh
,
maildir
, or pop3
.
Read new messages from the folder, which where received after opening it. This is quite dangerous and shouldn't be possible: folders which are open are locked. However, some applications do not use locks or the wrong kind of locks. This method reads the changes (not always failsafe) and incorporates them in the open folder administration.
The OPTIONS are extra values which are passed to the updateMessages() method which is doing the actual work here.
Represent the folder as a URL (Universal Resource Locator) string. You may pass such a URL as folder name to Mail::Box::Manager::open().
print $folder->url; # may result in # mbox:/var/mail/markov or # pop3://user:password@pop.aol.com:101
Returns the access mode of the folder, as set by new(access)
Checks if the folder, as stored in memory, is modified. A true value is returned when any of the messages is to be deleted, has changed, or messages were added after the folder was read from file.
WARNING: this flag is not related to an external change to the folder structure on disk. Have a look at update() for that.
Sets whether the folder is modified or not.
Some mail-readers keep the current message, which represents the last used message. This method returns [after setting] the current message. You may specify a NUMBER, to specify that that message number is to be selected as current, or a MESSAGE/MESSAGE-ID (as long as you are sure that the header is already loaded, otherwise they are not recognized).
$folder->current(0); $folder->current($message);
Like messageId(), this method searches for a message with the
MESSAGE-ID, returning the corresponding message object. However, find
will cause unparsed message in the folder to be parsed until the message-id
is found. The folder will be scanned back to front.
Find the first message which has this LABEL with the correct setting. The BOOLEAN indicates whether any true value or any false value is to be found. By default, a true value is searched for. When a message does not have the requested label, it is taken as false.
my $current = $folder->findFirstLabeled('current'); my $first = $folder->findFirstLabeled(seen => 0); my $last = $folder->findFirstLabeled(seen => 0, [ reverse $self->messages('ACTIVE') ] )
Get or set a message with on a certain index. Messages which are flagged for deletion are counted. Negative indexes start at the end of the folder.
my $msg = $folder->message(3); $folder->message(3)->delete; # status changes to `deleted' $folder->message(3, $msg); print $folder->message(-1); # last message.
With one argument, returns the message in the folder with the specified MESSAGE-ID. If a reference to a message object is passed as the optional second argument, the message is first stored in the folder, replacing any existing message whose message ID is MESSAGE-ID. (The message ID of MESSAGE need not match MESSAGE-ID.)
!!WARNING!!: when the message headers are delay-parsed, the message
might be in the folder but not yet parsed into memory. In this case, use
find() instead of messageId()
if you really need a thorough search.
This is especially the case for directory organized folders without
special indexi, like Mail::Box::MH.
The MESSAGE-ID may still be in angles, which will be stripped. In that case blanks (which origin from header line folding) are removed too. Other info around the angles will be removed too.
my $msg = $folder->messageId('<complex-message.id>'); $folder->messageId("<complex-message\n.id>", $msg); my $msg = $folder->messageId('complex-message.id'); my $msg = $folder->messageId('garbage <complex-message.id> trash');
The message id is discovered more than once within the same folder, but the content of the message seems to be different. This should not be possible: each message must be unique.
According to the RFCs, message-ids need to contain a unique random part,
then an @
, and then a domain name. This is made to avoid the creation
of two messages with the same id. The warning emerges when the @
is
missing from the string.
Returns a list of all message-ids in the folder, including those of messages which are to be deleted.
For some folder-types (like MH), this method may cause all message-files to be read. See their respective manual pages.
foreach my $id ($folder->messageIds) { $folder->messageId($id)->print; }
Returns multiple messages from the folder. The default is ALL
which will return (as expected maybe) all the messages in the
folder. The ACTIVE
flag will return the messages not flagged for
deletion. This is the opposite of DELETED
, which returns all
messages from the folder which will be deleted when the folder is
closed.
You may also specify a RANGE: two numbers specifying begin and end index in the array of messages. Negative indexes count from the end of the folder. When an index is out-of-range, the returned list will be shorter without complaints.
Everything else than the predefined names is seen as labels. The messages which have that label set will be returned. When the sequence starts with an exclamation mark (!), the search result is reversed.
For more complex searches, you can specify a FILTER, which is simply a code reference. The message is passed as only argument.
foreach my $message ($folder->messages) {...} foreach my $message (@$folder) {...} # twice the same my @messages = $folder->messages; my @messages = $folder->messages('ALL'); # Selection based on a range (begin, end) my $subset = $folder->messages(10,-8); # twice the same: my @not_deleted= grep {not $_->isDeleted} $folder->messages; my @not_deleted= $folder->messages('ACTIVE'); # scalar context the number of messages my $nr_of_msgs = $folder->messages; # third message, via overloading $folder->[2]; # Selection based on labels $mgr->moveMessages($spam, $inbox->message('spam')); $mgr->moveMessages($archive, $inbox->message('seen'));
Simply calls messages() in scalar context to return a count instead of the messages itself. Some people seem to understand this better.
You start with a MESSAGE, and are looking for a set of messages which are related to it. For instance, messages which appear in the 'In-Reply-To' and 'Reference' header fields of that message. These messages are known by their MESSAGE-IDS and you want to find them in the folder.
When all message-ids are known, then looking-up messages is simple: they are found in a plain hash using messageId(). But Mail::Box is lazy where it can, so many messages may not have been read from file yet, and that's the prefered situation, because that saves time and memory.
It is not smart to search for the messages from front to back in the folder: the chances are much higher that related message reside closely to each other. Therefore, this method starts scanning the folder from the specified MESSAGE, back to the front of the folder.
The TIMESPAN can be used to terminate the search based on the time
enclosed in the message. When the constant string EVER
is used as
TIMESPAN, then the search is not limited by that. When an integer
is specified, it will be used as absolute time in time-ticks as
provided by your platform dependent time
function. In other cases,
it is passed to timespan2seconds() to determine the threshold
as time relative to the message's time.
The WINDOW is used to limit the search in number of messages to be
scanned as integer or constant string ALL
.
Returned are the message-ids which were not found during the scan. Be warned that a message-id could already be known and therefore not found: check that first.
my $refs = $msg->get('References') or return; my @msgids = $ref =~ m/\<([^>]+\>/g; my @failed = $folder->scanForMessages($msg, \@msgids, '3 days', 50);
List the names of all sub-folders to this folder, not recursively decending. Use these names as argument to openSubFolder(), to get access to that folder.
For MBOX folders, sub-folders are simulated.
Option | Default |
---|---|
check | <false> |
folder | <from calling object> |
folderdir | <from folder> |
skip_empty | <false> |
my $folder = $mgr->open('=in/new'); my @subs = $folder->listSubFolders; my @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new'); my @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.
Returns the constructed name of the folder with NAME, which is a sub-folder of this current one. You have either to call this method as instance method, or specify a PARENTNAME.
my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc'); print $sub; # abc/xyz my $f = Mail::Box::Mbox->new(folder => 'abc'); print $f->nameOfSubfolder('xyz'); # abc/xyz my $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef); print $sub; # xyz
Open a folder (usually a sub-folder) with the same options as this one. If there is a folder manager in use, it will be informed about this new folder. OPTIONS overrule the options which where used for the folder this method is called upon.
Open (or create, if it does not exist yet) a new subfolder in an existing folder.
my $folder = Mail::Box::Mbox->new(folder => '=Inbox'); my $sub = $folder->openSubFolder('read');
Some folder types can have messages in the top-level folder, some other can't.
Coerce the MESSAGE to be of the correct type to be placed in the folder. You can specify Mail::Internet and MIME::Entity objects here: they will be translated into Mail::Message messages first.
Create a folder. If the folder already exists, it will be left unchanged. The folder is created, but not opened! If you want to open a file which may need to be created, then use Mail::Box::Manager::open() with the create flag, or Mail::Box::new(create).
Option | Default |
---|---|
folderdir | undef |
Determine which kind of body will be created for this message when reading the folder initially.
Determine if the specified folder is of the type handled by the folder class. This method is extended by each folder sub-type.
The FOLDERNAME specifies the name of the folder, as is specified by the
application. You need to specified the folder
option when you skip
this first argument.
OPTIONS is a list of extra information for the request. Read
the documentation for each type of folder for type specific options, but
each folder class will at least support the folderdir
option:
Option | Default |
---|---|
folderdir | undef |
Mail::Box::Mbox->foundIn('=markov', folderdir => "$ENV{HOME}/Mail"); Mail::Box::MH->foundIn(folder => '=markov');
Returns the character or characters used to separate lines in the folder file, optionally after setting it to STRING, or one of the constants. The first line of the folder sets the default.
UNIX uses a LF character, Mac a CR, and Windows both a CR and a LF. Each
separator will be represented by a "\n" within your program. However,
when processing platform foreign folders, complications appear. Think about
the Size
field in the header.
When the separator is changed, the whole folder me be rewritten. Although, that may not be required.
Returns the locking object.
Read messages from the folder into memory. The OPTIONS are folder
specific. Do not call read()
yourself: it will be called for you
when you open the folder via the manager or instantiate a folder
object directly.
NOTE: if you are copying messages from one folder to another, use
addMessages() instead of read()
.
my $mgr = Mail::Box::Manager->new; my $folder = $mgr->open('InBox'); # implies read my $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same
Called by read() to actually read the messages from one specific folder type. The read() organizes the general activities.
The OPTIONS are trusted
, head_type
, field_type
,
message_type
, body_delayed_type
, and head_delayed_type
as
defined by the folder at hand. The defaults are the constructor
defaults (see new()).
Store the message in the folder without the checks as performed by addMessage().
The specified message is ready to be removed from a thread. This will be passed on to the mail-manager, which keeps an overview on which thread-detection objects are floating around.
The specified message is ready to be included in a thread. This will be passed on to the mail-manager, which keeps an overview on which thread-detection objects are floating around.
Called by update() to read messages which arrived in the folder after it was opened. Sometimes, external applications dump messages in a folder without locking (or using a different lock than your application does).
Although this is quite a dangerous, it only fails when a folder is updated (reordered or message removed) at exactly the same time as new messages arrive. These collisions are sparse.
The options are the same as for readMessages().
Write the data to disk. The folder (a true
value) is returned if
successful. Deleted messages are transformed into destroyed messages:
their memory is freed.
WARNING: When moving messages from one folder to another, be sure to write (or close()) the destination folder before writing (or closing) the source folder: otherwise you may lose data if the system crashes or if there are software problems.
To write a folder to a different file, you must first create a new folder, then move all the messages, and then write or close() that new folder.
Option | Default |
---|---|
force | <false> |
save_deleted | <false> |
You can not write to this folder unless you have opened the folder to
write or append with new(access), or the force
option is set true.
For some reason (you probably got more error messages about this problem) it is impossible to write the folder, although you should because there were changes made.
Called by write() to actually write the messages from one specific
folder type. The write
organizes the general activities. All options
to write() are passed to writeMessages
as well. Besides, a few extra
are added by write
itself.
Option | Default |
---|---|
messages | <required> |
TIME is a string, which starts with a float, and then one of the words 'hour', 'hours', 'day', 'days', 'week', or 'weeks'. For instance: '1 hour' or '4 weeks'.
The string does not follow the strict rules of the time span syntax which is permitted as parameter.
This method is called by Perl when an folder-object is no longer accessible by the rest of the program.