unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Mail::Message::Head::FUserGContributed PerMail::Message::Head::FieldGroup(3pm)



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 "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.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2008 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.10.0                      2008-04-Mail::Message::Head::FieldGroup(3pm)