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

FreeBSD Manual Pages

  
 
  

home | help
Log::Report::DispatcheUseriContributed Perl DoLog::Report::Dispatcher::File(3)

NAME
       Log::Report::Dispatcher::File - send messages to	a file or file-handle

INHERITANCE
	Log::Report::Dispatcher::File
	  is a Log::Report::Dispatcher

SYNOPSIS
	dispatcher Log::Report::Dispatcher::File => 'stderr'
	  , to => \*STDERR, accept => 'NOTICE-';

	# close	a dispatcher
	dispatcher close => 'stderr';

	# let dispatcher open and close	the file
	dispatcher FILE	=> 'mylog', to => '/var/log/mylog'
	  , charset => 'utf-8';
	...
	dispatcher close => 'mylog';  #	will close file

	# open yourself, then also close yourself
	open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
	    or fault "...";
	dispatcher FILE	=> 'mylog', to => \*OUT;
	...
	dispatcher close => 'mylog';
	close OUT;

	# dispatch into	a scalar
	my $output = '';
	open $outfile, '>', \$output;
	dispatcher FILE	=> 'into-scalar', to =>	\$outfile;
	...
	dispatcher close => 'into-scalar';
	print $output;

DESCRIPTION
       This basic file logger accepts an file-handle or	filename as
       destination.

       [1.00] writing to the file protected by a lock, so multiple processes
       can write to the	same file.

       Extends "DESCRIPTION" in	Log::Report::Dispatcher.

METHODS
       Extends "METHODS" in Log::Report::Dispatcher.

   Constructors
       Extends "Constructors" in Log::Report::Dispatcher.

       $obj->close()
	   Only	when initiated with a FILENAME,	the file will be closed.  In
	   any other case, nothing will	be done.

       Log::Report::Dispatcher::File->new($type, $name,	%options)
	    -Option	  --Defined in		   --Default
	     accept	    Log::Report::Dispatcher  depend on mode
	     charset	    Log::Report::Dispatcher  LOCALE
	     format				     <adds timestamp>
	     format_reason  Log::Report::Dispatcher  'LOWERCASE'
	     locale	    Log::Report::Dispatcher  <system locale>
	     mode	    Log::Report::Dispatcher  'NORMAL'
	     replace				     false
	     to					     <required>

	   accept => REASONS
	   charset => CHARSET
	   format => CODE|'LONG'
	     [1.00] process each printed line.	By default, this adds a
	     timestamp,	but you	may want to add	hostname, process number, or
	     more.

		format => sub {	'['.localtime().'] '.$_[0] }
		format => sub {	shift }	  # no timestamp
		format => 'LONG'

	     The first parameter to format is the string to print; it is
	     already translated	and trailed by a newline.  The second
	     parameter is the text-domain (if known).

	     [1.10] As third parameter,	you get	the $msg raw object as well
	     (maybe you	want to	use the	message	context?)  [1.19] After	the
	     three positional parameters, there	may be a list of pairs
	     providing additional facts	about the exception.  It may contain
	     "location"	information.

	     The "LONG"	format is equivalent to:

	       my $t = strftime	"%FT%T", gmtime;
	       "[$t $$]	$_[1] $_[0]"

	     Use of context:

		format => sub {	my ($msgstr, $domain, $msg, %more) = @_;
		   my $host = $msg->context->{host};
		   "$host $msgstr";
		}

	   format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
	   locale => LOCALE
	   mode	=> 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
	   replace => BOOLEAN
	     Only used in combination with a FILENAME: throw away the old file
	     if	it exists.  Probably you wish to append	to existing
	     information.

	     Use the LOCALE setting by default,	which is LC_CTYPE or LC_ALL or
	     LANG (in that order).  If these contain a character-set which
	     Perl understands, then that is used, otherwise silently ignored.

	   to => FILENAME|FILEHANDLE|OBJECT|CODE
	     You can either specify a FILENAME,	which is opened	in append mode
	     with autoflush on.	Or pass	any kind of FILE-HANDLE	or some	OBJECT
	     which implements a	"print()" method. You probably want to have
	     autoflush enabled on your FILE-HANDLES.

	     When cleaning-up the dispatcher, the file will only be closed in
	     case of a FILENAME.

	     [1.10] When you pass a CODE, then for each	log message the
	     function is called	with two arguments: this dispatcher object and
	     the message object.  In some way (maybe via the message context)
	     you have to determine the log filename.  This means that probably
	     many log-files are	open at	the same time.

		# configuration	time
		dispatcher FILE	=> 'logfile', to =>
		    sub	{ my ($disp, $msg) = @_; $msg->context->{logfile} };

		# whenever you want to change the logfile
		textdomain->updateContext(logfile => '/var/log/app');
		(textdomain 'mydomain')->setContext(logfile => '/var/log/app');

		# or
		error __x"help", _context => {logfile => '/dev/tty'};
		error __x"help", _context => "logfile=/dev/tty";

   Accessors
       Extends "Accessors" in Log::Report::Dispatcher.

       $obj->filename()
	   Returns the name of the opened file,	or "undef" in case this
	   dispatcher was started from a file-handle or	file-object.

       $obj->format()
       $obj->isDisabled()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->mode()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->name()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->needs( [$reason] )
	   Inherited, see "Accessors" in Log::Report::Dispatcher

       $obj->output($msg)
	   Returns the file-handle to write the	log lines to. [1.10] This may
	   depend on the $msg (especially message context)

       $obj->type()
	   Inherited, see "Accessors" in Log::Report::Dispatcher

   File	maintenance
       $obj->rotate($filename|CODE)
	   [1.00] Move the current file	to $filename, and start	a new file.

   Logging
       Extends "Logging" in Log::Report::Dispatcher.

       $obj->addSkipStack(@CODE)
       Log::Report::Dispatcher::File->addSkipStack(@CODE)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectLocation()
       Log::Report::Dispatcher::File->collectLocation()
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->collectStack( [$maxdepth] )
       Log::Report::Dispatcher::File->collectStack( [$maxdepth]	)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->log(HASH-$of-%options, $reason, $message, $domain)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->skipStack()
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->stackTraceLine(%options)
       Log::Report::Dispatcher::File->stackTraceLine(%options)
	   Inherited, see "Logging" in Log::Report::Dispatcher

       $obj->translate(HASH-$of-%options, $reason, $message)
	   Inherited, see "Logging" in Log::Report::Dispatcher

DETAILS
       Extends "DETAILS" in Log::Report::Dispatcher.

SEE ALSO
       This module is part of Log-Report distribution version 1.29, built on
       November	08, 2019. Website: http://perl.overmeer.net/CPAN/

LICENSE
       Copyrights 2007-2019 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.0			  2019-11-08  Log::Report::Dispatcher::File(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::File&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help