NAME

Log::Report - report a problem, pluggable handlers and language support

INHERITANCE

Log::Report
  is a Exporter

SYNOPSIS

# Read section "The Reason for the report" first!!!

# In each package, declare a name-space.  Different packages
# used by one program can have different translation tables.
use Log::Report 'my-domain';

# Many destinations in parallel possible. Log::Report::Dispatcher
dispatcher PERL => 'default'
  , reasons => 'NOTICE-';   # this disp. is automatically added

dispatcher SYSLOG => 'syslog'
  , charset => 'iso-8859-1' # explicit conversions
  , locale => 'en_US';      # overrule user's locale

# Produce an error, long syntax
report ERROR => __x('gettext string', param => $param, ...)
    if $condition;

# Syntax SHORT, adding error() and many other
use Log::Report 'my-domain', syntax => 'SHORT';
error __x('gettext string', param => $param, ...)
    if $condition;

# Overrule standard behavior for single message with HASH as
# first parameter.  Only long syntax
use Errno qw/ENOMEM/;
report {to => 'syslog', errno => ENOMEM}
  , FAULT => __x"cannot allocate {size} bytes", size => $size;

# avoid messages without report level for daemons
print __"Hello World", "\n";  # only translation, no exception
print __'Hello World';  # ERROR!!  ' is alternative for ::

# fill-in values, like Locale::TextDomain and gettext
# See Log::Report::Message section DETAILS
fault __x "cannot allocate {size} bytes", size => $size;
fault "cannot allocate $size bytes";      # no translation
fault __x "cannot allocate $size bytes";  # wrong, not static

print __xn("found one file", "found {_count} files", @files), "\n";

# catch errors (implements hidden eval/die)
try { error };
if($@) {...}      # $@ isa Log::Report::Dispatcher::Try

# Language translations at the IO/layer
use POSIX ':locale_h';
setlocale(LC_ALL, 'nl_NL');
info __"Hello World!";  # in Dutch, if translation table found

# Exception classes, see Log::Report::Exception
my $msg = __x"something", _class => 'local,mine';
if($msg->inClass('local')) ...

DESCRIPTION

Handling messages to users can be a hassle, certainly when the same module is used for command-line and in a graphical interfaces, and has to cope with internationalization at the same time; this set of modules tries to simplify this. Log::Report combines gettext features with Log::Dispatch-like features. However, you can also use this module to do only translations or only message dispatching.

Read more about how and why in the "DETAILS" section, below. Especially, you should read about the REASON parameter.

Content of the whole Log::Report package:

. Log::Report: Exports the functions to end-users. To avoid the need to pass around an logger-object to all end-user packages, the singleton object is wrapped in functions.
. Translating: You can use the GNU gettext infrastructure (via MO files handled by Log::Report::Translator::Gettext), or extract strings via PPI (Log::Report::Extract::PerlPPI) into PO files which can be used directly (Log::Report::Lexicon::POTcompact).
. Dispatching: Multiple dispatchers in parallel can be active. Log::Report::Dispatcher takes care that the back-end gets the messages of the severity it needs, translated and in the right character-set.
. Exception handling: A simple exception system is implemented via try() and Log::Report::Dispatcher::Try.

FUNCTIONS

Report Production and Configuration

dispatcher((TYPE, OPTIONS)|(COMMAND => NAME, [NAMEs]))

The Log::Report suite has its own dispatcher TYPES, but also connects to external dispatching frame-works. Each need some (minor) conversions, especially with respect to translation of REASONS of the reports into log-levels as the back-end understands.

The OPTIONS are a mixture of parameters needed for the Log::Report dispatcher wrapper and the settings of the back-end. See Log::Report::Dispatcher, the documentation for the back-end specific wrappers, and the back-ends for more details.

