{
    "mode": "perldoc",
    "parameter": "Mail::Message::Head::Complete",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AMessage%3A%3AHead%3A%3AComplete/json",
    "generated": "2026-06-09T17:14:38Z",
    "synopsis": "my $head = Mail::Message::Head::Complete->new;\nSee Mail::Message::Head",
    "sections": {
        "NAME": {
            "content": "Mail::Message::Head::Complete - the header of one message\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Message::Head::Complete\nis a Mail::Message::Head\nis a Mail::Reporter\n\nMail::Message::Head::Complete is extended by\nMail::Message::Head::Partial\nMail::Message::Replace::MailHeader\n\nMail::Message::Head::Complete is realized by\nMail::Message::Head::Delayed\nMail::Message::Head::Subset\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $head = Mail::Message::Head::Complete->new;\nSee Mail::Message::Head\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "E-mail's message can be in various states: unread, partially read, and fully read. The class\nstores a message of which all header lines are known for sure.\n\nExtends \"DESCRIPTION\" in Mail::Message::Head.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "Extends \"OVERLOADED\" in Mail::Message::Head.\n\noverload: \"\"\nInherited, see \"OVERLOADED\" in Mail::Message::Head\n\noverload: bool\nInherited, see \"OVERLOADED\" in Mail::Message::Head\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Message::Head.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Message::Head.\n\nMail::Message::Head::Complete->build( [PAIR|$field], ... )\nUndefined values are interpreted as empty field values, and therefore skipped.\n\n$obj->clone( [@names|ARRAY|Regexps] )\nMake a copy of the header, optionally limited only to the header lines specified by @names.\nSee grepNames() on the way these fields can be used.\n\nexample:\n\nmy $newhead = $head->clone('Subject', 'Received');\n\nMail::Message::Head::Complete->new(%options)\nInherited, see \"Constructors\" in Mail::Message::Head\n"
                },
                {
                    "name": "The header",
                    "content": "Extends \"The header\" in Mail::Message::Head.\n\n$obj->isDelayed()\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->isEmpty()\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->isModified()\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->knownNames()\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->message( [$message] )\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->modified( [BOOLEAN] )\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->nrLines()\nReturn the number of lines needed to display this header (including the trailing newline)\n\n$obj->orderedFields()\nInherited, see \"The header\" in Mail::Message::Head\n\n$obj->size()\nReturn the number of bytes needed to display this header (including the trailing newline).\nOn systems which use CRLF as line separator, the number of lines in the header (see\nnrLines()) must be added to find the actual size in the file.\n\n$obj->wrap($integer)\nRe-fold all fields from the header to contain at most $integer number of characters per\nline.\n\nexample: re-folding a header\n\n$msg->head->wrap(78);\n"
                },
                {
                    "name": "Access to the header",
                    "content": "Extends \"Access to the header\" in Mail::Message::Head.\n\n$obj->add( $field | $line | <$name, $body, [$attrs]> )\nAdd a field to the header. If a field is added more than once, all values are stored in the\nheader, in the order they are added.\n\nWhen a $field object is specified (some Mail::Message::Field instance), that will be added.\nAnother possibility is to specify a raw header $line, or a header line nicely split-up in\n$name and $body, in which case the field constructor is called for you.\n\n$line or $body specifications which are terminated by a new-line are considered to be\ncorrectly folded. Lines which are not terminated by a new-line will be folded when needed:\nnew-lines will be added where required. It is strongly advised to let MailBox do the folding\nfor you.\n\nThe return value of this method is the Mail::Message::Field object which is created (or was\nspecified).\n\nexample:\n\nmy $head  = Mail::Message::Head->new;\n$head->add('Subject: hi!');\n$head->add(From => 'me@home');\nmy $field = Mail::Message::Field->new('To: you@there');\n$head->add($field);\nmy Mail::Message::Field $s = $head->add(Sender => 'I');\n\n$obj->addListGroup($object)\nA *list group* is a set of header fields which contain data about a mailing list which was\nused to transmit the message. See Mail::Message::Head::ListGroup for details about the\nimplementation of the $object.\n\nWhen you have a list group prepared, you can add it later using this method. You will get\nyour private copy of the list group data in return, because the same group can be used for\nmultiple messages.\n\nexample: of adding a list group to a header\n\nmy $lg = Mail::Message::Head::ListGroup->new(...);\nmy $ownlg = $msg->head->addListGroup($lg);\n\n$obj->addResentGroup($resentgroup|$data)\nAdd a $resentgroup (a Mail::Message::Head::ResentGroup object) to the header. If you\nspecify $data, that is used to create such group first. If no \"Received\" line is specified,\nit will be created for you.\n\nThese header lines have nothing to do with the user's sense of \"reply\" or \"forward\" actions:\nthese lines trace the e-mail transport mechanism.\n\nexample:\n\nmy $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);\n$head->addResentGroup($rg);\n\nmy $rg = $head->addResentGroup(From => 'me');\n\n$obj->addSpamGroup($object)\nA *spam fighting group* is a set of header fields which contains data which is used to fight\nspam. See Mail::Message::Head::SpamGroup for details about the implementation of the\n$object.\n\nWhen you have a spam group prepared, you can add it later using this method. You will get\nyour private copy of the spam group data in return, because the same group can be used for\nmultiple messages.\n\nexample: of adding a spam group to a header\n\nmy $sg = Mail::Message::Head::SpamGroup->new(...);\nmy $ownsg = $msg->head->addSpamGroup($sg);\n\n$obj->count($name)\nCount the number of fields with this $name. Most fields will return 1: only one occurrence\nin the header. As example, the \"Received\" fields are usually present more than once.\n\n$obj->delete($name)\nRemove the field with the specified name. If the header contained multiple lines with the\nsame name, they will be replaced all together. This method simply calls reset() without\nreplacement fields. READ THE IMPORTANT WARNING IN removeField()\n\n$obj->get( $name, [$index] )\nInherited, see \"Access to the header\" in Mail::Message::Head\n\n$obj->grepNames( [@names|ARRAY|Regexps] )\nFilter from all header fields those with names which start will any of the specified list.\nWhen no names are specified, all fields will be returned. The list is ordered as they where\nread from file, or added later.\n\nThe @names are considered regular expressions, and will all be matched case insensitive and\nattached to the front of the string only. You may also specify one or more prepared regexes.\n\nexample:\n\nmy @f  = $head->grepNames();       # same as $head->orderedFields\nmy @f  = $head->grepNames('X-', 'Subject', ');\nmy @to = $head->grepNames('To\\b'); # will only select To\n\n$obj->listGroup()\nReturns a *list group* description: the set of headers which form the information about\nmailing list software used to transport the message. See also addListGroup() and\nremoveListGroup().\n\nexample: use of listGroup()\n\nif(my $lg = $msg->head->listGroup)\n{  $lg->print(\\*STDERR);\n$lg->delete;\n}\n\n$msg->head->removeListGroup;\n\n$obj->names()\nReturns a full ordered list of known field names, as defined in the header. Fields which\nwere reset() to be empty will still be listed here.\n\n$obj->print( [$fh] )\nPrint all headers to the specified $fh, by default the selected filehandle. See\nprintUndisclosed() to limit the headers to include only the public headers.\n\nexample:\n\n$head->print(\\*OUT);\n$head->print;\n\nmy $fh = IO::File->new(...);\n$head->print($fh);\n\n$obj->printSelected($fh, <STRING|Regexp>, ...)\nLike the usual print(), the header lines are printed to the specified $fh. In this case,\nhowever, only the fields with names as specified by STRING (case insensative) or Regexp are\nprinted. They will stay the in-order of the source header.\n\nexample: printing only a subset of the fields\n\n$head->printSelected(STDOUT, qw/Subject From To/, qr/^x\\-(spam|xyz)\\-/i)\n\n$obj->printUndisclosed( [$fh] )\nLike the usual print(), the header lines are printed to the specified $fh, by default the\nselected filehandle. In this case, however, \"Bcc\" and \"Resent-Bcc\" lines are included.\n\n$obj->removeContentInfo()\nRemove all body related fields from the header. The header will become partial.\n\n$obj->removeField($field)\nRemove the specified $field object from the header. This is useful when there are possible\nmore than one fields with the same name, and you need to remove exactly one of them. Also\nhave a look at delete(), reset(), and set().\n\nSee also Mail::Message::Head::Partial::removeFields() (mind the 's' at the end of the name),\nwhich accepts a string or regular expression as argument to select the fields to be removed.\n\nWARNING WARNING WARNING: for performance reasons, the header administration uses weak\nreferences (see Scalar::Util method weaken()> to figure-out which fields have been removed.\nA header is a hash of field for fast search and an array of weak references to remember the\norder of the fields, required for printing. If the field is removed from the hash, the\nweak-ref is set to undef and the field not printed.\n\nHowever... it is easy to disturb this process. Example: my $msg = ....; # subject ref-count\n= 1 + 0 = 1 $msg->head->delete('Subject'); # subject ref-count = 0 = 0: clean-up\n$msg->print; # subject doesn't show: ok\n\nBut my $msg = ....; # subject ref-count = 1 + 0 = 1 my $s = $msg->head->get('subject'); #\nref-count = 1 + 1 + 0 = 2 $msg->head->delete('Subject'); # subject ref-count = 1 + 0 = 1: no\nclean-up $msg->print; # subject DOES show: not ok undef $s; # ref-count becomes 0: clean-up\n$msg->print; # subject doesn't show: ok\n\nTo avoid the latter situation, do not catch the field object, but only the field content.\nSAVE are all methods which return the text: my $s = $msg->head->get('subject')->body; my $s\n= $msg->head->get('subject')->unfoldedBody; my $s = $msg->head->get('subject')->foldedBody;\nmy $s = $msg->head->get('subject')->foldedBody; my $s = $msg->get('subject'); my $s =\n$msg->subject; my $s = $msg->string;\n\n$obj->removeFields( <STRING|Regexp>, ... )\nThe header object is turned into a Mail::Message::Head::Partial object which has a set of\nfields removed. Read about the implications and the possibilities in\nMail::Message::Head::Partial::removeFields().\n\n$obj->removeFieldsExcept( <STRING|Regexp>, ... )\nThe header object is turned into a Mail::Message::Head::Partial object which has a set of\nfields removed. Read about the implications and the possibilities in\nMail::Message::Head::Partial::removeFieldsExcept().\n\n$obj->removeListGroup()\nRemoves all fields related to mailing list administration at once. The header object is\nturned into a Mail::Message::Head::Partial object. Read about the implications and the\npossibilities in Mail::Message::Head::Partial::removeListGroup().\n\n$obj->removeResentGroups()\nRemoves all resent groups at once. The header object is turned into a\nMail::Message::Head::Partial object. Read about the implications and the possibilities in\nMail::Message::Head::Partial::removeResentGroups().\n\n$obj->removeSpamGroups()\nRemoves all fields which were added by various spam detection software at once. The header\nobject is turned into a Mail::Message::Head::Partial object. Read about the implications and\nthe possibilities in Mail::Message::Head::Partial::removeSpamGroups().\n\n$obj->resentGroups()\nReturns a list of Mail::Message::Head::ResentGroup objects which each represent one\nintermediate point in the message's transmission in the order as they appear in the header:\nthe most recent one first. See also addResentGroup() and removeResentGroups().\n\nA resent group contains a set of header fields whose names start with \"Resent-*\". Before the\nfirst \"Resent\" line is *trace* information, which is composed of an optional \"Return-Path\"\nfield and an required \"Received\" field.\n\n$obj->reset($name, @fields)\nReplace the values in the header fields named by $name with the values specified in the list\nof @fields. A single name can correspond to multiple repeated fields. READ THE IMPORTANT\nWARNING IN removeField()\n\nRemoving fields which are part of one of the predefined field groups is not a smart idea.\nYou can better remove these fields as group, all together. For instance, the 'Received'\nlines are part of resent groups, 'X-Spam' is past of a spam group, and \"List-Post\" belongs\nto a list group. You can delete a whole group with\nMail::Message::Head::FieldGroup::delete(), or with methods which are provided by\nMail::Message::Head::Partial.\n\nIf FIELDS is empty, the corresponding $name fields will be removed. The location of removed\nfields in the header order will be remembered. Fields with the same name which are added\nlater will appear at the remembered position. This is equivalent to the delete() method.\n\nexample:\n\n# reduce number of 'Keywords' lines to last 5)\nmy @keywords = $head->get('Keywords');\n$head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;\n\n# Reduce the number of Received lines to only the last added one.\nmy @rgs = $head->resentGroups;\nshift @rgs;     # keep this one (later is added in front)\n$->delete foreach @rgs;\n\n$obj->set( $field | $line | <$name, $body, [$attrs]> )\nThe \"set\" method is similar to the add() method, and takes the same options. However,\nexisting values for fields will be removed before a new value is added. READ THE IMPORTANT\nWARNING IN removeField()\n\n$obj->spamDetected()\nReturns whether one of the spam groups defines a report about spam. If there are not header\nfields in the message which relate to spam-detection software, \"undef\" is returned. The\nspamgroups which report spam are returned.\n\nexample:\n\n$message->delete if $message->spamDetected;\n\ncallspamassassin($message)\nunless defined $message->spamDetected;\n\n$obj->spamGroups( [$names] )\nReturns a list of Mail::Message::Head::SpamGroup objects, each collecting some lines which\ncontain spam fighting information. When any $names are given, then only these groups are\nreturned. See also addSpamGroup() and removeSpamGroups().\n\nIn scalar context, with exactly one NAME specified, that group will be returned. With more\n$names or without $names, a list will be returned (which defaults to the length of the list\nin scalar context).\n\nexample: use of listGroup()\n\nmy @sg = $msg->head->spamGroups;\n$sg[0]->print(\\*STDERR);\n$sg[-1]->delete;\n\nmy $sg = $msg->head->spamGroups('SpamAssassin');\n\n$obj->string()\nReturns the whole header as one scalar (in scalar context) or list of lines (list context).\nTriggers completion.\n\n$obj->study( $name, [$index] )\nInherited, see \"Access to the header\" in Mail::Message::Head\n"
                },
                {
                    "name": "About the body",
                    "content": "Extends \"About the body\" in Mail::Message::Head.\n\n$obj->guessBodySize()\nInherited, see \"About the body\" in Mail::Message::Head\n\n$obj->guessTimeStamp()\nMake a guess about when the message was origanally posted, based on the information found in\nthe header's \"Date\" field.\n\nFor some kinds of folders, Mail::Message::guessTimestamp() may produce a better result, for\ninstance by looking at the modification time of the file in which the message is stored.\nAlso some protocols, like POP can supply that information.\n\n$obj->isMultipart()\nInherited, see \"About the body\" in Mail::Message::Head\n\n$obj->recvstamp()\nReturns an indication about when the message was sent, but only using the \"Date\" field in\nthe header as last resort: we do not trust the sender of the message to specify the correct\ndate. See timestamp() when you do trust the sender.\n\nMany spam producers fake a date, which mess up the order of receiving things. The timestamp\nwhich is produced is derived from the Received headers, if they are present, and \"undef\"\notherwise.\n\nThe timestamp is encoded as \"time\" is on your system (see perldoc -f time), and as such\nusable for the \"gmtime\" and \"localtime\" methods.\n\nexample: of time-sorting folders with received messages\n\nmy $folder = $mgr->open('InBox');\nmy @messages = sort {$a->recvstamp <=> $b->recvstamp}\n$folder->messages;\n\nexample: of time-sorting messages of mixed origin\n\nmy $folder = $mgr->open('MyFolder');\n\n# Pre-calculate timestamps to be sorted (for speed)\nmy @stamps = map { [ ($->timestamp || 0), $ ] }\n$folder->messages;\n\nmy @sorted\n= map { $->[1] }      # get the message for the stamp\nsort {$a->[0] <=> $b->[0]}   # stamps are numerics\n@stamps;\n\n$obj->timestamp()\nReturns an indication about when the message was sent, with as little guessing as possible.\nIn this case, the date as specified by the sender is trusted. See recvstamp() when you do\nnot want to trust the sender.\n\nThe timestamp is encoded as \"time\" is on your system (see perldoc -f time), and as such\nusable for the \"gmtime\" and \"localtime\" methods.\n"
                },
                {
                    "name": "Internals",
                    "content": "Extends \"Internals\" in Mail::Message::Head.\n\n$obj->addNoRealize($field)\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->addOrderedFields($fields)\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->createFromLine()\nFor some mail-folder types separate messages by a line starting with '\"From \"'. If a message\nis moved to such folder from a folder-type which does not support these separators, this\nmethod is called to produce one.\n\n$obj->createMessageId()\nCreates a message-id for this message. This method will be run when a new message is\ncreated, or a message is discovered without the message-id header field. Message-ids are\nrequired for detection of message-threads. See messageIdPrefix().\n\n$obj->fileLocation()\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->load()\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->messageIdPrefix( [$prefix, [$hostname]|CODE] )\nMail::Message::Head::Complete->messageIdPrefix( [$prefix, [$hostname]|CODE] )\nWhen options are provided, it sets a new way to create message-ids, as used by\ncreateMessageId(). You have two choices: either by providing a $prefix and optionally a\n$hostname, or a CODE reference.\n\nThe CODE reference will be called with the header as first argument. You must ensure\nyourself that the returned value is RFC compliant.\n\nThe $prefix defaults to \"mailbox-$$\", the $hostname defaults to the return of Net::Domains's\nfunction \"hostfqdn()\", or when not installed, the Sys::Hostname's function \"hostname()\".\nInbetween the two, a nano-second time provided by Time::HiRes is used. If that module is not\navailable, \"time\" is called at the start of the program, and incremented for each newly\ncreated id.\n\nIn any case, a subroutine will be created to be used. A reference to that will be returned.\nWhen the method is called without arguments, but no subroutine is defined yet, one will be\ncreated.\n\nexample: setting a message prefix\n\n$head->messageIdPrefix('prefix');\nMail::Message::Head::Complete->messageIdPrefix('prefix');\nmy $code = $head->messageIdPrefix('mailbox', 'nohost');\n\nsub newmsgid()\n{   my $head = shift;\n\"myid-$$-${(rand 10000)}@example.com\";\n}\n\n$manymsg->messageIdPrefix(\\&newmsgid);\nMail::Message::Head::Complete->messageIdPrefix(&newmsgid);\n\n$obj->moveLocation($distance)\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->read($parser)\nInherited, see \"Internals\" in Mail::Message::Head\n\n$obj->setNoRealize($field)\nInherited, see \"Internals\" in Mail::Message::Head\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Message::Head.\n\n$obj->AUTOLOAD()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->addReport($object)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nMail::Message::Head::Complete->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,\n$callback] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->errors()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->log( [$level, [$strings]] )\nMail::Message::Head::Complete->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Message::Head::Complete->logPriority($level)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logSettings()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->notImplemented()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->report( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->reportAll( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->trace( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->warnings()\nInherited, see \"Error handling\" in Mail::Reporter\n"
                },
                {
                    "name": "Cleanup",
                    "content": "Extends \"Cleanup\" in Mail::Message::Head.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Reporter\n"
                }
            ]
        },
        "DETAILS": {
            "content": "Extends \"DETAILS\" in Mail::Message::Head.\n",
            "subsections": []
        },
        "DIAGNOSTICS": {
            "content": "Warning: Cannot remove field $name from header: not found.\nYou ask to remove a field which is not known in the header. Using delete(), reset(), or\nset() to do the job will not result in warnings: those methods check the existence of the\nfield first.\n\nWarning: Field objects have an implied name ($name)\nError: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does not implement this\nmethod where it should. This message means that some other related classes do implement this\nmethod however the class at hand does not. Probably you should investigate this and probably\ninform the author of the package.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Message distribution version 3.012, built on February 11, 2022.\nWebsite: http://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Message::Head::Complete - the header of one message",
    "flags": [],
    "examples": [],
    "see_also": []
}