{ "content": [ { "type": "text", "text": "# Mail::Box (perldoc)\n\n## NAME\n\nMail::Box - manage a mailbox, a folder with messages\n\n## SYNOPSIS\n\nuse Mail::Box::Manager;\nmy $mgr = Mail::Box::Manager->new;\nmy $folder = $mgr->open(folder => $ENV{MAIL}, ...);\nprint $folder->name;\n# Get the first message.\nprint $folder->message(0);\n# Delete the third message\n$folder->message(3)->delete;\n# Get the number of messages in scalar context.\nmy $emails = $folder->messages;\n# Iterate over the messages.\nforeach ($folder->messages) {...} # all messages\nforeach (@$folder) {...} # all messages\n$folder->addMessage(Mail::Box::Message->new(...));\nTied-interface:\ntie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox;\n# Four times the same:\n$inbox[3]->print; # tied\n$folder->[3]->print; # overloaded folder\n$folder->message(3)->print; # usual\nprint $folder->[3]; # overloaded message\ntie my(%inbox), 'Mail::Box::Tie::HASH', $inbox;\n# Twice times the same\n$inbox{$msgid}->print; # tied\n$folder->messageId($msgid)->print;# usual\n\n## DESCRIPTION\n\nA Mail::Box::Manager creates \"Mail::Box\" objects. But you already knew, because you started with\nthe Mail::Box-Overview manual page. That page is obligatory reading, sorry!\n\n## Sections\n\n- **NAME**\n- **INHERITANCE**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OVERLOADED**\n- **METHODS** (9 subsections)\n- **DETAILS** (3 subsections)\n- **DIAGNOSTICS**\n- **SEE ALSO**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Mail::Box", "section": "", "mode": "perldoc", "summary": "Mail::Box - manage a mailbox, a folder with messages", "synopsis": "use Mail::Box::Manager;\nmy $mgr = Mail::Box::Manager->new;\nmy $folder = $mgr->open(folder => $ENV{MAIL}, ...);\nprint $folder->name;\n# Get the first message.\nprint $folder->message(0);\n# Delete the third message\n$folder->message(3)->delete;\n# Get the number of messages in scalar context.\nmy $emails = $folder->messages;\n# Iterate over the messages.\nforeach ($folder->messages) {...} # all messages\nforeach (@$folder) {...} # all messages\n$folder->addMessage(Mail::Box::Message->new(...));\nTied-interface:\ntie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox;\n# Four times the same:\n$inbox[3]->print; # tied\n$folder->[3]->print; # overloaded folder\n$folder->message(3)->print; # usual\nprint $folder->[3]; # overloaded message\ntie my(%inbox), 'Mail::Box::Tie::HASH', $inbox;\n# Twice times the same\n$inbox{$msgid}->print; # tied\n$folder->messageId($msgid)->print;# usual", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "INHERITANCE", "lines": 8, "subsections": [] }, { "name": "SYNOPSIS", "lines": 36, "subsections": [] }, { "name": "DESCRIPTION", "lines": 14, "subsections": [] }, { "name": "OVERLOADED", "lines": 28, "subsections": [] }, { "name": "METHODS", "lines": 2, "subsections": [ { "name": "Constructors", "lines": 245 }, { "name": "The folder", "lines": 230 }, { "name": "Folder flags", "lines": 21 }, { "name": "The messages", "lines": 161 }, { "name": "Sub-folders", "lines": 67 }, { "name": "Internals", "lines": 141 }, { "name": "Other methods", "lines": 5 }, { "name": "Error handling", "lines": 41 }, { "name": "Cleanup", "lines": 6 } ] }, { "name": "DETAILS", "lines": 1, "subsections": [ { "name": "Different kinds of folders", "lines": 46 }, { "name": "Available folder types", "lines": 51 }, { "name": "Folder class implementation", "lines": 21 } ] }, { "name": "DIAGNOSTICS", "lines": 55, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "LICENSE", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "Mail::Box - manage a mailbox, a folder with messages\n", "subsections": [] }, "INHERITANCE": { "content": "Mail::Box\nis a Mail::Reporter\n\nMail::Box is extended by\nMail::Box::Dir\nMail::Box::File\nMail::Box::Net\n", "subsections": [] }, "SYNOPSIS": { "content": "use Mail::Box::Manager;\nmy $mgr = Mail::Box::Manager->new;\nmy $folder = $mgr->open(folder => $ENV{MAIL}, ...);\nprint $folder->name;\n\n# Get the first message.\nprint $folder->message(0);\n\n# Delete the third message\n$folder->message(3)->delete;\n\n# Get the number of messages in scalar context.\nmy $emails = $folder->messages;\n\n# Iterate over the messages.\nforeach ($folder->messages) {...} # all messages\nforeach (@$folder) {...} # all messages\n\n$folder->addMessage(Mail::Box::Message->new(...));\n\nTied-interface:\n\ntie my(@inbox), 'Mail::Box::Tie::ARRAY', $inbox;\n\n# Four times the same:\n$inbox[3]->print; # tied\n$folder->[3]->print; # overloaded folder\n$folder->message(3)->print; # usual\nprint $folder->[3]; # overloaded message\n\ntie my(%inbox), 'Mail::Box::Tie::HASH', $inbox;\n\n# Twice times the same\n$inbox{$msgid}->print; # tied\n$folder->messageId($msgid)->print;# usual\n", "subsections": [] }, "DESCRIPTION": { "content": "A Mail::Box::Manager creates \"Mail::Box\" objects. But you already knew, because you started with\nthe Mail::Box-Overview manual page. That page is obligatory reading, sorry!\n\n\"Mail::Box\" is the base class for accessing various types of mailboxes (folders) in a uniform\nmanner. The various folder types vary on how they store their messages, but when some effort\nthose differences could be hidden behind a general API. For example, some folders store many\nmessages in one single file, where other store each message in a separate file within the same\ndirectory.\n\nNo object in your program will be of type \"Mail::Box\": it is only used as base class for the\nreal folder types. \"Mail::Box\" is extended by\n\nExtends \"DESCRIPTION\" in Mail::Reporter.\n", "subsections": [] }, "OVERLOADED": { "content": "overload: \"\"\n(stringification) The folder objects stringify to their name. This simplifies especially\nprint statements and sorting a lot.\n\nexample: use overloaded folder as string\n\n# Three lines with overloading: resp. cmp, @{}, and \"\"\nforeach my $folder (sort @folders)\n{ my $msgcount = @$folder;\nprint \"$folder contains $msgcount messages\\n\";\n}\n\noverload: @{}\nWhen the folder is used as if it is a reference to an array, it will show the messages, like\nmessages() and message() would do.\n\nexample: use overloaded folder as array\n\nmy $msg = $folder->[3];\nmy $msg = $folder->message(3); # same\n\nforeach my $msg (@$folder) ...\nforeach my $msg ($folder->messages) ... # same\n\noverload: cmp\n(string comparison) folders are compared based on their name. The sort rules are those of\nthe build-in \"cmp\".\n", "subsections": [] }, "METHODS": { "content": "Extends \"METHODS\" in Mail::Reporter.\n", "subsections": [ { "name": "Constructors", "content": "Extends \"Constructors\" in Mail::Reporter.\n\nMail::Box->new(%options)\nOpen a new folder. A list of labeled %options for the mailbox can be supplied. Some options\npertain to Mail::Box, and others are added by sub-classes.\n\nTo control delay-loading of messages, as well the headers as the bodies, a set of *type\noptions are available. \"extract\" determines whether we want delay-loading.\n\n-Option --Defined in --Default\naccess 'r'\nbodydelayedtype Mail::Message::Body::Delayed\nbodytype \ncoerceoptions []\ncreate \nextract 10240\nfieldtype undef\nfixheaders \nfolder $ENV{MAIL}\nfolderdir undef\nheaddelayedtype Mail::Message::Head::Delayed\nheadtype Mail::Message::Head::Complete\nkeepdups \nlockfile undef\nlocktimeout 1 hour\nlocktype Mail::Box::Locker::DotLock\nlockwait 10 seconds\nlocker undef\nlog Mail::Reporter 'WARNINGS'\nmanager undef\nmessagetype ::Message\nmultiparttype Mail::Message::Body::Multipart\nremovewhenempty \nsaveonexit \ntrace Mail::Reporter 'WARNINGS'\ntrusted \n\naccess => MODE\nAccess-rights to the folder. Folders are opened for read-only (which means\nwrite-protected) by default! MODE can be\n\n'r': read-only (default)\n'a': append\n'rw': read-write\n'd': delete\n\nThese MODE has no relation to the modes actually used to open the folder files within this\nmodule. For instance, if you specify \"rw\", and open the folder, only read permission on\nthe folder-file is required.\n\nBe warned: writing a MBOX folder may create a new file to replace the old folder. The\npermissions and owner of the file may get changed by this.\n\nbodydelayedtype => CLASS\nThe bodies which are delayed: which will be read from file when it is needed, but not\nbefore.\n\nbodytype => CLASS|CODE\nWhen messages are read from a folder-file, the headers will be stored in a \"headtype\"\nobject. For the body, however, there is a range of choices about type, which are all\ndescribed in Mail::Message::Body.\n\nSpecify a CODE-reference which produces the body-type to be created, or a CLASS of the\nbody which is used when the body is not a multipart or nested. In case of a code\nreference, the header structure is passed as first argument to the routine.\n\nDo *not* return a delayed body-type (like \"::Delayed\"), because that is determined by the\n\"extract\" option while the folder is opened. Even delayed message will require some real\nbody type when they get parsed eventually. Multiparts and nested messages are also outside\nyour control.\n\nFor instance:\n\n$mgr->open('InBox', bodytype => \\&whichbody);\n\nsub whichbody($) {\nmy $head = shift;\nmy $size = $head->guessBodySize || 0;\nmy $type = $size > 100000 ? 'File' : 'Lines';\n\"Mail::Message::Body::$type\";\n}\n\nThe default depends on the mail-folder type, although the general default is\nMail::Message::Body::Lines. Please check the applicable manual pages.\n\ncoerceoptions => ARRAY\nKeep configuration information for messages which are coerced into the specified folder\ntype, starting with a different folder type (or even no folder at all). Messages which are\ncoerced are always fully read, so this kind of information does not need to be kept here.\n\ncreate => BOOLEAN\nAutomatically create the folder when it does not exist yet. This will only work when\naccess is granted for writing or appending to the folder.\n\nBe careful: you may create a different folder type than you expect unless you explicitly\nspecify Mail::Box::Manager::open(type).\n\nextract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'\nDefines when to parse (process) the content of the message. When the header of a message\nis read, you may want to postpone the reading of the body: header information is more\noften needed than the body data, so why parse it always together? The cost of delaying is\nnot too high, and with some luck you may never need parsing the body.\n\nIf you supply an INTEGER to this option, bodies of those messages with a total size less\nthan that number will be extracted from the folder only when necessary. Messages where the\nsize (in the \"Content-Length\" field) is not included in the header, like often the case\nfor multiparts and nested messages, will not be extracted by default.\n\nIf you supply a CODE reference, that subroutine is called every time that the extraction\nmechanism wants to determine whether to parse the body or not. The subroutine is called\nwith the following arguments:\n\nCODE->(FOLDER, HEAD)\n\nwhere FOLDER is a reference to the folder we are reading. HEAD refers to the\nMail::Message::Head::Complete head of the message at hand. The routine must return a\n\"true\" value (extract now) or a \"false\" value (be lazy, do not parse yet). Think about\nusing the Mail::Message::Head::guessBodySize() and Mail::Message::guessTimestamp() on the\nheader to determine your choice.\n\nThe third possibility is to specify the NAME of a method. In that case, for each message\nis called:\n\nFOLDER->NAME(HEAD)\n\nWhere each component has the same meaning as described above.\n\nThe fourth way to use this option involves constants: with \"LAZY\" all messages will be\ndelayed. With \"ALWAYS\" you enforce unconditional parsing, no delaying will take place. The\nlatter is usuful when you are sure you always need all the messages in the folder.\n\n$folder->new(extract => 'LAZY'); # Very lazy\n$folder->new(extract => 10000); # Less than 10kB\n\n# same, but implemented yourself\n$folder->new(extract => &large);\nsub large($) {\nmy ($f, $head) = @;\nmy $size = $head->guessBodySize;\ndefined $size ? $size < 10000 : 1\n};\n\n# method call by name, useful for Mail::Box\n# extensions. The example selects all messages\n# sent by you to be loaded without delay.\n# Other messages will be delayed.\n$folder->new(extract => 'sentbyme');\nsub Mail::Box::sendbyme($) {\nmy ($self, $header) = @;\n$header->get('from') =~ m/\\bmy\\@example.com\\b/i;\n}\n\nfieldtype => CLASS\nThe type of the fields to be used in a header. Must extend Mail::Message::Field.\n\nfixheaders => BOOLEAN\nBroken MIME headers usually stop the parser: all lines not parsed are added to the body of\nthe message. With this flag set, the erroneous line is added to the previous header field\nand parsing is continued. See Mail::Box::Parser::Perl::new(fixheadererrors).\n\nfolder => FOLDERNAME\nWhich folder to open (for reading or writing). When used for reading (the \"access\" option\nset to \"r\" or \"a\") the mailbox should already exist and must be readable. The file or\ndirectory of the mailbox need not exist if it is opened for reading and writing (\"rw\").\nWrite-permission is checked when opening an existing mailbox.\n\nThe folder name can be preceded by a \"=\", to indicate that it is named relative to the\ndirectory specified in new(folderdir). Otherwise, it is taken as relative or absolute\npath.\n\nfolderdir => DIRECTORY\nWhere are folders to be found by default? A folder-name may be preceded by a equals-sign\n(\"=\", a \"mutt\" convension) to explicitly state that the folder is located below the\ndefault directory. For example: in case \"folderdir => '/tmp'\" and \"folder => '=abc'\", the\nname of the folder-file is '/tmp/abc'. Each folder type has already some default set.\n\nheaddelayedtype => CLASS\nThe headers which are delayed: which will be read from file when it is needed, but not\nbefore.\n\nheadtype => CLASS\nThe type of header which contains all header information. Must extend\nMail::Message::Head::Complete.\n\nkeepdups => BOOLEAN\nIndicates whether or not duplicate messages within the folder should be retained. A\nmessage is considered to be a duplicate if its message-id is the same as a previously\nparsed message within the same folder. If this option is false (the default) such messages\nare automatically deleted, because it is considered useless to store the same message\ntwice.\n\nlockfile => FILENAME\nThe name of the file which is used to lock. This must be specified when locking is to be\nused.\n\nlocktimeout => SECONDS\nWhen the lock file is older than the specified number of SECONDS, it is considered a\nmistake. The original lock is released, and accepted for this folder.\n\nlocktype => CLASS|STRING|ARRAY\nThe type of the locker object. This may be the full name of a CLASS which extends\nMail::Box::Locker, or one of the known locker types \"DotLock\", \"Flock\", \"FcntlLock\",\n\"Mutt\", \"NFS\", \"POSIX\", or \"NONE\". If an ARRAY is specified, then a Multi locker is built\nwhich uses the specified list.\n\nlockwait => SECONDS\nSECONDS to wait before failing on opening this folder.\n\nlocker => OBJECT\nAn OBJECT which extends Mail::Box::Locker, and will handle folder locking replacing the\ndefault lock behavior.\n\nlog => LEVEL\nmanager => MANAGER\nA reference to the object which manages this folder -- typically an Mail::Box::Manager\ninstance.\n\nmessagetype => CLASS\nWhat kind of message objects are stored in this type of folder. The default is constructed\nfrom the folder class followed by \"::Message\". For instance, the message type for\n\"Mail::Box::POP3\" is \"Mail::Box::POP3::Message\"\n\nmultiparttype => CLASS\nThe default type of objects which are to be created for multipart message bodies.\n\nremovewhenempty => BOOLEAN\nDetermines whether to remove the folder file or directory automatically when the write\nwould result in a folder without messages nor sub-folders.\n\nsaveonexit => BOOLEAN\nSets the policy for saving the folder when it is closed. A folder can be closed manually\n(see close()) or in a number of implicit ways, including on the moment the program is\nterminated.\n\ntrace => LEVEL\ntrusted => BOOLEAN\nFlags whether to trust the data in the folder or not. Folders which reside in your\n\"folderdir\" will be trusted by default (even when the names if not specified staring with\n\"=\"). Folders which are outside the folderdir or read from STDIN\n(Mail::Message::Construct::read()) are not trused by default, and require some extra\nchecking.\n\nIf you do not check encodings of received messages, you may print binary data to the\nscreen, which is a security risk.\n" }, { "name": "The folder", "content": "$obj->addMessage($message, %options)\nAdd a message to the folder. A message is usually a Mail::Box::Message object or a sub-class\nthereof. The message shall not be in an other folder, when you use this method. In case it\nis, use Mail::Box::Manager::moveMessage() or Mail::Box::Manager::copyMessage() via the\nmanager.\n\nMessages with id's which already exist in this folder are not added.\n\nBE WARNED that message labels may get lost when a message is moved from one folder type to\nan other. An attempt is made to translate labels, but there are many differences in\ninterpretation by applications.\n\n-Option--Default\nshare \n\nshare => BOOLEAN\nTry to share the physical resource of the current message with the indicated message. It\nis sometimes possible to share messages between different folder types. When the sharing\nis not possible, than this option is simply ignored.\n\nSharing the resource is quite dangerous, and only available for a limited number of folder\ntypes, at the moment only some Mail::Box::Dir folders; these file-based messages can be\nhardlinked (on platforms that support it). The link may get broken when one message is\nmodified in one of the folders.... but maybe not, depending on the folder types involved.\n\nexample:\n\n$folder->addMessage($msg);\n$folder->addMessages($msg1, $msg2, ...);\n\n$obj->addMessages(@messages)\nAdds a set of message objects to the open folder at once. For some folder types this may be\nfaster than adding them one at a time.\n\nexample:\n\n$folder->addMessages($msg1, $msg2, ...);\n\nMail::Box->appendMessages(%options)\nAppend one or more messages to an unopened folder. Usually, this method is called by the\nMail::Box::Manager::appendMessage(), in which case the correctness of the folder type is\nchecked.\n\nFor some folder types it is required to open the folder before it can be used for appending.\nThis can be fast, but this can also be very slow (depends on the implementation). All\n%options passed will also be used to open the folder, if needed.\n\n-Option --Default\nfolder \nmessage undef\nmessages undef\nshare \n\nfolder => FOLDERNAME\nThe name of the folder to which the messages are to be appended. The folder implementation\nwill avoid opening the folder when possible, because this is resource consuming.\n\nmessage => MESSAGE\nmessages => ARRAY-OF-MESSAGES\nOne reference to a MESSAGE or a reference to an ARRAY of MESSAGEs, which may be of any\ntype. The messages will be first coerced into the correct message type to fit in the\nfolder, and then will be added to it.\n\nshare => BOOLEAN\nTry to share physical storage of the message. Only available for a limited number of\nfolder types, otherwise no-op.\n\nexample:\n\nmy $message = Mail::Message->new(...);\nMail::Box::Mbox->appendMessages\n( folder => '=xyz'\n, message => $message\n, folderdir => $ENV{FOLDERS}\n);\n\nbetter:\n\nmy Mail::Box::Manager $mgr;\n$mgr->appendMessages($message, folder => '=xyz');\n\n$obj->close(%options)\nClose the folder, which usually implies writing the changes. This will return \"false\" when\nwriting is required but fails. Please do check this result.\n\nWARNING: When moving messages from one folder to another, be sure to write the destination\nfolder before writing and closing the source folder. Otherwise you may lose data if the\nsystem crashes or if there are software problems.\n\n-Option --Default\nforce \nsavedeleted false\nwrite MODIFIED\n\nforce => BOOLEAN\nOverride the new(access) setting which was specified when the folder was opened. This\noption only has an effect if its value is TRUE. NOTE: Writing to the folder may not be\npermitted by the operating system, in which case even \"force\" will not help.\n\nsavedeleted => BOOLEAN\nDo also write messages which where flagged to be deleted to their folder. The flag for\ndeletion is conserved (when possible), which means that a re-open of the folder may remove\nthe messages for real. See write(savedeleted).\n\nwrite => 'ALWAYS'|'NEVER'|'MODIFIED'\nSpecifies whether the folder should be written. As could be expected, \"ALWAYS\" means\nalways (even if there are no changes), \"NEVER\" means that changes to the folder will be\nlost, and \"MODIFIED\" only saves the folder if there are any changes.\n\nexample:\n\nmy $f = $mgr->open('spam', access => 'rw')\nor die \"Cannot open spam: $!\\n\";\n\n$f->message(0)->delete\nif $f->messages;\n\n$f->close\nor die \"Couldn't write $f: $!\\n\";\n\n$obj->copyTo($folder, %options)\nCopy the folder's messages to a new folder. The new folder may be of a different type.\n\n-Option --Default\ndeletecopied \nselect 'ACTIVE'\nshare \nsubfolders \n\ndeletecopied => BOOLEAN\nFlag the messages from the source folder to be deleted, just after it was copied. The\ndeletion will only take effect when the originating folder is closed.\n\nselect => 'ACTIVE'|'DELETED'|'ALL'|LABEL|!LABEL|FILTER\nWhich messages are to be copied. See the description of messages() about how this works.\n\nshare => BOOLEAN\nTry to share the message between the folders. Some Mail::Box::Dir folder types do support\nit by creating a hardlink (on UNIX/Linux).\n\nsubfolders => BOOLEAN|'FLATTEN'|'RECURSE'\nHow to handle sub-folders. When false (0 or \"undef\"), sub-folders are simply ignored. With\n\"FLATTEN\", messages from sub-folders are included in the main copy. \"RECURSE\" recursively\ncopies the sub-folders as well. By default, when the destination folder supports\nsub-folders \"RECURSE\" is used, otherwise \"FLATTEN\". A value of true will select the\ndefault.\n\nexample:\n\nmy $mgr = Mail::Box::Manager->new;\nmy $imap = $mgr->open(type => 'imap', host => ...);\nmy $mh = $mgr->open(type => 'mh', folder => '/tmp/mh',\ncreate => 1, access => 'w');\n\n$imap->copyTo($mh, deletecopied => 1);\n$mh->close; $imap->close;\n\n$obj->delete(%options)\nRemove the specified folder file or folder directory (depending on the type of folder) from\ndisk. Of course, THIS IS DANGEROUS: you \"may\" lose data. Returns a \"true\" value on success.\n\nWARNING: When moving messages from one folder to another, be sure to write the destination\nfolder before deleting the source folder. Otherwise you may lose data if the system crashes\nor if there are software problems.\n\n-Option --Default\nrecursive 1\n\nrecursive => BOOLEAN\n\nexample: removing an open folder\n\nmy $folder = Mail::Box::Mbox->new(folder => 'InBox', access => 'rw');\n... some other code ...\n$folder->delete;\n\nexample: removing an closed folder\n\nmy $folder = Mail::Box::Mbox->new(folder => 'INBOX', access => 'd');\n$folder->delete;\n\n$obj->folderdir( [$directory] )\nGet or set the $directory which is used to store mail-folders by default.\n\nexample:\n\nprint $folder->folderdir;\n$folder->folderdir(\"$ENV{HOME}/nsmail\");\n\n$obj->name()\nReturns the name of the folder. What the name represents depends on the actual type of\nmailbox used.\n\nexample:\n\nprint $folder->name;\nprint \"$folder\"; # overloaded stringification\n\n$obj->organization()\nReturns how the folder is organized: as one \"FILE\" with many messages, a \"DIRECTORY\" with\none message per file, or by a \"REMOTE\" server.\n\n$obj->size()\nReturns the size of the folder in bytes, not counting in the deleted messages. The error in\nthe presented result may be as large as 10%, because the in-memory representation of\nmessages is not always the same as the size when they are written.\n\n$obj->type()\nReturns a name for the type of mail box. This can be \"mbox\", \"mh\", \"maildir\", or \"pop3\".\n\n$obj->update(%options)\nRead new messages from the folder, which where received after opening it. This is quite\ndangerous and shouldn't be possible: folders which are open are locked. However, some\napplications do not use locks or the wrong kind of locks. This method reads the changes (not\nalways failsafe) and incorporates them in the open folder administration.\n\nThe %options are extra values which are passed to the updateMessages() method which is doing\nthe actual work here.\n\n$obj->url()\nRepresent the folder as a URL (Universal Resource Locator) string. You may pass such a URL\nas folder name to Mail::Box::Manager::open().\n\nexample:\n\nprint $folder->url;\n# may result in\n# mbox:/var/mail/markov or\n# pop3://user:password@pop.aol.com:101\n" }, { "name": "Folder flags", "content": "$obj->access()\nReturns the access mode of the folder, as set by new(access)\n\n$obj->isModified()\nChecks if the folder, as stored in memory, is modified. A true value is returned when any of\nthe messages is to be deleted, has changed, or messages were added after the folder was read\nfrom file.\n\nWARNING: this flag is not related to an external change to the folder structure on disk.\nHave a look at update() for that.\n\n$obj->modified( [BOOLEAN] )\nSets whether the folder is modified or not.\n\n$obj->writable()\nChecks whether the current folder is writable.\n\nexample:\n\n$folder->addMessage($msg) if $folder->writable;\n" }, { "name": "The messages", "content": "$obj->current( [$number|$message|$messageid] )\nSome mail-readers keep the *current* message, which represents the last used message. This\nmethod returns [after setting] the current message. You may specify a $number, to specify\nthat that message number is to be selected as current, or a $message/$messageid (as long as\nyou are sure that the header is already loaded, otherwise they are not recognized).\n\nexample:\n\n$folder->current(0);\n$folder->current($message);\n\n$obj->find($messageid)\nLike messageId(), this method searches for a message with the $messageid, returning the\ncorresponding message object. However, \"find\" will cause unparsed message in the folder to\nbe parsed until the message-id is found. The folder will be scanned back to front.\n\n$obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )\nFind the first message which has this $label with the correct setting. The BOOLEAN indicates\nwhether any true value or any false value is to be found in the ARRAY of $msgs. By default,\na true value is searched for. When a message does not have the requested label, it is taken\nas false.\n\nexample: looking for a labeled message\n\nmy $current = $folder->findFirstLabeled('current');\n\nmy $first = $folder->findFirstLabeled(seen => 0);\n\nmy $last = $folder->findFirstLabeled(seen => 0,\n[ reverse $self->messages('ACTIVE') ] )\n\n$obj->message( $index, [$message] )\nGet or set a message with on a certain index. Messages which are flagged for deletion are\ncounted. Negative indexes start at the end of the folder.\n\nexample:\n\nmy $msg = $folder->message(3);\n$folder->message(3)->delete; # status changes to `deleted'\n$folder->message(3, $msg);\nprint $folder->message(-1); # last message.\n\n$obj->messageId( $messageid, [$message] )\nWith one argument, returns the message in the folder with the specified $messageid. If a\nreference to a message object is passed as the optional second argument, the message is\nfirst stored in the folder, replacing any existing message whose message ID is $messageid.\n(The message ID of $message need not match $messageid.)\n\n!!WARNING!!: when the message headers are delay-parsed, the message might be in the folder\nbut not yet parsed into memory. In this case, use find() instead of \"messageId()\" if you\nreally need a thorough search. This is especially the case for directory organized folders\nwithout special indexi, like Mail::Box::MH.\n\nThe $messageid may still be in angles, which will be stripped. In that case blanks (which\norigin from header line folding) are removed too. Other info around the angles will be\nremoved too.\n\nexample:\n\nmy $msg = $folder->messageId('');\n$folder->messageId(\"\", $msg);\nmy $msg = $folder->messageId('complex-message.id');\nmy $msg = $folder->messageId('garbage trash');\n\n$obj->messageIds()\nReturns a list of *all* message-ids in the folder, including those of messages which are to\nbe deleted.\n\nFor some folder-types (like MH), this method may cause all message-files to be read. See\ntheir respective manual pages.\n\nexample:\n\nforeach my $id ($folder->messageIds) {\n$folder->messageId($id)->print;\n}\n\n$obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label| !$label|$filter> )\nReturns multiple messages from the folder. The default is \"ALL\" which will return (as\nexpected maybe) all the messages in the folder. The \"ACTIVE\" flag will return the messages\nnot flagged for deletion. This is the opposite of \"DELETED\", which returns all messages from\nthe folder which will be deleted when the folder is closed.\n\nYou may also specify a $range: two numbers specifying begin and end index in the array of\nmessages. Negative indexes count from the end of the folder. When an index is out-of-range,\nthe returned list will be shorter without complaints.\n\nEverything else than the predefined names is seen as labels. The messages which have that\nlabel set will be returned. When the sequence starts with an exclamation mark (!), the\nsearch result is reversed.\n\nFor more complex searches, you can specify a $filter, which is simply a code reference. The\nmessage is passed as only argument.\n\nexample:\n\nforeach my $message ($folder->messages) {...}\nforeach my $message (@$folder) {...}\n\n# twice the same\nmy @messages = $folder->messages;\nmy @messages = $folder->messages('ALL');\n\n# Selection based on a range (begin, end)\nmy $subset = $folder->messages(10,-8);\n\n# twice the same:\nmy @notdeleted= grep {not $->isDeleted}\n$folder->messages;\nmy @notdeleted= $folder->messages('ACTIVE');\n\n# scalar context the number of messages\nmy $nrofmsgs = $folder->messages;\n\n# third message, via overloading\n$folder->[2];\n\n# Selection based on labels\n$mgr->moveMessages($spam, $inbox->message('spam'));\n$mgr->moveMessages($archive, $inbox->message('seen'));\n\n$obj->nrMessages(%options)\nSimply calls messages() in scalar context to return a count instead of the messages itself.\nSome people seem to understand this better. Note that nrMessages() will default to returning\na count of \"ALL\" messages in the folder, including both \"ACTIVE\" and \"DELETED\".\n\nThe %options are passed to (and explained in) messages().\n\n$obj->scanForMessages($message, $messageids, $timespan, $window)\nYou start with a $message, and are looking for a set of messages which are related to it.\nFor instance, messages which appear in the 'In-Reply-To' and 'Reference' header fields of\nthat message. These messages are known by their $messageids and you want to find them in\nthe folder.\n\nWhen all message-ids are known, then looking-up messages is simple: they are found in a\nplain hash using messageId(). But Mail::Box is lazy where it can, so many messages may not\nhave been read from file yet, and that's the preferred situation, because that saves time\nand memory.\n\nIt is not smart to search for the messages from front to back in the folder: the chances are\nmuch higher that related message reside closely to each other. Therefore, this method starts\nscanning the folder from the specified $message, back to the front of the folder.\n\nThe $timespan can be used to terminate the search based on the time enclosed in the message.\nWhen the constant string \"EVER\" is used as $timespan, then the search is not limited by\nthat. When an integer is specified, it will be used as absolute time in time-ticks as\nprovided by your platform dependent \"time\" function. In other cases, it is passed to\ntimespan2seconds() to determine the threshold as time relative to the message's time.\n\nThe $window is used to limit the search in number of messages to be scanned as integer or\nconstant string \"ALL\".\n\nReturned are the message-ids which were not found during the scan. Be warned that a\nmessage-id could already be known and therefore not found: check that first.\n\nexample: scanning through a folder for a message\n\nmy $refs = $msg->get('References') or return;\nmy @msgids = $ref =~ m/\\<([^>]+\\>/g;\nmy @failed = $folder->scanForMessages($msg, \\@msgids, '3 days', 50);\n" }, { "name": "Sub-folders", "content": "$obj->listSubFolders(%options)\nMail::Box->listSubFolders(%options)\nList the names of all sub-folders to this folder, not recursively decending. Use these names\nas argument to openSubFolder(), to get access to that folder.\n\nFor MBOX folders, sub-folders are simulated.\n\n-Option --Default\ncheck \nfolder \nfolderdir \nskipempty \n\ncheck => BOOLEAN\nShould all returned foldernames be checked to be sure that they are of the right type?\nEach sub-folder may need to be opened to check this, with a folder type dependent penalty\n(in some cases very expensive).\n\nfolder => FOLDERNAME\nThe folder whose sub-folders should be listed.\n\nfolderdir => DIRECTORY\nskipempty => BOOL\nShall empty folders (folders which currently do not contain any messages) be included?\nEmpty folders are not useful to open, but may be useful to save to.\n\nexample:\n\nmy $folder = $mgr->open('=in/new');\nmy @subs = $folder->listSubFolders;\n\nmy @subs = Mail::Box::Mbox->listSubFolders(folder => '=in/new');\nmy @subs = Mail::Box::Mbox->listSubFolders; # toplevel folders.\n\n$obj->nameOfSubFolder( $subname, [$parentname] )\nMail::Box->nameOfSubFolder( $subname, [$parentname] )\nReturns the constructed name of the folder with NAME, which is a sub-folder of this current\none. You have either to call this method as instance method, or specify a $parentname.\n\nexample: how to get the name of a subfolder\n\nmy $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', 'abc');\nprint $sub; # abc/xyz\n\nmy $f = Mail::Box::Mbox->new(folder => 'abc');\nprint $f->nameOfSubfolder('xyz'); # abc/xyz\n\nmy $sub = Mail::Box::Mbox->nameOfSubfolder('xyz', undef);\nprint $sub; # xyz\n\n$obj->openRelatedFolder(%options)\nOpen a folder (usually a sub-folder) with the same options as this one. If there is a folder\nmanager in use, it will be informed about this new folder. %options overrule the options\nwhich where used for the folder this method is called upon.\n\n$obj->openSubFolder($subname, %options)\nOpen (or create, if it does not exist yet) a new subfolder in an existing folder.\n\nexample:\n\nmy $folder = Mail::Box::Mbox->new(folder => '=Inbox');\nmy $sub = $folder->openSubFolder('read');\n\n$obj->topFolderWithMessages()\nMail::Box->topFolderWithMessages()\nSome folder types can have messages in the top-level folder, some other can't.\n" }, { "name": "Internals", "content": "$obj->coerce($message, %options)\nCoerce the $message to be of the correct type to be placed in the folder. You can specify\nMail::Internet and MIME::Entity objects here: they will be translated into Mail::Message\nmessages first.\n\n$obj->create($foldername, %options)\nMail::Box->create($foldername, %options)\nCreate a folder. If the folder already exists, it will be left unchanged. The folder is\ncreated, but not opened! If you want to open a file which may need to be created, then use\nMail::Box::Manager::open() with the create flag, or Mail::Box::new(create).\n\n-Option --Default\nfolderdir undef\n\nfolderdir => DIRECTORY\nWhen the foldername is preceded by a \"=\", the \"folderdir\" directory will be searched for\nthe named folder.\n\n$obj->determineBodyType($message, $head)\nDetermine which kind of body will be created for this message when reading the folder\ninitially.\n\nMail::Box->foundIn( [$foldername], %options )\nDetermine if the specified folder is of the type handled by the folder class. This method is\nextended by each folder sub-type.\n\nThe $foldername specifies the name of the folder, as is specified by the application. You\nneed to specified the \"folder\" option when you skip this first argument.\n\n%options is a list of extra information for the request. Read the documentation for each\ntype of folder for type specific options, but each folder class will at least support the\n\"folderdir\" option:\n\n-Option --Default\nfolderdir undef\n\nfolderdir => DIRECTORY\nThe location where the folders of this class are stored by default. If the user specifies\na name starting with a \"=\", that indicates that the folder is to be found in this default\nDIRECTORY.\n\nexample:\n\nMail::Box::Mbox->foundIn('=markov',\nfolderdir => \"$ENV{HOME}/Mail\");\nMail::Box::MH->foundIn(folder => '=markov');\n\n$obj->lineSeparator( [] )\nReturns the character or characters used to separate lines in the folder file, optionally\nafter setting it to STRING, or one of the constants. The first line of the folder sets the\ndefault.\n\nUNIX uses a LF character, Mac a CR, and Windows both a CR and a LF. Each separator will be\nrepresented by a \"\\n\" within your program. However, when processing platform foreign\nfolders, complications appear. Think about the \"Size\" field in the header.\n\nWhen the separator is changed, the whole folder me be rewritten. Although, that may not be\nrequired.\n\n$obj->locker()\nReturns the locking object.\n\n$obj->read(%options)\nRead messages from the folder into memory. The %options are folder specific. Do not call\n\"read()\" yourself: it will be called for you when you open the folder via the manager or\ninstantiate a folder object directly.\n\nNOTE: if you are copying messages from one folder to another, use addMessages() instead of\n\"read()\".\n\nexample:\n\nmy $mgr = Mail::Box::Manager->new;\nmy $folder = $mgr->open('InBox'); # implies read\nmy $folder = Mail::Box::Mbox->new(folder => 'Inbox'); # same\n\n$obj->readMessages(%options)\nCalled by read() to actually read the messages from one specific folder type. The read()\norganizes the general activities.\n\nThe %options are \"trusted\", \"headtype\", \"fieldtype\", \"messagetype\", \"bodydelayedtype\",\nand \"headdelayedtype\" as defined by the folder at hand. The defaults are the constructor\ndefaults (see new()).\n\n$obj->storeMessage($message)\nStore the message in the folder without the checks as performed by addMessage().\n\n$obj->toBeThreaded($messages)\nThe specified message is ready to be removed from a thread. This will be passed on to the\nmail-manager, which keeps an overview on which thread-detection objects are floating around.\n\n$obj->toBeUnthreaded($messages)\nThe specified message is ready to be included in a thread. This will be passed on to the\nmail-manager, which keeps an overview on which thread-detection objects are floating around.\n\n$obj->updateMessages(%options)\nCalled by update() to read messages which arrived in the folder after it was opened.\nSometimes, external applications dump messages in a folder without locking (or using a\ndifferent lock than your application does).\n\nAlthough this is quite a dangerous, it only fails when a folder is updated (reordered or\nmessage removed) at exactly the same time as new messages arrive. These collisions are\nsparse.\n\nThe options are the same as for readMessages().\n\n$obj->write(%options)\nWrite the data to disk. The folder (a \"true\" value) is returned if successful. Deleted\nmessages are transformed into destroyed messages: their memory is freed.\n\nWARNING: When moving messages from one folder to another, be sure to write (or close()) the\ndestination folder before writing (or closing) the source folder: otherwise you may lose\ndata if the system crashes or if there are software problems.\n\nTo write a folder to a different file, you must first create a new folder, then move all the\nmessages, and then write or close() that new folder.\n\n-Option --Default\nforce \nsavedeleted \n\nforce => BOOLEAN\nOverride write-protection with new(access) while opening the folder (whenever possible, it\nmay still be blocked by the operating system).\n\nsavedeleted => BOOLEAN\nDo also write messages which where flagged to be deleted to their folder. The flag for\ndeletion is conserved (when possible), which means that a re-open of the folder may remove\nthe messages for real. See close(savedeleted).\n\n$obj->writeMessages(%options)\nCalled by write() to actually write the messages from one specific folder type. The \"write\"\norganizes the general activities. All options to write() are passed to \"writeMessages\" as\nwell. Besides, a few extra are added by \"write\" itself.\n\n-Option --Default\nmessages \n\nmessages => ARRAY\nThe messages to be written, which is a sub-set of all messages in the current folder.\n" }, { "name": "Other methods", "content": "$obj->timespan2seconds($time)\nMail::Box->timespan2seconds($time)\n$time is a string, which starts with a float, and then one of the words 'hour', 'hours',\n'day', 'days', 'week', or 'weeks'. For instance: '1 hour' or '4 weeks'.\n" }, { "name": "Error handling", "content": "Extends \"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, $callback] )\nMail::Box->defaultTrace( [$level]|[$loglevel, $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::Box->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Box->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::Reporter.\n\n$obj->DESTROY()\nThis method is called by Perl when an folder-object is no longer accessible by the rest of\nthe program.\n" } ] }, "DETAILS": { "content": "", "subsections": [ { "name": "Different kinds of folders", "content": "In general, there are three classes of folders: those who group messages per file, those who\ngroup messages in a directory, and those do not provide direct access to the message data. These\nfolder types are each based on a different base class.\n\n* File based folders Mail::Box::File\n\nFile based folders maintain a folder (a set of messages) in one single file. The advantage\nis that your folder has only one single file to access, which speeds-up things when all\nmessages must be accessed at once.\n\nOne of the main disadvantages over directory based folders is that you have to construct\nsome means to keep all message apart. For instance MBOX adds a message separator line\nbetween the messages in the file, and this line can cause confusion with the message's\ncontents.\n\nWhere access to all messages at once is faster in file based folders, access to a single\nmessage is (much) slower, because the whole folder must be read. However, in directory based\nfolders you have to figure-out which message you need, which may be a hassle as well.\n\nExamples of file based folders are MBOX, DBX, and NetScape.\n\n* Directory based folders Mail::Box::Dir\n\nIn stead of collecting multiple messages in one file, you can also put each message in a\nseparate file and collect those files in a directory to represent a folder.\n\nThe main disadvantages of these folders are the enormous amount of tiny files you usually\nget in your file-system. It is extremely slow to search through your whole folder, because\nmany files have to be opened to do so.\n\nThe best feature of this organization is that each message is kept exactly as it was\nreceived, and can be processed with external scripts as well: you do not need any mail user\nagent (MUA).\n\nExamples of directory organized folders are MH, Maildir, EMH and XMH.\n\n* Network (external) folders Mail::Box::Net\n\nWhere both types described before provide direct access to the message data, maintain these\nfolder types the message data for you: you have to request for messages or parts of them.\nThese folders do not have a filename, file-system privileges and system locking to worry\nabout, but typically require a hostname, folder and message IDs, and authorization.\n\nExamples of these folder types are the popular POP and IMAP, and database oriented message\nstorage.\n" }, { "name": "Available folder types", "content": "* Mail::Box::Dbx (read only)\n\nDbx files are created by Outlook Express. Using the external (optional) Mail::Transport::Dbx\nmodule, you can read these folders, even when you are running MailBox on a UNIX/Linux\nplatform.\n\nWriting and deleting messages is not supported by the library, and therefore not by MailBox.\nRead access is enough to do folder conversions, for instance.\n\n* Mail::Box::IMAP4 (partially)\n\nThe IMAP protocol is very complex. Some parts are implemented to create (sub-optimal but\nusable) IMAP clients. Besides, there are also some parts for IMAP servers present. The most\nimportant lacking feature is support for encrypted connections.\n\n* Mail::Box::Maildir\n\nMaildir folders have a directory for each folder. A folder directory contains \"tmp\", \"new\",\nand \"cur\" sub-directories, each containing messages with a different purpose. Files with new\nmessages are created in \"tmp\", then moved to \"new\" (ready to be accepted). Later, they are\nmoved to the \"cur\" directory (accepted). Each message is one file with a name starting with\ntimestamp. The name also contains flags about the status of the message.\n\nMaildir folders can not be used on Windows by reason of file-name limitations on that\nplatform.\n\n* Mail::Box::Mbox\n\nA folder type in which all related messages are stored in one file. This is a very common\nfolder type for UNIX.\n\n* Mail::Box::MH\n\nThis folder creates a directory for each folder, and a message is one file inside that\ndirectory. The message files are numbered sequentially on order of arrival. A special\n\".mhsequences\" file maintains flags about the messages.\n\n* Mail::Box::POP3 (read/delete only)\n\nPOP3 is a protocol which can be used to retrieve messages from a remote system. After the\nconnection to a POP server is made, the messages can be looked at and removed as if they are\non the local system.\n\n* Mail::Box::Netzwert\n\nThe Netzwert folder type is optimized for mailbox handling on a cluster of systems with a\nshared NFS storage. The code is not released under GPL (yet)\n\nOther folder types are on the (long) wishlist to get implemented. Please, help implementing more\nof them.\n" }, { "name": "Folder class implementation", "content": "The class structure of folders is very close to that of messages. For instance, a\nMail::Box::File::Message relates to a Mail::Box::File folder. The folder types are:\n\nMail::Box::Netzwert\nMail::Box::Mbox | Mail::Box::Maildir Mail::Box::POP3\n| Mail::Box::Dbx | | Mail::Box::MH | Mail::Box::IMAP4\n| | | | | | |\n| | | | | | |\nMail::Box::File Mail::Box::Dir Mail::Box::Net\n| | |\n`--------------. | .---------------'\n| | |\nMail::Box\n|\n|\nMail::Reporter (general base class)\n\nBy far most folder features are implemented in Mail::Box, so available to all folder types.\nSometimes, features which appear in only some of the folder types are simulated for folders that\nmiss them, like sub-folder support for MBOX.\n" } ] }, "DIAGNOSTICS": { "content": "Warning: Changes not written to read-only folder $self.\nYou have opened the folder read-only --which is the default set by new(access)--, made\nmodifications, and now want to close it. Set close(force) if you want to overrule the access\nmode, or close the folder with close(write) set to \"NEVER\".\n\nError: Copying failed for one message.\nFor some reason, for instance disc full, removed by external process, or read-protection, it\nis impossible to copy one of the messages. Copying will proceed for the other messages.\n\nError: Destination folder $name is not writable.\nThe folder where the messages are copied to is not opened with write access (see\nnew(access)). This has no relation with write permission to the folder which is controlled\nby your operating system.\n\nWarning: Different messages with id $msgid\nThe message id is discovered more than once within the same folder, but the content of the\nmessage seems to be different. This should not be possible: each message must be unique.\n\nError: Folder $name is opened read-only\nYou can not write to this folder unless you have opened the folder to write or append with\nnew(access), or the \"force\" option is set true.\n\nError: Folder $name not deleted: not writable.\nThe folder must be opened with write access via new(access), otherwise removing it will be\nrefused. So, you may have write-access according to the operating system, but that will not\nautomatically mean that this \"delete\" method permits you to. The reverse remark is valid as\nwell.\n\nError: Invalid timespan '$timespan' specified.\nThe string does not follow the strict rules of the time span syntax which is permitted as\nparameter.\n\nWarning: Message-id '$msgid' does not contain a domain.\nAccording to the RFCs, message-ids need to contain a unique random part, then an \"@\", and\nthen a domain name. This is made to avoid the creation of two messages with the same id. The\nwarning emerges when the \"@\" is missing from the string.\n\nError: No folder name specified.\nYou did not specify the name of a folder to be opened. Use the new(folder) option or set the\n\"MAIL\" environment variable.\n\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\nError: Unable to create subfolder $name of $folder.\nThe copy includes the subfolders, but for some reason it was not possible to copy one of\nthese. Copying will proceed for all other sub-folders.\n\nError: Writing folder $name failed\nFor some reason (you probably got more error messages about this problem) it is impossible\nto write the folder, although you should because there were changes made.\n", "subsections": [] }, "SEE ALSO": { "content": "This module is part of Mail-Box distribution version 3.009, built on August 18, 2020. Website:\nhttp://perl.overmeer.net/CPAN/\n", "subsections": [] }, "LICENSE": { "content": "Copyrights 2001-2020 by [Mark Overmeer]. 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": [] } } } }