Implemented COMMANDs are close, find, list, disable, enable, mode, filter, and needs. Most commands are followed by a LIST of dispatcher NAMEs to be address. For mode see section "Run modes"; it requires a MODE argument before the LIST of NAMEs. Non-existing names will be ignored. When ALL is specified, then all existing dispatchers will get addressed. For filter see "Filters" in Log::Report::Dispatcher; it requires a CODE reference before the NAMEs of the dispatchers which will have the it applied (defaults to all).

With needs, you only provide a REASON: it will return the list of dispatchers which need to be called in case of a message with the REASON is triggered.

For both the creation as COMMANDs version of this method, all objects involved are returned as LIST, non-existing ones skipped. In SCALAR context with only one name, the one object is returned.

example: play with dispatchers

dispatcher Log::Dispatcher::File => mylog =>
  , accept   => 'MISTAKE-'              # for wrapper
  , locale   => 'pt_BR'                 # other language
  , filename => 'logfile';              # for back-end

dispatcher close => 'mylog';            # cleanup
my $obj = dispatcher find => 'mylog'; 
my @obj = dispatcher list;
dispatcher disable => 'syslog';
dispatcher enable => 'mylog', 'syslog'; # more at a time
dispatcher mode => DEBUG => 'mylog';
dispatcher mode => DEBUG => 'ALL';

my @need_info = dispatcher needs => 'INFO';
if(dispatcher needs => 'INFO') ...

# Getopt::Long integration: see Log::Report::Dispatcher::mode()
dispatcher PERL => 'default', mode => 'DEBUG', accept => 'ALL'
    if $debug;

report([HASH-of-OPTIONS], REASON, MESSAGE|(STRING,PARAMS),)

Produce a report for certain REASON. The MESSAGE is a Log::Report::Message object (which are created with the special translation syntax like __x()). A not-translated message is ONE string with optional parameters. The HASH is an optional first parameter, which can be used to influence the dispatchers. The HASH contains any combination of the OPTIONS listed below.

When syntax = 'SHORT'> is configured, you will also have abbreviations available, where the REASON is the name of the function. See for instance info(). In that case, you loose the chance for OPTIONS.

Returns is the LIST of dispatchers used to log the MESSAGE. When empty, no back-end has accepted it so the MESSAGE was "lost". Even when no back-end need the message, it program will still exit when there is REASON to.

Option  --Default
errno     $! or 1
locale    undef
location  undef
stack     undef
to        undef

. errno => INTEGER

When the REASON includes the error text (See "Run modes"), you can overrule the error code kept in $!. In other cases, the return code default to 1 (historical UNIX behavior). When the message REASON (combined with the run-mode) is severe enough to stop the program, this value as return code. The use of this option itself will not trigger an die().

. locale => LOCALE

Use this specific locale, in stead of the user's preference.

. location => STRING

When defined, this location is used in the display. Otherwise, it is determined automatically if needed. An empty string will disable any attempt to display this line.

. stack => ARRAY

When defined, that data is used to display the call stack. Otherwise, it is collected via caller() if needed.

. to => NAME|ARRAY-of-NAMEs

Sent the MESSAGE only to the NAMEd dispatchers. Ignore unknown NAMEs. Still, the dispatcher needs to be enabled and accept the REASONs.

example: for use of report()

report TRACE => "start processing now";
report INFO  => '500: ' . __'Internal Server Error';

report {to => 'syslog'}, NOTICE => "started process $$";

# with syntax SHORT
trace "start processing now";
warning  __x'Disk {percent%.2f}% full', percent => $p
    if $p > 97;

# error message, overruled to be printed in Brazilian
report {locale => 'pt_BR'}
   , WARNING => "do this at home!";

try(CODE, OPTIONS)

Execute the CODE, but block all dispatchers as long as it is running. When the execution of the CODE is terminated with an report which triggers an error, that is captured. After the try, the $@ will contain a Log::Report::Dispatcher::Try object, which contains the collected error messages. When there where no errors, the result of the code execution is returned.

Run-time errors from Perl and die's, croak's and confess's within the program (which shouldn't appear, but you never know) are collected into an Log::Report::Message object, using Log::Report::Die.

