.\" 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::FieldGroup 3pm"
.TH Mail::Message::Head::FieldGroup 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::FieldGroup \- a sub set of fields in a header
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Mail::Message::Head::FieldGroup
\&   is a Mail::Reporter
\&
\& Mail::Message::Head::FieldGroup is extended by
\&   Mail::Message::Head::ListGroup
\&   Mail::Message::Head::ResentGroup
\&   Mail::Message::Head::SpamGroup
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Never instantiated directly.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Some fields have a combined meaning: a set of fields which represent
one intermediate step during the transport of the message (a
\&\fIresent group\fR, implemented in Mail::Message::Head::ResentGroup), 
fields added by mailing list software (implemented in
Mail::Message::Head::ListGroup), or fields added by Spam detection
related software (implemented by Mail::Message::Head::SpamGroup).
Each set of fields can be extracted or added as group with objects
which are based on the implementation in this class.
.PP
Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Mail::Reporter.
.SH "METHODS"
.IX Header "METHODS"
Extends \*(L"\s-1METHODS\*(R"\s0 in Mail::Reporter.
.SS "Constructors"
.IX Subsection "Constructors"
Extends \*(L"Constructors\*(R" in Mail::Reporter.
.ie n .IP "$obj\->\fBclone\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBclone\fR()" 4
.IX Item "$obj->clone()"
Make a copy of this object.  The collected fieldnames are copied and the
list type information.  No deep copy is made for the header: this is
only copied as reference.
.ie n .IP "$obj\->\fBfrom\fR($head|$message)" 4
.el .IP "\f(CW$obj\fR\->\fBfrom\fR($head|$message)" 4
.IX Item "$obj->from($head|$message)"
Create a group of fields based on the specified \f(CW$message\fR or message \f(CW$head\fR.
This may return one or more of the objects, which depends on the
type of group.  Mailing list fields are all stored in one object,
where resent and spam groups can appear more than once.
.ie n .IP "$obj\->\fBimplementedTypes\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBimplementedTypes\fR()" 4
.IX Item "$obj->implementedTypes()"
.PD 0
.IP "Mail::Message::Head::FieldGroup\->\fBimplementedTypes\fR()" 4
.IX Item "Mail::Message::Head::FieldGroup->implementedTypes()"
.PD
Returns a list of strings containing all possible return values for
\&\fItype()\fR.
.ie n .IP "Mail::Message::Head::FieldGroup\->\fBnew\fR($fields, %options)" 4
.el .IP "Mail::Message::Head::FieldGroup\->\fBnew\fR($fields, \f(CW%options\fR)" 4
.IX Item "Mail::Message::Head::FieldGroup->new($fields, %options)"
Construct an object which maintains one set of header \f(CW$fields\fR.  The
\&\f(CW$fields\fR may be specified as \f(CW\*(C`Mail::Message::Field\*(C'\fR objects or as key-value
pairs.  The \f(CW%options\fR and \f(CW$fields\fR (as key-value pair) can be mixed: they are
distinguished by their name, where the fields always start with a capital.
The field objects must aways lead the \f(CW%options\fR.
.Sp
.Vb 7
\& \-Option  \-\-Defined in     \-\-Default
\&  head                       undef
\&  log       Mail::Reporter   \*(AqWARNINGS\*(Aq
\&  software                   undef
\&  trace     Mail::Reporter   \*(AqWARNINGS\*(Aq
\&  type                       undef
\&  version                    undef
.Ve
.RS 4
.IP "head => \s-1HEAD\s0" 2
.IX Item "head => HEAD"
The header \s-1HEAD\s0 object is used to store the grouped fields in.
If no header is specified, a Mail::Message::Head::Partial is created
for you.  If you wish to scan the existing fields in a header, then use
the \fIfrom()\fR method.
.IP "log => \s-1LEVEL\s0" 2
.IX Item "log => LEVEL"
.PD 0
.IP "software => \s-1STRING\s0" 2
.IX Item "software => STRING"
.PD
Name of the software which produced the fields.
.IP "trace => \s-1LEVEL\s0" 2
.IX Item "trace => LEVEL"
.PD 0
.IP "type => \s-1STRING\s0" 2
.IX Item "type => STRING"
.PD
Group name for the fields.  Often the same, or close
to the same \s-1STRING,\s0 as the \f(CW\*(C`software\*(C'\fR option contains.
.IP "version => \s-1STRING\s0" 2
.IX Item "version => STRING"
Version number for the software which produced the fields.
.RE
.RS 4
.RE
.SS "The header"
.IX Subsection "The header"
.ie n .IP "$obj\->\fBadd\fR( <$field, $value> | $object )" 4
.el .IP "\f(CW$obj\fR\->\fBadd\fR( <$field, \f(CW$value\fR> | \f(CW$object\fR )" 4
.IX Item "$obj->add( <$field, $value> | $object )"
Add a field to the header, using the field group.  When the field group
is already attached to a real message header, it will appear in that
one as well as being registed in this set.  If no header is defined,
the field only appears internally.
.Sp
example: adding a field to a detached list group
.Sp
.Vb 4
\& my $this = Mail::Message::Head::ListGroup\->new(...);
\& $this\->add(\*(AqList\-Id\*(Aq => \*(Aqmailbox\*(Aq);
\& $msg\->addListGroup($this);
\& $msg\->send;
.Ve
.Sp
example: adding a field to an attached list group
.Sp
.Vb 2
\& my $lg = Mail::Message::Head::ListGroup\->from($msg);
\& $lg\->add(\*(AqList\-Id\*(Aq => \*(Aqmailbox\*(Aq);
.Ve
.ie n .IP "$obj\->\fBaddFields\fR( [$fieldnames] )" 4
.el .IP "\f(CW$obj\fR\->\fBaddFields\fR( [$fieldnames] )" 4
.IX Item "$obj->addFields( [$fieldnames] )"
Add some \f(CW$fieldnames\fR to the set.
.ie n .IP "$obj\->\fBattach\fR($head)" 4
.el .IP "\f(CW$obj\fR\->\fBattach\fR($head)" 4
.IX Item "$obj->attach($head)"
Add a group of fields to a message \f(CW$head\fR.  The fields will be cloned(!)
into the header, so that the field group object can be used again.
.Sp
example: attaching a list group to a message
.Sp
.Vb 3
\& my $lg = Mail::Message::Head::ListGroup\->new(...);
\& $lg\->attach($msg\->head);
\& $msg\->head\->addListGroup($lg);   # same
\&
\& $msg\->head\->addSpamGroup($sg);   # also implemented with attach
.Ve
.ie n .IP "$obj\->\fBdelete\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdelete\fR()" 4
.IX Item "$obj->delete()"
Remove all the header lines which are combined in this fields group,
from the header.
.ie n .IP "$obj\->\fBfieldNames\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBfieldNames\fR()" 4
.IX Item "$obj->fieldNames()"
Return the names of the fields which are used in this group.
.ie n .IP "$obj\->\fBfields\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBfields\fR()" 4
.IX Item "$obj->fields()"
Return the fields which are defined for this group.
.ie n .IP "$obj\->\fBhead\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBhead\fR()" 4
.IX Item "$obj->head()"
Returns the header object, which includes these fields.
.SS "Access to the header"
.IX Subsection "Access to the header"
.ie n .IP "$obj\->\fBsoftware\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBsoftware\fR()" 4
.IX Item "$obj->software()"
Returns the name of the software as is defined in the headers.  The may
be slightly different from the return value of \fItype()\fR, but usually
not too different.
.ie n .IP "$obj\->\fBtype\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBtype\fR()" 4
.IX Item "$obj->type()"
Returns an abstract name for the field group; which software is
controling it.  \f(CW\*(C`undef\*(C'\fR is returned in case the type is not known.
Valid names are group type dependent: see the applicable manual
pages.  A list of all types can be retrieved with \fIimplementedTypes()\fR.
.ie n .IP "$obj\->\fBversion\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBversion\fR()" 4
.IX Item "$obj->version()"
Returns the version number of the software used to produce the fields.
Some kinds of software do leave such a trace, other cases will return
\&\f(CW\*(C`undef\*(C'\fR
.SS "Internals"
.IX Subsection "Internals"
.ie n .IP "$obj\->\fBcollectFields\fR( [$name] )" 4
.el .IP "\f(CW$obj\fR\->\fBcollectFields\fR( [$name] )" 4
.IX Item "$obj->collectFields( [$name] )"
Scan the header for fields which are usually contained in field group
with the specified \f(CW$name\fR.  For mailinglist groups, you can not specify
a \f(CW$name:\fR only one set of headers will be found (all headers are considered
to be produced by exactly one package of mailinglist software).
.Sp
This method is automatically called when a field group is
constructed via \fIfrom()\fR on an existing header or message.
.Sp
Returned are the names of the list header fields found, in scalar
context the amount of fields.  An empty list/zero indicates that there
was no group to be found.
.Sp
Please warn the author of MailBox if you see that to few
or too many fields are included.
.ie n .IP "$obj\->\fBdetected\fR($type, $software, $version)" 4
.el .IP "\f(CW$obj\fR\->\fBdetected\fR($type, \f(CW$software\fR, \f(CW$version\fR)" 4
.IX Item "$obj->detected($type, $software, $version)"
Sets the values for the field group type, software, and version,
prossibly to \f(CW\*(C`undef\*(C'\fR.
.SS "Error handling"
.IX Subsection "Error handling"
Extends \*(L"Error handling\*(R" in Mail::Reporter.
.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::FieldGroup\->\fBdefaultTrace\fR( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )" 4
.el .IP "Mail::Message::Head::FieldGroup\->\fBdefaultTrace\fR( [$level]|[$loglevel, \f(CW$tracelevel\fR]|[$level, \f(CW$callback\fR] )" 4
.IX Item "Mail::Message::Head::FieldGroup->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )"
.PD
Inherited, see \*(L"Error handling\*(R" in Mail::Reporter
.ie n .IP "$obj\->\fBdetails\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdetails\fR()" 4
.IX Item "$obj->details()"
Produce information about the detected/created field group, which may be
helpful during debugging.  A nicely formatted string is returned.
.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::FieldGroup\->\fBlog\fR( [$level, [$strings]] )" 4
.IX Item "Mail::Message::Head::FieldGroup->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::FieldGroup\->\fBlogPriority\fR($level)" 4
.IX Item "Mail::Message::Head::FieldGroup->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\->\fBprint\fR( [$fh] )" 4
.el .IP "\f(CW$obj\fR\->\fBprint\fR( [$fh] )" 4
.IX Item "$obj->print( [$fh] )"
Print the group to the specified \f(CW$fh\fR or \s-1GLOB. \s0 This is probably only
useful for debugging purposed.  The output defaults to the selected file
handle.
.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::Reporter.
.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 "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.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."
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