.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Log::Report 3pm"
.TH Log::Report 3pm "2014-06-24" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Report \- report a problem, with exceptions and translation support
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Log::Report
\&   is a Exporter
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # Invocation with \*(Aqmode\*(Aq to get trace and verbose messages
\& use Log::Report mode => \*(AqDEBUG\*(Aq;
\&
\& # Usually invoked with a domain, which groups packages
\& use Log::Report \*(Aqmy\-domain\*(Aq, %options;
\&
\& # Interpolation syntax via String::Print
\& # First step to translations, once you need it.
\& print _\|_x"my name is {name}", name => $n;  # print, so no exception
\& print _\|_"Hello World\en";     # (optional) translation, no interpolation
\& print _\|_x\*(AqHello World\*(Aq;      # SYNTAX ERROR!!  \*(Aq is alternative for ::
\&
\& # Functions replacing die/warn/carp, casting exceptions.
\& error "oops";                # exception like die(), no translation
\& \-f $config or panic "Help!"; # alert/error/fault/info/...more
\&
\& # Combined exception, interpolation, and optional translation
\& error _\|_x"Help!";            # _\|_x() creates ::Message object
\& error _\|_x(\*(Aqgettext msgid\*(Aq, param => $value, ...)
\&     if $condition;
\&
\& # Also non fatal "exceptions" find their way to dispatchers
\& info _\|_x"started {pid}", pid => $$;   # translatable
\& debug "$i was here!";        # you probably do not want to translate debug
\& panic "arrghhh";             # like Carp::Confess
\&
\& # Many destinations for an exception message (may exist in parallel)
\& dispatcher PERL => \*(Aqdefault\*(Aq # see Log::Report::Dispatcher: use die/warn
\&   , reasons => \*(AqNOTICE\-\*(Aq;    # this dispatcher is already present at start
\&
\& dispatcher SYSLOG => \*(Aqsyslog\*(Aq# also send to syslog
\&   , charset => \*(Aqiso\-8859\-1\*(Aq  # explicit character conversions
\&   , locale => \*(Aqen_US\*(Aq;       # overrule user\*(Aqs locale
\&
\& dispatcher close => \*(Aqdefault\*(Aq;  # stop default die/warn dispatcher
\&
\& # 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, ok
\& fault _\|_x"cannot allocate $size bytes";  # not translatable, wrong
\&
\& # Translation depending on count
\& # Leading and trailing whitespace stay magically outside translation
\& # tables.  @files in scalar context.  Special parameter with _
\& print _\|_xn"found one file\en", "found {_count} files", @files;
\&
\& # Borrow from an other text\-domain (see Log::Report::Message)
\& print _\|_x(+"errors in {line}", _domain => \*(Aqglobal\*(Aq, line => $line);
\&
\& # catch errors (implements hidden eval/die)
\& try { error };
\& if($@) {...}      # $@ isa Log::Report::Dispatcher::Try
\& if(my $exception = $@\->wasFatal)         # ::Exception object
\&
\& # Language translations at the output component
\& # Translation management via Log::Report::Lexicon
\& use POSIX::1003::Locale qw/setlocale LC_ALL/;
\& setlocale(LC_ALL, \*(Aqnl_NL\*(Aq);
\& info _\|_"Hello World!";      # in Dutch, if translation table found
\&
\& # Exception classes, see Log::Report::Exception
\& try { error _\|_x"something", _class => \*(Aqparsing,schema\*(Aq };
\& if($@\->wasFatal\->inClass(\*(Aqparsing\*(Aq)) ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Handling messages directed to users can be a hassle, certainly when the
same software is used for command-line and in a graphical interfaces
(you may not now how it is used, writing an abstract module), or has to
cope with internationalization; this modules tries to simplify this.
.PP
\&\f(CW\*(C`Log::Report\*(C'\fR combines
.IP ". exceptions (like error and info), with" 4
.IX Item ". exceptions (like error and info), with"
.PD 0
.IP ". logging (like Log::Log4Perl and syslog), and" 4
.IX Item ". logging (like Log::Log4Perl and syslog), and"
.ie n .IP ". translations (like ""gettext"" and Locale::TextDomain)" 4
.el .IP ". translations (like \f(CWgettext\fR and Locale::TextDomain)" 4
.IX Item ". translations (like gettext and Locale::TextDomain)"
.PD
.PP
You \fBdo not need\fR to use this module for all three reasons: pick what
you need now, maybe extend the usage later.  Read more about how and
why in the \*(L"\s-1DETAILS\*(R"\s0 section, below.  Especially, you should \fBread
about the \s-1REASON\s0 parameter\fR.
.PP
Also, you can study this module swiftly via the article published in
the German Perl \f(CW\*(C`$foo\-magazine\*(C'\fR.  English version:
\&\fIhttp://perl.overmeer.net/log\-report/papers/201306\-PerlMagazine\-article\-en.html\fR
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "Report Production and Configuration"
.IX Subsection "Report Production and Configuration"
.ie n .IP "\fBdispatcher\fR( <$type, $name, %options>|<$command, @names> )" 4
.el .IP "\fBdispatcher\fR( <$type, \f(CW$name\fR, \f(CW%options\fR>|<$command, \f(CW@names\fR> )" 4
.IX Item "dispatcher( <$type, $name, %options>|<$command, @names> )"
The \f(CW\*(C`dispatcher\*(C'\fR function controls access to dispatchers: the back-ends
which process messages, do the logging.  Dispatchers are global entities,
addressed by a symbolic \f(CW$name\fR.  Please read Log::Report::Dispatcher as
well.
.Sp
The \f(CW\*(C`Log::Report\*(C'\fR suite has its own dispatcher \s-1TYPES,\s0 but also connects
to external dispatching frameworks.  Each need some (minor) conversions,
especially with respect to translation of \s-1REASONS\s0 of the reports
into log-levels as the back-end understands.
.Sp
The \f(CW%options\fR 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.
.Sp
Implemented COMMANDs are \f(CW\*(C`close\*(C'\fR, \f(CW\*(C`find\*(C'\fR, \f(CW\*(C`list\*(C'\fR, \f(CW\*(C`disable\*(C'\fR,
\&\f(CW\*(C`enable\*(C'\fR, \f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`filter\*(C'\fR, and \f(CW\*(C`needs\*(C'\fR.  Most commands are followed
by a \s-1LIST\s0 of dispatcher \f(CW@names\fR to be addressed.  For \f(CW\*(C`mode\*(C'\fR see section
\&\*(L"Run modes\*(R"; it requires a \s-1MODE\s0 argument before the \s-1LIST\s0 of NAMEs.
Non-existing names will be ignored. When \f(CW\*(C`ALL\*(C'\fR is specified, then
all existing dispatchers will get addressed.  For \f(CW\*(C`filter\*(C'\fR see
\&\*(L"Filters\*(R" in Log::Report::Dispatcher; it requires a \s-1CODE\s0 reference before
the \f(CW@names\fR of the dispatchers which will have the it applied (defaults to
all).
.Sp
With \f(CW\*(C`needs\*(C'\fR, you only provide a \s-1REASON:\s0 it will return the list of
dispatchers which need to be called in case of a message with the \s-1REASON\s0
is triggered.
.Sp
For both the creation as COMMANDs version of this method, all objects
involved are returned as \s-1LIST,\s0 non-existing ones skipped.  In \s-1SCALAR\s0
context with only one name, the one object is returned.
.Sp
example: play with dispatchers
.Sp
.Vb 4
\& dispatcher Log::Dispatcher::File => mylog =>
\&   , accept   => \*(AqMISTAKE\-\*(Aq              # for wrapper
\&   , locale   => \*(Aqpt_BR\*(Aq                 # other language
\&   , filename => \*(Aqlogfile\*(Aq;              # for back\-end
\&
\& dispatcher close => \*(Aqmylog\*(Aq;            # cleanup
\& my $obj = dispatcher find => \*(Aqmylog\*(Aq; 
\& my @obj = dispatcher \*(Aqlist\*(Aq;
\& dispatcher disable => \*(Aqsyslog\*(Aq;
\& dispatcher enable => \*(Aqmylog\*(Aq, \*(Aqsyslog\*(Aq; # more at a time
\& dispatcher mode => \*(AqDEBUG\*(Aq, \*(Aqmylog\*(Aq;
\& dispatcher mode => \*(AqDEBUG\*(Aq, \*(AqALL\*(Aq;
\&
\& my @need_info = dispatcher needs => \*(AqINFO\*(Aq;
\& if(dispatcher needs => \*(AqINFO\*(Aq) ...      # anyone needs INFO
\&
\& # Getopt::Long integration: see Log::Report::Dispatcher::mode()
\& dispatcher PERL => \*(Aqdefault\*(Aq, mode => \*(AqDEBUG\*(Aq, accept => \*(AqALL\*(Aq
\&     if $debug;
.Ve
.ie n .IP "\fBreport\fR( [%options], $reason, $message|<\s-1STRING\s0,$params>, )" 4
.el .IP "\fBreport\fR( [%options], \f(CW$reason\fR, \f(CW$message\fR|<\s-1STRING\s0,$params>, )" 4
.IX Item "report( [%options], $reason, $message|<STRING,$params>, )"
The \f(CW\*(C`report\*(C'\fR function is sending (for some \f(CW$reason\fR) a \f(CW$message\fR to be
displayed or logged (by a `dispatcher').  This function is the core
for \fIerror()\fR, \fIinfo()\fR etc functions, which are nicer names for this
exception throwing: better use those short names.
.Sp
The \f(CW$reason\fR is a string like '\s-1ERROR\s0' (for function \f(CW\*(C`error()\*(C'\fR).
The \f(CW$message\fR is a Log::Report::Message object (which are created with
the special translation syntax like _\|\fI_x()\fR).  The \f(CW$message\fR may also
be a plain string, or an Log::Report::Exception object. The optional
first parameter is a \s-1HASH\s0 which can be used to influence the dispatchers.
.Sp
The optional \f(CW%options\fR are listed below.  Quite differently from other
functions and methods, they have to be passed in a \s-1HASH\s0 as first parameter.
.Sp
This function returns the \s-1LIST\s0 of dispatchers which accepted the \f(CW$message\fR.
When empty, no back-end has accepted it so the \f(CW$message\fR was \*(L"lost\*(R".
Even when no back-end needs the message, the program will still exit
when there is a \f(CW$reason\fR to \f(CW\*(C`die()\*(C'\fR.
.Sp
.Vb 7
\& \-Option  \-\-Default
\&  errno     $! or 1
\&  is_fatal  <depends on reason>
\&  locale    undef
\&  location  undef
\&  stack     undef
\&  to        undef
.Ve
.RS 4
.IP "errno => \s-1INTEGER\s0" 2
.IX Item "errno => INTEGER"
When the \f(CW$reason\fR includes the error text (See \*(L"Run modes\*(R"), you can
overrule the error code kept in \f(CW$!\fR.  In other cases, the return code
defaults to \f(CW1\fR (historical \s-1UNIX\s0 behavior). When the message \f(CW$reason\fR
(combined with the run-mode) is severe enough to stop the program,
this value as return code of the program.  The use of this option itself
will not trigger an \f(CW\*(C`die()\*(C'\fR.
.IP "is_fatal => \s-1BOOLEAN\s0" 2
.IX Item "is_fatal => BOOLEAN"
Some logged exceptions are fatal, other aren't.  The default usually
is correct. However, you may want an error to be caught (usually with
\&\fItry()\fR), redispatch it to syslog, but without it killing the main
program.
.IP "locale => \s-1LOCALE\s0" 2
.IX Item "locale => LOCALE"
Use this specific locale, in stead of the user's preference.
.IP "location => \s-1STRING\s0" 2
.IX Item "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.
.IP "stack => \s-1ARRAY\s0" 2
.IX Item "stack => ARRAY"
When defined, that data is used to display the call stack.  Otherwise,
it is collected via \f(CW\*(C`caller()\*(C'\fR if needed.
.IP "to => NAME|ARRAY\-of\-NAMEs" 2
.IX Item "to => NAME|ARRAY-of-NAMEs"
Sent the \f(CW$message\fR only to the NAMEd dispatchers.  Ignore unknown NAMEs.
Still, the dispatcher needs to be enabled and accept the REASONs.
.RE
.RS 4
.Sp
example: for use of \fIreport()\fR
.Sp
.Vb 3
\& # long syntax example
\& report TRACE => "start processing now";
\& report INFO  => \*(Aq500: \*(Aq . _\|_\*(AqInternal Server Error\*(Aq;
\&
\& # explicit dispatcher, no translation
\& report {to => \*(Aqsyslog\*(Aq}, NOTICE => "started process $$";
\& notice "started process $$", _to => \*(Aqsyslog\*(Aq;   # same
\&
\& # short syntax examples
\& trace "start processing now";
\& warning  _\|_x\*(AqDisk {percent%.2f}% full\*(Aq, percent => $p
\&     if $p > 97;
\&
\& # error message, overruled to be printed in Brazilian
\& report {locale => \*(Aqpt_BR\*(Aq}
\&    , WARNING => "do this at home!";
.Ve
.RE
.ie n .IP "\fBtry\fR(\s-1CODE,\s0 %options)" 4
.el .IP "\fBtry\fR(\s-1CODE,\s0 \f(CW%options\fR)" 4
.IX Item "try(CODE, %options)"
Execute the \s-1CODE\s0 while blocking all dispatchers as long as it is running.
The exceptions which occur while running the \s-1CODE\s0 are caught until it
has finished.  When there where no fatal errors, the result of the \s-1CODE\s0
execution is returned.
.Sp
After the \s-1CODE\s0 was tried, the \f(CW$@\fR will contain a
Log::Report::Dispatcher::Try object, which contains the collected
messages.
.Sp
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.
.Sp
The \f(CW%options\fR are passed to the constructor of the try-dispatcher, see
\&\fILog::Report::Dispatcher::Try::new()\fR.  For instance, you may like to
add \f(CW\*(C`mode => \*(AqDEBUG\*(Aq\*(C'\fR, or \f(CW\*(C`accept => \*(AqERROR\-\*(Aq\*(C'\fR.
.Sp
\&\fBBe warned\fR that the parameter to \f(CW\*(C`try\*(C'\fR is a \s-1CODE\s0 reference.  This means
that you shall not use a comma after the block when there are \f(CW%options\fR
specified.  On the other hand, you shall use a semi-colon after the
block if there are no arguments.
.Sp
\&\fBBe warned\fR that the {} are interpreted as subroutine, which means that,
for instance, it has its own \f(CW@_\fR.  The manual-page of Try::Tiny
lists a few more side-effects of this.
.Sp
example:
.Sp
.Vb 2
\& my $x = try { 3/$x };  # mind the \*(Aq;\*(Aq !!
\& if($@) {               # signals something went wrong
\&
\& if(try {...}) {        # block ended normally, returns bool
\&
\& try { ... }            # no comma!!
\&    mode => \*(AqDEBUG\*(Aq, accept => \*(AqERROR\-\*(Aq;
\&
\& try sub { ... },       # with comma, also \e&function
\&    mode => \*(AqDEBUG\*(Aq, accept => \*(AqALL\*(Aq;
\&
\& my $response = try { $ua\->request($request) };
\& if(my $e = $@\->wasFatal) ...
.Ve
.SS "Abbreviations for \fIreport()\fP"
.IX Subsection "Abbreviations for report()"
The following functions are all wrappers for calls to \fIreport()\fR,
and available when \*(L"syntax is \s-1SHORT\*(R" \s0(by default, see \fIimport()\fR).
You cannot specify additional options to influence the behavior of
\&\f(CW\*(C`report()\*(C'\fR, which are usually not needed anyway.
.IP "\fBalert\fR($message)" 4
.IX Item "alert($message)"
Short for \f(CW\*(C`report ALERT => $message\*(C'\fR
.IP "\fBassert\fR($message)" 4
.IX Item "assert($message)"
Short for \f(CW\*(C`report ASSERT => $message\*(C'\fR
.IP "\fBerror\fR($message)" 4
.IX Item "error($message)"
Short for \f(CW\*(C`report ERROR => $message\*(C'\fR
.IP "\fBfailure\fR($message)" 4
.IX Item "failure($message)"
Short for \f(CW\*(C`report FAILURE => $message\*(C'\fR
.IP "\fBfault\fR($message)" 4
.IX Item "fault($message)"
Short for \f(CW\*(C`report FAULT => $message\*(C'\fR
.IP "\fBinfo\fR($message)" 4
.IX Item "info($message)"
Short for \f(CW\*(C`report INFO => $message\*(C'\fR
.IP "\fBmistake\fR($message)" 4
.IX Item "mistake($message)"
Short for \f(CW\*(C`report MISTAKE => $message\*(C'\fR
.IP "\fBnotice\fR($message)" 4
.IX Item "notice($message)"
Short for \f(CW\*(C`report NOTICE => $message\*(C'\fR
.IP "\fBpanic\fR($message)" 4
.IX Item "panic($message)"
Short for \f(CW\*(C`report PANIC => $message\*(C'\fR
.IP "\fBtrace\fR($message)" 4
.IX Item "trace($message)"
Short for \f(CW\*(C`report TRACE => $message\*(C'\fR
.IP "\fBwarning\fR($message)" 4
.IX Item "warning($message)"
Short for \f(CW\*(C`report WARNING => $message\*(C'\fR
.SS "Language Translations"
.IX Subsection "Language Translations"
The language translations are initiate by limited set of functions
which contain \fBtwo under-scores\fR (\f(CW\*(C`_\|_\*(C'\fR) in their name.  Most
of them return a Log::Report::Message object.
.PP
\&\fBBe \f(BIwarned\fB\|(1)\fR 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 person
which translates only sees smaller parts of the text, his (or her) job
becomes more complex.  So:
.PP
.Vb 2
\& print _\|_"Hello" . \*(Aq, \*(Aq . _\|_"World!";  # works, but to be avoided
\& print _\|_"Hello, World!";              # preferred, complete sentence
.Ve
.PP
The the former case, tricks with overloading used by the
Log::Report::Message objects will still make delayed translations
work.
.PP
In normal situations, it is not a problem to translate interpolated
values:
.PP
.Vb 1
\& print _\|_"the color is {c}", c => _\|_"red";
.Ve
.PP
\&\fBBe \f(BIwarned\fB\|(2)\fR that using \f(CW\*(C`_\|_\*(AqHello\*(Aq\*(C'\fR will produce a syntax error like
\&\*(L"String found where operator expected at .... Can't find string terminator
\&\*(R"'\*(L" anywhere before \s-1EOF\*(R". \s0 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 \f(CW\*(C`_\|_\*(AqHello\*(Aq\*(C'\fR gets interpreted
as \f(CW\*(C`_\|_::Hello \*(Aq\*(C'\fR.  Then, there is a trailing single quote which has
no counterpart.
.IP "\fBN_\|_\fR($msgid)" 4
.IX Item "N__($msgid)"
Label to indicate that the string is a text which will be translated
later.  The function itself does nothing.  See also N_\|\fI_w()\fR.
.Sp
This no-op function is used as label to the xgettext program to build the
translation tables.
.Sp
example: how to use N_\|_()
.Sp
.Vb 4
\& # add three msgids to the translation table
\& my @colors = (N_\|_"red", N_\|_"green", N_\|_"blue");
\& my @colors = N_\|_w "red green blue";   # same
\& print _\|_ $colors[1];                  # translate green
\&
\& # 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.
.Ve
.ie n .IP "\fBN_\|_n\fR($single_msgid, $plural_msgid)" 4
.el .IP "\fBN_\|_n\fR($single_msgid, \f(CW$plural_msgid\fR)" 4
.IX Item "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.
.Sp
example: how to use N_\|\fI_n()\fR
.Sp
.Vb 3
\& 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], @files, %vars;
.Ve
.IP "\fBN_\|_w\fR(\s-1STRING\s0)" 4
.IX Item "N__w(STRING)"
This extension to the Locale::TextDomain syntax, is a combined
\&\f(CW\*(C`qw\*(C'\fR (list of quoted words) and N_\|_() into a list of translatable
words.
.Sp
example: of N_\|\fI_w()\fR
.Sp
.Vb 3
\&  my @colors = (N_\|_"red", N_\|_"green", N_\|_"blue");
\&  my @colors = N_\|_w"red green blue";  # same
\&  print _\|_ $colors[1];
.Ve
.IP "\fB_\|_\fR($msgid)" 4
.IX Item "__($msgid)"
This function (name is \fBtwo\fR under-score characters) will cause the \f(CW$msgid\fR
to be replaced by the translations when doing the actual output.  Returned
is a Log::Report::Message object, which will be used in translation
later.  Translating is invoked when the object gets stringified.  When
you have no translation tables, the \f(CW$msgid\fR will be shown untranslated.
.Sp
If you need options for \fILog::Report::Message::new()\fR then use _\|\fI_x()\fR;
the prototype of this function does not permit parameters: it is a
prefix operator!
.Sp
example: how to use _\|_()
.Sp
.Vb 4
\& print _\|_"Hello World";      # translated into user\*(Aqs language
\& print _\|_\*(AqHello World\*(Aq;      # syntax error!
\& print _\|_(\*(AqHello World\*(Aq);    # 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(\*(Aqfr\*(Aq);   # ok, forced into French
.Ve
.ie n .IP "\fB_\|_n\fR($msgid, $plural_msgid, $count, \s-1PAIRS\s0)" 4
.el .IP "\fB_\|_n\fR($msgid, \f(CW$plural_msgid\fR, \f(CW$count\fR, \s-1PAIRS\s0)" 4
.IX Item "__n($msgid, $plural_msgid, $count, PAIRS)"
It depends on the value of \f(CW$count\fR (and the selected language) which
text will be displayed.  When translations can not be performed, then
\&\f(CW$msgid\fR will be used when \f(CW$count\fR is 1, and \s-1PLURAL_MSGSID\s0 in other cases.
However, some languages have more complex schemes than English.
.Sp
The \s-1PAIRS\s0 are options for \fILog::Report::Message::new()\fR and variables
to be filled in.
.Sp
example: how to use _\|\fI_n()\fR
.Sp
.Vb 3
\& print _\|_n "one", "more", $a;
\& print _\|_n("one", "more", $a), "\en";
\& print +(_\|_n "one", "more", $a), "\en";
\&
\& # new\-lines are ignore at lookup, but printed.
\& print _\|_n "one\en", "more\en", $a;
\&
\& # count is in scalar context
\& # the value is also available as _count
\& print _\|_n "found one\en", "found {_count}\en", @r;
\&
\& # ARRAYs and HASHes are counted
\& print _\|_n "one", "more", \e@r;
.Ve
.ie n .IP "\fB_\|_nx\fR($msgid, $plural_msgid, $count, \s-1PAIRS\s0)" 4
.el .IP "\fB_\|_nx\fR($msgid, \f(CW$plural_msgid\fR, \f(CW$count\fR, \s-1PAIRS\s0)" 4
.IX Item "__nx($msgid, $plural_msgid, $count, PAIRS)"
It depends on the value of \f(CW$count\fR (and the selected language) which
text will be displayed.  See details in _\|\fI_n()\fR.  After translation,
the \s-1VARIABLES\s0 will be filled-in.
.Sp
The \s-1PAIRS\s0 are options for \fILog::Report::Message::new()\fR and variables
to be filled in.
.Sp
example: how to use _\|\fI_nx()\fR
.Sp
.Vb 2
\& print _\|_nx "one file", "{_count} files", $nr_files;
\& print _\|_nx "one file", "{_count} files", @files;
\&
\& local $" = \*(Aq, \*(Aq;
\& print _\|_nx "one file: {f}", "{_count} files: {f}", @files, f => \e@files;
.Ve
.IP "\fB_\|_x\fR($msgid, \s-1PAIRS\s0)" 4
.IX Item "__x($msgid, PAIRS)"
Translate the \f(CW$msgid\fR and then interpolate the \s-1VARIABLES\s0 in that string.
Of course, translation and interpolation is delayed as long as possible.
Both \s-1OPTIONS\s0 and \s-1VARIABLES\s0 are key-value pairs.
.Sp
The \s-1PAIRS\s0 are options for \fILog::Report::Message::new()\fR and variables
to be filled in.
.ie n .IP "\fB_\|_xn\fR($single_msgid, $plural_msgid, $count, $paurs)" 4
.el .IP "\fB_\|_xn\fR($single_msgid, \f(CW$plural_msgid\fR, \f(CW$count\fR, \f(CW$paurs\fR)" 4
.IX Item "__xn($single_msgid, $plural_msgid, $count, $paurs)"
Same as _\|\fI_nx()\fR, because we have no preferred order for 'x' and 'n'.
.SS "Configuration"
.IX Subsection "Configuration"
.ie n .IP "$obj\->\fBimport\fR( [$level,][$domain,] %options )" 4
.el .IP "\f(CW$obj\fR\->\fBimport\fR( [$level,][$domain,] \f(CW%options\fR )" 4
.IX Item "$obj->import( [$level,][$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 \f(CW$domain\fR.
.Sp
For one package, the import list may additionally contain textdomain
configuration \f(CW%options\fR.  These \f(CW%options\fR are used for all packages which
use the same \f(CW$domain\fR.  These are alternatives:
.Sp
.Vb 1
\&  use Log::Report \*(Aqmy\-domain\*(Aq, %config, %domain_config;
\&
\&  use Log::Report \*(Aqmy\-domain\*(Aq, %config;
\&  textdomain \*(Aqmy\-domain\*(Aq, %domain_config;
.Ve
.Sp
The latter syntax has major advantages, when the configuration of the
domain is determined at run-time.  It is probably also easier to understand.
.Sp
See \fILog::Report::Domain::configure()\fR, for the \fBlist of \f(CB%options\fB\fR
for the domain configuration.  Here, we only list the options which are
related to the normal import behavior.
.Sp
The export \f(CW$level\fR is a plus (+) followed by a number, for instance \f(CW+1\fR,
to indicate to on which caller level we need to work.  This is used
in Log::Report::Optional.  It defaults to '0': my direct caller.
.Sp
.Vb 4
\& \-Option\-\-Default
\&  import  undef
\&  mode    \*(AqNORMAL\*(Aq
\&  syntax  \*(AqSHORT\*(Aq
.Ve
.RS 4
.IP "import => FUNCTION|ARRAY" 2
.IX Item "import => FUNCTION|ARRAY"
[0.998] When not specified, the \f(CW\*(C`syntax\*(C'\fR option determines the list
of functions which are being exported.  With this option, the \f(CW\*(C`syntax\*(C'\fR
option is ignored and only the specified \s-1FUNCTION\s0(s) are imported.
.IP "mode => \s-1LEVEL\s0" 2
.IX Item "mode => LEVEL"
This sets the default mode for all created dispatchers.  You can
also selectively change the output mode, like
 dispatcher \s-1PERL\s0 => 'default', mode => 3
.IP "syntax => '\s-1REPORT\s0'|'\s-1SHORT\s0'|'\s-1LONG\s0'" 2
.IX Item "syntax => 'REPORT'|'SHORT'|'LONG'"
The \s-1SHORT\s0 syntax will add the report abbreviations (like function
\&\fIerror()\fR) to your name-space.  Otherwise, each message must be produced
with \fIreport()\fR. \f(CW\*(C`LONG\*(C'\fR is an alternative to \f(CW\*(C`REPORT\*(C'\fR: both do not
polute your namespace with the useful abbrev functions.
.RE
.RS 4
.Sp
example: of import
.Sp
.Vb 1
\& use Log::Report mode => 3;     # \*(Aq3\*(Aq or \*(AqDEBUG\*(Aq
\&
\& use Log::Report \*(Aqmy\-domain\*(Aq;   # in each package producing messages
\&
\& use Log::Report \*(Aqmy\-domain\*(Aq    # in one package, top of distr
\&  , mode            => \*(AqVERBOSE\*(Aq
\&  , syntax          => \*(AqREPORT\*(Aq # report ERROR, not error()
\&  , translator      => Log::Report::Translator::POT\->new
\&     ( lexicon => \*(Aq/home/mine/locale\*(Aq  # bindtextdomain
\&     , charset => \*(AqUTF\-8\*(Aq              # codeset
\&     )
\&  , native_language => \*(Aqnl_NL\*(Aq; # untranslated msgs are Dutch
\&
\& use Log::Report import => \*(Aqtry\*(Aq;      # or ARRAY of functions
.Ve
.RE
.ie n .IP "\fBtextdomain\fR( <[$domain], $config> | <$domain, '\s-1DELETE\s0'> )" 4
.el .IP "\fBtextdomain\fR( <[$domain], \f(CW$config\fR> | <$domain, '\s-1DELETE\s0'> )" 4
.IX Item "textdomain( <[$domain], $config> | <$domain, 'DELETE'> )"
[1.00] Without CONFIGuration, this returns the Log::Report::Domain object
which administers the \f(CW$domain\fR, by default the domain effictive in the scope
of the package.
.Sp
A very special case is for \*(L"\s-1DELETE\*(R",\s0 which will remove the domain
configuration.
.SS "Reasons"
.IX Subsection "Reasons"
.ie n .IP "Log::Report\->\fBneeds\fR( $reason, [$reasons] )" 4
.el .IP "Log::Report\->\fBneeds\fR( \f(CW$reason\fR, [$reasons] )" 4
.IX Item "Log::Report->needs( $reason, [$reasons] )"
Returns true when the reporter needs any of the \f(CW$reasons\fR, 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.
.Sp
example:
.Sp
.Vb 4
\&  if(Log::Report\->needs(\*(AqTRACE\*(Aq))
\&  {   my @args = ...expensive calculation...;
\&      trace "your options are: @args";
\&  }
.Ve
.SH "DETAILS"
.IX Header "DETAILS"
.SS "Introduction"
.IX Subsection "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 in Perl are produced by commands like \f(CW\*(C`print\*(C'\fR,
\&\f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`carp\*(C'\fR, or \f(CW\*(C`croak\*(C'\fR, which have no way of configuring
the way they deliver text to the user.  Therefore, they are replaced
with a single new command: \f(CW\*(C`report\*(C'\fR with many abbreviations.
.PP
Besides, the \f(CW\*(C`print\*(C'\fR/\f(CW\*(C`warn\*(C'\fR/\f(CW\*(C`die\*(C'\fR together produce only three different
output levels with a message.  Many people manually implement their
own additional levels, like verbose and debug.  Syslog has some extra
levels as well, like \f(CW\*(C`critical\*(C'\fR.  The \f(CW$reason\fR argument to \f(CW\*(C`report()\*(C'\fR
offers them all.
.PP
The (optional) 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: until a dispatcher actually writes this message into a file or sends
it to syslog.  This means that the pop-up in the graphical interface of
the user may show the text in the language of the user \-\-say Chinese in
utf8\-\-, but at the same time syslog may write the latin1 English version
of the same message.
.SS "Background ideas"
.IX Subsection "Background ideas"
The following ideas are the base of this implementation:
.IP ". simplification" 4
.IX Item ". 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.
.IP ". multiple dispatchers" 4
.IX Item ". multiple dispatchers"
It is not the location where the (for instance) error occurs which
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' classification, they can get ignored, send to one
or multiple dispatchers, like Log::Dispatch, Log::Log4perl,
or \s-1UNIX\s0 syslog.
.IP ". delayed translations" 4
.IX Item ". delayed translations"
The background ideas are that of Locale::TextDomain, based
on \f(CW\*(C`gettext()\*(C'\fR.  However, in the \f(CW\*(C`Log::Report\*(C'\fR infrastructure,
translations are postponed until the text is dispatched to a screen
or log-file; the same report can be sent to syslog in (for instance)
English and to the user interface in Dutch.
.SS "Error handling models"
.IX Subsection "Error handling models"
There are two approaches to handling errors and warnings.  In the first
approach, as produced by \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR and the \f(CW\*(C`carp\*(C'\fR family of
commands, the program handles the problem immediately on the location
where the problem appears.  In the second approach, an \fIexception\fR
is thrown on the spot where the problem is created, and then somewhere
else in the program the condition is handled.
.PP
The implementation of exceptions in Perl5 is done with a eval-die pair:
on the spot where the problem occurs, \f(CW\*(C`die\*(C'\fR is called.  But, because of
the execution of that routine is placed within an \f(CW\*(C`eval\*(C'\fR, 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.
.PP
The \f(CW\*(C`Log::Report\*(C'\fR 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.
.PP
\fIThe Reason for the report\fR
.IX Subsection "The Reason for the report"
.PP
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 \f(CW\*(C`Log::Report\*(C'\fR, the produced
reports in the code tell \fIwhat\fR is wrong.  The main application defines
loggers, which interpret the cause into (syslog) levels.
.PP
Defined by \f(CW\*(C`Log::Report\*(C'\fR are
.IP ". trace (debug, program)" 4
.IX Item ". 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.
.IP ". assert (program)" 4
.IX Item ". assert (program)"
Shows an unexpected condition, but continues to run.  When you want the
program to abort in such situation, that use \f(CW\*(C`panic\*(C'\fR.
.IP ". info (verbose, program)" 4
.IX Item ". 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 \f(CW\*(C`verbose\*(C'\fR flag is given on the command-line.
.IP ". notice (program)" 4
.IX Item ". notice (program)"
An user may need to be aware of the program's accidental smart behavior,
for instance, that it initializes a lasting \f(CW\*(C`Desktop\*(C'\fR directory in your
home directory.  Notices should be sparse.
.IP ". warning (program)" 4
.IX Item ". 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.
.IP ". mistake (user)" 4
.IX Item ". 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 \*(L"yes\*(R" or \*(L"no\*(R", but the user wrote \*(L"yeah\*(R".  The program
interprets this as \*(L"yes\*(R", producing a mistake message as warning.
.Sp
It is much nicer to tell someone that he/she made a mistake, than
to call that an error.
.IP ". error (user)" 4
.IX Item ". 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 \f(CW$!\fR.  The program will be stopped, usually before taken off.
.IP ". fault (system)" 4
.IX Item ". 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
\&\f(CW$!\fR (\f(CW$ERRNO\fR) variable is set here.
.IP ". alert (system)" 4
.IX Item ". 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 \f(CW$!\fR is set.  Usually, a system administrator
needs to be informed about the problem.
.IP ". failure (system)" 4
.IX Item ". failure (system)"
Some external cause makes it impossible for this program to continue.
\&\f(CW$!\fR is set, and usually the system administrator wants to be
informed.  The program will die.
.Sp
The difference with \f(CW\*(C`fault\*(C'\fR is subtile and not always clear.  A fault
reports an error returned by an operating system call, where the failure
would report an operational problem, like a failing mount.
.IP ". panic (program)" 4
.IX Item ". 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.
.Sp
For instance, in an \s-1OO\s0 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 \f(CW\*(C`assert\*(C'\fR.
.PP
\&\fIDebugging\fR or being \f(CW\*(C`verbose\*(C'\fR are run-time behaviors, and have nothing
directly to do with the type of message which is produced.  These two
are \fBmodes\fR which can be set on the dispatchers: one dispatcher may
be more verbose that some other.
.PP
On purpose, we do not use the terms \f(CW\*(C`die\*(C'\fR or \f(CW\*(C`fatal\*(C'\fR, 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.
.PP
The terms \f(CW\*(C`carp\*(C'\fR and \f(CW\*(C`croak\*(C'\fR 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 \f(CW\*(C`confess\*(C'\fR and \f(CW\*(C`croak\*(C'\fR
either, because the dispatcher can be configured to produce stack-trace
information (for a limited sub-set of dispatchers)
.PP
\fIReport levels\fR
.IX Subsection "Report levels"
.PP
Various frameworks used with perl programs define different labels
to indicate the reason for the message to be produced.
.PP
.Vb 12
\& 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\en  2,notice    notice info     notice
\& warn    3,warning   warn   warn     mistake
\& carp    3,warning   warn   warn     warning
\& die\en   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
.Ve
.PP
\fIRun modes\fR
.IX Subsection "Run modes"
.PP
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
\&\*(L"Processing the message\*(R" in Log::Report::Dispatcher.  However, it should
behave as you expect: the \s-1DEBUG\s0 mode shows more than the \s-1VERBOSE\s0 mode,
and both show more than the \s-1NORMAL\s0 mode.
.PP
\fIExceptions\fR
.IX Subsection "Exceptions"
.PP
The simple view on live says: you 're dead when you die.  However,
more complex situations try to revive the dead.  Typically, the \*(L"die\*(R"
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.
.PP
Java-like languages do not \*(L"die\*(R" but throw exceptions which contain the
information about what went wrong.  Perl modules like \f(CW\*(C`Exception::Class\*(C'\fR
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.
.PP
Log::Report follows a simpler scheme.  Fatal messages will \*(L"die\*(R", which is
caught with \*(L"eval\*(R", 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.
.PP
.Vb 6
\& 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
\& }
.Ve
.PP
See Log::Report::Dispatcher::Try and Log::Report::Exception.
.SS "Comparison"
.IX Subsection "Comparison"
\fIdie/warn/Carp\fR
.IX Subsection "die/warn/Carp"
.PP
A typical perl5 program can look like this:
.PP
.Vb 1
\& my $dir = \*(Aq/etc\*(Aq;
\&
\& File::Spec\->file_name is_absolute($dir)
\&     or die "ERROR: directory name must be absolute.\en";
\&
\& \-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\en"
\&     if $verbose;
\&
\& while(defined(my $file = readdir DIR))
\& {   if($file =~ m/\e.bak$/)
\&     {   warn "WARNING: found backup file $dir/$f\en";
\&         next;
\&     }
\&
\&     die "ERROR: file $dir/$file is binary"
\&         if $debug && \-B "$dir/$file";
\&
\&     print "DEBUG: processing file $dir/$file\en"
\&         if $debug;
\&
\&     open FILE, "<", "$dir/$file"
\&         or die "ERROR: cannot read from $dir/$f: $!";
\&
\&     close FILE
\&         or croak "ERROR: read errors in $dir/$file: $!";
\& }
.Ve
.PP
Where \f(CW\*(C`die\*(C'\fR, \f(CW\*(C`warn\*(C'\fR, and \f(CW\*(C`print\*(C'\fR are used for various tasks.  With
\&\f(CW\*(C`Log::Report\*(C'\fR, you would write
.PP
.Vb 1
\& use Log::Report;
\&
\& # can be left\-out when there is no debug/verbose
\& dispatcher PERL => \*(Aqdefault\*(Aq, mode => \*(AqDEBUG\*(Aq;
\&
\& my $dir = \*(Aq/etc\*(Aq;
\&
\& 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/\e.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";
\& }
.Ve
.PP
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 \f(CW$!\fR is added
automatically.
.PP
\fILog::Dispatch and Log::Log4perl\fR
.IX Subsection "Log::Dispatch and Log::Log4perl"
.PP
The two major logging frameworks for Perl are Log::Dispatch and
Log::Log4perl; both provide a pluggable logging interface.
.PP
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.
.PP
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.
.PP
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.
.PP
\fILocale::gettext and Locate::TextDomain\fR
.IX Subsection "Locale::gettext and Locate::TextDomain"
.PP
Both on \s-1GNU\s0 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 \f(CW\*(C`$_\|_\*(C'\fR and \f(CW\*(C`%_\|_\*(C'\fR are not supported.
.PP
The main difference with these modules is the moment when the translation
takes place.  In Locale::TextDomain, an \f(CW\*(C`_\|_x()\*(C'\fR will result in an
immediate translation request via \f(CW\*(C`gettext()\*(C'\fR.  \f(CW\*(C`Log::Report\*(C'\fR's version
of \f(CW\*(C`_\|_x()\*(C'\fR 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.
.PP
To be able to postpone translation, objects are returned which stringify
into the translated text.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Error: in \s-1SCALAR\s0 context, only one dispatcher name accepted" 4
.IX Item "Error: in SCALAR context, only one dispatcher name accepted"
The \fIdispatcher()\fR method returns the Log::Report::Dispatcher
objects which it has accessed.  When multiple names where given, it
wishes to return a \s-1LIST\s0 of objects, not the count of them.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Log-Report distribution version 1.05,
built on June 24, 2014. Website: \fIhttp://perl.overmeer.net/log\-report/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2007\-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://www.perl.com/perl/misc/Artistic.html\fR