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 C it will be INFO->, C results in ASSERT->, and C 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.
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.

$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
$class->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] )
$class->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 )
$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).