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.

$class->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 C results in ASSERT->, and "DEBUG" in C.
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.
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.

$obj->name

Returns the unique name of this dispatcher.

$obj->needs( [$reason] )

Returns the list with all REASONS which are needed to fulfill this dispatcher's needs. When disabled, the list is empty, but not forgotten.

[0.999] when only one $reason is specified, it is returned if in the list.

$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->addSkipStack( @CODE )
$class->addSkipStack( @CODE )

[1.13] Add one or more CODE blocks of caller lines which should not be collected for stack-traces or location display. A CODE gets called with an ARRAY of caller information, and returns true when that line should get skipped.

Warning: this logic is applied globally: on all dispatchers.

» Example:

By default, all lines in the Log::Report packages are skipped from display, with a simple CODE as this:

  sub in_lr { $_[0][0] =~ m/^Log\:\:Report(?:\:\:|$)/ }
  Log::Report::Dispatcher->addSkipStack(\&in_lr);

The only parameter to in_lr is the return of caller(). The first element of that ARRAY is the package name of a stack line.

$obj->collectLocation
$class->collectLocation

Collect the information to be displayed as line where the error occurred.

$obj->collectStack( [$maxdepth] )
$class->collectStack( [$maxdepth] )

Returns an ARRAY of ARRAYs with text, filename, line-number.

$obj->log( HASH-$of-%options, $reason, $message, $domain )

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->skipStack

[1.13] Returns the number of nestings in the stack which should be skipped to get outside the Log::Report (and related) modules. The end-user does not want to see those internals in stack-traces.

$obj->stackTraceLine( %options )
$class->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).