man Mail::Message::Head::FieldGroup () - a sub set of fields in a header

NAME

Mail::Message::Head::FieldGroup - a sub set of fields in a header

INHERITANCE

 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

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 CWMail::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                       C<undef>     
 log       L<Mail::Reporter>  C<'WARNINGS'>
 software                   C<undef>     
 trace     L<Mail::Reporter>  C<'WARNINGS'>
 type                       C<undef>     
 version                    C<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 CWsoftware 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. CWundef 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 CWundef

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 CWundef.

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 CW$package does not implement CW$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.

REFERENCES

See the MailBox website at <http://perl.overmeer.net/mailbox/> for more details.

COPYRIGHTS

Distribution version 2.063. Written by Mark Overmeer (mark@overmeer.net). See the ChangeLog for other contributors.

Copyright (c) 2001-2003 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.