.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Mail::Message::Head::Complete 3pm"
.TH Mail::Message::Head::Complete 3pm "2016-12-27" "perl v5.24.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"
Mail::Message::Head::Complete \- the header of one message
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 3
\& Mail::Message::Head::Complete
\&   is a Mail::Message::Head
\&   is a Mail::Reporter
\&
\& Mail::Message::Head::Complete is extended by
\&   Mail::Message::Head::Partial
\&   Mail::Message::Replace::MailHeader
\&
\& Mail::Message::Head::Complete is realized by
\&   Mail::Message::Head::Delayed
\&   Mail::Message::Head::Subset
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& my $head = Mail::Message::Head::Complete\->new;
\& See Mail::Message::Head
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
E\-mail's message can be in various states: unread, partially read, and
fully read.  The class stores a message of which all header lines are
known for sure.
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Mail::Message::Head.
.SH "OVERLOADED"
.IX Header "OVERLOADED"
Extends \*(L"\s-1OVERLOADED\*(R"\s0 in Mail::Message::Head.
.ie n .IP "overload: \fB""""\fR" 4
.el .IP "overload: \fB``''\fR" 4
.IX Item "overload: """""
Inherited, see \*(L"\s-1OVERLOADED\*(R"\s0 in Mail::Message::Head
.IP "overload: \fBbool\fR" 4
.IX Item "overload: bool"
Inherited, see \*(L"\s-1OVERLOADED\*(R"\s0 in Mail::Message::Head
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Mail::Message::Head.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fBbuild\fR( [PAIR|$field], ... )" 4
.el .IP "\f(CW$obj\fR\->\fBbuild\fR( [PAIR|$field], ... )" 4
.IX Item "$obj->build( [PAIR|$field], ... )"
Undefined values are interpreted as empty field values, and therefore skipped.
.ie n .IP "$obj\->\fBclone\fR( [@names|ARRAY|Regexps] )" 4
.el .IP "\f(CW$obj\fR\->\fBclone\fR( [@names|ARRAY|Regexps] )" 4
.IX Item "$obj->clone( [@names|ARRAY|Regexps] )"
Make a copy of the header, optionally limited only to the header lines
specified by \f(CW@names\fR.  See \fIgrepNames()\fR on the way these fields can be
used.
.Sp
example:
.Sp
.Vb 1
\& my $newhead = $head\->clone(\*(AqSubject\*(Aq, \*(AqReceived\*(Aq);
.Ve
.IP "Mail::Message::Head::Complete\->\fBnew\fR(%options)" 4
.IX Item "Mail::Message::Head::Complete->new(%options)"
Inherited, see \*(L"Constructors\*(R" in Mail::Message::Head
.SS "The header"
.IX Subsection "The header"
Extends \*(L"The header\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fBisDelayed\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisDelayed\fR()" 4
.IX Item "$obj->isDelayed()"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBisEmpty\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisEmpty\fR()" 4
.IX Item "$obj->isEmpty()"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBisModified\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisModified\fR()" 4
.IX Item "$obj->isModified()"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBknownNames\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBknownNames\fR()" 4
.IX Item "$obj->knownNames()"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBmessage\fR( [$message] )" 4
.el .IP "\f(CW$obj\fR\->\fBmessage\fR( [$message] )" 4
.IX Item "$obj->message( [$message] )"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBmodified\fR( [\s-1BOOLEAN\s0] )" 4
.el .IP "\f(CW$obj\fR\->\fBmodified\fR( [\s-1BOOLEAN\s0] )" 4
.IX Item "$obj->modified( [BOOLEAN] )"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBnrLines\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnrLines\fR()" 4
.IX Item "$obj->nrLines()"
Return the number of lines needed to display this header (including
the trailing newline)
.ie n .IP "$obj\->\fBorderedFields\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBorderedFields\fR()" 4
.IX Item "$obj->orderedFields()"
Inherited, see \*(L"The header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBsize\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBsize\fR()" 4
.IX Item "$obj->size()"
Return the number of bytes needed to display this header (including
the trailing newline).  On systems which use \s-1CRLF\s0 as line separator,
the number of lines in the header (see \fInrLines()\fR) must be added to
find the actual size in the file.
.ie n .IP "$obj\->\fBwrap\fR($integer)" 4
.el .IP "\f(CW$obj\fR\->\fBwrap\fR($integer)" 4
.IX Item "$obj->wrap($integer)"
Re-fold all fields from the header to contain at most \f(CW$integer\fR number of
characters per line.
.Sp
example: re-folding a header
.Sp
.Vb 1
\& $msg\->head\->wrap(78);
.Ve
.SS "Access to the header"
.IX Subsection "Access to the header"
Extends \*(L"Access to the header\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fBadd\fR( $field | $line | <$name, $body, [$attrs]> )" 4
.el .IP "\f(CW$obj\fR\->\fBadd\fR( \f(CW$field\fR | \f(CW$line\fR | <$name, \f(CW$body\fR, [$attrs]> )" 4
.IX Item "$obj->add( $field | $line | <$name, $body, [$attrs]> )"
Add a field to the header.  If a field is added more than once, all values
are stored in the header, in the order they are added.
.Sp
When a \f(CW$field\fR object is specified (some Mail::Message::Field instance), that
will be added.  Another possibility is to specify a raw header \f(CW$line\fR, or a
header line nicely split-up in \f(CW$name\fR and \f(CW$body\fR, in which case the
field constructor is called for you.
.Sp
\&\f(CW$line\fR or \f(CW$body\fR specifications which are terminated by a new-line are considered
to be correctly folded.  Lines which are not terminated by a new-line will
be folded when needed: new-lines will be added where required.  It is strongly
advised to let MailBox do the folding for you.
.Sp
The return value of this method is the Mail::Message::Field object
which is created (or was specified).
.Sp
example:
.Sp
.Vb 6
\& my $head  = Mail::Message::Head\->new;
\& $head\->add(\*(AqSubject: hi!\*(Aq);
\& $head\->add(From => \*(Aqme@home\*(Aq);
\& my $field = Mail::Message::Field\->new(\*(AqTo: you@there\*(Aq);
\& $head\->add($field);
\& my Mail::Message::Field $s = $head\->add(Sender => \*(AqI\*(Aq);
.Ve
.ie n .IP "$obj\->\fBaddListGroup\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddListGroup\fR($object)" 4
.IX Item "$obj->addListGroup($object)"
A \fIlist group\fR is a set of header fields which contain data about a
mailing list which was used to transmit the message.  See
Mail::Message::Head::ListGroup for details about the implementation
of the \f(CW$object\fR.
.Sp
When you have a list group prepared, you can add it later using this
method.  You will get your private copy of the list group data in
return, because the same group can be used for multiple messages.
.Sp
example: of adding a list group to a header
.Sp
.Vb 2
\& my $lg = Mail::Message::Head::ListGroup\->new(...);
\& my $own_lg = $msg\->head\->addListGroup($lg);
.Ve
.ie n .IP "$obj\->\fBaddResentGroup\fR($resent_group|$data)" 4
.el .IP "\f(CW$obj\fR\->\fBaddResentGroup\fR($resent_group|$data)" 4
.IX Item "$obj->addResentGroup($resent_group|$data)"
Add a \f(CW$resent_group\fR (a Mail::Message::Head::ResentGroup object) to
the header.  If you specify \f(CW$data\fR, that is used to create such group
first.  If no \f(CW\*(C`Received\*(C'\fR line is specified, it will be created
for you.
.Sp
These header lines have nothing to do with the user's sense
of \f(CW\*(C`reply\*(C'\fR or \f(CW\*(C`forward\*(C'\fR actions: these lines trace the e\-mail
transport mechanism.
.Sp
example:
.Sp
.Vb 2
\& my $rg = Mail::Message::Head::ResentGroup\->new(head => $head, ...);
\& $head\->addResentGroup($rg);
\&
\& my $rg = $head\->addResentGroup(From => \*(Aqme\*(Aq);
.Ve
.ie n .IP "$obj\->\fBaddSpamGroup\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddSpamGroup\fR($object)" 4
.IX Item "$obj->addSpamGroup($object)"
A \fIspam fighting group\fR is a set of header fields which contains data
which is used to fight spam.  See Mail::Message::Head::SpamGroup
for details about the implementation of the \f(CW$object\fR.
.Sp
When you have a spam group prepared, you can add it later using this
method.  You will get your private copy of the spam group data in
return, because the same group can be used for multiple messages.
.Sp
example: of adding a spam group to a header
.Sp
.Vb 2
\& my $sg = Mail::Message::Head::SpamGroup\->new(...);
\& my $own_sg = $msg\->head\->addSpamGroup($sg);
.Ve
.ie n .IP "$obj\->\fBcount\fR($name)" 4
.el .IP "\f(CW$obj\fR\->\fBcount\fR($name)" 4
.IX Item "$obj->count($name)"
Count the number of fields with this \f(CW$name\fR.  Most fields will return 1:
only one occurance in the header.  As example, the \f(CW\*(C`Received\*(C'\fR fields
are usually present more than once.
.ie n .IP "$obj\->\fBdelete\fR($name)" 4
.el .IP "\f(CW$obj\fR\->\fBdelete\fR($name)" 4
.IX Item "$obj->delete($name)"
Remove the field with the specified name.  If the header contained
multiple lines with the same name, they will be replaced all together.
This method simply calls \fIreset()\fR without replacement fields.
\&\s-1READ THE IMPORTANT WARNING IN \s0\fIremoveField()\fR
.ie n .IP "$obj\->\fBget\fR( $name, [$index] )" 4
.el .IP "\f(CW$obj\fR\->\fBget\fR( \f(CW$name\fR, [$index] )" 4
.IX Item "$obj->get( $name, [$index] )"
Inherited, see \*(L"Access to the header\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBgrepNames\fR( [@names|ARRAY|Regexps] )" 4
.el .IP "\f(CW$obj\fR\->\fBgrepNames\fR( [@names|ARRAY|Regexps] )" 4
.IX Item "$obj->grepNames( [@names|ARRAY|Regexps] )"
Filter from all header fields those with names which start will any of the
specified list.  When no names are specified, all fields will be returned.
The list is ordered as they where read from file, or added later.
.Sp
The \f(CW@names\fR are considered regular expressions, and will all be matched
case insensitive and attached to the front of the string only.  You may
also specify one or more prepared regexes.
.Sp
example:
.Sp
.Vb 3
\& my @f  = $head\->grepNames();       # same as $head\->orderedFields
\& my @f  = $head\->grepNames(\*(AqX\-\*(Aq, \*(AqSubject\*(Aq, \*(Aq);
\& my @to = $head\->grepNames(\*(AqTo\eb\*(Aq); # will only select To
.Ve
.ie n .IP "$obj\->\fBlistGroup\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlistGroup\fR()" 4
.IX Item "$obj->listGroup()"
Returns a \fIlist group\fR description: the set of headers which form
the information about mailing list software used to transport the
message.  See also \fIaddListGroup()\fR and \fIremoveListGroup()\fR.
.Sp
example: use of \fIlistGroup()\fR
.Sp
.Vb 4
\& if(my $lg = $msg\->head\->listGroup)
\& {  $lg\->print(\e*STDERR);
\&    $lg\->delete;
\& }
\&
\& $msg\->head\->removeListGroup;
.Ve
.ie n .IP "$obj\->\fBnames\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnames\fR()" 4
.IX Item "$obj->names()"
Returns a full ordered list of known field names, as defined in the
header.  Fields which were \fIreset()\fR to be empty will still be
listed here.
.ie n .IP "$obj\->\fBprint\fR( [$fh] )" 4
.el .IP "\f(CW$obj\fR\->\fBprint\fR( [$fh] )" 4
.IX Item "$obj->print( [$fh] )"
Print all headers to the specified \f(CW$fh\fR, by default the selected
filehandle.  See \fIprintUndisclosed()\fR to limit the headers to include
only the public headers.
.Sp
example:
.Sp
.Vb 2
\& $head\->print(\e*OUT);
\& $head\->print;
\&
\& my $fh = IO::File\->new(...);
\& $head\->print($fh);
.Ve
.ie n .IP "$obj\->\fBprintSelected\fR($fh, <STRING|Regexp>, ...)" 4
.el .IP "\f(CW$obj\fR\->\fBprintSelected\fR($fh, <STRING|Regexp>, ...)" 4
.IX Item "$obj->printSelected($fh, <STRING|Regexp>, ...)"
Like the usual \fIprint()\fR, the header lines are printed to the specified
\&\f(CW$fh\fR.  In this case, however, only the fields with names as specified by
\&\s-1STRING \s0(case insensative) or Regexp are printed.  They will stay the in-order
of the source header.
.Sp
example: printing only a subset of the fields
.Sp
.Vb 1
\& $head\->printSelected(STDOUT, qw/Subject From To/, qr/^x\e\-(spam|xyz)\e\-/i)
.Ve
.ie n .IP "$obj\->\fBprintUndisclosed\fR( [$fh] )" 4
.el .IP "\f(CW$obj\fR\->\fBprintUndisclosed\fR( [$fh] )" 4
.IX Item "$obj->printUndisclosed( [$fh] )"
Like the usual \fIprint()\fR, the header lines are printed to the specified
\&\f(CW$fh\fR, by default the selected filehandle.  In this case, however,
\&\f(CW\*(C`Bcc\*(C'\fR and \f(CW\*(C`Resent\-Bcc\*(C'\fR lines are included.
.ie n .IP "$obj\->\fBremoveContentInfo\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBremoveContentInfo\fR()" 4
.IX Item "$obj->removeContentInfo()"
Remove all body related fields from the header.  The header will become
partial.
.ie n .IP "$obj\->\fBremoveField\fR($field)" 4
.el .IP "\f(CW$obj\fR\->\fBremoveField\fR($field)" 4
.IX Item "$obj->removeField($field)"
Remove the specified \f(CW$field\fR object from the header.  This is useful when
there are possible more than one fields with the same name, and you
need to remove exactly one of them.  Also have a look at \fIdelete()\fR,
\&\fIreset()\fR, and \fIset()\fR.
.Sp
See also \fIMail::Message::Head::Partial::removeFields()\fR (mind the 's'
at the end of the name), which accepts a string or regular expression
as argument to select the fields to be removed.
.Sp
\&\s-1WARNING WARNING WARNING:\s0 for performance reasons, the header administration
uses weak references (see Scalar::Util method \fIweaken()\fR> to figure-out
which fields have been removed.  A header is a hash of field for fast search
and an array of weak references to remember the order of the fields, required
for printing.  If the field is removed from the hash, the weak-ref is set to
undef and the field not printed.
.Sp
However... it is easy to disturb this process.  Example:
 my \f(CW$msg\fR = ....;                 # subject ref-count = 1 + 0 = 1
 \f(CW$msg\fR\->head\->delete('Subject');  # subject ref-count =     0 = 0: clean-up
 \f(CW$msg\fR\->print;                    # subject doesn't show: ok
.Sp
But
 my \f(CW$msg\fR = ....;                 # subject ref-count = 1 + 0 = 1
 my \f(CW$s\fR = \f(CW$msg\fR\->head\->get('subject'); # ref-count = 1 + 1 + 0 = 2
 \f(CW$msg\fR\->head\->delete('Subject');  # subject ref-count = 1 + 0 = 1: no clean-up
 \f(CW$msg\fR\->print;                    # subject \s-1DOES\s0 show: not ok
 undef \f(CW$s\fR;                       # ref-count becomes 0: clean-up
 \f(CW$msg\fR\->print;                    # subject doesn't show: ok
.Sp
To avoid the latter situation, do not catch the field object, but only
the field content.  \s-1SAVE\s0 are all methods which return the text:
 my \f(CW$s\fR = \f(CW$msg\fR\->head\->get('subject')\->body;
 my \f(CW$s\fR = \f(CW$msg\fR\->head\->get('subject')\->unfoldedBody;
 my \f(CW$s\fR = \f(CW$msg\fR\->head\->get('subject')\->foldedBody;
 my \f(CW$s\fR = \f(CW$msg\fR\->head\->get('subject')\->foldedBody;
 my \f(CW$s\fR = \f(CW$msg\fR\->get('subject');
 my \f(CW$s\fR = \f(CW$msg\fR\->subject;
 my \f(CW$s\fR = \f(CW$msg\fR\->string;
.ie n .IP "$obj\->\fBremoveFields\fR( <STRING|Regexp>, ... )" 4
.el .IP "\f(CW$obj\fR\->\fBremoveFields\fR( <STRING|Regexp>, ... )" 4
.IX Item "$obj->removeFields( <STRING|Regexp>, ... )"
The header object is turned into a Mail::Message::Head::Partial object
which has a set of fields removed.  Read about the implications and the
possibilities in \fIMail::Message::Head::Partial::removeFields()\fR.
.ie n .IP "$obj\->\fBremoveFieldsExcept\fR( <STRING|Regexp>, ... )" 4
.el .IP "\f(CW$obj\fR\->\fBremoveFieldsExcept\fR( <STRING|Regexp>, ... )" 4
.IX Item "$obj->removeFieldsExcept( <STRING|Regexp>, ... )"
The header object is turned into a Mail::Message::Head::Partial object
which has a set of fields removed.  Read about the implications and the
possibilities in \fIMail::Message::Head::Partial::removeFieldsExcept()\fR.
.ie n .IP "$obj\->\fBremoveListGroup\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBremoveListGroup\fR()" 4
.IX Item "$obj->removeListGroup()"
Removes all fields related to mailing list administration at once.
The header object is turned into a Mail::Message::Head::Partial
object.  Read about the implications and the possibilities in
\&\fIMail::Message::Head::Partial::removeListGroup()\fR.
.ie n .IP "$obj\->\fBremoveResentGroups\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBremoveResentGroups\fR()" 4
.IX Item "$obj->removeResentGroups()"
Removes all resent groups at once.  The header object is turned into
a Mail::Message::Head::Partial object.  Read about the implications and the
possibilities in \fIMail::Message::Head::Partial::removeResentGroups()\fR.
.ie n .IP "$obj\->\fBremoveSpamGroups\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBremoveSpamGroups\fR()" 4
.IX Item "$obj->removeSpamGroups()"
Removes all fields which were added by various spam detection software
at once.  The header object is turned into a Mail::Message::Head::Partial
object.  Read about the implications and the possibilities in
\&\fIMail::Message::Head::Partial::removeSpamGroups()\fR.
.ie n .IP "$obj\->\fBresentGroups\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBresentGroups\fR()" 4
.IX Item "$obj->resentGroups()"
Returns a list of Mail::Message::Head::ResentGroup objects which
each represent one intermediate point in the message's transmission in
the order as they appear in the header: the most recent one first.
See also \fIaddResentGroup()\fR and \fIremoveResentGroups()\fR.
.Sp
A resent group contains a set of header fields whose names start
with \f(CW\*(C`Resent\-*\*(C'\fR.  Before the first \f(CW\*(C`Resent\*(C'\fR line is \fItrace\fR information,
which is composed of an optional \f(CW\*(C`Return\-Path\*(C'\fR field and an required
\&\f(CW\*(C`Received\*(C'\fR field.
.ie n .IP "$obj\->\fBreset\fR($name, @fields)" 4
.el .IP "\f(CW$obj\fR\->\fBreset\fR($name, \f(CW@fields\fR)" 4
.IX Item "$obj->reset($name, @fields)"
Replace the values in the header fields named by \f(CW$name\fR with the values
specified in the list of \f(CW@fields\fR. A single name can correspond to multiple
repeated fields.  \s-1READ THE IMPORTANT WARNING IN \s0\fIremoveField()\fR
.Sp
Removing fields which are part of one of the predefined field groups is
not a smart idea.  You can better remove these fields as group, all
together.  For instance, the \f(CW\*(AqReceived\*(Aq\fR lines are part of resent
groups, \f(CW\*(AqX\-Spam\*(Aq\fR is past of a spam group, and \f(CW\*(C`List\-Post\*(C'\fR belongs
to a list group.  You can delete a whole group with
\&\fIMail::Message::Head::FieldGroup::delete()\fR, or with methods which
are provided by Mail::Message::Head::Partial.
.Sp
If \s-1FIELDS\s0 is empty, the corresponding \f(CW$name\fR fields will
be removed. The location of removed fields in the header order will be
remembered. Fields with the same name which are added later will appear at
the remembered position.  This is equivalent to the \fIdelete()\fR method.
.Sp
example:
.Sp
.Vb 3
\& # reduce number of \*(AqKeywords\*(Aq lines to last 5)
\& my @keywords = $head\->get(\*(AqKeywords\*(Aq);
\& $head\->reset(\*(AqKeywords\*(Aq, @keywords[\-5..\-1]) if @keywords > 5;
\&
\& # Reduce the number of Received lines to only the last added one.
\& my @rgs = $head\->resentGroups;
\& shift @rgs;     # keep this one (later is added in front)
\& $_\->delete foreach @rgs;
.Ve
.ie n .IP "$obj\->\fBset\fR( $field | $line | <$name, $body, [$attrs]> )" 4
.el .IP "\f(CW$obj\fR\->\fBset\fR( \f(CW$field\fR | \f(CW$line\fR | <$name, \f(CW$body\fR, [$attrs]> )" 4
.IX Item "$obj->set( $field | $line | <$name, $body, [$attrs]> )"
The \f(CW\*(C`set\*(C'\fR method is similar to the \fIadd()\fR method, and takes the same
options. However, existing values for fields will be removed before a new
value is added.  \s-1READ THE IMPORTANT WARNING IN \s0\fIremoveField()\fR
.ie n .IP "$obj\->\fBspamDetected\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBspamDetected\fR()" 4
.IX Item "$obj->spamDetected()"
Returns whether one of the spam groups defines a report about spam.  If there
are not header fields in the message which relate to spam-detection
software, \f(CW\*(C`undef\*(C'\fR is returned.  The spamgroups which report spam are returned.
.Sp
example:
.Sp
.Vb 1
\& $message\->delete if $message\->spamDetected;
\&
\& call_spamassassin($message)
\&    unless defined $message\->spamDetected;
.Ve
.ie n .IP "$obj\->\fBspamGroups\fR( [$names] )" 4
.el .IP "\f(CW$obj\fR\->\fBspamGroups\fR( [$names] )" 4
.IX Item "$obj->spamGroups( [$names] )"
Returns a list of Mail::Message::Head::SpamGroup objects, each collecting
some lines which contain spam fighting information.  When any \f(CW$names\fR are
given, then only these groups are returned.
See also \fIaddSpamGroup()\fR and \fIremoveSpamGroups()\fR.
.Sp
In scalar context, with exactly one \s-1NAME\s0 specified, that group will be
returned.  With more \f(CW$names\fR or without \f(CW$names\fR, a list will be returned
(which defaults to the length of the list in scalar context).
.Sp
example: use of \fIlistGroup()\fR
.Sp
.Vb 3
\& my @sg = $msg\->head\->spamGroups;
\& $sg[0]\->print(\e*STDERR);
\& $sg[\-1]\->delete;
\&
\& my $sg = $msg\->head\->spamGroups(\*(AqSpamAssassin\*(Aq);
.Ve
.ie n .IP "$obj\->\fBstring\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBstring\fR()" 4
.IX Item "$obj->string()"
Returns the whole header as one scalar (in scalar context) or list
of lines (list context).  Triggers completion.
.ie n .IP "$obj\->\fBstudy\fR( $name, [$index] )" 4
.el .IP "\f(CW$obj\fR\->\fBstudy\fR( \f(CW$name\fR, [$index] )" 4
.IX Item "$obj->study( $name, [$index] )"
Inherited, see \*(L"Access to the header\*(R" in Mail::Message::Head
.SS "About the body"
.IX Subsection "About the body"
Extends \*(L"About the body\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fBguessBodySize\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBguessBodySize\fR()" 4
.IX Item "$obj->guessBodySize()"
Inherited, see \*(L"About the body\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBguessTimeStamp\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBguessTimeStamp\fR()" 4
.IX Item "$obj->guessTimeStamp()"
Make a guess about when the message was origanally posted, based on the
information found in the header's \f(CW\*(C`Date\*(C'\fR field.
.Sp
For some kinds of folders, \fIMail::Message::guessTimestamp()\fR may produce
a better result, for instance by looking at the modification time of the
file in which the message is stored.  Also some protocols, like \s-1POP\s0 can
supply that information.
.ie n .IP "$obj\->\fBisMultipart\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisMultipart\fR()" 4
.IX Item "$obj->isMultipart()"
Inherited, see \*(L"About the body\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBrecvstamp\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBrecvstamp\fR()" 4
.IX Item "$obj->recvstamp()"
Returns an indication about when the message was sent, but only using the
\&\f(CW\*(C`Date\*(C'\fR field in the header as last resort: we do not trust the sender of
the message to specify the correct date.  See \fItimestamp()\fR when you do
trust the sender.
.Sp
Many spam producers fake a date, which mess up the order of receiving
things.  The timestamp which is produced is derived from the Received
headers, if they are present, and \f(CW\*(C`undef\*(C'\fR otherwise.
.Sp
The timestamp is encoded as \f(CW\*(C`time\*(C'\fR is on your system (see perldoc \-f
time), and as such usable for the \f(CW\*(C`gmtime\*(C'\fR and \f(CW\*(C`localtime\*(C'\fR methods.
.Sp
example: of time-sorting folders with received messages
.Sp
.Vb 3
\& my $folder = $mgr\->open(\*(AqInBox\*(Aq);
\& my @messages = sort {$a\->recvstamp <=> $b\->recvstamp}
\&                   $folder\->messages;
.Ve
.Sp
example: of time-sorting messages of mixed origin
.Sp
.Vb 1
\& my $folder = $mgr\->open(\*(AqMyFolder\*(Aq);
\&
\& # Pre\-calculate timestamps to be sorted (for speed)
\& my @stamps = map { [ ($_\->timestamp || 0), $_ ] }
\&                     $folder\->messages;
\&
\& my @sorted
\&   = map { $_\->[1] }      # get the message for the stamp
\&       sort {$a\->[0] <=> $b\->[0]}   # stamps are numerics
\&          @stamps;
.Ve
.ie n .IP "$obj\->\fBtimestamp\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBtimestamp\fR()" 4
.IX Item "$obj->timestamp()"
Returns an indication about when the message was sent, with as
little guessing as possible.  In this case, the date as specified by the
sender is trusted.  See \fIrecvstamp()\fR when you do not want to trust the
sender.
.Sp
The timestamp is encoded as \f(CW\*(C`time\*(C'\fR is
on your system (see perldoc \-f time), and as such usable for the \f(CW\*(C`gmtime\*(C'\fR
and \f(CW\*(C`localtime\*(C'\fR methods.
.SS "Internals"
.IX Subsection "Internals"
Extends \*(L"Internals\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fBaddNoRealize\fR($field)" 4
.el .IP "\f(CW$obj\fR\->\fBaddNoRealize\fR($field)" 4
.IX Item "$obj->addNoRealize($field)"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBaddOrderedFields\fR($fields)" 4
.el .IP "\f(CW$obj\fR\->\fBaddOrderedFields\fR($fields)" 4
.IX Item "$obj->addOrderedFields($fields)"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBcreateFromLine\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBcreateFromLine\fR()" 4
.IX Item "$obj->createFromLine()"
For some mail-folder types separate messages by a line starting with
\&'\f(CW\*(C`From \*(C'\fR'.  If a message is moved to such folder from a folder-type
which does not support these separators, this method is called to produce
one.
.ie n .IP "$obj\->\fBcreateMessageId\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBcreateMessageId\fR()" 4
.IX Item "$obj->createMessageId()"
Creates a message-id for this message.  This method will be run when
a new message is created, or a message is discovered without the
message-id header field.  Message-ids are required for detection of
message-threads.  See \fImessageIdPrefix()\fR.
.ie n .IP "$obj\->\fBfileLocation\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBfileLocation\fR()" 4
.IX Item "$obj->fileLocation()"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBload\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBload\fR()" 4
.IX Item "$obj->load()"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBmessageIdPrefix\fR( [$prefix, [$hostname]|CODE] )" 4
.el .IP "\f(CW$obj\fR\->\fBmessageIdPrefix\fR( [$prefix, [$hostname]|CODE] )" 4
.IX Item "$obj->messageIdPrefix( [$prefix, [$hostname]|CODE] )"
.PD 0
.IP "Mail::Message::Head::Complete\->\fBmessageIdPrefix\fR( [$prefix, [$hostname]|CODE] )" 4
.IX Item "Mail::Message::Head::Complete->messageIdPrefix( [$prefix, [$hostname]|CODE] )"
.PD
When options are provided, it sets a new way to create message-ids,
as used by \fIcreateMessageId()\fR.  You have two choices: either by
providing a \f(CW$prefix\fR and optionally a \f(CW$hostname\fR, or a \s-1CODE\s0 reference.
.Sp
The \s-1CODE\s0 reference will be called with the header as first argument.
You must ensure yourself that the returned value is \s-1RFC\s0 compliant.
.Sp
The \f(CW$prefix\fR defaults to \f(CW\*(C`mailbox\-$$\*(C'\fR, the \f(CW$hostname\fR defaults to the
return of Net::Domains's function \f(CW\*(C`hostfqdn()\*(C'\fR, or when not installed,
the Sys::Hostname's function \f(CW\*(C`hostname()\*(C'\fR.  Inbetween the
two, a nano-second time provided by Time::HiRes is used.  If that
module is not available, \f(CW\*(C`time\*(C'\fR is called at the start of the program,
and incremented for each newly created id.
.Sp
In any case, a subroutine will be created to be used.  A reference
to that will be returned.  When the method is called without arguments,
but no subroutine is defined yet, one will be created.
.Sp
example: setting a message prefix
.Sp
.Vb 3
\&  $head\->messageIdPrefix(\*(Aqprefix\*(Aq);
\&  Mail::Message::Head::Complete\->messageIdPrefix(\*(Aqprefix\*(Aq);
\&  my $code = $head\->messageIdPrefix(\*(Aqmailbox\*(Aq, \*(Aqnohost\*(Aq);
\&
\&  sub new_msgid()
\&  {   my $head = shift;
\&      "myid\-$$\-${(rand 10000)}@example.com";
\&  }
\&
\&  $many_msg\->messageIdPrefix(\e&new_msgid);
\&  Mail::Message::Head::Complete\->messageIdPrefix(&new_msgid);
.Ve
.ie n .IP "$obj\->\fBmoveLocation\fR($distance)" 4
.el .IP "\f(CW$obj\fR\->\fBmoveLocation\fR($distance)" 4
.IX Item "$obj->moveLocation($distance)"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBread\fR($parser)" 4
.el .IP "\f(CW$obj\fR\->\fBread\fR($parser)" 4
.IX Item "$obj->read($parser)"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.ie n .IP "$obj\->\fBsetNoRealize\fR($field)" 4
.el .IP "\f(CW$obj\fR\->\fBsetNoRealize\fR($field)" 4
.IX Item "$obj->setNoRealize($field)"
Inherited, see \*(L"Internals\*(R" in Mail::Message::Head
.SS "Error handling"
.IX Subsection "Error handling"
Extends \*(L"Error handling\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fB\s-1AUTOLOAD\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1AUTOLOAD\s0\fR()" 4
.IX Item "$obj->AUTOLOAD()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBaddReport\fR($object)" 4
.el .IP "\f(CW$obj\fR\->\fBaddReport\fR($object)" 4
.IX Item "$obj->addReport($object)"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "\f(CW$obj\fR\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD 0
.ie n .IP "Mail::Message::Head::Complete\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "Mail::Message::Head::Complete\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "Mail::Message::Head::Complete->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBerrors\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBerrors\fR()" 4
.IX Item "$obj->errors()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlog\fR( [$level, [$strings]] )" 4
.el .IP "\f(CW$obj\fR\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "$obj->log( [$level, [$strings]] )"
.PD 0
.IP "Mail::Message::Head::Complete\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "Mail::Message::Head::Complete->log( [$level, [$strings]] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogPriority\fR($level)" 4
.el .IP "\f(CW$obj\fR\->\fBlogPriority\fR($level)" 4
.IX Item "$obj->logPriority($level)"
.PD 0
.IP "Mail::Message::Head::Complete\->\fBlogPriority\fR($level)" 4
.IX Item "Mail::Message::Head::Complete->logPriority($level)"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBlogSettings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlogSettings\fR()" 4
.IX Item "$obj->logSettings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBnotImplemented\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnotImplemented\fR()" 4
.IX Item "$obj->notImplemented()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreport\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreport\fR( [$level] )" 4
.IX Item "$obj->report( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBreportAll\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBreportAll\fR( [$level] )" 4
.IX Item "$obj->reportAll( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBtrace\fR( [$level] )" 4
.el .IP "\f(CW$obj\fR\->\fBtrace\fR( [$level] )" 4
.IX Item "$obj->trace( [$level] )"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBwarnings\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBwarnings\fR()" 4
.IX Item "$obj->warnings()"
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.SS "Cleanup"
.IX Subsection "Cleanup"
Extends \*(L"Cleanup\*(R" in Mail::Message::Head.
.ie n .IP "$obj\->\fB\s-1DESTROY\s0\fR()" 4
.el .IP "\f(CW$obj\fR\->\fB\s-1DESTROY\s0\fR()" 4
.IX Item "$obj->DESTROY()"
Inherited, see \*(L"Cleanup\*(R" in Mail::Reporter
.SH "DETAILS"
.IX Header "DETAILS"
Extends \*(L"\s-1DETAILS\*(R"\s0 in Mail::Message::Head.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "Warning: Cannot remove field $name from header: not found." 4
.el .IP "Warning: Cannot remove field \f(CW$name\fR from header: not found." 4
.IX Item "Warning: Cannot remove field $name from header: not found."
You ask to remove a field which is not known in the header.  Using
\&\fIdelete()\fR, \fIreset()\fR, or \fIset()\fR to do the job will not result
in warnings: those methods check the existence of the field first.
.IP "Warning: Field objects have an implied name ($name)" 4
.IX Item "Warning: Field objects have an implied name ($name)"
.PD 0
.ie n .IP "Error: Package $package does not implement $method." 4
.el .IP "Error: Package \f(CW$package\fR does not implement \f(CW$method\fR." 4
.IX Item "Error: Package $package does not implement $method."
.PD
Fatal error: the specific package (or one of its superclasses) does not
implement this method where it should. This message means that some other
related classes do implement this method however the class at hand does
not.  Probably you should investigate this and probably inform the author
of the package.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Mail-Box distribution version 2.120,
built on September 21, 2016. Website: \fIhttp://perl.overmeer.net/mailbox/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2001\-2016 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR