{
    "content": [
        {
            "type": "text",
            "text": "# Mail::Message::Head (info)\n\n## NAME\n\nMail::Message::Head - the header of one message\n\n## SYNOPSIS\n\nmy $head = Mail::Message::Head->new;\n$head->add('From: me@localhost');\n$head->add(From => 'me@localhost');\n$head->add(Mail::Message::Field->new(From => 'me'));\nmy $subject = $head->get('subject');\nmy @rec = $head->get('received');\n$head->delete('From');\n\n## DESCRIPTION\n\n\"Mail::Message::Head\" MIME headers are part of Mail::Message messages,\nwhich are grouped in Mail::Box folders.\n\n## Sections\n\n- **Mail::Message::Head(3pUser Contributed Perl DocumentatMail::Message::Head(3pm)**\n- **NAME**\n- **INHERITANCE**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OVERLOADED**\n- **METHODS**\n- **DETAILS**\n- **DIAGNOSTICS**\n- **SEE ALSO**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Mail::Message::Head",
        "section": "",
        "mode": "info",
        "summary": "Mail::Message::Head - the header of one message",
        "synopsis": "my $head = Mail::Message::Head->new;\n$head->add('From: me@localhost');\n$head->add(From => 'me@localhost');\n$head->add(Mail::Message::Field->new(From => 'me'));\nmy $subject = $head->get('subject');\nmy @rec = $head->get('received');\n$head->delete('From');",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "Mail::Message::Head(3pUser Contributed Perl DocumentatMail::Message::Head(3pm)",
                "lines": 1,
                "subsections": []
            },
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "INHERITANCE",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "OVERLOADED",
                "lines": 19,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 230,
                "subsections": []
            },
            {
                "name": "DETAILS",
                "lines": 75,
                "subsections": []
            },
            {
                "name": "DIAGNOSTICS",
                "lines": 7,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "Mail::Message::Head(3pUser Contributed Perl DocumentatMail::Message::Head(3pm)": {
                "content": "",
                "subsections": []
            },
            "NAME": {
                "content": "Mail::Message::Head - the header of one message\n",
                "subsections": []
            },
            "INHERITANCE": {
                "content": "Mail::Message::Head\nis a Mail::Reporter\n\nMail::Message::Head is extended by\nMail::Message::Head::Complete\nMail::Message::Head::Delayed\nMail::Message::Head::Subset\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "my $head = Mail::Message::Head->new;\n$head->add('From: me@localhost');\n$head->add(From => 'me@localhost');\n$head->add(Mail::Message::Field->new(From => 'me'));\nmy $subject = $head->get('subject');\nmy @rec = $head->get('received');\n$head->delete('From');\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "\"Mail::Message::Head\" MIME headers are part of Mail::Message messages,\nwhich are grouped in Mail::Box folders.\n\nATTENTION!!! most functionality about e-mail headers is described in\nMail::Message::Head::Complete, which is a matured header object.  Other\nkinds of headers will be translated to that type when time comes.\n\nOn this page, the general methods which are available on any header are\ndescribed.  Read about differences in the sub-class specific pages.\n\nExtends \"DESCRIPTION\" in Mail::Reporter.\n",
                "subsections": []
            },
            "OVERLOADED": {
                "content": "overload: \"\"\n(stringifaction) The header, when used as string, will format as if\nMail::Message::Head::Complete::string() was called, so return a\nnicely folder full header.  An exception is made for Carp, which\nwill get a simplified string to avoid unreadible messages from\n\"croak\" and \"confess\".\n\nexample: using a header object as string\n\nprint $head;     # implicit stringification by print\n$head->print;    # the same\n\nprint \"$head\";   # explicit stringication\n\noverload: bool\nWhen the header does not contain any lines (which is illegal,\naccording to the RFCs), false is returned.  In all other cases, a\ntrue value is produced.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "Extends \"METHODS\" in Mail::Reporter.\n\nConstructors\nExtends \"Constructors\" in Mail::Reporter.\n\nMail::Message::Head->build( [PAIR|$field]-LIST )\nA fast way to construct a header with many lines.  The PAIRs are\n\"(name, content)\" pairs of the header, but it is also possible to\npass Mail::Message::Field objects.   A\nMail::Message::Head::Complete header is created by simply calling\nMail::Message::Head::Complete::build(), and then each field is\nadded.  Double field names are permitted.\n\nexample:\n\nmy $subject = Mail::Message::Field->new(Subject => 'xyz');\n\nmy $head = Mail::Message::Head->build\n( From     => 'me@example.com'\n, To       => 'you@anywhere.aq'\n, $subject\n, Received => 'one'\n, Received => 'two'\n);\n\nprint ref $head;\n# -->  Mail::Message::Head::Complete\n\nMail::Message::Head->new(%options)\nCreate a new message header object.  The object will store all the\nfields of a header.  When you get information from the header, it\nwill be returned to you as Mail::Message::Field objects, although\nthe fields may be stored differently internally.\n\nIf you try to instantiate a Mail::Message::Head, you will\nautomatically be upgraded to a Mail::Message::Head::Complete --a\nfull head.\n\n-Option    --Defined in     --Default\nfieldtype                   Mail::Message::Field::Fast\nlog         Mail::Reporter   'WARNINGS'\nmessage                      undef\nmodified                     <false>\ntrace       Mail::Reporter   'WARNINGS'\n\nfieldtype => CLASS\nThe type of objects that all the fields will have.  This must be\nan extension of Mail::Message::Field.\n\nlog => LEVEL\nmessage => MESSAGE\nThe MESSAGE where this header belongs to.  Usually, this is not\nknown at creation of the header, but sometimes it is.  If not,\ncall the message() method later to set it.\n\nmodified => BOOLEAN\ntrace => LEVEL\n\nThe header\n$obj->isDelayed()\nHeaders may only be partially read, in which case they are called\ndelayed.  This method returns true if some header information still\nneeds to be read. Returns false if all header data has been read.\nWill never trigger completion.\n\n$obj->isEmpty()\nAre there any fields defined in the current header?  Be warned that\nthe header will not be loaded for this: delayed headers will return\ntrue in any case.\n\n$obj->isModified()\nReturns whether the header has been modified after being read.\n\nexample:\n\nif($head->isModified) { ... }\n\n$obj->knownNames()\nLike Mail::Message::Head::Complete::names(), but only returns the\nknown header fields, which may be less than \"names\" for header\ntypes which are partial.  \"names()\" will trigger completion, where\n\"knownNames()\" does not.\n\n$obj->message( [$message] )\nGet (after setting) the message where this header belongs to.  This\ndoes not trigger completion.\n\n$obj->modified( [BOOLEAN] )\nSets the modified flag to BOOLEAN.  Without value, the current\nsetting is returned, but in that case you can better use\nisModified().  Changing this flag will not trigger header\ncompletion.\n\nexample:\n\n$head->modified(1);\nif($head->modified) { ... }\nif($head->isModified) { ... }\n\n$obj->orderedFields()\nReturns the fields ordered the way they were read or added.\n\nAccess to the header\n$obj->get( $name, [$index] )\nGet the data which is related to the field with the $name.  The\ncase of the characters in $name does not matter.\n\nIf there is only one data element defined for the $name, or if\nthere is an $index specified as the second argument, only the\nspecified element will be returned. If the field $name matches more\nthan one header the return value depends on the context. In LIST\ncontext, all values will be returned in the order they are read. In\nSCALAR context, only the last value will be returned.\n\nexample:\n\nmy $head = Mail::Message::Head->new;\n$head->add('Received: abc');\n$head->add('Received: xyz');\n$head->add('Subject: greetings');\n\nmy @reclist   = $head->get('Received');\nmy $recscalar = $head->get('Received');\nprint \",@reclist,$recscalar,\"     # ,abc xyz, xyz,\nprint $head->get('Received', 0);    # abc\nmy @sublist   = $head->get('Subject');\nmy $subscalar = $head->get('Subject');\nprint \",@sublist,$subscalar,\"     # ,greetings, greetings,\n\n$obj->study( $name, [$index] )\nLike get(), but puts more effort in understanding the contents of\nthe field.  Mail::Message::Field::study() will be called for the\nfield with the specified FIELDNAME, which returns\nMail::Message::Field::Full objects. In scalar context only the last\nfield with that name is returned.  When an $index is specified,\nthat element is returned.\n\nAbout the body\n$obj->guessBodySize()\nTry to estimate the size of the body of this message, but without\nparsing the header or body.  The result might be \"undef\" or a few\npercent of the real size.  It may even be very far of the real\nvalue, that's why this is a guess.\n\n$obj->isMultipart()\nReturns whether the body of the related message is a multipart\nbody.  May trigger completion, when the \"Content-Type\" field is not\ndefined.\n\nInternals\n$obj->addNoRealize($field)\nAdd a field, like Mail::Message::Head::Complete::add() does, but\navoid the loading of a possibly partial header.  This method does\nnot test the validity of the argument, nor flag the header as\nchanged.  This does not trigger completion.\n\n$obj->addOrderedFields($fields)\n$obj->fileLocation()\nReturns the location of the header in the file, as a pair begin and\nend.  The begin is the first byte of the header.  The end is the\nfirst byte after the header.\n\n$obj->load()\nBe sure that the header is loaded.  This returns the loaded header\nobject.\n\n$obj->moveLocation($distance)\nMove the registration of the header in the file.\n\n$obj->read($parser)\nRead the header information of one message into this header\nstructure.  This method is called by the folder object (some\nMail::Box sub-class), which passes the $parser as an argument.\n\n$obj->setNoRealize($field)\nSet a field, but avoid the loading of a possibly partial header as\nset() does.  This method does not test the validity of the\nargument, nor flag the header as changed.  This does not trigger\ncompletion.\n\nError handling\nExtends \"Error handling\" in Mail::Reporter.\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,\n$callback] )\nMail::Message::Head->defaultTrace( [$level]|[$loglevel,\n$tracelevel]|[$level, $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->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Message::Head->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\nCleanup\nExtends \"Cleanup\" in Mail::Reporter.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Reporter\n",
                "subsections": []
            },
            "DETAILS": {
                "content": "Ordered header fields\nMany Perl implementations make a big mistake by disturbing the order of\nheader fields.  For some fields (especially the resent groups, see\nMail::Message::Head::ResentGroup) the order shall be maintained.\n\nMailBox will keep the order of the fields as they were found in the\nsource.  When your add a new field, it will be added at the end.  If\nyour replace a field with a new value, it will stay in the original\norder.\n\nHead class implementation\nThe header of a MIME message object contains a set of lines, which are\ncalled fields (by default represented by Mail::Message::Field objects).\nDependent on the situation, the knowledge about the fields can be in\none of three situations, each represented by a sub-class of this\nmodule:\n\no   Mail::Message::Head::Complete\n\nIn this case, it is sure that all knowledge about the header is\navailable.  When you get() information from the header and it is\nnot there, it will never be there.\n\no   Mail::Message::Head::Subset\n\nThere is no certainty whether all header lines are known (probably\nnot).  This may be caused as result of reading a fast index file,\nas described in Mail::Box::MH::Index.  The object is automatically\ntransformed into a Mail::Message::Head::Complete when all header\nlines must be known.\n\no   Mail::Message::Head::Partial\n\nA partial header is like a subset header: probably the header is\nincomplete.  The means that you are not sure whether a get() for a\nfield fails because the field is not a part of the message or that\nit fails because it is not yet known to the program.  Where the\nsubset header knows where to get the other fields, the partial\nheader does not know it.  It cannot hide its imperfection.\n\no   Mail::Message::Head::Delayed\n\nIn this case, there is no single field known.  Access to this\nheader will always trigger the loading of the full header.\n\nSubsets of header fields\nMessage headers can be quite large, and therefore MailBox provides\nsimplified access to some subsets of information.  You can grab these\nsets of fields together, create and delete them as group.\n\nOn the moment, the following sets are defined:\n\no   Mail::Message::Head::ResentGroup\n\nA resent group is a set of fields which is used to log one step in\nthe transmission of the message from the original sender to the\ndestination.\n\nEach step adds a set of headers to indicate when the message was\nreceived and how it was forwarded (without modification).  These\nfields are best created using Mail::Message::bounce().\n\no   Mail::Message::Head::ListGroup\n\nFields which are used to administer and log mailing list activity.\nMailing list software has to play trics with the original message\nto be able to get the reply on that message back to the mailing\nlist.  Usually a large number of lines are added.\n\no   Mail::Message::Head::SpamGroup\n\nA set of fields which contains header fields which are produced by\nspam detection software.  You may want to remove these fields when\nyou store a message for a longer period of time.\n",
                "subsections": []
            },
            "DIAGNOSTICS": {
                "content": "Error: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does\nnot implement this method where it should. This message means that\nsome other related classes do implement this method however the\nclass at hand does not.  Probably you should investigate this and\nprobably inform the author of the package.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "This module is part of Mail-Message distribution version 3.012, built\non February 11, 2022. Website: http://perl.overmeer.net/CPAN/\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other\ncontributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it\nunder the same terms as Perl itself.  See http://dev.perl.org/licenses/\n\nperl v5.34.0                      2022-02-14          Mail::Message::Head(3pm)",
                "subsections": []
            }
        }
    }
}