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(3pUser Contributed Perl DocumentatMail::Message::Head(3pm)



NAME
       Mail::Message::Head - the header of one message

INHERITANCE
        Mail::Message::Head
          is a Mail::Reporter

        Mail::Message::Head is extended by
          Mail::Box::IMAP4::Head
          Mail::Message::Head::Complete
          Mail::Message::Head::Delayed
          Mail::Message::Head::Subset

SYNOPSIS
        my $head = Mail::Message::Head->new;
        $head->add('From: me@localhost');
        $head->add(From => 'me@localhost');
        $head->add(Mail::Message::Field->new(From => 'me'));
        my Mail::Message::Field $subject = $head->get('subject');
        my Mail::Message::Field @rec = $head->get('received');
        $head->delete('From');

DESCRIPTION
       "Mail::Message::Head" MIME headers are part of Mail::Message messages,
       which are grouped in Mail::Box folders.

       ATTENTION!!! most functionality about e-mail headers is described in
       Mail::Message::Head::Complete, which is a matured header object.  Other
       kinds of headers will be translated to that type when time comes.

       On this page, the general methods which are available on any header are
       described.  Read about differences in the sub-class specific pages.

OVERLOADED
       overload: ""

           (stringifaction) The header, when used as string, will format as if
           Mail::Message::Head::Complete::string() was called, so return a
           nicely folder full header.  An exception is made for Carp, which
           will get a simplified string to avoid unreadible messages from
           "croak" and "confess".

           example: using a header object as string

            print $head;     # implicit stringification by print
            $head->print;    # the same

            print "$head";   # explicit stringication

       overload: bool

           When the header does not contain any lines (which is illegal,
           according to the RFCs), false is returned.  In all other cases, a
           true value is produced.

METHODS
       Constructors

       $obj->build([PAIR|FIELD]-LIST)

           A fast way to construct a header with many lines.  The PAIRs are
           "(name, content)" pairs of the header, but it is also possible to
           pass Mail::Message::Field objects.   A
           Mail::Message::Head::Complete header is created by simply calling
           Mail::Message::Head::Complete::build(), and then each field is
           added.  Double field names are permitted.

           example:

            my $subject = Mail::Message::Full->new(Subject => 'xyz');

            my $head = Mail::Message::Head->build
             ( From     => 'meATexample.com'
             , To       => 'youATanywhere.aq'
             , $subject
             , Received => 'one'
             , Received => 'two'
             );

            print ref $head;
             # -->  Mail::Message::Head::Complete

       Mail::Message::Head->new(OPTIONS)

           Create a new message header object.  The object will store all the
           fields of a header.  When you get information from the header, it
           will be returned to you as Mail::Message::Field objects, although
           the fields may be stored differently internally.

           If you try to instantiate a Mail::Message::Head, you will
           automatically be upgraded to a Mail::Message::Head::Complete --a
           full head.

            Option    --Defined in     --Default
            field_type                   Mail::Message::Field::Fast
            log         Mail::Reporter   'WARNINGS'
            message                      undef
            modified                     <false>
            trace       Mail::Reporter   'WARNINGS'

           . field_type => CLASS

               The type of objects that all the fields will have.  This must
               be an extension of Mail::Message::Field.

           . log => LEVEL

           . message => MESSAGE

               The MESSAGE where this header belongs to.  Usually, this is not
               known at creation of the header, but sometimes it is.  If not,
               call the message() method later to set it.

           . modified => BOOLEAN

           . trace => LEVEL

       The header

       $obj->isDelayed

           Headers may only be partially read, in which case they are called
           delayed.  This method returns true if some header information still
           needs to be read. Returns false if all header data has been read.
           Will never trigger completion.

       $obj->isEmpty

           Are there any fields defined in the current header?  Be warned that
           the header will not be loaded for this: delayed headers will return
           true in any case.

       $obj->isModified

           Returns whether the header has been modified after being read.

           example:

            if($head->isModified) { ... }

       $obj->knownNames

           Like Mail::Message::Head::Complete::names(), but only returns the
           known header fields, which may be less than "names" for header
           types which are partial.  "names()" will trigger completion, where
           "knownNames()" does not.

       $obj->message([MESSAGE])

           Get (after setting) the message where this header belongs to.  This
           does not trigger completion.

       $obj->modified([BOOLEAN])

           Sets the modified flag to BOOLEAN.  Without value, the current
           setting is returned, but in that case you can better use
           isModified().  Changing this flag will not trigger header
           completion.

           example:

            $head->modified(1);
            if($head->modified) { ... }
            if($head->isModified) { ... }

       $obj->orderedFields

           Retuns the fields ordered the way they were read or added.

       Access to the header

       $obj->get(NAME [,INDEX])

           Get the data which is related to the field with the NAME.  The case
           of the characters in NAME does not matter.

           If there is only one data element defined for the NAME, or if there
           is an INDEX specified as the second argument, only the specified
           element will be returned. If the field NAME matches more than one
           header the return value depends on the context. In LIST context,
           all values will be returned in the order they are read. In SCALAR
           context, only the last value will be returned.

           example:

            my $head = Mail::Message::Head->new;
            $head->add('Received: abc');
            $head->add('Received: xyz');
            $head->add('Subject: greetings');

            my @rec_list   = $head->get('Received');
            my $rec_scalar = $head->get('Received');
            print ",@rec_list,$rec_scalar,"     # ,abc xyz, xyz,
            print $head->get('Received', 0);    # abc
            my @sub_list   = $head->get('Subject');
            my $sub_scalar = $head->get('Subject');
            print ",@sub_list,$sub_scalar,"     # ,greetings, greetings,

       $obj->study(NAME [,INDEX])

           Like get(), but puts more effort in understanding the contents of
           the field.  Mail::Message::Field::study() will be called for the
           field with the specified FIELDNAME, which returns
           Mail::Message::Field::Full objects. In scalar context only the last
           field with that name is returned.  When an INDEX is specified, that
           element is returned.

       About the body

       $obj->guessBodySize

           Try to estimate the size of the body of this message, but without
           parsing the header or body.  The result might be "undef" or a few
           percent of the real size.  It may even be very far of the real
           value, that's why this is a guess.

       $obj->isMultipart

           Returns whether the body of the related message is a multipart
           body.  May trigger completion, when the "Content-Type" field is not
           defined.

       Internals

       $obj->addNoRealize(FIELD)

           Add a field, like Mail::Message::Head::Complete::add() does, but
           avoid the loading of a possibly partial header.  This method does
           not test the validity of the argument, nor flag the header as
           changed.  This does not trigger completion.

       $obj->addOrderedFields(FIELDS)

       $obj->fileLocation

           Returns the location of the header in the file, as a pair begin and
           end.  The begin is the first byte of the header.  The end is the
           first byte after the header.

       $obj->load

           Be sure that the header is loaded.  This returns the loaded header
           object.

       $obj->moveLocation(DISTANCE)

           Move the registration of the header in the file.

       $obj->read(PARSER)

           Read the header information of one message into this header
           structure.  This method is called by the folder object (some
           Mail::Box sub-class), which passes the PARSER as an argument.

       $obj->setNoRealize(FIELD)

           Set a field, but avoid the loading of a possibly partial header as
           set() does.  This method does not test the validity of the
           argument, nor flag the header as changed.  This does not trigger
           completion.

       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->defaultTrace([LEVEL]|[LOGLEVEL,
       TRACELEVEL]|[LEVEL, CALLBACK])

           See "Error handling" in Mail::Reporter

       $obj->errors

           See "Error handling" in Mail::Reporter

       $obj->log([LEVEL [,STRINGS]])

       Mail::Message::Head->log([LEVEL [,STRINGS]])

           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)

       Mail::Message::Head->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->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

