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'
;
$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
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.20, built on June 27, 2017. Website: http://perl.overmeer.net/log-report/
LICENSE
Copyrights 2007-2017 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under the Artistic license. See http://dev.perl.org/licenses/artistic.html