NAME
MMS::Mail::Parser - A class for parsing MMS (or picture) messages.
VERSION
Version 0.04
SYNOPSIS
This class takes an MMS message and parses it into two 'standard' formats (an MMS::Mail::Message and MMS::Mail::Message::Parsed) for further use. It is intended to make parsing MMS messages network/provider agnostic such that a 'standard' object results from parsing, independant of the network/provider it was sent through.
Code usage example
This example demonstrates the use of the two stage parse. The first pass provides an MMS::Mail::Message object that is then passed through to the provider_parse message that attempts to determine the Network provider the message was sent through and extracts the relevant information and places it into an MMS::Mail::Message::Parsed object.
use MMS::Mail::Parser;
my $mms = MMS::Mail::Parser->new();
my $message = $mms->parse(\*STDIN);
if (defined($message)) {
my $parsed = $mms->provider_parse;
print $parsed->subject."\n";
}Examples of input
MMS::Mail::Parser has the same input methods as MIME::Parser.
# Parse from a filehandle:
$entity = $parser->parse(\*STDIN);
# Parse an in-memory MIME message:
$entity = $parser->parse_data($message);
# Parse a file based MIME message:
$entity = $parser->parse_open("/some/file.msg");
# Parse already-split input (as "deliver" would give it to you):
$entity = $parser->parse_two("msg.head", "msg.body");Examples of parser modification
MMS::Mail::Parser uses MIME::Parser as it's parsing engine. The MMS::Mail::Parser class creates it's own MIME::Parser object if one is not passed in via the new or mime_parser methods. There are a number of reasons for providing your own parser such as forcing all attachment storage to be done in memory than on disk (providing a speed increase to your application at the cost of memory usage).
my $parser = new MIME::Parser;
$parser->output_to_core(1);
my $mmsparser = new MMS::Mail::Parser;
$mmsparser->mime_parser($parser);
my $message = $mmsparser->parse(\*STDIN);
if (defined($message)) {
my $parsed = $mms->provider_parse;
}Examples of error handling
The parser contains an error stack and will ultimately return an undef value from any of the main parse methods if an error occurs. The last error message can be retreived by calling last_error method.
my $message = $mmsparser->parse(\*STDIN);
unless (defined($message)) {
print STDERR $mmsparser->last_error."\n";
exit(0);
}Miscellaneous methods
There are a small set of miscellaneous methods available. The output_dir method is provided so that a new MIME::Parser object does not have to be created to supply a separate storage directory for parsed attachments (however any attachments created as part of the process are removed when the message object is detroyed so the lack of specification of a storage location is not a huge issue ).
# Provide debug ouput to STDERR
$mmsparser->debug(1);
# Set an output directory for MIME::Parser
$mmsparser->output_dir('/tmp');
# Get/set an array reference to the error stack
my $errors = $mmsparser->errors;
# Get/set the MIME::Parser object used by MMS::Parser
$mmsparser->mime_parser($parser);
# Set the characters to be stripped from the returned MMS::Mail::Message and MMS::Mail::Message::Parsed objects
$mmsparser->strip_characters("\r\n");Tutorial
A thorough tutorial can be accessed at http://www.robl.co.uk/redirects/articles/mmsmailparser/
METHODS
The following are the top-level methods of MMS::Mail::Parser object.
Constructor
- new()
-
Return a new MMS::Mail::Parser object. Valid attributes are:
- mime_parser MIME::Parser
-
Passed as an array reference, parser specifies the MIME::Parser object to use instead of MMS::Mail::Parser creating it's own.
- debug INTEGER
-
Passed as an array reference, debug determines whether debuging information is outputted to standard error (defaults to 0).
- strip_characters STRING
-
Pass as an array reference, strip_characters defines the characters to strip from the MMS::Mail::Message (and MMS::Mail::Message::Parsed) class header and text properties.
Regular Methods
- parse INSTREAM
-
Returns an MMS::Mail::Message object by parsing the input stream INSTREAM
- parse_data DATA
-
Returns an MMS::Mail::Message object by parsing the in memory string DATA
- parse_open EXPR
-
Returns an MMS::Mail::Message object by parsing the file specified in EXPR
- parse_two HEADFILE, BODYFILE
-
Returns an MMS::Mail::Message object by parsing the header and body file specified in HEADFILE and BODYFILE filenames
- provider_parse MMS::MailMessage
-
Returns an MMS::Mail::Message::Parsed object by attempting to discover the network provider the message was sent through and parsing through the appropriate MMS::ProviderMailParser. If an MMS::MailMessage object is supplied as an argument then the provider_parse method will parse the supplied MMS::Mail::Message object. If a provider has been set via the provider method then that parser will be used by the provider_parse method instead of attempting to discover the network provider from the MMS::Mail::Message.
- output_dir DIRECTORY
-
Returns the output_dir parameter used with the MIME::Parser object when invoked with no argument supplied. When an argument is supplied it sets the output_dir used by the MIME::Parser to the value of the argument supplied.
- mime_parser MIME::Parser
-
Returns the MIME::Parser object used by MMS::Mail::Parser (if created) when invoked with no argument supplied. When an argument is supplied it sets the MIME::Parser object used by MMS::Mail::Parser to parse messages.
- provider MMS::Mail::Provider
-
Returns an object for the currently set provider when invoked with no argument supplied. When an argument is supplied it sets the provider to the supplied object.
- strip_characters STRING
-
Returns the characters to be stripped from the returned MMS::Mail::Message and MMS::Mail::Message::Parsed objects. When an argument is supplied it sets the strip characters to the supplied string.
- errors
-
Returns the error stack used by the MMS::Mail::Parser object as an array reference.
- last_error
-
Returns the last error from the stack.
- debug INTEGER
-
Returns a number indicating whether STDERR debugging output is active (1) or not (0). When an argument is supplied it sets the debug property to that value.
AUTHOR
Rob Lee, <robl@robl.co.uk>
BUGS
Please report any bugs or feature requests to bug-mms-mail-parser@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MMS-Mail-Parser. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
NOTES
To quote the perl artistic license ('perldoc perlartistic') :
10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
ACKNOWLEDGEMENTS
As per usual this module is sprinkled with a little Deb magic.
COPYRIGHT & LICENSE
Copyright 2005 Rob Lee, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
SEE ALSO
MMS::Mail::Message, MMS::Mail::Message::Parsed, MMS::Mail::Provider, MMS::Mail::Provider