.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "MIME::Head 3pm"
.TH MIME::Head 3pm "2013-11-14" "perl v5.18.1" "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"
MIME::Head \- MIME message header (a subclass of Mail::Header)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Before reading further, you should see MIME::Tools to make sure that
you understand where this module fits into the grand scheme of things.
Go on, do it now.  I'll wait.
.PP
Ready?  Ok...
.SS "Construction"
.IX Subsection "Construction"
.Vb 4
\&    ### Create a new, empty header, and populate it manually:
\&    $head = MIME::Head\->new;
\&    $head\->replace(\*(Aqcontent\-type\*(Aq, \*(Aqtext/plain; charset=US\-ASCII\*(Aq);
\&    $head\->replace(\*(Aqcontent\-length\*(Aq, $len);
\&
\&    ### Parse a new header from a filehandle:
\&    $head = MIME::Head\->read(\e*STDIN);
\&
\&    ### Parse a new header from a file, or a readable pipe:
\&    $testhead = MIME::Head\->from_file("/tmp/test.hdr");
\&    $a_b_head = MIME::Head\->from_file("cat a.hdr b.hdr |");
.Ve
.SS "Output"
.IX Subsection "Output"
.Vb 2
\&    ### Output to filehandle:
\&    $head\->print(\e*STDOUT);
\&
\&    ### Output as string:
\&    print STDOUT $head\->as_string;
\&    print STDOUT $head\->stringify;
.Ve
.SS "Getting field contents"
.IX Subsection "Getting field contents"
.Vb 2
\&    ### Is this a reply?
\&    $is_reply = 1 if ($head\->get(\*(AqSubject\*(Aq) =~ /^Re: /);
\&
\&    ### Get receipt information:
\&    print "Last received from: ", $head\->get(\*(AqReceived\*(Aq, 0);
\&    @all_received = $head\->get(\*(AqReceived\*(Aq);
\&
\&    ### Print the subject, or the empty string if none:
\&    print "Subject: ", $head\->get(\*(AqSubject\*(Aq,0);
\&
\&    ### Too many hops?  Count \*(Aqem and see!
\&    if ($head\->count(\*(AqReceived\*(Aq) > 5) { ...
\&
\&    ### Test whether a given field exists
\&    warn "missing subject!" if (! $head\->count(\*(Aqsubject\*(Aq));
.Ve
.SS "Setting field contents"
.IX Subsection "Setting field contents"
.Vb 2
\&    ### Declare this to be an HTML header:
\&    $head\->replace(\*(AqContent\-type\*(Aq, \*(Aqtext/html\*(Aq);
.Ve
.SS "Manipulating field contents"
.IX Subsection "Manipulating field contents"
.Vb 2
\&    ### Get rid of internal newlines in fields:
\&    $head\->unfold;
\&
\&    ### Decode any Q\- or B\-encoded\-text in fields (DEPRECATED):
\&    $head\->decode;
.Ve
.SS "Getting high-level \s-1MIME\s0 information"
.IX Subsection "Getting high-level MIME information"
.Vb 4
\&    ### Get/set a given MIME attribute:
\&    unless ($charset = $head\->mime_attr(\*(Aqcontent\-type.charset\*(Aq)) {
\&        $head\->mime_attr("content\-type.charset" => "US\-ASCII");
\&    }
\&
\&    ### The content type (e.g., "text/html"):
\&    $mime_type     = $head\->mime_type;
\&
\&    ### The content transfer encoding (e.g., "quoted\-printable"):
\&    $mime_encoding = $head\->mime_encoding;
\&
\&    ### The recommended name when extracted:
\&    $file_name     = $head\->recommended_filename;
\&
\&    ### The boundary text, for multipart messages:
\&    $boundary      = $head\->multipart_boundary;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A class for parsing in and manipulating \s-1RFC\-822\s0 message headers, with
some methods geared towards standard (and not so standard) \s-1MIME\s0 fields
as specified in the various \fIMultipurpose Internet Mail Extensions\fR
RFCs (starting with \s-1RFC 2045\s0)
.SH "PUBLIC INTERFACE"
.IX Header "PUBLIC INTERFACE"
.SS "Creation, input, and output"
.IX Subsection "Creation, input, and output"
.IP "new [\s-1ARG\s0],[\s-1OPTIONS\s0]" 4
.IX Item "new [ARG],[OPTIONS]"
\&\fIClass method, inherited.\fR
Creates a new header object.  Arguments are the same as those in the
superclass.
.IP "from_file \s-1EXPR,OPTIONS\s0" 4
.IX Item "from_file EXPR,OPTIONS"
\&\fIClass or instance method\fR.
For convenience, you can use this to parse a header object in from \s-1EXPR,\s0
which may actually be any expression that can be sent to \fIopen()\fR so as to
return a readable filehandle.  The \*(L"file\*(R" will be opened, read, and then
closed:
.Sp
.Vb 2
\&    ### Create a new header by parsing in a file:
\&    my $head = MIME::Head\->from_file("/tmp/test.hdr");
.Ve
.Sp
Since this method can function as either a class constructor \fIor\fR
an instance initializer, the above is exactly equivalent to:
.Sp
.Vb 2
\&    ### Create a new header by parsing in a file:
\&    my $head = MIME::Head\->new\->from_file("/tmp/test.hdr");
.Ve
.Sp
On success, the object will be returned; on failure, the undefined value.
.Sp
The \s-1OPTIONS\s0 are the same as in \fInew()\fR, and are passed into \fInew()\fR
if this is invoked as a class method.
.Sp
\&\fBNote:\fR This is really just a convenience front-end onto \f(CW\*(C`read()\*(C'\fR,
provided mostly for backwards-compatibility with MIME-parser 1.0.
.IP "read \s-1FILEHANDLE\s0" 4
.IX Item "read FILEHANDLE"
\&\fIInstance (or class) method.\fR
This initializes a header object by reading it in from a \s-1FILEHANDLE,\s0
until the terminating blank line is encountered.
A syntax error or end-of-stream will also halt processing.
.Sp
Supply this routine with a reference to a filehandle glob; e.g., \f(CW\*(C`\e*STDIN\*(C'\fR:
.Sp
.Vb 2
\&    ### Create a new header by parsing in STDIN:
\&    $head\->read(\e*STDIN);
.Ve
.Sp
On success, the self object will be returned; on failure, a false value.
.Sp
\&\fBNote:\fR in the \s-1MIME\s0 world, it is perfectly legal for a header to be
empty, consisting of nothing but the terminating blank line.  Thus,
we can't just use the formula that \*(L"no tags equals error\*(R".
.Sp
\&\fBWarning:\fR as of the time of this writing, Mail::Header::read did not flag
either syntax errors or unexpected end-of-file conditions (an \s-1EOF\s0
before the terminating blank line).  MIME::ParserBase takes this
into account.
.SS "Getting/setting fields"
.IX Subsection "Getting/setting fields"
The following are methods related to retrieving and modifying the header
fields.  Some are inherited from Mail::Header, but I've kept the
documentation around for convenience.
.IP "add \s-1TAG,TEXT\s0,[\s-1INDEX\s0]" 4
.IX Item "add TAG,TEXT,[INDEX]"
\&\fIInstance method, inherited.\fR
Add a new occurrence of the field named \s-1TAG,\s0 given by \s-1TEXT:\s0
.Sp
.Vb 3
\&    ### Add the trace information:
\&    $head\->add(\*(AqReceived\*(Aq,
\&               \*(Aqfrom eryq.pr.mcs.net by gonzo.net with smtp\*(Aq);
.Ve
.Sp
Normally, the new occurrence will be \fIappended\fR to the existing
occurrences.  However, if the optional \s-1INDEX\s0 argument is 0, then the
new occurrence will be \fIprepended\fR.  If you want to be \fIexplicit\fR
about appending, specify an \s-1INDEX\s0 of \-1.
.Sp
\&\fBWarning\fR: this method always adds new occurrences; it doesn't overwrite
any existing occurrences... so if you just want to \fIchange\fR the value
of a field (creating it if necessary), then you probably \fBdon't\fR want to use
this method: consider using \f(CW\*(C`replace()\*(C'\fR instead.
.IP "count \s-1TAG\s0" 4
.IX Item "count TAG"
\&\fIInstance method, inherited.\fR
Returns the number of occurrences of a field; in a boolean context, this
tells you whether a given field exists:
.Sp
.Vb 2
\&    ### Was a "Subject:" field given?
\&    $subject_was_given = $head\->count(\*(Aqsubject\*(Aq);
.Ve
.Sp
The \s-1TAG\s0 is treated in a case-insensitive manner.
This method returns some false value if the field doesn't exist,
and some true value if it does.
.IP "decode [\s-1FORCE\s0]" 4
.IX Item "decode [FORCE]"
\&\fIInstance method, \s-1DEPRECATED.\s0\fR
Go through all the header fields, looking for \s-1RFC 1522 / RFC 2047\s0 style
\&\*(L"Q\*(R" (quoted-printable, sort of) or \*(L"B\*(R" (base64) encoding, and decode
them in-place.  Fellow Americans, you probably don't know what the hell
I'm talking about.  Europeans, Russians, et al, you probably do.
\&\f(CW\*(C`:\-)\*(C'\fR.
.Sp
\&\fBThis method has been deprecated.\fR
See \*(L"decode_headers\*(R" in MIME::Parser for the full reasons.
If you absolutely must use it and don't like the warning, then
provide a \s-1FORCE:\s0
.Sp
.Vb 3
\&   "I_NEED_TO_FIX_THIS"
\&          Just shut up and do it.  Not recommended.
\&          Provided only for those who need to keep old scripts functioning.
\&
\&   "I_KNOW_WHAT_I_AM_DOING"
\&          Just shut up and do it.  Not recommended.
\&          Provided for those who REALLY know what they are doing.
.Ve
.Sp
\&\fBWhat this method does.\fR
For an example, let's consider a valid email header you might get:
.Sp
.Vb 6
\&    From: =?US\-ASCII?Q?Keith_Moore?= <moore@cs.utk.edu>
\&    To: =?ISO\-8859\-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
\&    CC: =?ISO\-8859\-1?Q?Andr=E9_?= Pirard <PIRARD@vm1.ulg.ac.be>
\&    Subject: =?ISO\-8859\-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=
\&     =?ISO\-8859\-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?=
\&     =?US\-ASCII?Q?.._cool!?=
.Ve
.Sp
That basically decodes to (sorry, I can only approximate the
Latin characters with 7 bit sequences /o and 'e):
.Sp
.Vb 4
\&    From: Keith Moore <moore@cs.utk.edu>
\&    To: Keld J/orn Simonsen <keld@dkuug.dk>
\&    CC: Andr\*(Aqe  Pirard <PIRARD@vm1.ulg.ac.be>
\&    Subject: If you can read this you understand the example... cool!
.Ve
.Sp
\&\fBNote:\fR currently, the decodings are done without regard to the
character set: thus, the Q\-encoding \f(CW\*(C`=F8\*(C'\fR is simply translated to the
octet (hexadecimal \f(CW\*(C`F8\*(C'\fR), period.  For piece-by-piece decoding
of a given field, you want the array context of
\&\f(CW\*(C`MIME::Words::decode_mimewords()\*(C'\fR.
.Sp
\&\fBWarning:\fR the \s-1CRLF+SPACE\s0 separator that splits up long encoded words
into shorter sequences (see the Subject: example above) gets lost
when the field is unfolded, and so decoding after unfolding causes
a spurious space to be left in the field.
\&\fI\s-1THEREFORE:\s0 if you're going to decode, do so \s-1BEFORE\s0 unfolding!\fR
.Sp
This method returns the self object.
.Sp
\&\fIThanks to Kent Boortz for providing the idea, and the baseline
RFC\-1522\-decoding code.\fR
.IP "delete \s-1TAG\s0,[\s-1INDEX\s0]" 4
.IX Item "delete TAG,[INDEX]"
\&\fIInstance method, inherited.\fR
Delete all occurrences of the field named \s-1TAG.\s0
.Sp
.Vb 3
\&    ### Remove some MIME information:
\&    $head\->delete(\*(AqMIME\-Version\*(Aq);
\&    $head\->delete(\*(AqContent\-type\*(Aq);
.Ve
.IP "get \s-1TAG\s0,[\s-1INDEX\s0]" 4
.IX Item "get TAG,[INDEX]"
\&\fIInstance method, inherited.\fR
Get the contents of field \s-1TAG.\s0
.Sp
If a \fBnumeric \s-1INDEX\s0\fR is given, returns the occurrence at that index,
or undef if not present:
.Sp
.Vb 3
\&    ### Print the first and last \*(AqReceived:\*(Aq entries (explicitly):
\&    print "First, or most recent: ", $head\->get(\*(Aqreceived\*(Aq, 0);
\&    print "Last, or least recent: ", $head\->get(\*(Aqreceived\*(Aq,\-1);
.Ve
.Sp
If \fBno \s-1INDEX\s0\fR is given, but invoked in a \fBscalar\fR context, then
\&\s-1INDEX\s0 simply defaults to 0:
.Sp
.Vb 2
\&    ### Get the first \*(AqReceived:\*(Aq entry (implicitly):
\&    my $most_recent = $head\->get(\*(Aqreceived\*(Aq);
.Ve
.Sp
If \fBno \s-1INDEX\s0\fR is given, and invoked in an \fBarray\fR context, then
\&\fIall\fR occurrences of the field are returned:
.Sp
.Vb 2
\&    ### Get all \*(AqReceived:\*(Aq entries:
\&    my @all_received = $head\->get(\*(Aqreceived\*(Aq);
.Ve
.Sp
\&\fB\s-1NOTE\s0\fR: The header(s) returned may end with a newline.  If you don't
want this, then \fBchomp\fR the return value.
.IP "get_all \s-1FIELD\s0" 4
.IX Item "get_all FIELD"
\&\fIInstance method.\fR
Returns the list of \fIall\fR occurrences of the field, or the
empty list if the field is not present:
.Sp
.Vb 2
\&    ### How did it get here?
\&    @history = $head\->get_all(\*(AqReceived\*(Aq);
.Ve
.Sp
\&\fBNote:\fR I had originally experimented with having \f(CW\*(C`get()\*(C'\fR return all
occurrences when invoked in an array context... but that causes a lot of
accidents when you get careless and do stuff like this:
.Sp
.Vb 1
\&    print "\eu$field: ", $head\->get($field);
.Ve
.Sp
It also made the intuitive behaviour unclear if the \s-1INDEX\s0 argument
was given in an array context.  So I opted for an explicit approach
to asking for all occurrences.
.IP "print [\s-1OUTSTREAM\s0]" 4
.IX Item "print [OUTSTREAM]"
\&\fIInstance method, override.\fR
Print the header out to the given \s-1OUTSTREAM,\s0 or the currently-selected
filehandle if none.  The \s-1OUTSTREAM\s0 may be a filehandle, or any object
that responds to a \fIprint()\fR message.
.Sp
The override actually lets you print to any object that responds to
a \fIprint()\fR method.  This is vital for outputting \s-1MIME\s0 entities to scalars.
.Sp
Also, it defaults to the \fIcurrently-selected\fR filehandle if none is given
(not \s-1STDOUT\s0!), so \fIplease\fR supply a filehandle to prevent confusion.
.IP "stringify" 4
.IX Item "stringify"
\&\fIInstance method.\fR
Return the header as a string.  You can also invoke it as \f(CW\*(C`as_string\*(C'\fR.
.IP "unfold [\s-1FIELD\s0]" 4
.IX Item "unfold [FIELD]"
\&\fIInstance method, inherited.\fR
Unfold (remove newlines in) the text of all occurrences of the given \s-1FIELD.\s0
If the \s-1FIELD\s0 is omitted, \fIall\fR fields are unfolded.
Returns the \*(L"self\*(R" object.
.SS "MIME-specific methods"
.IX Subsection "MIME-specific methods"
All of the following methods extract information from the following fields:
.PP
.Vb 3
\&    Content\-type
\&    Content\-transfer\-encoding
\&    Content\-disposition
.Ve
.PP
Be aware that they do not just return the raw contents of those fields,
and in some cases they will fill in sensible (I hope) default values.
Use \f(CW\*(C`get()\*(C'\fR or \f(CW\*(C`mime_attr()\*(C'\fR if you need to grab and process the
raw field text.
.PP
\&\fBNote:\fR some of these methods are provided both as a convenience and
for backwards-compatibility only, while others (like
\&\fIrecommended_filename()\fR) \fIreally do have to be in MIME::Head to work
properly,\fR since they look for their value in more than one field.
However, if you know that a value is restricted to a single
field, you should really use the Mail::Field interface to get it.
.IP "mime_attr \s-1ATTR\s0,[\s-1VALUE\s0]" 4
.IX Item "mime_attr ATTR,[VALUE]"
A quick-and-easy interface to set/get the attributes in structured
\&\s-1MIME\s0 fields:
.Sp
.Vb 3
\&    $head\->mime_attr("content\-type"         => "text/html");
\&    $head\->mime_attr("content\-type.charset" => "US\-ASCII");
\&    $head\->mime_attr("content\-type.name"    => "homepage.html");
.Ve
.Sp
This would cause the final output to look something like this:
.Sp
.Vb 1
\&    Content\-type: text/html; charset=US\-ASCII; name="homepage.html"
.Ve
.Sp
Note that the special empty sub-field tag indicates the anonymous
first sub-field.
.Sp
\&\fBGiving \s-1VALUE\s0 as undefined\fR will cause the contents of the named subfield
to be deleted:
.Sp
.Vb 1
\&    $head\->mime_attr("content\-type.charset" => undef);
.Ve
.Sp
\&\fBSupplying no \s-1VALUE\s0 argument\fR just returns the attribute's value,
or undefined if it isn't there:
.Sp
.Vb 2
\&    $type = $head\->mime_attr("content\-type");      ### text/html
\&    $name = $head\->mime_attr("content\-type.name"); ### homepage.html
.Ve
.Sp
In all cases, the new/current value is returned.
.IP "mime_encoding" 4
.IX Item "mime_encoding"
\&\fIInstance method.\fR
Try \fIreal hard\fR to determine the content transfer encoding
(e.g., \f(CW"base64"\fR, \f(CW"binary"\fR), which is returned in all-lowercase.
.Sp
If no encoding could be found, the default of \f(CW"7bit"\fR is returned
I quote from \s-1RFC 2045\s0 section 6.1:
.Sp
.Vb 2
\&    This is the default value \-\- that is, "Content\-Transfer\-Encoding: 7BIT"
\&    is assumed if the Content\-Transfer\-Encoding header field is not present.
.Ve
.Sp
I do one other form of fixup: \*(L"7_bit\*(R", \*(L"7\-bit\*(R", and \*(L"7 bit\*(R" are
corrected to \*(L"7bit\*(R"; likewise for \*(L"8bit\*(R".
.IP "mime_type [\s-1DEFAULT\s0]" 4
.IX Item "mime_type [DEFAULT]"
\&\fIInstance method.\fR
Try \f(CW\*(C`real hard\*(C'\fR to determine the content type (e.g., \f(CW"text/plain"\fR,
\&\f(CW"image/gif"\fR, \f(CW"x\-weird\-type"\fR, which is returned in all-lowercase.
\&\*(L"Real hard\*(R" means that if no content type could be found, the default
(usually \f(CW"text/plain"\fR) is returned.  From \s-1RFC 2045\s0 section 5.2:
.Sp
.Vb 3
\&   Default RFC 822 messages without a MIME Content\-Type header are
\&   taken by this protocol to be plain text in the US\-ASCII character
\&   set, which can be explicitly specified as:
\&
\&      Content\-type: text/plain; charset=us\-ascii
\&
\&   This default is assumed if no Content\-Type header field is specified.
.Ve
.Sp
Unless this is a part of a \*(L"multipart/digest\*(R", in which case
\&\*(L"message/rfc822\*(R" is the default.  Note that you can also \fIset\fR the
default, but you shouldn't: normally only the \s-1MIME\s0 parser uses this
feature.
.IP "multipart_boundary" 4
.IX Item "multipart_boundary"
\&\fIInstance method.\fR
If this is a header for a multipart message, return the
\&\*(L"encapsulation boundary\*(R" used to separate the parts.  The boundary
is returned exactly as given in the \f(CW\*(C`Content\-type:\*(C'\fR field; that
is, the leading double-hyphen (\f(CW\*(C`\-\-\*(C'\fR) is \fInot\fR prepended.
.Sp
Well, \fIalmost\fR exactly... this passage from \s-1RFC 2046\s0 dictates
that we remove any trailing spaces:
.Sp
.Vb 2
\&   If a boundary appears to end with white space, the white space
\&   must be presumed to have been added by a gateway, and must be deleted.
.Ve
.Sp
Returns undef (\fBnot\fR the empty string) if either the message is not
multipart or if there is no specified boundary.
.IP "recommended_filename" 4
.IX Item "recommended_filename"
\&\fIInstance method.\fR
Return the recommended external filename.  This is used when
extracting the data from the \s-1MIME\s0 stream.  The filename is always
returned as a string in Perl's internal format (the \s-1UTF8\s0 flag may be on!)
.Sp
Returns undef if no filename could be suggested.
.SH "NOTES"
.IX Header "NOTES"
.IP "Why have separate objects for the entity, head, and body?" 4
.IX Item "Why have separate objects for the entity, head, and body?"
See the documentation for the MIME-tools distribution
for the rationale behind this decision.
.IP "Why assume that \s-1MIME\s0 headers are email headers?" 4
.IX Item "Why assume that MIME headers are email headers?"
I quote from Achim Bohnet, who gave feedback on v.1.9 (I think
he's using the word \*(L"header\*(R" where I would use \*(L"field\*(R"; e.g.,
to refer to \*(L"Subject:\*(R", \*(L"Content-type:\*(R", etc.):
.Sp
.Vb 3
\&    There is also IMHO no requirement [for] MIME::Heads to look
\&    like [email] headers; so to speak, the MIME::Head [simply stores]
\&    the attributes of a complex object, e.g.:
\&
\&        new MIME::Head type => "text/plain",
\&                       charset => ...,
\&                       disposition => ..., ... ;
.Ve
.Sp
I agree in principle, but (alas and dammit) \s-1RFC 2045\s0 says otherwise.
\&\s-1RFC 2045\s0 [\s-1MIME\s0] headers are a syntactic subset of \s-1RFC\-822\s0 [email] headers.
.Sp
In my mind's eye, I see an abstract class, call it MIME::Attrs, which does
what Achim suggests... so you could say:
.Sp
.Vb 3
\&     my $attrs = new MIME::Attrs type => "text/plain",
\&                                 charset => ...,
\&                                 disposition => ..., ... ;
.Ve
.Sp
We could even make it a superclass of MIME::Head: that way, MIME::Head
would have to implement its interface, \fIand\fR allow itself to be
initialized from a MIME::Attrs object.
.Sp
However, when you read \s-1RFC 2045,\s0 you begin to see how much \s-1MIME\s0 information
is organized by its presence in particular fields.  I imagine that we'd
begin to mirror the structure of \s-1RFC 2045\s0 fields and subfields to such
a degree that this might not give us a tremendous gain over just
having MIME::Head.
.ie n .IP "Why all this ""occurrence"" and ""index"" jazz?  Isn't every field unique?" 4
.el .IP "Why all this ``occurrence'' and ``index'' jazz?  Isn't every field unique?" 4
.IX Item "Why all this occurrence and index jazz? Isn't every field unique?"
Aaaaaaaaaahh....no.
.Sp
Looking at a typical mail message header, it is sooooooo tempting to just
store the fields as a hash of strings, one string per hash entry.
Unfortunately, there's the little matter of the \f(CW\*(C`Received:\*(C'\fR field,
which (unlike \f(CW\*(C`From:\*(C'\fR, \f(CW\*(C`To:\*(C'\fR, etc.) will often have multiple
occurrences; e.g.:
.Sp
.Vb 10
\&    Received: from gsfc.nasa.gov by eryq.pr.mcs.net  with smtp
\&        (Linux Smail3.1.28.1 #5) id m0tStZ7\-0007X4C;
\&         Thu, 21 Dec 95 16:34 CST
\&    Received: from rhine.gsfc.nasa.gov by gsfc.nasa.gov
\&         (5.65/Ultrix3.0\-C) id AA13596;
\&         Thu, 21 Dec 95 17:20:38 \-0500
\&    Received: (from eryq@localhost) by rhine.gsfc.nasa.gov
\&         (8.6.12/8.6.12) id RAA28069;
\&         Thu, 21 Dec 1995 17:27:54 \-0500
\&    Date: Thu, 21 Dec 1995 17:27:54 \-0500
\&    From: Eryq <eryq@rhine.gsfc.nasa.gov>
\&    Message\-Id: <199512212227.RAA28069@rhine.gsfc.nasa.gov>
\&    To: eryq@eryq.pr.mcs.net
\&    Subject: Stuff and things
.Ve
.Sp
The \f(CW\*(C`Received:\*(C'\fR field is used for tracing message routes, and although
it's not generally used for anything other than human debugging, I
didn't want to inconvenience anyone who actually wanted to get at that
information.
.Sp
I also didn't want to make this a special case; after all, who
knows what other fields could have multiple occurrences in the
future?  So, clearly, multiple entries had to somehow be stored
multiple times... and the different occurrences had to be retrievable.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::Header, Mail::Field, MIME::Words, MIME::Tools
.SH "AUTHOR"
.IX Header "AUTHOR"
Eryq (\fIeryq@zeegee.com\fR), ZeeGee Software Inc (\fIhttp://www.zeegee.com\fR).
David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
.PP
All rights reserved.  This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The more-comprehensive filename extraction is courtesy of
Lee E. Brotzman, Advanced Data Solutions.