NAME
Mail::MboxParser - read-only access to UNIX-mailboxes
SYNOPSIS
use Mail::MboxParser;
my $mb = Mail::MboxParser->new('some_mailbox');
for my $msg ($mb->get_messages) {
my %header = %{$msg->header};
print $msg->from->{name}, "\n";
print $msg->from->{email}, "\n";
print $header{subject}, "\n";
print $header{'reply-to'}, "\n";
$msg->store_all_attachements('/tmp');
}
DESCRIPTION
This module attempts to provide a simplified access to standard UNIX-mailboxes. It offers only a subset of methods to get 'straight to the point'. More sophisticated things can still be done by invoking any method from MIME::Tools on the appropriate return values.
METHODS
The below methods refer to Mail::MboxParser-objects.
- new
- new(MAILBOX)
-
This creates a new MboxParser-object opening the specified MAILBOX with either absolute or relative path. It does not necessarily need a parameter in which case you need to pass the mailbox to the object using the method 'open'. Returns nothing.
- open(mailbox)
-
Can be used to either pass a mailbox to the MboxParser-object either the first time or for changing the mailbox. Returns nothing.
- get_messages
-
Returns an array containing all messages in the mailbox respresented as Mail::MboxParser::Mail objects.
- nmsgs
-
Returns the number of messages in a mailbox. You could naturally also call get_messages in an array context, but this one wont create new objects. It just counts them and thus it is much quicker and wont eat a lot of memory.
The below methods refer to Mail::MboxParser::Mail-objects returned by get_messages.
- new(header, body)
-
This is usually not called directly but instead by $mb->get_messages. You could however create a mail-object manually providing the header and body both as one string.
- header
-
Returns the mail-header as a hash-ref with header-fields as keys. All keys are turned to lower-case, so $header{Subject} has to be written as $header{subject}.
- body
-
Returns the body as a single string.
- from
-
Returns a hash-ref with the two fields 'name' and 'email'. Returns undef if empty.
- id
-
Returns the message-id of a message cutting off the leading and trailing '<' and '>' respectively.
- num_entitities
-
Returns the number of MIME-entities. That is, the number of sub-entitities actually.
- get_entitities([n])
-
Either returns an array of all MIME::Entity objects or one particular if called with a number.
- get_entity_body(n)
-
Returns the body of the n-th MIME::Entity as a single string.
- store_entity_body(n, FILEHANDLE)
-
Stores the stringified body of n-th entity to the specified filehandle. That's basically the same as:
my $body = $mail->get_entity_body(0); print FILEHANDLE $body;
and could be shortened to this:
$mail->store_entity_body(0, \*FILEHANDLE);
- store_attachement(n, path)
-
It is really just a call to store_entity_body but it will take care that the n-th entity really is a saveable attachement. That is, it wont save anything with a MIME-type of, say, text/html or so. It uses the recommended-filename found in the MIME-header. 'path' is the place where the new file will go to.
- store_all_attachements(path)
-
Walks through an entire mail and stores all apparent attachements to 'path'. See the supplied store_att.pl script in the eg-directory of the package to see a useful example.
FIELDS
Mail::MboxParser is basically a pseudo-hash containing two fields.
- $mb->{READER}
-
This is the filehandle from which is read internally. As to yet, it is read-only so you can't use it for writing. This may be changed later.
- $mb->{NMSGS}
-
Having called nmsgs once this field contains the number of messages in the mailbox. Thus there is no need for calling the method twice which speeds up matters a little.
Mail::MboxParser::Mail is a pseudo-hash with four fields.
- $mail->{RAW}
-
Contains the whole message (that is, header plus body) in one string.
- $mail->{HEADER}
-
Well, just the header of the message as a string.
- $mail->{BODY}
-
You guess it.
- $mail->{ENTITY}
-
The top-level MIME::Entity of a message. You can call any suitable methods from the MIME::tools upon this object to give you more specific access to MIME-parts.
BUGS
Don't know yet of any. However, since I only have a limited number of mailboxes on which I could test the module, there might be circumstances under which Mail::MboxParser fails to work correctly. It will probably fail on mal-formated mails produced by some cheap CGI-webmailers.
The way of counting the number of mails in a mailbox is a little suspect. Internally this looks like '$self->{NMSGS}++ if /^Lines: \d+\n$/;'. In case nmsgs really produces bogus then you could try calling get_messages in scalar context: '$mb->{NMSGS} = $mb->get_messages'. Once having done so, a call to nmsgs will produce this number since it only parses once and will only return the previously cached results on later calls.
AUTHOR AND COPYRIGHT
Tassilo von Parseval <Tassilo.Parseval@post.RWTH-Aachen.de>.
Copyright (c) 2001 Tassilo von Parseval. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
4 POD Errors
The following errors were encountered while parsing the POD:
- Around line 144:
'=item' outside of any '=over'
- Around line 218:
You forgot a '=back' before '=head2'
- Around line 222:
'=item' outside of any '=over'
- Around line 248:
You forgot a '=back' before '=head1'