/ 
MIME-Structure-0.06
River stage zero No dependents
/ MIME::Structure

NAME

MIME::Structure - determine structure of MIME messages

SYNOPSIS

use MIME::Structure;
$parser = MIME::Structure->new;
$root = $parser->parse($filehandle);
print $root->{'header'};
$parts = $root->{'parts'};
foreach ($parts) {
    $offset  = $_->{'offset'};
    $type    = $_->{'type'};
    $subtype = $_->{'subtype'};
    $line    = $_->{'line'};
    $header  = $_->{'header'};
}
print $parser->concise_structure($root), "\n";

METHODS

new
$parser = MIME::Structure->new;
parse
$root = $parser->parse($filehandle);
($root, @other_entities) = $parser->parse($filehandle);

Parses the message found in the given filehandle.

A MIME message takes the form of a non-empty tree, each of whose nodes is termed an entity (see RFCs 2045-2049). The root entity is the message itself; the children of a multipart message are the parts it contains. (A non-multipart message has no children.)

The parse method returns a list of all the entities in the message; the first entity is the root entity, the second entity is the root's first child, and so on. If called in scalar context, only the root is returned.

Besides parsing the message, this method may also be used to print the message, or portions thereof, as it parses; see the print method for details.

keep_header
$keep_header = $parser->keep_header;
$parser->keep_header(1);

Set (or get) whether headers should be remembered during parsing.

keep_fields

Set (or get) whether fields (normalized headers) should be remembered.

print
$print = $parser->print;
$parser->print($MIME::Structure::PRINT_HEADER | $MIME::Structure::PRINT_BODY);
$parser->print('header,body');

Set (or get) what should be printed. This may be specified either as any of the following symbolic constants, ORed together:

PRINT_BODY

Or using the following string constants concatenated using any delimiter:

none
body
preamble
epilogue
$print_header = $parser->print_header;
$parser->print_header(1);

Set (or get) whether headers should be printed.

print_body
$print_body = $parser->print_body;
$parser->print_body(1);

Set (or get) whether bodies should be printed.

$print_preamble = $parser->print_preamble;
$parser->print_preamble(1);

Set (or get) whether preambles should be printed.

$print_epilogue = $parser->print_epilogue;
$parser->print_epilogue(1);

Set (or get) whether epilogues should be printed.

entities
$parser->parse;
print "$_->{type}/$_->{subtype} $_->{offset}\n"
    for @{ $parser->entities };

Returns a reference to an array of all the entities in a message, in the order in which they occur in the message. Thus the first entity is always the root entity, i.e., the message itself).

concise_structure
$parser->parse;
print $parser->concise_structure;
# e.g., '(multipart/alternative:0 (text/html:291) (text/plain:9044))'

Returns a string showing the structure of a message, including the content type and offset of each entity (i.e., the message and [if it's multipart] all of its parts, recursively). Each entity is printed in the form:

"(" content-type ":" byte-offset [ " " parts... ")"

Offsets are byte offsets of the entity's header from the beginning of the message. (If parse() was called with an offset parameter, this is added to the offset of the entity's header.)

N.B.: The first offset is always 0.

BUGS

Documentation is sketchy.

AUTHOR

Paul Hoffman <nkuitse (at) cpan (dot) org>

COPYRIGHT

Copyright 2008 Paul M. Hoffman. All rights reserved.

This program is free software; you can redistribute it and modify it under the same terms as Perl itself.