Provided by: liblog-report-perl_1.36-1_all bug

NAME

       Log::Report::Dispatcher - manage message dispatching, display or logging

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-';

DESCRIPTION

       In Log::Report, dispatchers are used to handle (exception) messages which are created
       somewhere else.  Those message were produced (thrown) by Log::Report::error() and friends.

       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( [$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)
       Log::Report::Dispatcher->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()
       Log::Report::Dispatcher->collectLocation()
           Collect the information to be displayed as line where the error occurred.

       $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, $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)
       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::Report::Dispatcher::Callback (abbreviation 'CALLBACK')
           Calls any CODE reference on receipt of each selected message, for instance to send
           important message as email or SMS.

       "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 function Log::Report::try().  It collects the exceptions and can produce them
           on request.

   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.!  SL   SL   SC   SC
        failure  system   TE!  SL   SL   SC   SC
        panic    program  .E.  SC   SC   SC   SC

        T - usually translated
        E - exception (execution interrupted)
        ! - will include $! text at display
        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_seriously;
        sub take_warns_seriously($$$$)
        {   my ($disp, $opts, $reason, $message) = @_;
              $reason eq 'MISTAKE' ? (ERROR   => $message)
            : $reason eq 'WARNING' ? (FAULT   => $message)
            :                        ($reason => $message);
        }

SEE ALSO

       This module is part of Log-Report distribution version 1.36, built on October 27, 2023.
       Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2007-2023 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/