Provided by: libmail-box-perl_2.110-1_all bug

NAME

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

INHERITANCE

        Mail::Message::Head::Complete
          is a Mail::Message::Head
          is a Mail::Reporter

        Mail::Message::Head::Complete is extended by
          Mail::Message::Head::Partial
          Mail::Message::Replace::MailHeader

        Mail::Message::Head::Complete is realized by
          Mail::Message::Head::Delayed
          Mail::Message::Head::Subset

SYNOPSIS

        my $head = Mail::Message::Head::Complete->new;
        See Mail::Message::Head

DESCRIPTION

       E-mail's message can be in various states: unread, partially read, and fully read.  The
       class stores a message of which all header lines are known for sure.

       See documentation in the base class.

OVERLOADED

       See documentation in the base class.

       overload: ""()
           See "OVERLOADED" in Mail::Message::Head

       overload: bool()
           See "OVERLOADED" in Mail::Message::Head

METHODS

       See documentation in the base class.

   Constructors
       See documentation in the base class.

       $obj->build([PAIR|FIELD]-LIST)
           Undefined values are interpreted as empty field values, and therefore skipped.

       $obj->clone([NAMES|ARRAY-OF-NAMES|REGEXS])
           Make a copy of the header, optionally limited only to the header lines specified by
           NAMES.  See grepNames() on the way these fields can be used.

           example:

            my $newhead = $head->clone('Subject', 'Received');

       Mail::Message::Head::Complete->new(OPTIONS)
           See "Constructors" in Mail::Message::Head

   The header
       See documentation in the base class.

       $obj->isDelayed()
           See "The header" in Mail::Message::Head

       $obj->isEmpty()
           See "The header" in Mail::Message::Head

       $obj->isModified()
           See "The header" in Mail::Message::Head

       $obj->knownNames()
           See "The header" in Mail::Message::Head

       $obj->message([MESSAGE])
           See "The header" in Mail::Message::Head

       $obj->modified([BOOLEAN])
           See "The header" in Mail::Message::Head

       $obj->nrLines()
           Return the number of lines needed to display this header (including the trailing
           newline)

       $obj->orderedFields()
           See "The header" in Mail::Message::Head

       $obj->size()
           Return the number of bytes needed to display this header (including the trailing
           newline).  On systems which use CRLF as line separator, the number of lines in the
           header (see nrLines()) must be added to find the actual size in the file.

       $obj->wrap(INTEGER)
           Re-fold all fields from the header to contain at most INTEGER number of characters per
           line.

           example: re-folding a header

            $msg->head->wrap(78);

   Access to the header
       See documentation in the base class.

       $obj->add(FIELD | LINE | (NAME,BODY[,ATTRS]))
           Add a field to the header.  If a field is added more than once, all values are stored
           in the header, in the order they are added.

           When a FIELD object is specified (some Mail::Message::Field instance), that will be
           added.  Another possibility is to specify a raw header LINE, or a header line nicely
           split-up in NAME and BODY, in which case the field constructor is called for you.

           LINE or BODY specifications which are terminated by a new-line are considered to be
           correctly folded.  Lines which are not terminated by a new-line will be folded when
           needed: new-lines will be added where required.  It is strongly advised to let MailBox
           do the folding for you.

           The return value of this method is the Mail::Message::Field object which is created
           (or was specified).

           example:

            my $head  = Mail::Message::Head->new;
            $head->add('Subject: hi!');
            $head->add(From => 'me@home');
            my $field = Mail::Message::Field->new('To: you@there');
            $head->add($field);
            my Mail::Message::Field $s = $head->add(Sender => 'I');

       $obj->addListGroup(OBJECT)
           A list group is a set of header fields which contain data about a mailing list which
           was used to transmit the message.  See Mail::Message::Head::ListGroup for details
           about the implementation of the OBJECT.

           When you have a list group prepared, you can add it later using this method.  You will
           get your private copy of the list group data in return, because the same group can be
           used for multiple messages.

           example: of adding a list group to a header

            my $lg = Mail::Message::Head::ListGroup->new(...);
            my $own_lg = $msg->head->addListGroup($lg);

       $obj->addResentGroup(RESENT-GROUP|DATA)
           Add a RESENT-GROUP (a Mail::Message::Head::ResentGroup object) to the header.  If you
           specify DATA, that is used to create such group first.  If no "Received" line is
           specified, it will be created for you.

           These header lines have nothing to do with the user's sense of "reply" or "forward"
           actions: these lines trace the e-mail transport mechanism.

           example:

            my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);
            $head->addResentGroup($rg);

            my $rg = $head->addResentGroup(From => 'me');

       $obj->addSpamGroup(OBJECT)
           A spam fighting group is a set of header fields which contains data which is used to
           fight spam.  See Mail::Message::Head::SpamGroup for details about the implementation
           of the OBJECT.

           When you have a spam group prepared, you can add it later using this method.  You will
           get your private copy of the spam group data in return, because the same group can be
           used for multiple messages.

           example: of adding a spam group to a header

            my $sg = Mail::Message::Head::SpamGroup->new(...);
            my $own_sg = $msg->head->addSpamGroup($sg);

       $obj->count(NAME)
           Count the number of fields with this NAME.  Most fields will return 1: only one
           occurance in the header.  As example, the "Received" fields are usually present more
           than once.

       $obj->delete(NAME)
           Remove the field with the specified name.  If the header contained multiple lines with
           the same name, they will be replaced all together.  This method simply calls reset()
           without replacement fields.  READ THE IMPORTANT WARNING IN removeField()

       $obj->get(NAME [,INDEX])
           See "Access to the header" in Mail::Message::Head

       $obj->grepNames([NAMES|ARRAY-OF-NAMES|REGEXS])
           Filter from all header fields those with names which start will any of the specified
           list.  When no names are specified, all fields will be returned.  The list is ordered
           as they where read from file, or added later.

           The NAMES are considered regular expressions, and will all be matched case insensitive
           and attached to the front of the string only.  You may also specify one or more
           prepared regexes.

           example:

            my @f  = $head->grepNames();       # same as $head->orderedFields
            my @f  = $head->grepNames('X-', 'Subject', ');
            my @to = $head->grepNames('To\b'); # will only select To

       $obj->listGroup()
           Returns a list group description: the set of headers which form the information about
           mailing list software used to transport the message.  See also addListGroup() and
           removeListGroup().

           example: use of listGroup()

            if(my $lg = $msg->head->listGroup)
            {  $lg->print(\*STDERR);
               $lg->delete;
            }

            $msg->head->removeListGroup;

       $obj->names()
           Returns a full ordered list of known field names, as defined in the header.  Fields
           which were reset() to be empty will still be listed here.

       $obj->print([FILEHANDLE])
           Print all headers to the specified FILEHANDLE, by default the selected filehandle.
           See printUndisclosed() to limit the headers to include only the public headers.

           example:

            $head->print(\*OUT);
            $head->print;

            my $fh = IO::File->new(...);
            $head->print($fh);

       $obj->printSelected(FILEHANDLE, (STRING|REGEXP)s)
           Like the usual print(), the header lines are printed to the specified FILEHANDLE.  In
           this case, however, only the fields with names as specified by STRING (case
           insensative) or REGEXP are printed.  They will stay the in-order of the source header.

           example: printing only a subset of the fields

            $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)

       $obj->printUndisclosed([FILEHANDLE])
           Like the usual print(), the header lines are printed to the specified FILEHANDLE, by
           default the selected filehandle.  In this case, however, "Bcc" and "Resent-Bcc" lines
           are included.

       $obj->removeContentInfo()
           Remove all body related fields from the header.  The header will become partial.

       $obj->removeField(FIELD)
           Remove the specified FIELD object from the header.  This is useful when there are
           possible more than one fields with the same name, and you need to remove exactly one
           of them.  Also have a look at delete(), reset(), and set().

           See also Mail::Message::Head::Partial::removeFields() (mind the 's' at the end of the
           name), which accepts a string or regular expression as argument to select the fields
           to be removed.

           WARNING WARNING WARNING: for performance reasons, the header administration uses weak
           references (see Scalar::Util method weaken()> to figure-out which fields have been
           removed.  A header is a hash of field for fast search and an array of weak references
           to remember the order of the fields, required for printing.  If the field is removed
           from the hash, the weak-ref is set to undef and the field not printed.

           However... it is easy to disturb this process.  Example:
            my $msg = ....;                 # subject ref-count = 1 + 0 = 1
            $msg->head->delete('Subject');  # subject ref-count =     0 = 0: clean-up
            $msg->print;                    # subject doesn't show: ok

           But
            my $msg = ....;                 # subject ref-count = 1 + 0 = 1
            my $s = $msg->head->get('subject'); # ref-count = 1 + 1 + 0 = 2
            $msg->head->delete('Subject');  # subject ref-count = 1 + 0 = 1: no clean-up
            $msg->print;                    # subject DOES show: not ok
            undef $s;                       # ref-count becomes 0: clean-up
            $msg->print;                    # subject doesn't show: ok

           To avoid the latter situation, do not catch the field object, but only the field
           content.  SAVE are all methods which return the text:
            my $s = $msg->head->get('subject')->body;
            my $s = $msg->head->get('subject')->unfoldedBody;
            my $s = $msg->head->get('subject')->foldedBody;
            my $s = $msg->head->get('subject')->foldedBody;
            my $s = $msg->get('subject');
            my $s = $msg->subject;
            my $s = $msg->string;

       $obj->removeFields(STRING|REGEXP, [STRING|REGEXP, ...])
           The header object is turned into a Mail::Message::Head::Partial object which has a set
           of fields removed.  Read about the implications and the possibilities in
           Mail::Message::Head::Partial::removeFields().

       $obj->removeFieldsExcept(STRING|REGEXP, [STRING|REGEXP, ...])
           The header object is turned into a Mail::Message::Head::Partial object which has a set
           of fields removed.  Read about the implications and the possibilities in
           Mail::Message::Head::Partial::removeFieldsExcept().

       $obj->removeListGroup()
           Removes all fields related to mailing list administration at once.  The header object
           is turned into a Mail::Message::Head::Partial object.  Read about the implications and
           the possibilities in Mail::Message::Head::Partial::removeListGroup().

       $obj->removeResentGroups()
           Removes all resent groups at once.  The header object is turned into a
           Mail::Message::Head::Partial object.  Read about the implications and the
           possibilities in Mail::Message::Head::Partial::removeResentGroups().

       $obj->removeSpamGroups()
           Removes all fields which were added by various spam detection software at once.  The
           header object is turned into a Mail::Message::Head::Partial object.  Read about the
           implications and the possibilities in
           Mail::Message::Head::Partial::removeSpamGroups().

       $obj->resentGroups()
           Returns a list of Mail::Message::Head::ResentGroup objects which each represent one
           intermediate point in the message's transmission in the order as they appear in the
           header: the most recent one first.  See also addResentGroup() and
           removeResentGroups().

           A resent group contains a set of header fields whose names start with "Resent-*".
           Before the first "Resent" line is trace information, which is composed of an optional
           "Return-Path" field and an required "Received" field.

       $obj->reset(NAME, FIELDS)
           Replace the values in the header fields named by NAME with the values specified in the
           list of FIELDS. A single name can correspond to multiple repeated fields.  READ THE
           IMPORTANT WARNING IN removeField()

           Removing fields which are part of one of the predefined field groups is not a smart
           idea.  You can better remove these fields as group, all together.  For instance, the
           'Received' lines are part of resent groups, 'X-Spam' is past of a spam group, and
           "List-Post" belongs to a list group.  You can delete a whole group with
           Mail::Message::Head::FieldGroup::delete(), or with methods which are provided by
           Mail::Message::Head::Partial.

           If FIELDS is empty, the corresponding NAME fields will be removed. The location of
           removed fields in the header order will be remembered. Fields with the same name which
           are added later will appear at the remembered position.  This is equivalent to the
           delete() method.

           example:

            # reduce number of 'Keywords' lines to last 5)
            my @keywords = $head->get('Keywords');
            $head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;

            # Reduce the number of Received lines to only the last added one.
            my @rgs = $head->resentGroups;
            shift @rgs;     # keep this one (later is added in front)
            $_->delete foreach @rgs;

       $obj->set(FIELD | LINE | (NAME, BODY [,ATTRS]))
           The "set" method is similar to the add() method, and takes the same options. However,
           existing values for fields will be removed before a new value is added.  READ THE
           IMPORTANT WARNING IN removeField()

       $obj->spamDetected()
           Returns whether one of the spam groups defines a report about spam.  If there are not
           header fields in the message which relate to spam-detection software, "undef" is
           returned.  The spamgroups which report spam are returned.

           example:

            $message->delete if $message->spamDetected;

            call_spamassassin($message)
               unless defined $message->spamDetected;

       $obj->spamGroups([NAMES])
           Returns a list of Mail::Message::Head::SpamGroup objects, each collecting some lines
           which contain spam fighting information.  When any NAMES are given, then only these
           groups are returned.  See also addSpamGroup() and removeSpamGroups().

           In scalar context, with exactly one NAME specified, that group will be returned.  With
           more NAMES or without NAMES, a list will be returned (which defaults to the length of
           the list in scalar context).

           example: use of listGroup()

            my @sg = $msg->head->spamGroups;
            $sg[0]->print(\*STDERR);
            $sg[-1]->delete;

            my $sg = $msg->head->spamGroups('SpamAssassin');

       $obj->string()
           Returns the whole header as one scalar (in scalar context) or list of lines (list
           context).  Triggers completion.

       $obj->study(NAME [,INDEX])
           See "Access to the header" in Mail::Message::Head

   About the body
       See documentation in the base class.

       $obj->guessBodySize()
           See "About the body" in Mail::Message::Head

       $obj->guessTimeStamp()
           Make a guess about when the message was origanally posted, based on the information
           found in the header's "Date" field.

           For some kinds of folders, Mail::Message::guessTimestamp() may produce a better
           result, for instance by looking at the modification time of the file in which the
           message is stored.  Also some protocols, like POP can supply that information.

       $obj->isMultipart()
           See "About the body" in Mail::Message::Head

       $obj->recvstamp()
           Returns an indication about when the message was sent, but only using the "Date" field
           in the header as last resort: we do not trust the sender of the message to specify the
           correct date.  See timestamp() when you do trust the sender.

           Many spam producers fake a date, which mess up the order of receiving things.  The
           timestamp which is produced is derived from the Received headers, if they are present,
           and "undef" otherwise.

           The timestamp is encoded as "time" is on your system (see perldoc -f time), and as
           such usable for the "gmtime" and "localtime" methods.

           example: of time-sorting folders with received messages

            my $folder = $mgr->open('InBox');
            my @messages = sort {$a->recvstamp <=> $b->recvstamp}
                              $folder->messages;

           example: of time-sorting messages of mixed origin

            my $folder = $mgr->open('MyFolder');

            # Pre-calculate timestamps to be sorted (for speed)
            my @stamps = map { [ ($_->timestamp || 0), $_ ] }
                                $folder->messages;

            my @sorted
              = map { $_->[1] }      # get the message for the stamp
                  sort {$a->[0] <=> $b->[0]}   # stamps are numerics
                     @stamps;

       $obj->timestamp()
           Returns an indication about when the message was sent, with as little guessing as
           possible.  In this case, the date as specified by the sender is trusted.  See
           recvstamp() when you do not want to trust the sender.

           The timestamp is encoded as "time" is on your system (see perldoc -f time), and as
           such usable for the "gmtime" and "localtime" methods.

   Internals
       See documentation in the base class.

       $obj->addNoRealize(FIELD)
           See "Internals" in Mail::Message::Head

       $obj->addOrderedFields(FIELDS)
           See "Internals" in Mail::Message::Head

       $obj->createFromLine()
           For some mail-folder types separate messages by a line starting with '"From "'.  If a
           message is moved to such folder from a folder-type which does not support these
           separators, this method is called to produce one.

       $obj->createMessageId()
           Creates a message-id for this message.  This method will be run when a new message is
           created, or a message is discovered without the message-id header field.  Message-ids
           are required for detection of message-threads.  See messageIdPrefix().

       $obj->fileLocation()
           See "Internals" in Mail::Message::Head

       $obj->load()
           See "Internals" in Mail::Message::Head

       $obj->messageIdPrefix([PREFIX, [HOSTNAME]|CODE])
       Mail::Message::Head::Complete->messageIdPrefix([PREFIX, [HOSTNAME]|CODE])
           When options are provided, it sets a new way to create message-ids, as used by
           createMessageId().  You have two choices: either by providing a PREFIX and optionally
           a HOSTNAME, or a CODE reference.

           The CODE reference will be called with the header as first argument.  You must ensure
           yourself that the returned value is RFC compliant.

           The PREFIX defaults to "mailbox-$$", the HOSTNAME defaults to the return of
           Net::Domains's function "hostfqdn()", or when not installed, the Sys::Hostname's
           function "hostname()".  Inbetween the two, a nano-second time provided by Time::HiRes
           is used.  If that module is not available, "time" is called at the start of the
           program, and incremented for each newly created id.

           In any case, a subroutine will be created to be used.  A reference to that will be
           returned.  When the method is called without arguments, but no subroutine is defined
           yet, one will be created.

           example: setting a message prefix

             $head->messageIdPrefix('prefix');
             Mail::Message::Head::Complete->messageIdPrefix('prefix');
             my $code = $head->messageIdPrefix('mailbox', 'nohost');

             sub new_msgid()
             {   my $head = shift;
                 "myid-$$-${(rand 10000)}@example.com";
             }

             $many_msg->messageIdPrefix(\&new_msgid);
             Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);

       $obj->moveLocation(DISTANCE)
           See "Internals" in Mail::Message::Head

       $obj->read(PARSER)
           See "Internals" in Mail::Message::Head

       $obj->setNoRealize(FIELD)
           See "Internals" in Mail::Message::Head

   Error handling
       See documentation in the base class.

       $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::Complete->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::Complete->log([LEVEL [,STRINGS]])
           See "Error handling" in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Message::Head::Complete->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
       See documentation in the base class.

       $obj->DESTROY()
           See "Cleanup" in Mail::Reporter

DETAILS

       See documentation in the base class.

DIAGNOSTICS

       Warning: Cannot remove field $name from header: not found.
           You ask to remove a field which is not known in the header.  Using delete(), reset(),
           or set() to do the job will not result in warnings: those methods check the existence
           of the field first.

       Warning: Field objects have an implied name ($name)
       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.110, built on January 05, 2014.
       Website: http://perl.overmeer.net/mailbox/

LICENSE

       Copyrights 2001-2014 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