{ "content": [ { "type": "text", "text": "# Mail::Reporter (info)\n\n## NAME\n\nMail::Reporter - base-class and error reporter for Mail::Box\n\n## SYNOPSIS\n\n$folder->log(WARNING => 'go away');\nprint $folder->trace; # current level\n$folder->trace('PROGRESS'); # set level\nprint $folder->errors;\nprint $folder->report('PROGRESS');\n\n## DESCRIPTION\n\nThe \"Mail::Reporter\" class is the base class for all classes, except\nMail::Message::Field::Fast because it would become slow... This base\nclass is used during initiation of the objects, and for configuring and\nlogging error messages.\n\n## Sections\n\n- **Mail::Reporter(3pm) User Contributed Perl Documentation Mail::Reporter(3pm)**\n- **NAME**\n- **INHERITANCE**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **DIAGNOSTICS**\n- **SEE ALSO**\n- **LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Mail::Reporter", "section": "", "mode": "info", "summary": "Mail::Reporter - base-class and error reporter for Mail::Box", "synopsis": "$folder->log(WARNING => 'go away');\nprint $folder->trace; # current level\n$folder->trace('PROGRESS'); # set level\nprint $folder->errors;\nprint $folder->report('PROGRESS');", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "Mail::Reporter(3pm) User Contributed Perl Documentation Mail::Reporter(3pm)", "lines": 1, "subsections": [] }, { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "INHERITANCE", "lines": 24, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 5, "subsections": [] }, { "name": "METHODS", "lines": 215, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 7, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "LICENSE", "lines": 7, "subsections": [] } ], "sections": { "Mail::Reporter(3pm) User Contributed Perl Documentation Mail::Reporter(3pm)": { "content": "", "subsections": [] }, "NAME": { "content": "Mail::Reporter - base-class and error reporter for Mail::Box\n", "subsections": [] }, "INHERITANCE": { "content": "Mail::Reporter is extended by\nMail::Box\nMail::Box::Collection\nMail::Box::Identity\nMail::Box::Locker\nMail::Box::MH::Index\nMail::Box::MH::Labels\nMail::Box::Manager\nMail::Box::Parser\nMail::Box::Search\nMail::Box::Thread::Manager\nMail::Box::Thread::Node\nMail::Message\nMail::Message::Body\nMail::Message::Body::Delayed\nMail::Message::Convert\nMail::Message::Field\nMail::Message::Field::Attribute\nMail::Message::Head\nMail::Message::Head::FieldGroup\nMail::Message::TransferEnc\nMail::Server\nMail::Transport\n", "subsections": [] }, "SYNOPSIS": { "content": "$folder->log(WARNING => 'go away');\nprint $folder->trace; # current level\n$folder->trace('PROGRESS'); # set level\nprint $folder->errors;\nprint $folder->report('PROGRESS');\n", "subsections": [] }, "DESCRIPTION": { "content": "The \"Mail::Reporter\" class is the base class for all classes, except\nMail::Message::Field::Fast because it would become slow... This base\nclass is used during initiation of the objects, and for configuring and\nlogging error messages.\n", "subsections": [] }, "METHODS": { "content": "The \"Mail::Reporter\" class is the base for nearly all other objects.\nIt can store and report problems, and contains the general constructor\nnew().\n\nConstructors\nMail::Reporter->new(%options)\nThis error container is also the base constructor for all modules,\n(as long as there is no need for another base object) The\nconstructor always accepts the following %options related to error\nreports.\n\n-Option--Default\nlog 'WARNINGS'\ntrace 'WARNINGS'\n\nlog => LEVEL\nLog messages which have a priority higher or equal to the\nspecified level are stored internally and can be retrieved later.\nThe global default for this option can be changed with\ndefaultTrace().\n\nKnown levels are \"INTERNAL\", \"ERRORS\", \"WARNINGS\", \"PROGRESS\",\n\"NOTICES\" \"DEBUG\", and \"NONE\". The \"PROGRESS\" level relates to\nthe reading and writing of folders. \"NONE\" will cause only\n\"INTERNAL\" errors to be logged. By the way: \"ERROR\" is an alias\nfor \"ERRORS\", as \"WARNING\" is an alias for \"WARNINGS\", and\n\"NOTICE\" for \"NOTICES\".\n\ntrace => LEVEL\nTrace messages which have a level higher or equal to the\nspecified level are directly printed using warn. The global\ndefault for this option can be changed with defaultTrace().\n\nError handling\n$obj->AUTOLOAD()\nBy default, produce a nice warning if the sub-classes cannot\nresolve a method.\n\n$obj->addReport($object)\nAdd the report from other $object to the report of this object.\nThis is useful when complex actions use temporary objects which are\nnot returned to the main application but where the main application\nwould like to know about any problems.\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,\n$callback] )\nMail::Reporter->defaultTrace( [$level]|[$loglevel,\n$tracelevel]|[$level, $callback] )\nReports the default log and trace level which is used for object as\nlist of two elements. When not explicitly set, both are set to\n\"WARNINGS\".\n\nThis method has three different uses. When one argument is\nspecified, that $level is set for both loglevel as tracelevel.\n\nWith two arguments, the second determines which configuration you\nlike. If the second argument is a CODE reference, you install a\n$callback. The loglevel will be set to NONE, and all warnings\nproduced in your program will get passed to the $callback function.\nThat function will get the problem level, the object or class which\nreports the problem, and the problem text passed as arguments.\n\nIn any case two values are returned: the first is the log level,\nthe second represents the trace level. Both are special variables:\nin numeric context they deliver a value (the internally used\nvalue), and in string context the string name. Be warned that the\nstring is always in singular form!\n\nexample: setting loglevels\n\nmy ($loglevel, $tracelevel) = Mail::Reporter->defaultTrace;\nMail::Reporter->defaultTrace('NOTICES');\n\nmy ($l, $t) = Mail::Reporter->defaultTrace('WARNINGS', 'DEBUG');\nprint $l; # prints \"WARNING\" (no S!)\nprint $l+0; # prints \"4\"\nprint \"Auch\" if $l >= $self->logPriority('ERROR');\n\nMail::Reporter->defaultTrace('NONE'); # silence all reports\n\n$folder->defaultTrace('DEBUG'); # Still set as global default!\n$folder->trace('DEBUG'); # local default\n\nexample: installing a callback\n\nMail::Reporter->defaultTrace\n\n$obj->errors()\nEquivalent to\n\n$folder->report('ERRORS')\n\n$obj->log( [$level, [$strings]] )\nMail::Reporter->log( [$level, [$strings]] )\nAs instance method, this function has three different purposes.\nWithout any argument, it returns one scalar containing the number\nwhich is internally used to represent the current log level, and\nthe textual representation of the string at the same time. See\nScalar::Util method \"dualvar\" for an explanation.\n\nWith one argument, a new level of logging detail is set (specify a\nnumber of one of the predefined strings). With more arguments, it\nis a report which may need to be logged or traced.\n\nAs class method, only a message can be passed. The global\nconfiguration value set with defaultTrace() is used to decide\nwhether the message is shown or ignored.\n\nEach log-entry has a $level and a text string which will be\nconstructed by joining the $strings. If there is no newline, it\nwill be added.\n\nexample:\n\nprint $message->log; # may print \"NOTICE\"\nprint $message->log +0; # may print \"3\"\n$message->log('ERRORS'); # sets a new level, returns the numeric value\n\n$message->log(WARNING => \"This message is too large.\");\n$folder ->log(NOTICE => \"Cannot read from file $filename.\");\n$manager->log(DEBUG => \"Hi there!\", reverse sort @l);\n\nMail::Message->log(ERROR => 'Unknown');\n\n$obj->logPriority($level)\nMail::Reporter->logPriority($level)\nOne error level (log or trace) has more than one representation: a\nnumeric value and one or more strings. For instance, 4, 'WARNING',\nand 'WARNINGS' are all the same. You can specify any of these, and\nin return you get a dualvar (see Scalar::Util method \"dualvar\")\nback, which contains the number and the singular form.\n\nThe higher the number, the more important the message. Only\nmessages about \"INTERNAL\" problems are more important than \"NONE\".\n\nexample:\n\nmy $r = Mail::Reporter->logPriority('WARNINGS');\nmy $r = Mail::Reporter->logPriority('WARNING'); # same\nmy $r = Mail::Reporter->logPriority(4); # same, deprecated\nprint $r; # prints 'WARNING' (no S!)\nprint $r + 0; # prints 4\nif($r < Mail::Reporter->logPriority('ERROR')) {..} # true\n\n$obj->logSettings()\nReturns a list of \"(key =\" value)> pairs which can be used to\ninitiate a new object with the same log-settings as this one.\n\nexample:\n\n$head->new($folder->logSettings);\n\n$obj->notImplemented()\nA special case of log(), which logs a \"INTERNAL\"-error and then\ncroaks. This is used by extension writers.\n\n$obj->report( [$level] )\nGet logged reports, as list of strings. If a $level is specified,\nthe log for that level is returned.\n\nIn case no $level is specified, you get all messages each as\nreference to a tuple with level and message.\n\nexample:\n\nmy @warns = $message->report('WARNINGS');\n# previous indirectly callable with\nmy @warns = $msg->warnings;\n\nprint $folder->report('ERRORS');\n\nif($folder->report('DEBUG')) {...}\n\nmy @reports = $folder->report;\nforeach (@reports) {\nmy ($level, $text) = @$;\nprint \"$level report: $text\";\n}\n\n$obj->reportAll( [$level] )\nReport all messages which were produced by this object and all the\nobjects which are maintained by this object. This will return a\nlist of triplets, each containing a reference to the object which\ncaught the report, the level of the report, and the message.\n\nexample:\n\nmy $folder = Mail::Box::Manager->new->open(folder => 'inbox');\nmy @reports = $folder->reportAll;\nforeach (@reports) {\nmy ($object, $level, $text) = @$;\n\nif($object->isa('Mail::Box')) {\nprint \"Folder $object: $level: $message\";\n} elsif($object->isa('Mail::Message') {\nprint \"Message \".$object->seqnr.\": $level: $message\";\n}\n}\n\n$obj->trace( [$level] )\nChange the trace $level of the object. When no arguments are\nspecified, the current level is returned only. It will be returned\nin one scalar which contains both the number which is internally\nused to represent the level, and the string which represents it.\nSee logPriority().\n\n$obj->warnings()\nEquivalent to\n\n$folder->report('WARNINGS')\n\nCleanup\n$obj->DESTROY()\nCleanup the object.\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 ]. 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::Reporter(3pm)", "subsections": [] } } } }