Mail::Message::Head::FUserGContributed Perl Mail::Message::Head::FieldGroup(3)NAMEMail::Message::Head::FieldGroup - a sub set of fields in a header
INHERITANCEMail::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
SYNOPSIS
Never instantiated directly.
DESCRIPTION
Some fields have a combined meaning: a set of fields which represent
one intermediate step during the transport of the message (a resent
group, 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.
METHODS
Constructors
$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.
$obj->from(HEAD|MESSAGE)
Create a group of fields based on the specified MESSAGE or message
HEAD. 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.
$obj->implementedTypes
Mail::Message::Head::FieldGroup->implementedTypes
Returns a list of strings containing all possible return values for
type().
Mail::Message::Head::FieldGroup->new(FIELDS, OPTIONS)
Construct an object which maintains one set of header FIELDS. The
FIELDS may be specified as "Mail::Message::Field" objects or as
key-value pairs. The OPTIONS and FIELDS (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
OPTIONS.
-Option--Defined in --Default
head undef
log Mail::Reporter 'WARNINGS'
software undef
trace Mail::Reporter 'WARNINGS'
type undef
version undef
head => HEAD
The header HEAD 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 from() method.
log => LEVEL
software => STRING
Name of the software which produced the fields.
trace => LEVEL
type => STRING
Group name for the fields. Often the same, or close to the same
STRING, as the "software" option contains.
version => STRING
Version number for the software which produced the fields.
The header
$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.
example: adding a field to a detached list group
my $this = Mail::Message::Head::ListGroup->new(...);
$this->add('List-Id' => 'mailbox');
$msg->addListGroup($this);
$msg->send;
example: adding a field to an attached list group
my $lg = Mail::Message::Head::ListGroup->from($msg);
$lg->add('List-Id' => 'mailbox');
$obj->addFields([FIELDNAMES])
Add some FIELDNAMES to the set.
$obj->attach(HEAD)
Add a group of fields to a message HEAD. The fields will be
cloned(!) into the header, so that the field group object can be
used again.
example: attaching a list group to a message
my $lg = Mail::Message::Head::ListGroup->new(...);
$lg->attach($msg->head);
$msg->head->addListGroup($lg); # same
$msg->head->addSpamGroup($sg); # also implemented with attach
$obj->delete
Remove all the header lines which are combined in this fields
group, from the header.
$obj->fieldNames
Return the names of the fields which are used in this group.
$obj->fields
Return the fields which are defined for this group.
$obj->head
Returns the header object, which includes these fields.
Access to the header
$obj->software
Returns the name of the software as is defined in the headers. The
may be slightly different from the return value of type(), but
usually not too different.
$obj->type
Returns an abstract name for the field group; which software is
controling it. "undef" 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 retreived with
implementedTypes().
$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 "undef"
Internals
$obj->collectFields([NAME])
Scan the header for fields which are usually contained in field
group with the specified NAME. For mailinglist groups, you can not
specify a NAME: only one set of headers will be found (all headers
are considered to be produced by exactly one package of mailinglist
software).
This method is automatically called when a field group is
constructed via from() on an existing header or message.
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.
Please warn the author of MailBox if you see that to few or too
many fields are included.
$obj->detected(TYPE, SOFTWARE, VERSION)
Sets the values for the field group type, software, and version,
prossibly to "undef".
Error handling
$obj->AUTOLOAD
See "Error handling" in Mail::Reporter
$obj->addReport(OBJECT)
See "Error handling" in Mail::Reporter
$obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
Mail::Message::Head::FieldGroup->defaultTrace([LEVEL]|[LOGLEVEL,
TRACELEVEL]|[LEVEL, CALLBACK])
See "Error handling" in Mail::Reporter
$obj->details
Produce information about the detected/created field group, which
may be helpful during debugging. A nicely formatted string is
returned.
$obj->errors
See "Error handling" in Mail::Reporter
$obj->log([LEVEL [,STRINGS]])
Mail::Message::Head::FieldGroup->log([LEVEL [,STRINGS]])
See "Error handling" in Mail::Reporter
$obj->logPriority(LEVEL)
Mail::Message::Head::FieldGroup->logPriority(LEVEL)
See "Error handling" in Mail::Reporter
$obj->logSettings
See "Error handling" in Mail::Reporter
$obj->notImplemented
See "Error handling" in Mail::Reporter
$obj->print([FILEHANDLE])
Print the group to the specified FILEHANDLE or GLOB. This is
probably only useful for debugging purposed. The output defaults
to the selected file handle.
$obj->report([LEVEL])
See "Error handling" in Mail::Reporter
$obj->reportAll([LEVEL])
See "Error handling" in Mail::Reporter
$obj->trace([LEVEL])
See "Error handling" in Mail::Reporter
$obj->warnings
See "Error handling" in Mail::Reporter
Cleanup
$obj->DESTROY
See "Cleanup" in Mail::Reporter
$obj->inGlobalDestruction
See "Cleanup" in Mail::Reporter
DIAGNOSTICS
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.
SEE ALSO
This module is part of Mail-Box distribution version 2.097, built on
January 26, 2011. Website: http://perl.overmeer.net/mailbox/
LICENSE
Copyrights 2001-2011 by Mark Overmeer. For other contributors see
ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself. See
http://www.perl.com/perl/misc/Artistic.html
perl v5.14.12011-01-26Mail::Message::Head::FieldGroup(3)