DETAILS
       Ordered header fields

       Many Perl implementations make a big mistake by disturbing the order of
       header fields.  For some fields (especially the resent groups, see
       Mail::Message::Head::ResentGroup) the order shall be maintained.

       MailBox will keep the order of the fields as they were found in the
       source.  When your add a new field, it will be added at the end.  If
       your replace a field with a new value, it will stay in the original
       order.

       Head class implementation

       The header of a MIME message object contains a set of lines, which are
       called fields (by default represented by Mail::Message::Field objects).
       Dependent on the situation, the knowledge about the fields can be in
       one of three situations, each represented by a sub-class of this
       module:

       o   Mail::Message::Head::Complete

           In this case, it is sure that all knowledge about the header is
           available.  When you get() information from the header and it is
           not there, it will never be there.

       o   Mail::Message::Head::Subset

           There is no certainty whether all header lines are known (probably
           not).  This may be caused as result of reading a fast index file,
           as described in Mail::Box::MH::Index.  The object is automatically
           transformed into a Mail::Message::Head::Complete when all header
           lines must be known.

       o   Mail::Message::Head::Partial

           A partial header is like a subset header: probably the header is
           incomplete.  The means that you are not sure whether a get() for a
           field fails because the field is not a part of the message or that
           it fails because it is not yet known to the program.  Where the
           subset header knows where to get the other fields, the partial
           header does not know it.  It cannot hide its imperfection.

       o   Mail::Message::Head::Delayed

           In this case, there is no single field known.  Access to this
           header will always trigger the loading of the full header.

       Subsets of header fields

       Message headers can be quite large, and therefore MailBox provides
       simplified access to some subsets of information.  You can grab these
       sets of fields together, create and delete them as group.

       On the moment, the following sets are defined:

       o   Mail::Message::Head::ResentGroup

           A resent group is a set of fields which is used to log one step in
           the transmission of the message from the original sender to the
           destination.

           Each step adds a set of headers to indicate when the message was
           received and how it was forwarded (without modification).  These
           fields are best created using Mail::Message::bounce().

       o   Mail::Message::Head::ListGroup

           Fields which are used to administer and log mailing list activity.
           Mailing list software has to play trics with the original message
           to be able to get the reply on that message back to the mailing
           list.  Usually a large number of lines are added.

       o   Mail::Message::Head::SpamGroup

           A set of fields which contains header fields which are produced by
           spam detection software.  You may want to remove these fields when
           you store a message for a longer period of time.

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-28          Mail::Message::Head(3pm)