/usr/share/perl5/Log/Report/Dispatcher.pod is in liblog-report-perl 1.05-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 | =encoding utf8
=head1 NAME
Log::Report::Dispatcher - manage message dispatching, display or logging
=head1 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
=head1 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-';
=head1 DESCRIPTION
In L<Log::Report|Log::Report>, dispatchers are used to handle (exception) messages
which are created somewhere else. Those message were produced (thrown)
by L<Log::Report::error()|Log::Report/"Abbreviations for report()"> and friends.
This base-class handles the creation of dispatchers, plus the common
filtering rules. See the L</DETAILS> section, below.
=head1 METHODS
=head2 Constructors
=over 4
=item $obj-E<gt>B<close>()
Terminate the dispatcher activities. The dispatcher gets disabled,
to avoid the case that it is accidentally used. Returns C<undef> (false)
if the dispatcher was already closed.
=item Log::Report::Dispatcher-E<gt>B<new>($type, $name, %options)
Create a dispatcher. The $type of back-end to start is required, and listed
in the L</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 L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">) 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'
=over 2
=item accept => REASONS
See L<Log::Report::Util::expand_reasons()|Log::Report::Util/"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 C<accept>'s default
is C<NOTICE->. In case of "VERBOSE"> it will be C<INFO->, C<ASSERT>
results in C<ASSERT->, and "DEBUG" in C<ALL>.
=item 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.
=item 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.
=item locale => LOCALE
Overrules the global setting. Can be overruled by
L<Log::Report::report(locale)|Log::Report/"Report Production and Configuration">.
=item mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
Possible values are C<NORMAL> (or C<0> or C<undef>), which will not show
C<INFO> or debug messages, C<VERBOSE> (C<1>; shows C<INFO> not debug),
C<ASSERT> (C<2>; only ignores C<TRACE> messages), or C<DEBUG> (C<3>)
which shows everything. See section L<Log::Report/Run modes>.
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.
=back
=back
=head2 Accessors
=over 4
=item $obj-E<gt>B<isDisabled>()
=item $obj-E<gt>B<mode>()
Returns the mode in use for the dispatcher as number. See L<new(mode)|Log::Report::Dispatcher/"Constructors">
and L<Log::Report/Run modes>.
=item $obj-E<gt>B<name>()
Returns the unique name of this dispatcher.
=item $obj-E<gt>B<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.
=item $obj-E<gt>B<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.
=back
=head2 Logging
=over 4
=item $obj-E<gt>B<collectLocation>()
=item Log::Report::Dispatcher-E<gt>B<collectLocation>()
Collect the information to be displayed as line where the error occurred.
Probably, this needs improvement, where carp and die show different lines.
=item $obj-E<gt>B<collectStack>( [$maxdepth] )
=item Log::Report::Dispatcher-E<gt>B<collectStack>( [$maxdepth] )
Returns an ARRAY of ARRAYs with text, filename, line-number.
=item $obj-E<gt>B<log>(HASH-$of-%options, $reason, $message, $domain)
This method is called by L<Log::Report::report()|Log::Report/"Report Production and Configuration"> and should not be called
directly. Internally, it will call L<translate()|Log::Report::Dispatcher/"Logging">, which does most $of
the work.
=item $obj-E<gt>B<stackTraceLine>(%options)
=item Log::Report::Dispatcher-E<gt>B<stackTraceLine>(%options)
-Option --Default
abstract 1
call <required>
filename <required>
linenr <required>
max_line undef
max_params 8
package <required>
params <required>
=over 2
=item 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 C<max_line>
margin.
=item call => STRING
=item filename => STRING
=item linenr => INTEGER
=item max_line => INTEGER
=item max_params => INTEGER
=item package => CLASS
=item params => ARRAY
=back
=item $obj-E<gt>B<translate>(HASH-$of-%options, $reason, $message)
See L</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).
=back
=head1 DETAILS
=head2 Available back-ends
When a dispatcher is created (via L<new()|Log::Report::Dispatcher/"Constructors"> or L<Log::Report::dispatcher()|Log::Report/"Report Production and Configuration">),
you must specify the TYPE of the dispatcher. This can either be a class
name, which extends a L<Log::Report::Dispatcher|Log::Report::Dispatcher>, or a pre-defined
abbreviation of a class name. Implemented are:
=over 4
=item L<Log::Report::Dispatcher::Perl|Log::Report::Dispatcher::Perl> (abbreviation 'PERL')
Use Perl's own C<print()>, C<warn()> and C<die()> to ventilate
reports. This is the default dispatcher.
=item L<Log::Report::Dispatcher::File|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.
=item L<Log::Report::Dispatcher::Syslog|Log::Report::Dispatcher::Syslog> (abbreviation 'SYSLOG')
Send messages into the system's syslog infrastructure, using
Sys::Syslog.
=item L<Log::Report::Dispatcher::Callback|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.
=item C<Log::Dispatch::*>
All of the Log::Dispatch::Output extensions can be used directly.
The L<Log::Report::Dispatcher::LogDispatch|Log::Report::Dispatcher::LogDispatch> will wrap around that
back-end.
=item C<Log::Log4perl>
Use the Log::Log4perl main object to write to dispatchers. This
infrastructure uses a configuration file.
=item L<Log::Report::Dispatcher::Try|Log::Report::Dispatcher::Try> (abbreviation 'TRY')
Used by function L<Log::Report::try()|Log::Report/"Report Production and Configuration">. It collects the exceptions
and can produce them on request.
=back
=head2 Processing the message
=head3 Addition information
The modules which use C<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:
=over 4
=item . the reason
=item . the filename/line-number where the problem appeared
=item . the filename/line-number where it problem was reported
=item . the error text in C<$!>
=item . a stack-trace
=item . a trailing new-line
=back
When the message is a translatable object (L<Log::Report::Message|Log::Report::Message>, for
instance created with L<Log::Report::__()|Log::Report/"Language Translations">), 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 L<mode()|Log::Report::Dispatcher/"Accessors">, initiate it with L<new(mode)|Log::Report::Dispatcher/"Constructors">).
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())
=head3 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 C<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 L<Log::Report::Dispatcher|Log::Report::Dispatcher>), the HASH-of-OPTIONS
passed as optional first argument to L<Log::Report::report()|Log::Report/"Report Production and Configuration">, the
REASON, and the MESSAGE. Returned is the new REASON and MESSAGE.
When the returned REASON is C<undef>, then the message will be ignored
for that dispatcher.
Be warned about processing the MESSAGE: it is a L<Log::Report::Message|Log::Report::Message>
object which may have a C<prepend> string and C<append> string or
object. When the call to L<Log::Report::report()|Log::Report/"Report Production and Configuration"> contained multiple
comma-separated components, these will already have been joined together
using concatenation (see L<Log::Report::Message::concat()|Log::Report::Message/"Processing">.
=head1 SEE ALSO
This module is part of Log-Report distribution version 1.05,
built on June 24, 2014. Website: F<http://perl.overmeer.net/log-report/>
=head1 LICENSE
Copyrights 2007-2014 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 F<http://www.perl.com/perl/misc/Artistic.html>
|