.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Log::Report::Dispatcher 3pm" .TH Log::Report::Dispatcher 3pm "2014-06-24" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Log::Report::Dispatcher \- manage message dispatching, display or logging .SH "INHERITANCE" .IX Header "INHERITANCE" .Vb 8 \& Log::Report::Dispatcher is extended by \& Log::Report::Dispatcher::Callback \& Log::Report::Dispatcher::File \& Log::Report::Dispatcher::Log4perl \& Log::Report::Dispatcher::LogDispatch \& Log::Report::Dispatcher::Perl \& Log::Report::Dispatcher::Syslog \& Log::Report::Dispatcher::Try .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Log::Report; \& \& # The following will be created for you automatically \& dispatcher \*(AqPERL\*(Aq, \*(Aqdefault\*(Aq, accept => \*(AqNOTICE\-\*(Aq; \& dispatcher close => \*(Aqdefault\*(Aq; # after deamonize \& \& dispatcher \*(AqFILE\*(Aq, \*(Aqlog\*(Aq \& , mode => \*(AqDEBUG\*(Aq, to => \*(Aq/var/log/mydir/myfile\*(Aq; \& \& # Full package name is used, same as \*(AqFILE\*(Aq \& dispatcher Log::Report::Dispatch::File => \*(Aqstderr\*(Aq \& , to => \e*STDERR, accept => \*(AqNOTICE\-\*(Aq; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" In Log::Report, dispatchers are used to handle (exception) messages which are created somewhere else. Those message were produced (thrown) by \fILog::Report::error()\fR and friends. .PP This base-class handles the creation of dispatchers, plus the common filtering rules. See the \*(L"\s-1DETAILS\*(R"\s0 section, below. .SH "METHODS" .IX Header "METHODS" .SS "Constructors" .IX Subsection "Constructors" .ie n .IP "$obj\->\fBclose\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBclose\fR()" 4 .IX Item "$obj->close()" Terminate the dispatcher activities. The dispatcher gets disabled, to avoid the case that it is accidentally used. Returns \f(CW\*(C`undef\*(C'\fR (false) if the dispatcher was already closed. .ie n .IP "Log::Report::Dispatcher\->\fBnew\fR($type, $name, %options)" 4 .el .IP "Log::Report::Dispatcher\->\fBnew\fR($type, \f(CW$name\fR, \f(CW%options\fR)" 4 .IX Item "Log::Report::Dispatcher->new($type, $name, %options)" Create a dispatcher. The \f(CW$type\fR of back-end to start is required, and listed in the \*(L"\s-1DESCRIPTION\*(R"\s0 part of this manual-page. For various external back-ends, special wrappers are created. .Sp The \f(CW$name\fR must be uniquely identifying this dispatcher. When a second dispatcher is created (via \fILog::Report::dispatcher()\fR) with the name of an existing dispatcher, the existing one will get replaced. .Sp All \f(CW%options\fR which are not consumed by this base constructor are passed to the wrapped back-end. Some of them will check whether all \f(CW%options\fR are understood, other ignore unknown \f(CW%options\fR. .Sp .Vb 6 \& \-Option \-\-Default \& accept depend on mode \& charset \& format_reason \*(AqLOWERCASE\*(Aq \& locale \& mode \*(AqNORMAL\*(Aq .Ve .RS 4 .IP "accept => \s-1REASONS\s0" 2 .IX Item "accept => REASONS" See \fILog::Report::Util::expand_reasons()\fR for possible values. If the initial mode for this dispatcher does not need verbose or debug information, then those levels will not be accepted. .Sp When the mode equals \*(L"\s-1NORMAL\*(R" \s0(the default) then \f(CW\*(C`accept\*(C'\fR's default is \f(CW\*(C`NOTICE\-\*(C'\fR. In case of \*(L"\s-1VERBOSE\*(R"\s0> it will be \f(CW\*(C`INFO\-\*(C'\fR, \f(CW\*(C`ASSERT\*(C'\fR results in \f(CW\*(C`ASSERT\-\*(C'\fR, and \*(L"\s-1DEBUG\*(R"\s0 in \f(CW\*(C`ALL\*(C'\fR. .IP "charset => \s-1CHARSET\s0" 2 .IX Item "charset => CHARSET" Convert the messages in the specified character-set (codeset). By default, no conversion will take place, because the right choice cannot be determined automatically. .IP "format_reason => '\s-1UPPERCASE\s0'|'\s-1LOWERCASE\s0'|'\s-1UCFIRST\s0'|'\s-1IGNORE\s0'|CODE" 2 .IX Item "format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE" How to show the reason text which is printed before the message. When a \s-1CODE\s0 is specified, it will be called with a translated text and the returned text is used. .IP "locale => \s-1LOCALE\s0" 2 .IX Item "locale => LOCALE" Overrules the global setting. Can be overruled by Log::Report::report(locale). .IP "mode => '\s-1NORMAL\s0'|'\s-1VERBOSE\s0'|'\s-1ASSERT\s0'|'\s-1DEBUG\s0'|0..3" 2 .IX Item "mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3" Possible values are \f(CW\*(C`NORMAL\*(C'\fR (or \f(CW0\fR or \f(CW\*(C`undef\*(C'\fR), which will not show \&\f(CW\*(C`INFO\*(C'\fR or debug messages, \f(CW\*(C`VERBOSE\*(C'\fR (\f(CW1\fR; shows \f(CW\*(C`INFO\*(C'\fR not debug), \&\f(CW\*(C`ASSERT\*(C'\fR (\f(CW2\fR; only ignores \f(CW\*(C`TRACE\*(C'\fR messages), or \f(CW\*(C`DEBUG\*(C'\fR (\f(CW3\fR) which shows everything. See section \*(L"Run modes\*(R" in Log::Report. .Sp You are advised to use the symbolic mode names when the mode is changed within your program: the numerical values are available for smooth Getopt::Long integration. .RE .RS 4 .RE .SS "Accessors" .IX Subsection "Accessors" .ie n .IP "$obj\->\fBisDisabled\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBisDisabled\fR()" 4 .IX Item "$obj->isDisabled()" .PD 0 .ie n .IP "$obj\->\fBmode\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBmode\fR()" 4 .IX Item "$obj->mode()" .PD Returns the mode in use for the dispatcher as number. See new(mode) and \*(L"Run modes\*(R" in Log::Report. .ie n .IP "$obj\->\fBname\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBname\fR()" 4 .IX Item "$obj->name()" Returns the unique name of this dispatcher. .ie n .IP "$obj\->\fBneeds\fR( [$reason] )" 4 .el .IP "\f(CW$obj\fR\->\fBneeds\fR( [$reason] )" 4 .IX Item "$obj->needs( [$reason] )" Returns the list with all \s-1REASONS\s0 which are needed to fulfill this dispatcher's needs. When disabled, the list is empty, but not forgotten. .Sp [0.999] when only one \f(CW$reason\fR is specified, it is returned if in the list. .ie n .IP "$obj\->\fBtype\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBtype\fR()" 4 .IX Item "$obj->type()" The dispatcher \f(CW$type\fR, which is usually the same as the class of this object, but not in case of wrappers like for Log::Dispatch. .SS "Logging" .IX Subsection "Logging" .ie n .IP "$obj\->\fBcollectLocation\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBcollectLocation\fR()" 4 .IX Item "$obj->collectLocation()" .PD 0 .IP "Log::Report::Dispatcher\->\fBcollectLocation\fR()" 4 .IX Item "Log::Report::Dispatcher->collectLocation()" .PD Collect the information to be displayed as line where the error occurred. Probably, this needs improvement, where carp and die show different lines. .ie n .IP "$obj\->\fBcollectStack\fR( [$maxdepth] )" 4 .el .IP "\f(CW$obj\fR\->\fBcollectStack\fR( [$maxdepth] )" 4 .IX Item "$obj->collectStack( [$maxdepth] )" .PD 0 .IP "Log::Report::Dispatcher\->\fBcollectStack\fR( [$maxdepth] )" 4 .IX Item "Log::Report::Dispatcher->collectStack( [$maxdepth] )" .PD Returns an \s-1ARRAY\s0 of ARRAYs with text, filename, line-number. .ie n .IP "$obj\->\fBlog\fR(HASH\-$of\-%options, $reason, $message, $domain)" 4 .el .IP "\f(CW$obj\fR\->\fBlog\fR(HASH\-$of\-%options, \f(CW$reason\fR, \f(CW$message\fR, \f(CW$domain\fR)" 4 .IX Item "$obj->log(HASH-$of-%options, $reason, $message, $domain)" This method is called by \fILog::Report::report()\fR and should not be called directly. Internally, it will call \fItranslate()\fR, which does most \f(CW$of\fR the work. .ie n .IP "$obj\->\fBstackTraceLine\fR(%options)" 4 .el .IP "\f(CW$obj\fR\->\fBstackTraceLine\fR(%options)" 4 .IX Item "$obj->stackTraceLine(%options)" .PD 0 .IP "Log::Report::Dispatcher\->\fBstackTraceLine\fR(%options)" 4 .IX Item "Log::Report::Dispatcher->stackTraceLine(%options)" .PD .Vb 9 \& \-Option \-\-Default \& abstract 1 \& call \& filename \& linenr \& max_line undef \& max_params 8 \& package \& params .Ve .RS 4 .IP "abstract => \s-1INTEGER\s0" 2 .IX Item "abstract => INTEGER" The higher the abstraction value, the less details are given about the caller. The minimum abstraction is specified, and then increased internally to make the line fit within the \f(CW\*(C`max_line\*(C'\fR margin. .IP "call => \s-1STRING\s0" 2 .IX Item "call => STRING" .PD 0 .IP "filename => \s-1STRING\s0" 2 .IX Item "filename => STRING" .IP "linenr => \s-1INTEGER\s0" 2 .IX Item "linenr => INTEGER" .IP "max_line => \s-1INTEGER\s0" 2 .IX Item "max_line => INTEGER" .IP "max_params => \s-1INTEGER\s0" 2 .IX Item "max_params => INTEGER" .IP "package => \s-1CLASS\s0" 2 .IX Item "package => CLASS" .IP "params => \s-1ARRAY\s0" 2 .IX Item "params => ARRAY" .RE .RS 4 .RE .ie n .IP "$obj\->\fBtranslate\fR(HASH\-$of\-%options, $reason, $message)" 4 .el .IP "\f(CW$obj\fR\->\fBtranslate\fR(HASH\-$of\-%options, \f(CW$reason\fR, \f(CW$message\fR)" 4 .IX Item "$obj->translate(HASH-$of-%options, $reason, $message)" .PD See \*(L"Processing the message\*(R", which describes the actions taken by this method. A string is returned, which ends on a new-line, and may be multi-line (in case a stack trace is produced). .SH "DETAILS" .IX Header "DETAILS" .SS "Available back-ends" .IX Subsection "Available back-ends" When a dispatcher is created (via \fInew()\fR or \fILog::Report::dispatcher()\fR), you must specify the \s-1TYPE\s0 of the dispatcher. This can either be a class name, which extends a Log::Report::Dispatcher, or a pre-defined abbreviation of a class name. Implemented are: .IP "Log::Report::Dispatcher::Perl (abbreviation '\s-1PERL\s0')" 4 .IX Item "Log::Report::Dispatcher::Perl (abbreviation 'PERL')" Use Perl's own \f(CW\*(C`print()\*(C'\fR, \f(CW\*(C`warn()\*(C'\fR and \f(CW\*(C`die()\*(C'\fR to ventilate reports. This is the default dispatcher. .IP "Log::Report::Dispatcher::File (abbreviation '\s-1FILE\s0')" 4 .IX Item "Log::Report::Dispatcher::File (abbreviation 'FILE')" Logs the message into a file, which can either be opened by the class or be opened before the dispatcher is created. .IP "Log::Report::Dispatcher::Syslog (abbreviation '\s-1SYSLOG\s0')" 4 .IX Item "Log::Report::Dispatcher::Syslog (abbreviation 'SYSLOG')" Send messages into the system's syslog infrastructure, using Sys::Syslog. .IP "Log::Report::Dispatcher::Callback (abbreviation '\s-1CALLBACK\s0')" 4 .IX Item "Log::Report::Dispatcher::Callback (abbreviation 'CALLBACK')" Calls any \s-1CODE\s0 reference on receipt of each selected message, for instance to send important message as email or \s-1SMS.\s0 .ie n .IP """Log::Dispatch::*""" 4 .el .IP "\f(CWLog::Dispatch::*\fR" 4 .IX Item "Log::Dispatch::*" All of the Log::Dispatch::Output extensions can be used directly. The Log::Report::Dispatcher::LogDispatch will wrap around that back-end. .ie n .IP """Log::Log4perl""" 4 .el .IP "\f(CWLog::Log4perl\fR" 4 .IX Item "Log::Log4perl" Use the Log::Log4perl main object to write to dispatchers. This infrastructure uses a configuration file. .IP "Log::Report::Dispatcher::Try (abbreviation '\s-1TRY\s0')" 4 .IX Item "Log::Report::Dispatcher::Try (abbreviation 'TRY')" Used by function \fILog::Report::try()\fR. It collects the exceptions and can produce them on request. .SS "Processing the message" .IX Subsection "Processing the message" \fIAddition information\fR .IX Subsection "Addition information" .PP The modules which use \f(CW\*(C`Log::Report\*(C'\fR will only specify the base of the message string. The base dispatcher and the back-ends will extend this message with additional information: .IP ". the reason" 4 .IX Item ". the reason" .PD 0 .IP ". the filename/line\-number where the problem appeared" 4 .IX Item ". the filename/line-number where the problem appeared" .IP ". the filename/line\-number where it problem was reported" 4 .IX Item ". the filename/line-number where it problem was reported" .ie n .IP ". the error text in $!" 4 .el .IP ". the error text in \f(CW$!\fR" 4 .IX Item ". the error text in $!" .IP ". a stack-trace" 4 .IX Item ". a stack-trace" .IP ". a trailing new-line" 4 .IX Item ". a trailing new-line" .PD .PP When the message is a translatable object (Log::Report::Message, for instance created with Log::Report::_\|_()), then the added components will get translated as well. Otherwise, all will be in English. .PP Exactly what will be added depends on the actual mode of the dispatcher (change it with \fImode()\fR, initiate it with new(mode)). .PP .Vb 10 \& mode mode mode mode \& REASON SOURCE TE! NORM VERB ASSE DEBUG \& trace program ... S \& assert program ... SL SL \& info program T.. S S S \& notice program T.. S S S S \& mistake user T.. S S S SL \& warning program T.. S S SL SL \& error user TE. S S SL SC \& fault system TE! S S SL SC \& alert system T.! SL SL SC SC \& failure system TE! SL SL SC SC \& panic program .E. SC SC SC SC \& \& T \- usually translated \& E \- exception (execution interrupted) \& ! \- will include $! text at display \& L \- include filename and linenumber \& S \- show/print when accepted \& C \- stack trace (like Carp::confess()) .Ve .PP \fIFilters\fR .IX Subsection "Filters" .PP With a filter, you can block or modify specific messages before translation. There may be a wish to change the \s-1REASON\s0 of a report or its content. It is not possible to avoid the exit which is related to the original message, because a module's flow depends on it to happen. .PP When there are filters defined, they will be called in order of definition. For each of the dispatchers which are called for a certain \s-1REASON \s0(which \f(CW\*(C`accept\*(C'\fR that \s-1REASON\s0), it is checked whether its name is listed for the filter (when no names where specified, then the filter is applied to all dispatchers). .PP When selected, the filter's \s-1CODE\s0 reference is called with four arguments: the dispatcher object (a Log::Report::Dispatcher), the HASH-of-OPTIONS passed as optional first argument to \fILog::Report::report()\fR, the \&\s-1REASON,\s0 and the \s-1MESSAGE. \s0 Returned is the new \s-1REASON\s0 and \s-1MESSAGE.\s0 When the returned \s-1REASON\s0 is \f(CW\*(C`undef\*(C'\fR, then the message will be ignored for that dispatcher. .PP Be warned about processing the \s-1MESSAGE:\s0 it is a Log::Report::Message object which may have a \f(CW\*(C`prepend\*(C'\fR string and \f(CW\*(C`append\*(C'\fR string or object. When the call to \fILog::Report::report()\fR contained multiple comma-separated components, these will already have been joined together using concatenation (see \fILog::Report::Message::concat()\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Log-Report distribution version 1.05, built on June 24, 2014. Website: \fIhttp://perl.overmeer.net/log\-report/\fR .SH "LICENSE" .IX Header "LICENSE" Copyrights 2007\-2014 by [Mark Overmeer]. For other contributors see ChangeLog. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR