SYNOPSIS

 use Log::Report;
 dispatcher 'FILE', 'log'
   , mode => 'DEBUG', to => '/var/log/mydir/myfile';

 # The follow will be created for you always (when STDERR leads
 # to a terminal).  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.

When the program sees a terminal on STDERR (the usual case for any non-daemon), it will create a dispatcher for you to show all messages with minimal level NOTICE to it. That dispatcher is named 'stderr', and when you create one with the same name yourself, it will replace the default one.

See the DETAILS section, below.

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 abbrevation of a class name. Implemented are:

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:

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 block
 REASON   SOURCE   TE!  NORM -v   -vv  -vvv TRY
 trace    program  ...                 S      
 assert   program  ...            SL   SL     
 info     program  T..       S    S    S 
 notice   program  T..  S    S    S    S    D
 mistake  user     T..  S    S    S    SL   D
 warning  program  T.!  SL   SL   SL   SL   DL
 error    user     TE.  S    S    SL   SC   B
 fault    system   TE!  S    S    SL   SC   B
 alert    system   T.!  S    S    SC   SC   S
 failure  system   TE!  S    S    SC   SC   S
 panic    program  .E.  SC   SC   SC   SC   SC

 -v = verbose, -vv = debug, -vvv = trace
 T - usually translated
 E - exception
 ! - will include $! text
 B - leave block with exception
 D - delayed; only shown when block completes without error
 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().

» Example: a filter on syslog
 dispatcher filter => \&myfilter, 'syslog';

 # ignore all translatable and non-translatable messages containing
 # the word "skip"
 sub myfilter($$$$)
 {   my ($disp, $opts, $reason, $message) = @_;
     return () if $message->untranslated =~ m/\bskip\b/;
     ($reason, $message);
 }
» Example: take all mistakes and warnings serious
 dispatch filter => \&take_warns_serious;
 sub take_warns_serious($$$$)
 {   my ($disp, $opts, $reason, $message) = @_;
       $reason eq 'MISTAKE' ? (ERROR   => $message)
     : $reason eq 'WARNING' ? (FAULT   => $message)
     :                        ($reason => $message);
 }