log::report::dispatcher::perl(3pm) [debian man page]
Log::Report::Dispatcher::Perl(3pm) User Contributed Perl Documentation Log::Report::Dispatcher::Perl(3pm) NAME
Log::Report::Dispatcher::Perl - send messages to die and warn INHERITANCE
Log::Report::Dispatcher::Perl is a Log::Report::Dispatcher SYNOPSIS
dispatcher Log::Report::Dispatcher::Perl => 'default' , accept => 'NOTICE-'; # close the default dispatcher dispatcher close => 'default'; DESCRIPTION
Ventilate the problem reports via the standard Perl error mechanisms: "die()", "warn()", and "print()". There can be only one such dispatcher (per thread), because once "die()" is called, we are not able to return. Therefore, this dispatcher will always be called last. In the early releases of Log::Report, it tried to simulate the behavior of warn and die using STDERR and exit; however: that is not possible. METHODS
Constructors $obj->close See "Constructors" in Log::Report::Dispatcher Log::Report::Dispatcher::Perl->new(TYPE, NAME, OPTIONS) See "Constructors" in Log::Report::Dispatcher Accessors $obj->isDisabled See "Accessors" in Log::Report::Dispatcher $obj->mode See "Accessors" in Log::Report::Dispatcher $obj->name See "Accessors" in Log::Report::Dispatcher $obj->needs See "Accessors" in Log::Report::Dispatcher $obj->type See "Accessors" in Log::Report::Dispatcher Logging $obj->collectLocation Log::Report::Dispatcher::Perl->collectLocation See "Logging" in Log::Report::Dispatcher $obj->collectStack([MAXDEPTH]) Log::Report::Dispatcher::Perl->collectStack([MAXDEPTH]) See "Logging" in Log::Report::Dispatcher $obj->log(HASH-of-OPTIONS, REASON, MESSAGE) See "Logging" in Log::Report::Dispatcher $obj->stackTraceLine(OPTIONS) Log::Report::Dispatcher::Perl->stackTraceLine(OPTIONS) See "Logging" in Log::Report::Dispatcher $obj->translate(HASH-of-OPTIONS, REASON, MESSAGE) See "Logging" in Log::Report::Dispatcher SEE ALSO
This module is part of Log-Report distribution version 0.94, built on August 23, 2011. Website: http://perl.overmeer.net/log-report/ LICENSE
Copyrights 2007-2011 by Mark Overmeer. For other contributors see ChangeLog. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html perl v5.14.2 2011-08-23 Log::Report::Dispatcher::Perl(3pm)
Check Out this Related Man Page
Log::Report::Dispatcher(3pm) User Contributed Perl Documentation Log::Report::Dispatcher(3pm) NAME
Log::Report::Dispatcher - manage dispatching INHERITANCE
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 SYNOPSIS
use Log::Report; # The following will be created for you automatically dispatcher 'PERL', 'default', accept => 'NOTICE-'; dispatcher close => 'default'; # after deamonize dispatcher 'FILE', 'log' , mode => 'DEBUG', to => '/var/log/mydir/myfile'; # Full package name is used, same as 'FILE' dispatcher Log::Report::Dispatch::File => 'stderr' , to => *STDERR, accept => 'NOTICE-'; # Within a "try" block, there is only one dispatcher dispatcher TRY => 'try'; DESCRIPTION
This base-class handles the creation of dispatchers, plus the common filtering rules. See the "DETAILS" section, below. METHODS
Constructors $obj->close Terminate the dispatcher activities. The dispatcher gets disabled, to avoid the case that it is accidentally used. Returns "undef" (false) if the dispatcher was already closed. Log::Report::Dispatcher->new(TYPE, NAME, OPTIONS) Create a dispatcher. The TYPE of back-end to start is required, and listed in the "DESCRIPTION" part of this manual-page. For various external back-ends, special wrappers are created. The NAME must be uniquely identifying this dispatcher. When a second dispatcher is created (via Log::Report::dispatcher()) with the name of an existing dispatcher, the existing one will get replaced. All OPTIONS which are not consumed by this base constructor are passed to the wrapped back-end. Some of them will check whether all OPTIONS are understood, other ignore unknown OPTIONS. -Option --Default accept depend on mode charset <undef> format_reason 'LOWERCASE' locale <system locale> mode 'NORMAL' accept => REASONS See Log::Report::Util::expand_reasons() for possible values. If the initial mode for this dispatcher does not need verbose or debug information, then those levels will not be accepted. When the mode equals "NORMAL" (the default) then "accept"'s default is "NOTICE-". In case of "VERBOSE" it will be "INFO-", "ASSERT" results in "ASSERT-", and "DEBUG" in "ALL". 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. format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE How to show the reason text which is printed before the message. When a CODE is specified, it will be called with a translated text and the returned text is used. locale => LOCALE Overrules the global setting. Can be overruled by Log::Report::report(locale). mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3 Possible values are "NORMAL" (or 0 or "undef"), which will not show "INFO" or debug messages, "VERBOSE" (1; shows "INFO" not debug), "ASSERT" (2; only ignores "TRACE" messages), or "DEBUG" (3) which shows everything. See section "Run modes" in Log::Report. 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. Accessors $obj->isDisabled $obj->mode Returns the mode in use for the dispatcher as number. See new(mode) and "Run modes" in Log::Report. $obj->name Returns the unique name of this dispatcher. $obj->needs Returns the list with all REASONS which are needed to fulfill this dispatcher's needs. When disabled, the list is empty, but not forgotten. $obj->type The dispatcher TYPE, which is usually the same as the class of this object, but not in case of wrappers like for Log::Dispatch. Logging $obj->collectLocation Log::Report::Dispatcher->collectLocation Collect the information to be displayed as line where the error occurred. Probably, this needs improvement, where carp and die show different lines. $obj->collectStack([MAXDEPTH]) Log::Report::Dispatcher->collectStack([MAXDEPTH]) Returns an ARRAY of ARRAYs with text, filename, line-number. $obj->log(HASH-of-OPTIONS, REASON, MESSAGE) This method is called by Log::Report::report() and should not be called directly. Internally, it will call translate(), which does most of the work. $obj->stackTraceLine(OPTIONS) Log::Report::Dispatcher->stackTraceLine(OPTIONS) -Option --Default abstract 1 call <required> filename <required> linenr <required> max_line undef max_params 8 package <required> params <required> 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 "max_line" margin. call => STRING filename => STRING linenr => INTEGER max_line => INTEGER max_params => INTEGER package => CLASS params => ARRAY $obj->translate(HASH-of-OPTIONS, REASON, MESSAGE) See "Processing the message", 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). DETAILS
Available back-ends When a dispatcher is created (via new() or Log::Report::dispatcher()), you must specify the TYPE 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: Log::Report::Dispatcher::Perl (abbreviation 'PERL') Use Perl's own "print()", "warn()" and "die()" to ventilate reports. This is the default dispatcher. 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. Log::Report::Dispatcher::Syslog (abbreviation 'SYSLOG') Send messages into the system's syslog infrastructure, using Sys::Syslog. "Log::Dispatch::*" All of the Log::Dispatch::Output extensions can be used directly. The Log::Report::Dispatcher::LogDispatch will wrap around that back- end. "Log::Log4perl" Use the Log::Log4perl main object to write to dispatchers. This infrastructure uses a configuration file. Log::Report::Dispatcher::Try (abbreviation 'TRY') Used by Log::Report::try(), it will translate reports into exceptions. Processing the message Addition information The modules which use "Log::Report" will only specify the base of the message string. The base dispatcher and the back-ends will extend this message with additional information: . the reason . the filename/line-number where the problem appeared . the filename/line-number where it problem was reported . the error text in $! . a stack-trace . a trailing new-line 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. Exactly what will be added depends on the actual mode of the dispatcher (change it with mode(), initiate it with new(mode)). 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.! S S SC SC failure system TE! S S SC SC panic program .E. SC SC SC SC T - usually translated E - exception (execution interrupted) ! - will include $! text L - include filename and linenumber S - show/print when accepted C - stack trace (like Carp::confess()) Filters With a filter, you can block or modify specific messages before translation. There may be a wish to change the REASON 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. When there are filters defined, they will be called in order of definition. For each of the dispatchers which are called for a certain REASON (which "accept" that REASON), it is checked whether its name is listed for the filter (when no names where specified, then the filter is applied to all dispatchers). When selected, the filter's CODE reference is called with four arguments: the dispatcher object (a Log::Report::Dispatcher), the HASH-of- OPTIONS passed as optional first argument to Log::Report::report(), the REASON, and the MESSAGE. Returned is the new REASON and MESSAGE. When the returned REASON is "undef", then the message will be ignored for that dispatcher. Be warned about processing the MESSAGE: it is a Log::Report::Message object which may have a "prepend" string and "append" string or object. When the call to Log::Report::report() contained multiple comma-separated components, these will already have been joined together using concatenation (see Log::Report::Message::concat(). SEE ALSO
This module is part of Log-Report distribution version 0.94, built on August 23, 2011. Website: http://perl.overmeer.net/log-report/ LICENSE
Copyrights 2007-2011 by Mark Overmeer. For other contributors see ChangeLog. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html perl v5.14.2 2011-08-23 Log::Report::Dispatcher(3pm)