Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Report::DispatcheUser Contributed Perl DocumentLog::Report::Dispatcher(3)

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.33, built on
       July 17,	2021. Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2007-2021 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/

perl v5.32.1			  2021-07-17	    Log::Report::Dispatcher(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Report::Dispatcher&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help