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



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.

OVERLOADED
       overload: ""

           See "OVERLOADED" in Mail::Message::Head

       overload: bool

           See "OVERLOADED" in Mail::Message::Head

METHODS
       Constructors

       $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

       $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

       $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 adviced 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

       $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

       $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 Sys::Hostname's method "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

       $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

       $obj->DESTROY

           See "Cleanup" in Mail::Reporter

       $obj->inGlobalDestruction

           See "Cleanup" in Mail::Reporter

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