{ "content": [ { "type": "text", "text": "# Mail::Reporter (perldoc)\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 Mail::Message::Field::Fast\nbecause it would become slow... This base class is used during initiation of the objects, and\nfor configuring and logging error messages.\n\n## Sections\n\n- **NAME**\n- **INHERITANCE**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS** (3 subsections)\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": "perldoc", "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": "NAME", "lines": 2, "subsections": [] }, { "name": "INHERITANCE", "lines": 24, "subsections": [] }, { "name": "SYNOPSIS", "lines": 6, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [] }, { "name": "METHODS", "lines": 3, "subsections": [ { "name": "Constructors", "lines": 23 }, { "name": "Error handling", "lines": 164 }, { "name": "Cleanup", "lines": 3 } ] }, { "name": "DIAGNOSTICS", "lines": 6, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "LICENSE", "lines": 5, "subsections": [] } ], "sections": { "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 Mail::Message::Field::Fast\nbecause it would become slow... This base class is used during initiation of the objects, and\nfor configuring and logging error messages.\n", "subsections": [] }, "METHODS": { "content": "The \"Mail::Reporter\" class is the base for nearly all other objects. It can store and report\nproblems, and contains the general constructor new().\n", "subsections": [ { "name": "Constructors", "content": "Mail::Reporter->new(%options)\nThis error container is also the base constructor for all modules, (as long as there is no\nneed for another base object) The constructor always accepts the following %options related\nto error reports.\n\n-Option--Default\nlog 'WARNINGS'\ntrace 'WARNINGS'\n\nlog => LEVEL\nLog messages which have a priority higher or equal to the specified level are stored\ninternally and can be retrieved later. The global default for this option can be changed\nwith defaultTrace().\n\nKnown levels are \"INTERNAL\", \"ERRORS\", \"WARNINGS\", \"PROGRESS\", \"NOTICES\" \"DEBUG\", and\n\"NONE\". The \"PROGRESS\" level relates to the reading and writing of folders. \"NONE\" will\ncause only \"INTERNAL\" errors to be logged. By the way: \"ERROR\" is an alias for \"ERRORS\",\nas \"WARNING\" is an alias for \"WARNINGS\", and \"NOTICE\" for \"NOTICES\".\n\ntrace => LEVEL\nTrace messages which have a level higher or equal to the specified level are directly\nprinted using warn. The global default for this option can be changed with defaultTrace().\n" }, { "name": "Error handling", "content": "$obj->AUTOLOAD()\nBy default, produce a nice warning if the sub-classes cannot resolve a method.\n\n$obj->addReport($object)\nAdd the report from other $object to the report of this object. This is useful when complex\nactions use temporary objects which are not returned to the main application but where the\nmain application would like to know about any problems.\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nMail::Reporter->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nReports the default log and trace level which is used for object as list of two elements.\nWhen not explicitly set, both are set to \"WARNINGS\".\n\nThis method has three different uses. When one argument is specified, that $level is set for\nboth loglevel as tracelevel.\n\nWith two arguments, the second determines which configuration you like. If the second\nargument is a CODE reference, you install a $callback. The loglevel will be set to NONE, and\nall warnings produced in your program will get passed to the $callback function. That\nfunction will get the problem level, the object or class which reports the problem, and the\nproblem text passed as arguments.\n\nIn any case two values are returned: the first is the log level, the second represents the\ntrace level. Both are special variables: in numeric context they deliver a value (the\ninternally used value), and in string context the string name. Be warned that the string is\nalways 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. Without any argument, it\nreturns one scalar containing the number which is internally used to represent the current\nlog level, and the textual representation of the string at the same time. See Scalar::Util\nmethod \"dualvar\" for an explanation.\n\nWith one argument, a new level of logging detail is set (specify a number of one of the\npredefined strings). With more arguments, it is a report which may need to be logged or\ntraced.\n\nAs class method, only a message can be passed. The global configuration value set with\ndefaultTrace() is used to decide whether the message is shown or ignored.\n\nEach log-entry has a $level and a text string which will be constructed by joining the\n$strings. If there is no newline, it will 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 numeric value and one or\nmore strings. For instance, 4, 'WARNING', and 'WARNINGS' are all the same. You can specify\nany of these, and in return you get a dualvar (see Scalar::Util method \"dualvar\") back,\nwhich contains the number and the singular form.\n\nThe higher the number, the more important the message. Only messages about \"INTERNAL\"\nproblems 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 initiate a new object with the\nsame 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 croaks. This is used by\nextension writers.\n\n$obj->report( [$level] )\nGet logged reports, as list of strings. If a $level is specified, the log for that level is\nreturned.\n\nIn case no $level is specified, you get all messages each as reference to a tuple with level\nand 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 objects which are\nmaintained by this object. This will return a list of triplets, each containing a reference\nto the object which caught 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 specified, the current level is\nreturned only. It will be returned in one scalar which contains both the number which is\ninternally used to represent the level, and the string which represents it. See\nlogPriority().\n\n$obj->warnings()\nEquivalent to\n\n$folder->report('WARNINGS')\n" }, { "name": "Cleanup", "content": "$obj->DESTROY()\nCleanup the object.\n" } ] }, "DIAGNOSTICS": { "content": "Error: 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 ]. 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": [] } } } }