The OPTIONS are passed to the constructor of the try-dispatcher, see Log::Report::Dispatcher::Try::new(). For instance, you may like to add mode => 'DEBUG', or accept => 'ERROR-'.

Be warned that the parameter to try is a CODE reference. This means that you shall not use a comma after the block when there are OPTIONS specified. On the other hand, you shall use a semi-colon after the block if there are no arguments.

example:

try { ... };       # mind the ';' !!
if($@) {           # signals something went wrong

if(try {...}) {    # block ended normally

try { ... }        # no comma!!
   mode => 'DEBUG', accept => 'ERROR-';

try sub { ... },   # with comma, also \&function
   mode => 'DEBUG', accept => 'ALL';

Abbreviations for report()

The following functions are abbreviations for calls to report(), and available when syntax is SHORT (see import()). You cannot specify additional options to influence the behavior of report(), which are usually not needed anyway.

alert(MESSAGE)

Short for report ALERT => MESSAGE

assert(MESSAGE)

Short for report ASSERT => MESSAGE

error(MESSAGE)

Short for report ERROR => MESSAGE

failure(MESSAGE)

Short for report FAILURE => MESSAGE

fault(MESSAGE)

Short for report FAULT => MESSAGE

info(MESSAGE)

Short for report INFO => MESSAGE

mistake(MESSAGE)

Short for report MISTAKE => MESSAGE

notice(MESSAGE)

Short for report NOTICE => MESSAGE

panic(MESSAGE)

Short for report PANIC => MESSAGE

trace(MESSAGE)

Short for report TRACE => MESSAGE

warning(MESSAGE)

Short for report WARNING => MESSAGE

Language Translations

The language translations are initiate by limited set of functions which contain two under-score (_) characters in their name. Most of them return a Log::Report::Message object.

BE WARNED(1) that -in general- its considered very bad practice to combine multiple translations into one message; translating may also affect the order of the translated components. Besides, when the translator only sees smaller parts of the text, his or her job becomes more complex. So:

print __"Hello" . ', ' . __"World!";  # very bad idea!
print __"Hello, World!";    # yes: complete sentence.

The the former case, tricks with overloading used by the Log::Report::Message objects will still make delayed translations work.

In normal situations, it is not a problem to translate interpolated values:

print __"the color is {c}", c => __"red";

BE WARNED(2) that using __'Hello' will produce a syntax error like "String found where operator expected at .... Can't find string terminator "'" anywhere before EOF". The first quote is the cause of the complaint, but the second generates the error. In the early days of Perl, the single quote was used to separate package name from function name, a role which was later replaced by a double-colon. So __'Hello' gets interpreted as __::Hello '. Then, there is a trailing single quote which has no counterpart.

N__(MSGID)

Label to indicate that the string is a text which will be translated later. The function itself does nothing. See also N__w().

example: how to use N__()

my @colors = (N__"red", N__"green", N__"blue");
my @colors = N__w "red green blue";   # same
print __ $colors[1];

Using __(), would work as well my @colors = (__"red", __"green", __"blue"); print $colors[1]; However: this will always create all Log::Report::Message objects, where maybe only one is used.

N__n(SINGLE_MSGID, PLURAL_MSGID)

Label to indicate that the two MSGIDs are related, the first as single, the seconds as its plural. Only used to find the text fragments to be translated. The function itself does nothing.

example: how to use N__n()

my @save = N__n "save file", "save files";
my @save = (N__n "save file", "save files");
my @save = N__n("save file", "save files");

# be warned about SCALARs in prototype!
print __n @save, $nr_files;  # wrong!
print __n $save[0], $save[1], $nr_files;

N__w(STRING)

This extension to the Locale::TextDomain syntax, is a combined qw (list of quoted words) and N__() into a list of translatable words.

example: of N__w()

my @colors = (N__"red", N__"green", N__"blue");
my @colors = N__w"red green blue";  # same
print __ $colors[1];

__(MSGID)

This function (name is two under-score characters) will cause the MSGID to be replaced by the translations when doing the actual output. Returned is one object, which will be used in translation later. Translating is invoked when the object gets stringified.

If you need OPTIONS, then take __x().

example: how to use __()

print __"Hello World";      # translated into user's language
print __'Hello World';      # syntax error!
print __('Hello World');    # ok, translated
print __"Hello", " World";  # World not translated

my $s = __"Hello World";    # creates object, not yet translated
print ref $s;               # Log::Report::Message
print $s;                   # ok, translated
print $s->toString('fr');   # ok, forced into French

__n(MSGID, PLURAL_MSGID, COUNT, OPTIONS)

It depends on the value of COUNT (and the selected language) which text will be displayed. When translations can not be performed, then MSGID will be used when COUNT is 1, and PLURAL_MSGSID in other cases. However, some languages have more complex schemes than English.

OPTIONS are explained in Log::Report::Message::new(). Locale::TextDomain subroutine __n does not have OPTIONS, but they mix with variables.

example: how to use __n()

print __n "one", "more", $a;
print __n("one", "more", $a), "\n";
print +(__n "one", "more", $a), "\n";
print __n "one\n", "more\n", $a;

__nx(MSGID, PLURAL_MSGID, COUNT, OPTIONS, VARIABLES)

It depends on the value of COUNT (and the selected language) which text will be displayed. See details in __n(). After translation, the VARIABLES will be filled-in.

OPTIONS are explained in Log::Report::Message::new(). Locale::TextDomain subroutine __nx does not support the OPTIONS, but they look like variables.

example: how to use __nx()

print __nx "one file", "{_count} files", $nr_files;
print __nx "one file", "{_count} files", @files;

local $" = ', ';
print __nx "one file: {f}", "{_count} files: {f}", @files, f => \@files;

__x(MSGID, OPTIONS, VARIABLES)

Translate the MSGID, and then expand the VARIABLES in that string. Of course, translation and expanding is delayed as long as possible. Both OPTIONS and VARIABLES are key-value pairs.

OPTIONS and VARIABLES are explained in Log::Report::Message::new(). Locale::TextDomain subroutine __x does not support the OPTIONS, but they mix with variables.

__xn(SINGLE_MSGID, PLURAL_MSGID, COUNT, OPTIONS, VARIABLES)

Same as __xn().

Configuration

$obj->import([DOMAIN], OPTIONS)

The import is automatically called when the package is compiled. For all packages but one in your distribution, it will only contain the name of the DOMAIN. For one package, it will contain configuration information. These OPTIONS are used for all packages which use the same DOMAIN.

Option         --Default
mode             'NORMAL'
native_language  'en_US'
syntax           'REPORT'
translator       <rescue>

. mode => LEVEL

This sets the default mode for all created dispatchers. You can also selectively change the output mode, like dispatcher PERL => 'default', mode => 3

. native_language => CODESET

This is the language which you have used to write the translatable and the non-translatable messages in. In case no translation is needed, you still wish the system error messages to be in the same language as the report. Of course, each textdomain can define its own.

. syntax => 'REPORT'|'SHORT'

The SHORT syntax will add the report abbreviations (like function error()) to your name-space. Otherwise, each message must be produced with report().

. translator => Log::Report::Translator

Without explicit translator, a dummy translator is used for the domain which will use the untranslated message-id .

example: of import

use Log::Report mode => 3;     # or 'DEBUG'

use Log::Report 'my-domain'    # in each package producing messages
 , syntax     => 'SHORT';

use Log::Report 'my-domain'    # in one package, top of distr
 , translator => Log::Report::Translator::POT->new
    ( lexicon  => '/home/me/locale'  # bindtextdomain
    , charset  => 'UTF-8'            # codeset
    )
 , native_language => 'nl_NL'; # untranslated msgs are Dutch

Log::Report->translator(TEXTDOMAIN, [TRANSLATOR])

Returns the translator configured for the TEXTDOMAIN. By default, a translator is configured which does not translate but directly uses the gettext message-ids.

When a TRANSLATOR is specified, it will be set to be used for the TEXTDOMAIN. When it is undef, the configuration is removed. You can only specify one TRANSLATOR per TEXTDOMAIN.

example: use if translator()

# in three steps
use Log::Report;
my $gettext = Log::Report::Translator::POT->new(...);
Log::Report->translator('my-domain', $gettext);

# in two steps
use Log::Report;
Log::Report->translator('my-domain'
  , Log::Report::Translator::POT->new(...));

# in one step
use Log::Report 'my-domain'
  , translator => Log::Report::Translator::POT->new(...);

Reasons

$obj->isFatal(REASON)

Log::Report->isFatal(REASON)

Returns true if the REASON is severe enough to cause an exception (or program termination).

$obj->isValidReason(STRING)

Log::Report->isValidReason(STRING)

Returns true if the STRING is one of the predefined REASONS.

$obj->needs(REASON, [REASONS])

Log::Report->needs(REASON, [REASONS])

Returns true when the reporter needs any of the REASONS, when any of the active dispatchers is collecting messages in the specified level. This is useful when the processing of data for the message is relatively expensive, but for instance only required in debug mode.

example:

if(Log::Report->needs('TRACE'))
{   my @args = ...expensive calculation...;
    trace "your options are: @args";
}

DETAILS

Introduction

There are three steps in this story: produce some text on a certain condition, translate it to the proper language, and deliver it in some way to a user. Texts are usually produced by commands like print, die, warn, carp, or croak, which have no way of configuring the way of delivery to the user. Therefore, they are replaced with a single new command: report (with various abbreviations)

Besides, the print/warn/die together produce only three levels of reasons to produce the message: many people manually implement more, like verbose and debug. Syslog has some extra levels as well, like critical. The REASON argument to report() replace them all.

The translations use the beautiful syntax defined by Locale::TextDomain, with some extensions (of course). The main difference is that the actual translations are delayed till the delivery step. This means that the pop-up in the graphical interface of the user will show the text in the language of the user, say Chinese, but at the same time syslog may write the English version of the text. With a little luck, translations can be avoided.

Background ideas

The following ideas are the base of this implementation:

. simplification: Handling errors and warnings is probably the most labor-intensive task for a programmer: when programs are written correctly, up-to three-quarters of the code is related to testing, reporting, and handling (problem) conditions. Simplifying the way to create reports, simplifies programming and maintenance.
. multiple dispatchers: It is not the location where the (for instance) error occurs determines what will happen with the text, but the main application which uses the the complaining module has control. Messages have a reason. Based on the reason, they can get ignored, send to one, or send to multiple dispatchers (like Log::Dispatch, Log::Log4perl, or UNIX syslog(1))
. delayed translations: The background ideas are that of Locale::TextDomain, based on gettext(). However, the Log::Report infrastructure has a pluggable translation backend. Translations are postponed until the text is dispatched to a user or log-file; the same report can be sent to syslog in (for instance) English and to the user interface in Dutch.
. avoid duplication: The same message may need to be documented on multiple locations: in web-pages for the graphical interface, in pod for the command-line configuration. The same text may even end-up in pdf user-manuals. When the message is written inside the Perl code, it's quite hard to get it out, to generate these documents. Only an abstract message description protocol will make flexible re-use possible. This component still needs to be implemented.

Error handling models

There are two approaches to handling errors and warnings. In the first approach, as produced by die, warn and the carp family of commands, the program handles the problem immediately on the location where the problem appears. In the second approach, an exception is thrown on the spot where the problem is created, and then somewhere else in the program the condition is handled.

The implementation of exceptions in Perl5 is done with a eval-die pair: on the spot where the problem occurs, die is called. But, because of the execution of that routine is placed within an eval, the program as a whole will not die, just the execution of a part of the program will seize. However, what if the condition which caused the routine to die is solvable on a higher level? Or what if the user of the code doesn't bother that a part fails, because it has implemented alternatives for that situation? Exception handling is quite clumsy in Perl5.

The Log::Report set of distributions let modules concentrate on the program flow, and let the main program decide on the report handling model. The infrastructure to translate messages into multiple languages, whether to create exceptions or carp/die, to collect longer explanations with the messages, to log to mail or syslog, and so on, is decided in pluggable back-ends.

The Reason for the report

Traditionally, perl has a very simple view on error reports: you either have a warning or an error. However, it would be much clearer for user's and module-using applications, when a distinction is made between various causes. For instance, a configuration error is quite different from a disk-full situation. In Log::Report, the produced reports in the code tell what is wrong. The main application defines loggers, which interpret the cause into (syslog) levels.

Defined by Log::Report are

. trace (debug, program)

The message will be used when some logger has debugging enabled. The messages show steps taken by the program, which are of interest by the developers and maintainers of the code, but not for end-users.

. assert (program)

Shows an unexpected condition, but continues to run. When you want the program to abort in such situation, that use panic.

. info (verbose, program)

These messages show larger steps in the execution of the program. Experienced users of the program usually do not want to see all these intermediate steps. Most programs will display info messages (and higher) when some verbose flag is given on the command-line.

. notice (program)

An user may need to be aware of the program's accidental smart behavior, for instance, that it initializes a lasting Desktop directory in your home directory. Notices should be sparse.

. warning (program)

The program encountered some problems, but was able to work around it by smart behavior. For instance, the program does not understand a line from a log-file, but simply skips the line.

. mistake (user)

When a user does something wrong, but what is correctable by smart behavior of the program. For instance, in some configuration file, you can fill-in "yes" or "no", but the user wrote "yeah". The program interprets this as "yes", producing a mistake message as warning.

It is much nicer to tell someone that he/she made a mistake, than to call that an error.

. error (user)

The user did something wrong, which is not automatically correctable or the program is not willing to correct it automatically for reasons of code quality. For instance, an unknown option flag is given on the command-line. These are configuration issues, and have no useful value in $!. The program will be stopped, usually before taken off.

. fault (system)

The program encountered a situation where it has no work-around. For instance, a file cannot be opened to be written. The cause of that problem can be some user error (i.e. wrong filename), or external (you accidentally removed a directory yesterday). In any case, the $! ($ERRNO) variable is set here.

. alert (system)

Some external cause disturbs the execution of the program, but the program stays alive and will try to continue operation. For instance, the connection to the database is lost. After a few attempts, the database can be reached and the program continues as if nothing happened. The cause is external, so $! is set. Usually, a system administrator needs to be informed about the problem.

. failure (system)

Some external cause makes it impossible for this program to continue. $! is set, and usually the system administrator wants to be informed. The program will die.

. panic (program)

All above report classes are expected: some predictable situation is encountered, and therefore a message is produced. However, programs often do some internal checking. Of course, these conditions should never be triggered, but if they do... then we can only stop.

For instance, in an OO perl module, the base class requires all sub-classes to implement a certain method. The base class will produce a stub method with triggers a panic when called. The non-dieing version of this test assert.

Debugging or being verbose are run-time behaviors, and have nothing directly to do with the type of message which is produced. These two are modes which can be set on the dispatchers: one dispatcher may be more verbose that some other.

On purpose, we do not use the terms die or fatal, because the dispatcher can be configured what to do in cause of which condition. For instance, it may decide to stop execution on warnings as well.

The terms carp and croak are avoided, because the program cause versus user cause distinction (warn vs carp) is reflected in the use of different reasons. There is no need for confess and croak either, because the dispatcher can be configured to produce stack-trace information (for a limited sub-set of dispatchers)

Report levels

Various frameworks used with perl programs define different labels to indicate the reason for the message to be produced.

Perl5 Log::Dispatch Syslog Log4Perl Log::Report
print   0,debug     debug  debug    trace
print   0,debug     debug  debug    assert
print   1,info      info   info     info
warn\n  2,notice    notice info     notice
warn    3,warning   warn   warn     mistake
carp    3,warning   warn   warn     warning
die\n   4,error     err    error    error
die     5,critical  crit   fatal    fault
croak   6,alert     alert  fatal    alert  
croak   7,emergency emerg  fatal    failure
confess 7,emergency emerg  fatal    panic

Run modes

The run-mode change which messages are passed to a dispatcher, but from a different angle than the dispatch filters; the mode changes behavioral aspects of the messages, which are described in detail in "Processing the message" in Log::Report::Dispatcher. However, it should behave as you expect: the DEBUG mode shows more than the VERBOSE mode, and both show more than the NORMAL mode.

example: extract run mode from Getopt::Long

The GetOptions() function will count the number of v options on the command-line when a + is after the option name.

use Log::Report syntax => 'SHORT';
use Getopt::Long qw(:config no_ignore_case bundling);

my $mode;    # defaults to NORMAL
GetOptions 'v+'        => \$mode
         , 'verbose=i' => \$mode
         , 'mode=s'    => \$mode
    or exit 1;

dispatcher 'PERL', 'default', mode => $mode;

Now, -vv will set $mode to 2, as will --verbose 2 and --verbose=2 and --mode=ASSERT. Of course, you do not need to provide all these options to the user: make a choice.

example: the mode of a dispatcher

my $mode = dispatcher(find => 'myname')->mode;

example: run-time change mode of a dispatcher

To change the running mode of the dispatcher, you can do dispatcher mode => DEBUG => 'myname';

However, be warned that this does not change the types of messages accepted by the dispatcher! So: probably you will not receive the trace, assert, and info messages after all. So, probably you need to replace the dispatcher with a new one with the same name: dispatcher FILE => 'myname', to => ..., mode => 'DEBUG';

This may reopen connections (depends on the actual dispatcher), which might be not what you wish to happened. In that case, you must take the following approach:

# at the start of your program
dispatcher FILE => 'myname', to => ...
   , accept => 'ALL';    # overrule the default 'NOTICE-' !!

# now it works
dispatcher mode => DEBUG => 'myname';    # debugging on
...
dispatcher mode => NORMAL => 'myname';   # debugging off

Of course, this comes with a small overall performance penalty.

Exceptions

The simple view on live says: you 're dead when you die. However, more complex situations try to revive the dead. Typically, the "die" is considered a terminating exception, but not terminating the whole program, but only some logical block. Of course, a wrapper round that block must decide what to do with these emerging problems.

Java-like languages do not "die" but throw exceptions which contain the information about what went wrong. Perl modules like Exception::Class simulate this. It's a hassle to create exception class objects for each emerging problem, and the same amount of work to walk through all the options.

Log::Report follows a simpler scheme. Fatal messages will "die", which is caught with "eval", just the Perl way (used invisible to you). However, the wrapper gets its hands on the message as the user has specified it: untranslated, with all unprocessed parameters still at hand.

try { fault __x "cannot open file {file}", file => $fn };
if($@)                         # is Log::Report::Dispatcher::Try
{   my $cause = $@->wasFatal;  # is Log::Report::Exception
    $cause->throw if $cause->message->msgid =~ m/ open /;
    # all other problems ignored
}

See Log::Report::Dispatcher::Try and Log::Report::Exception.

Comparison

die/warn/Carp

A typical perl5 program can look like this

my $dir = '/etc';

File::Spec->file_name is_absolute($dir)
    or die "ERROR: directory name must be absolute.\n";

-d $dir
    or die "ERROR: what platform are you on?";

until(opendir DIR, $dir)
{   warn "ERROR: cannot read system directory $dir: $!";
    sleep 60;
}

print "Processing directory $dir\n"
    if $verbose;

while(defined(my $file = readdir DIR))
{   if($file =~ m/\.bak$/)
    {   warn "WARNING: found backup file $dir/$f\n";
        next;
    }

    die "ERROR: file $dir/$file is binary"
        if $debug && -B "$dir/$file";

    print "DEBUG: processing file $dir/$file\n"
        if $debug;

    open FILE, "<", "$dir/$file"
        or die "ERROR: cannot read from $dir/$f: $!";

    close FILE
        or croak "ERROR: read errors in $dir/$file: $!";
}

Where die, warn, and print are used for various tasks. With Log::Report, you would write

use Log::Report syntax => 'SHORT';

# can be left-out when there is no debug/verbose
dispatcher PERL => 'default', mode => 'DEBUG';

my $dir = '/etc';

File::Spec->file_name is_absolute($dir)
    or mistake "directory name must be absolute";

-d $dir
    or panic "what platform are you on?";

until(opendir DIR, $dir)
{   alert "cannot read system directory $dir";
    sleep 60;
}

info "Processing directory $dir";

while(defined(my $file = readdir DIR))
{   if($file =~ m/\.bak$/)
    {   notice "found backup file $dir/$f";
        next;
    }

    assert "file $dir/$file is binary"
        if -B "$dir/$file";

    trace "processing file $dir/$file";

    unless(open FILE, "<", "$dir/$file")
    {   error "no permission to read from $dir/$f"
            if $!==ENOPERM;
        fault "unable to read from $dir/$f";
    }

    close FILE
        or failure "read errors in $dir/$file";
}

A lot of things are quite visibly different, and there are a few smaller changes. There is no need for a new-line after the text of the message. When applicable (error about system problem), then the $! is added automatically.

The distinction between error and fault is a bit artificial her, just to demonstrate the difference between the two. In this case, I want to express very explicitly that the user made an error by passing the name of a directory in which a file is not readable. In the common case, the user is not to blame and we can use fault.

A CPAN module like Log::Message is an object oriented version of the standard Perl functions, and as such not really contributing to abstraction.

Log::Dispatch and Log::Log4perl

The two major logging frameworks for Perl are Log::Dispatch and Log::Log4perl; both provide a pluggable logging interface.

Both frameworks do not have (gettext or maketext) language translation support, which has various consequences. When you wish for to report in some other language, it must be translated before the logging function is called. This may mean that an error message is produced in Chinese, and therefore also ends-up in the syslog file in Chinese. When this is not your language, you have a problem.

Log::Report translates only in the back-end, which means that the user may get the message in Chinese, but you get your report in your beloved Dutch. When no dispatcher needs to report the message, then no time is lost in translating.

With both logging frameworks, you use terminology comparable to syslog: the module programmer determines the seriousness of the error message, not the application which integrates multiple modules. This is the way perl programs usually work, but often the cause for inconsequent user interaction.

Locale::gettext and Locate::TextDomain

Both on GNU gettext based implementations can be used as translation frameworks. Locale::TextDomain syntax is supported, with quite some extensions. Read the excellent documentation of Locale::Textdomain. Only the tried access via $__ and %__ are not supported.

The main difference with these modules is the moment when the translation takes place. In Locale::TextDomain, an __x() will result in an immediate translation request via gettext(). Log::Report's version of __x() will only capture what needs to be translated in an object. When the object is used in a print statement, only then the translation will take place. This is needed to offer ways to send different translations of the message to different destinations.

To be able to postpone translation, objects are returned which stringify into the translated text.

DIAGNOSTICS

Error: in SCALAR context, only one dispatcher name accepted

The dispatcher() method returns the Log::Report::Dispatcher objects which it has accessed. When multiple names where given, it wishes to return a LIST of objects, not the count of them.

LICENSE

Copyrights 2007-2009 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

To install Log::Report, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Log::Report

CPAN shell

perl -MCPAN -e shell
install Log::Report

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)