.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MboxParser::Mail 3pm"
.TH MboxParser::Mail 3pm "2013-06-02" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::MboxParser::Mail \- Provide mail\-objects and methods upon
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
See Mail::MboxParser for an outline on usage. Examples however are also
provided in this manpage further below.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mail::MboxParser::Mail objects are usually not created directly though, in
theory, they could be. A description of the provided methods can be found in
Mail::MboxParser.
.PP
However, go on reading if you want to use methods from MIME::Entity and learn
about overloading.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew(header, body)\fR" 4
.IX Item "new(header, body)"
This is usually not called directly but instead by \f(CW\*(C`get_messages()\*(C'\fR. You could
however create a mail-object manually providing the header and body each as
either one string or as an array-ref representing the lines.
.Sp
Here is a common scenario: Retrieving mails from a remote POP-server using
Mail::POP3Client and directly feeding each mail to
\&\f(CW\*(C`Mail::MboxParser::Mail\->new\*(C'\fR:
.Sp
.Vb 2
\&    use Mail::POP3Client;
\&    use Mail::MboxParser::Mail;
\&    
\&    my $pop = new Mail::POP3Client (...);
\&
\&    for my $i (1 .. $pop\->Count) {
\&        my $msg = Mail::MboxParser::Mail\->new( [ $pop\->Head($i) ],
\&                                               [ $pop\->Body($i) ] );
\&        $msg\->store_all_attachments( path => \*(Aq/home/user/dump\*(Aq );
\&    }
.Ve
.Sp
The above effectively behaves like an attachment-only retriever.
.IP "\fBheader\fR" 4
.IX Item "header"
Returns the mail-header as a hash-ref with header-fields as keys. All keys are
turned to lower-case, so \f(CW$header{Subject}\fR has to be written as
\&\f(CW$header{subject}\fR.
.Sp
If a header-field occurs more than once in the header, the value of the key is
an array_ref. Example:
.Sp
.Vb 4
\&    my $field = $msg\->header\->{field};
\&    print $field\->[0]; # first occurance of \*(Aqfield\*(Aq
\&    print $field\->[1]; # second one
\&    ...
.Ve
.IP "\fBfrom_line\fR" 4
.IX Item "from_line"
Returns the \*(L"From \*(R"\-line of the message.
.IP "\fBtrace\fR" 4
.IX Item "trace"
This method returns the \*(L"Received: \*(R"\-lines of the message as a list.
.IP "\fBbody\fR" 4
.IX Item "body"
.PD 0
.IP "\fBbody(n)\fR" 4
.IX Item "body(n)"
.PD
Returns a Mail::MboxParser::Mail::Body object. For methods upon that see
further below. When called with the argument n, the n\-th body of the message is
retrieved. That is, the body of the n\-th entity.
.Sp
Sets \f(CW\*(C`$mail\->error\*(C'\fR if something went wrong.
.IP "\fBfind_body\fR" 4
.IX Item "find_body"
This will return an index number that represents what Mail::MboxParser::Mail
considers to be the actual (main)\-body of an email. This is useful if you don't
know about the structure of a message but want to retrieve the message's
signature for instance:
.Sp
.Vb 1
\&        $signature = $msg\->body($msg\->find_body)\->signature;
.Ve
.Sp
Changes are good that find_body does what it is supposed to do.
.IP "\fBmake_convertable\fR" 4
.IX Item "make_convertable"
Returns a Mail::MboxParser::Mail::Convertable object. For details on what you
can do with it, read Mail::MboxParser::Mail::Convertable.
.IP "\fBget_field(headerfield)\fR" 4
.IX Item "get_field(headerfield)"
Returns the specified raw field from the message header, that is: the fieldname
is not stripped off nor is any decoding done. Returns multiple lines as needed
if the field is \*(L"Received\*(R" or another multi-line field.  Not case sensitive.
.Sp
\&\f(CW\*(C`get_field()\*(C'\fR always returns one string regardless of how many times the field
occured in the header. Multiple occurances are separated by a newline and
multiple whitespaces squeezed to one. That means you can process each occurance
of the field thusly:
.Sp
.Vb 3
\&    for my $field ( split /\en/, $msg\->get_field(\*(Aqreceived\*(Aq) ) {
\&        # do something with $field
\&    }
.Ve
.Sp
Sets \f(CW\*(C`$mail\->error\*(C'\fR if the field was not found in which case
\&\f(CW\*(C`get_field()\*(C'\fR returns \f(CW\*(C`undef\*(C'\fR.
.IP "\fBfrom\fR" 4
.IX Item "from"
Returns a hash-ref with the two fields 'name' and 'email'. Returns \f(CW\*(C`undef\*(C'\fR if
empty. The name-field does not necessarily contain a value either. Example:
.Sp
.Vb 1
\&        print $mail\->from\->{email};
.Ve
.Sp
On behalf of suggestions I received from users, \fIfrom()\fR tries to be smart when
\&'name'is empty and 'email' has the form 'first.name@host.com'. In this case,
\&'name' is set to \*(L"First Name\*(R".
.IP "\fBto\fR" 4
.IX Item "to"
Returns an array of hash-references of all to-fields in the mail-header. Fields
are the same as those of \f(CW\*(C`$mail\->from\*(C'\fR. Example:
.Sp
.Vb 4
\&        for my $recipient ($mail\->to) {
\&                print $recipient\->{name} || "<no name>", "\en";
\&                print $recipient\->{email};
\&        }
.Ve
.Sp
The same 'name'\-smartness applies here as described under \f(CW\*(C`from()\*(C'\fR.
.IP "\fBcc\fR" 4
.IX Item "cc"
Identical with \fIto()\fR but returning the hash-refed \*(L"Cc: \*(R"\-line.
.Sp
The same 'name'\-smartness applies here as described under \f(CW\*(C`from()\*(C'\fR.
.IP "\fBid\fR" 4
.IX Item "id"
Returns the message-id of a message cutting off the leading and trailing '<'
and '>' respectively.
.IP "\fBnum_entities\fR" 4
.IX Item "num_entities"
Returns the number of MIME-entities. That is, the number of sub-entitities
actually. If 0 is returned and you think this is wrong, check
\&\f(CW\*(C`$mail\->log\*(C'\fR.
.IP "\fBget_entities\fR" 4
.IX Item "get_entities"
.PD 0
.IP "\fBget_entities(n)\fR" 4
.IX Item "get_entities(n)"
.PD
Either returns an array of all MIME::Entity objects or one particular if called
with a number. If no entity whatsoever could be found, an empty list is
returned.
.Sp
\&\f(CW\*(C`$mail\->log\*(C'\fR instantly called after get_entities will give you some
information of what internally may have failed. If set, this will be an error
raised by MIME::Entity but you don't need to worry about it at all. It's just
for the record.
.IP "\fBget_entity_body(n)\fR" 4
.IX Item "get_entity_body(n)"
Returns the body of the n\-th MIME::Entity as a single string, undef otherwise
in which case you could check \f(CW\*(C`$mail\->error\*(C'\fR.
.IP "\fBstore_entity_body(n, handle => \s-1FILEHANDLE\s0)\fR" 4
.IX Item "store_entity_body(n, handle => FILEHANDLE)"
Stores the stringified body of n\-th entity to the specified filehandle. That's
basically the same as:
.Sp
.Vb 2
\& my $body = $mail\->get_entity_body(0);
\& print FILEHANDLE $body;
.Ve
.Sp
and could be shortened to this:
.Sp
.Vb 1
\& $mail\->store_entity_body(0, handle => \e*FILEHANDLE);
.Ve
.Sp
It returns a true value on success and undef on failure. In this case, examine
the value of \f(CW$mail\fR\->error since the entity you specified with 'n' might not
exist.
.IP "\fBstore_attachment(n)\fR" 4
.IX Item "store_attachment(n)"
.PD 0
.IP "\fBstore_attachment(n, options)\fR" 4
.IX Item "store_attachment(n, options)"
.PD
It is really just a call to store_entity_body but it will take care that the
n\-th entity really is a saveable attachment. That is, it wont save anything
with a MIME-type of, say, text/html or so.
.Sp
Unless further 'options' have been given, an attachment (if found) is stored
into the current directory under the recommended filename given in the
MIME-header. 'options' are specified in key/value pairs:
.Sp
.Vb 10
\&    key:       | value:        | description:
\&    ===========|================|===============================
\&    path       | relative or    | directory to store attachment
\&    (".")      | absolute       |
\&               | path           |
\&    \-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    encode     | encoding       | Some platforms store files 
\&               | suitable for   | in e.g. UTF\-8. Specify the
\&               | Encode::encode | appropriate encoding here and
\&               |                | and the filename will be en\-
\&               |                | coded accordingly.
\&    \-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    store_only | a compiled     | store only files whose file
\&               | regex\-pattern  | names match this pattern
\&    \-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    code       | an anonym      | first argument will be the 
\&               | subroutine     | $msg\-object, second one the 
\&               |                | index\-number of the current
\&               |                | MIME\-part
\&               |                | should return a filename for
\&               |                | the attachment
\&    \-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    prefix     | prefix for     | all filenames are prefixed
\&               | filenames      | with this value
\&    \-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&    args       | additional     | this array\-ref will be passed  
\&               | arguments as   | on to the \*(Aqcode\*(Aq subroutine
\&               | array\-ref      | as a dereferenced array
.Ve
.Sp
Example:
.Sp
.Vb 7
\&        $msg\->store_attachment(1, 
\&                            path => "/home/ethan/", 
\&                            code => sub {
\&                                        my ($msg, $n, @args) = @_;
\&                                        return $msg\->id."+$n";
\&                                        },
\&                            args => [ "Foo", "Bar" ]);
.Ve
.Sp
This will save the attachment found in the second entity under the name that
consists of the message-ID and the appendix \*(L"+1\*(R" since the above code works on
the second entity (that is, with index = 1). 'args' isn't used in this example
but should demonstrate how to pass additional arguments. Inside the 'code' sub,
\&\f(CW@args\fR equals (\*(L"Foo\*(R", \*(L"Bar\*(R").
.Sp
If 'path' does not exist, it will try to create the directory for you.
.Sp
You can specify to save only files matching a certain pattern. To do that, use
the store-only switch:
.Sp
.Vb 2
\&    $msg\->store_attachment(1, path       => "/home/ethan/", 
\&                              store_only => qr/\e.jpg$/i);
.Ve
.Sp
The above will only save files that end on '.jpg', not case-sensitive. You
could also use a non-compiled pattern if you want, but that would make for
instance case-insensitive matching a little cumbersome:
.Sp
.Vb 1
\&    store_only => \*(Aq(?i)\e.jpg$\*(Aq
.Ve
.Sp
If you are working on a platform that requires a certain encoding for filenames
on disk, you can use the 'encode' option. This becomes necessary for instance on
Mac \s-1OS\s0 X which internally is \s-1UTF\-8\s0 based. If the filename contains 8bit characters 
(like the German umlauts or French accented characters as in 'e\*''), storing the
attachment under a non-encoded name will most likely fail. In this case, use something 
like this:
.Sp
.Vb 1
\&    $msg\->store_attachment(1, path => \*(Aq/tmp\*(Aq, encode => \*(Aqutf\-8\*(Aq);
.Ve
.Sp
See Encode::Supported for a list of encodings that you may use.
.Sp
Returns the filename under which the attachment has been saved. undef is
returned in case the entity did not contain a saveable attachment, there was
no such entity at all or there was something wrong with the 'path' you
specified. Check \f(CW\*(C`$mail\->error\*(C'\fR to find out which of these possibilities
apply.
.IP "\fBstore_all_attachments\fR" 4
.IX Item "store_all_attachments"
.PD 0
.IP "\fBstore_all_attachments(options)\fR" 4
.IX Item "store_all_attachments(options)"
.PD
Walks through an entire mail and stores all apparent attachments. 'options' are
exactly the same as in \f(CW\*(C`store_attachment()\*(C'\fR with the same behaviour if no
options are given.
.Sp
Returns a list of files that have been successfully saved and an empty list if
no attachment could be extracted.
.Sp
\&\f(CW\*(C`$mail\->error\*(C'\fR will tell you possible failures and a possible explanation
for that.
.IP "\fBget_attachments\fR" 4
.IX Item "get_attachments"
.PD 0
.IP "\fBget_attachments(file)\fR" 4
.IX Item "get_attachments(file)"
.PD
This method returns a mapping from attachment-names (if those are saveable) to
index-numbers of the MIME-part that represents this attachment. It returns a
hash-reference, the file-names being the key and the index the value:
.Sp
.Vb 4
\&    my $mapping = $msg\->get_attachments;
\&    for my $filename (keys %$mapping) {
\&        print "$filename => $mapping\->{$filename}\en";
\&    }
.Ve
.Sp
If called with a string as argument, it tries to look up this filename. If it
can't be found, undef is returned. In this case you also should have an
error-message patiently awaiting you in the return value of
\&\f(CW\*(C`$mail\->error\*(C'\fR.
.Sp
Even though it looks tempting, don't do the following:
.Sp
.Vb 1
\&    # BAD!
\&
\&    for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
\&        print "$file is in message ", $msg\->id, "\en"  
\&            if defined $msg\->get_attachments($file);
\&    }
.Ve
.Sp
The reason is that \f(CW\*(C`get_attachments()\*(C'\fR is currently \fBnot\fR optimized to cache
the filename mapping. So, each time you call it on (even the same) message, it
will scan it from beginning to end. Better would be:
.Sp
.Vb 1
\&    # GOOD!
\&
\&    my $mapping = $msg\->get_attachments;
\&    for my $file (qw/file1.ext file2.ext file3.ext file4.ext/) {
\&        print "$file is in message ", $msg\->id, "\en" 
\&            if exists $mapping\->{$file};
\&    }
.Ve
.IP "\fBas_string\fR" 4
.IX Item "as_string"
Returns the message as one string. This is the method that string overloading
depends on, so these two are the same:
.Sp
.Vb 1
\&    print $msg;
\&    
\&    print $msg\->as_string;
.Ve
.SH "EXTERNAL METHODS"
.IX Header "EXTERNAL METHODS"
Mail::MboxParser::Mail implements an autoloader that will do the appropriate
type-casts for you if you invoke methods from external modules. This, however,
currently only works with MIME::Entity. Support for other modules will follow.
Example:
.PP
.Vb 4
\&        my $mb = Mail::MboxParser\->new("/home/user/Mail/received");
\&        for my $msg ($mb\->get_messages) {
\&                print $msg\->effective_type, "\en";
\&        }
.Ve
.PP
\&\f(CW\*(C`effective_type()\*(C'\fR is not implemented by Mail::MboxParser::Mail and thus the
corresponding method of MIME::Entity is automatically called.
.PP
To learn about what methods might be useful for you, you should read the
\&\*(L"Access\*(R"\-part of the section \*(L"\s-1PUBLIC\s0 \s-1INTERFACE\s0\*(R" in the MIME::Entity manpage.
It may become handy if you have mails with a lot of MIME-parts and you not just
want to handle binary-attachments but any kind of MIME-data.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
Mail::MboxParser::Mail overloads the \*(L" \*(R" operator. Overloading operators is a
fancy feature of Perl and some other languages (\*(C+ for instance) which will
change the behaviour of an object when one of those overloaded operators is
applied onto it. Here you get the stringified mail when you write \f(CW$mail\fR
while otherwise you'd get the stringified reference:
\&\f(CW\*(C`Mail::MboxParser::Mail=HASH(...)\*(C'\fR.
.SH "VERSION"
.IX Header "VERSION"
This is version 0.55.
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
Tassilo von Parseval <tassilo.von.parseval@rwth\-aachen.de>
.PP
Copyright (c)  2001\-2005 Tassilo von Parseval.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
MIME::Entity
.PP
Mail::MboxParser, Mail::MboxParser::Mail::Body, Mail::MboxParser::Mail::Convertable