Log::R...patcher(3pm)

📦
version 1.46 · 10 versions
, in ubuntu stonking

💖 Log::Report::Dispatcher 💖

okay bestie, welcome to the manual page for Log::R...patcher(3pm) — yeah the header truncates it, it's from the User Contributed Perl Documentation, and it's the whole manage message dispatching, display or logging situation. sit down, grab a strawberry 🍓, we're doing this.

✨ 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

it's giving mother class with seven iconic daughters 👑

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

no cap, that's the whole vibe right there ↑

💅 DESCRIPTION 💅

so in Log::Report, dispatchers are the ones handling (exception) messages that got created somewhere else. those messages were produced (thrown) by Log::Report::error() and its little friend group.

this base-class handles the creation of dispatchers, plus the common filtering rules. if you want the tea, the "DETAILS" section is down below. 🫖

👑 METHODS 👑

🎀 Constructors 🎀

  • $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 has to uniquely identify this dispatcher. real talk: when a second dispatcher gets created (via Log::Report::dispatcher()) with the name of an existing dispatcher, the existing one will get replaced. so like, choose your names.

all the %options that this base constructor doesn't consume get passed to the wrapped back-end. some of them will check whether all %options are understood, others just ignore unknown %options 🙈

the defaults, laid out for you:

 -Option       --Default
  accept         depend on mode
  charset        undef
  format_reason  'LOWERCASE'
  locale         <system locale>
  mode           'NORMAL'

and now one by one:

  • accept => $reasons|@reasons — default: depend on mode. peep Log::Report::Util::expand_reasons() for possible values. if the initial mode for this dispatcher doesn't need verbose or debug info, 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'll be "INFO- ", "ASSERT" results in "ASSERT- ", and "DEBUG" in "ALL". ✨

  • charset => CHARSET — default: undef. convert the messages into the specified character-set (codeset). by default, no conversion will take place, because the right choice cannot be determined automatically. it's giving we're not gonna guess for you 💀
  • format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE — default: 'LOWERCASE'. how to show the reason text that gets printed before the message. when a CODE is specified, it will be called with a translated text and the returned text is used. obsessed with the flexibility fr fr.
  • locale => LOCALE — default: <system locale>. overrules the global locale setting. can itself be overruled by Log::Report::report(locale). yes it's a whole hierarchy, it's giving nested situationships 😭
  • mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3 — default: 'NORMAL'. 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.

🌈 Attributes 🌈

  • $obj->isDisabled() — [no description given in the original, bestie, so we're just vibing with the name 🧚]
  • $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. iconic, unique, the name 💅
  • $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 (she remembers 👀).

[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 🎀

  • $any->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. yep, all of them, no takebacks 💀

» 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. that's the whole trick bestie ✨

  • $obj->close() — Terminate this dispatcher activities. the dispatcher gets disabled, to avoid the case it accidentally gets used (she's in her do not perceive me era 🫥). Returns "undef" ("false") if the dispatcher was already closed.
  • $any->collectLocation() — Collect the information to be displayed as line where the error occurred.
  • $any->collectStack( [$maxdepth] ) — Returns an ARRAY of ARRAYs with text, filename, line-number.
  • $obj->log(\%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. it's giving backstage crew, don't touch 🎭
  • $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. periodt.
  • $any->stackTraceLine(%options)

the defaults for that one:

 -Option    --Default
  abstract    1
  call        <required>
  filename    <required>
  linenr      <required>
  max_line    undef
  max_params  8
  package     <required>
  params      <required>

and the breakdown, one by one:

  • abstract => INTEGER — default: 1. 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. it's giving fade to less detail 🌫️
  • call => STRING — default: <required>
  • filename => STRING — default: <required>
  • linenr => INTEGER — default: <required>
  • max_line => INTEGER — default: undef
  • max_params => INTEGER — default: 8
  • package => CLASS — default: <required>
  • params => ARRAY — default: <required>
  • $obj->translate(\%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). multi-line? she's doing the most and we love her for it 💖

okay that's the first half of the tea ☕ part 2 is coming, don't go anywhere bestie 🫶

💖 DETAILS 💖

🌈 Available back-ends

okay so when a dispatcher gets created (via new() or Log::Report::dispatcher()), you gotta tell it the TYPE. That TYPE can either be a whole class name that extends a Log::Report::Dispatcher, or a pre-defined abbreviation of a class name. easy 💅

Implemented are:

  • Log::Report::Dispatcher::Perl (abbreviation 'PERL') — uses Perl's very own print(), warn() and die() to ventilate your reports. this one is the default dispatcher, bestie, it's the main character 🫶
  • Log::Report::Dispatcher::File (abbreviation 'FILE') — logs the message into a file. the file can either be opened by the class itself, or already open before the dispatcher is created. your choice ✨
  • Log::Report::Dispatcher::Syslog (abbreviation 'SYSLOG') — sends messages straight into the system's syslog infrastructure, using Sys::Syslog. it's giving very sysadmin-core 🖥️
  • Log::Report::Dispatcher::Callback (abbreviation 'CALLBACK') — calls any CODE reference the moment each selected message arrives. so like, if u need to send an important message as email or SMS… this is the one 📧
  • "Log::Dispatch::*" — literally all of the Log::Dispatch::Output extensions can be used directly. Log::Report::Dispatcher::LogDispatch will wrap around that back-end for u 🎀
  • "Log::Log4perl" — use the Log::Log4perl main object to write to dispatchers. heads up tho, this infrastructure uses a configuration file 📄
  • Log::Report::Dispatcher::Try (abbreviation 'TRY') — used by the function Log::Report::try(). it collects the exceptions and can produce them on request. so iconic of it 💜

🦋 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. no cap.

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. maybe u wanna change the REASON of a report, or its content? go off 💅

⚠️ bestie listen: 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. so don't even try, fr fr.

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);
  }

🚑 DIAGNOSTICS 🚑

  • Error: Perl does not support charset $cs — Cast by new() 💀
  • Alert: cannot use class $backend:\n$@: $! — Cast by new() 😭
  • Error: illegal format_reason '$format' for dispatcher — Cast by new() 🙈

👀 SEE ALSO 👀

This module is part of Log-Report version 1.46, built on June 16, 2026.

Website: http://perl.overmeer.net/CPAN/

📜 LICENSE 📜

For contributors see file ChangeLog.

This software is copyright (c) 2007-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's a wrap, bestie!! 🫶 this little beauty shipped as perl v5.40.1, with the page dated 2026-07-05 — go forth and dispatch responsibly, ily 💖🌸✨

📦 where this page comes from