Log::Report::Dispatcher::File(3pm)

1Log::Report::DispatcherU:s:eFrilCeo(n3t)ributed Perl DocLuomge:n:tRaetpioornt::Dispatcher::File(3)
2
3
4

NAME

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

INHERITANCE

9        Log::Report::Dispatcher::File
10          is a Log::Report::Dispatcher
11

SYNOPSIS

13        dispatcher Log::Report::Dispatcher::File => 'stderr'
14          , to => \*STDERR, accept => 'NOTICE-';
15
16        # close a dispatcher
17        dispatcher close => 'stderr';
18
19        # let dispatcher open and close the file
20        dispatcher FILE => 'mylog', to => '/var/log/mylog'
21          , charset => 'utf-8';
22        ...
23        dispatcher close => 'mylog';  # will close file
24
25        # open yourself, then also close yourself
26        open OUT, ">:encoding('iso-8859-1')", '/var/log/mylog'
27            or fault "...";
28        dispatcher FILE => 'mylog', to => \*OUT;
29        ...
30        dispatcher close => 'mylog';
31        close OUT;
32
33        # dispatch into a scalar
34        my $output = '';
35        open $outfile, '>', \$output;
36        dispatcher FILE => 'into-scalar', to => \$outfile;
37        ...
38        dispatcher close => 'into-scalar';
39        print $output;
40

DESCRIPTION

42       This basic file logger accepts an file-handle or filename as
43       destination.
44
45       [1.00] writing to the file protected by a lock, so multiple processes
46       can write to the same file.
47
48       Extends "DESCRIPTION" in Log::Report::Dispatcher.
49

METHODS

51       Extends "METHODS" in Log::Report::Dispatcher.
52
53   Constructors
54       Extends "Constructors" in Log::Report::Dispatcher.
55
56       $obj->close()
57           Only when initiated with a FILENAME, the file will be closed.  In
58           any other case, nothing will be done.
59
60       Log::Report::Dispatcher::File->new($type, $name, %options)
61            -Option       --Defined in             --Default
62             accept         Log::Report::Dispatcher  depend on mode
63             charset        Log::Report::Dispatcher  LOCALE
64             format                                  <adds timestamp>
65             format_reason  Log::Report::Dispatcher  'LOWERCASE'
66             locale         Log::Report::Dispatcher  <system locale>
67             mode           Log::Report::Dispatcher  'NORMAL'
68             replace                                 false
69             to                                      <required>
70
71           accept => REASONS
72           charset => CHARSET
73           format => CODE|'LONG'
74             [1.00] process each printed line.  By default, this adds a
75             timestamp, but you may want to add hostname, process number, or
76             more.
77
78                format => sub { '['.localtime().'] '.$_[0] }
79                format => sub { shift }   # no timestamp
80                format => 'LONG'
81
82             The first parameter to format is the string to print; it is
83             already translated and trailed by a newline.  The second
84             parameter is the text-domain (if known).
85
86             [1.10] As third parameter, you get the $msg raw object as well
87             (maybe you want to use the message context?)  [1.19] After the
88             three positional parameters, there may be a list of pairs
89             providing additional facts about the exception.  It may contain
90             "location" information.
91
92             The "LONG" format is equivalent to:
93
94               my $t = strftime "%FT%T", gmtime;
95               "[$t $$] $_[1] $_[0]"
96
97             Use of context:
98
99                format => sub { my ($msgstr, $domain, $msg, %more) = @_;
100                   my $host = $msg->context->{host};
101                   "$host $msgstr";
102                }
103
104           format_reason => 'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE
105           locale => LOCALE
106           mode => 'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3
107           replace => BOOLEAN
108             Only used in combination with a FILENAME: throw away the old file
109             if it exists.  Probably you wish to append to existing
110             information.
111
112             Use the LOCALE setting by default, which is LC_CTYPE or LC_ALL or
113             LANG (in that order).  If these contain a character-set which
114             Perl understands, then that is used, otherwise silently ignored.
115
116           to => FILENAME|FILEHANDLE|OBJECT|CODE
117             You can either specify a FILENAME, which is opened in append mode
118             with autoflush on. Or pass any kind of FILE-HANDLE or some OBJECT
119             which implements a print() method. You probably want to have
120             autoflush enabled on your FILE-HANDLES.
121
122             When cleaning-up the dispatcher, the file will only be closed in
123             case of a FILENAME.
124
125             [1.10] When you pass a CODE, then for each log message the
126             function is called with two arguments: this dispatcher object and
127             the message object.  In some way (maybe via the message context)
128             you have to determine the log filename.  This means that probably
129             many log-files are open at the same time.
130
131                # configuration time
132                dispatcher FILE => 'logfile', to =>
133                    sub { my ($disp, $msg) = @_; $msg->context->{logfile} };
134
135                # whenever you want to change the logfile
136                textdomain->updateContext(logfile => '/var/log/app');
137                (textdomain 'mydomain')->setContext(logfile => '/var/log/app');
138
139                # or
140                error __x"help", _context => {logfile => '/dev/tty'};
141                error __x"help", _context => "logfile=/dev/tty";
142
143   Accessors
144       Extends "Accessors" in Log::Report::Dispatcher.
145
146       $obj->filename()
147           Returns the name of the opened file, or "undef" in case this
148           dispatcher was started from a file-handle or file-object.
149
150       $obj->format()
151       $obj->isDisabled()
152           Inherited, see "Accessors" in Log::Report::Dispatcher
153
154       $obj->mode()
155           Inherited, see "Accessors" in Log::Report::Dispatcher
156
157       $obj->name()
158           Inherited, see "Accessors" in Log::Report::Dispatcher
159
160       $obj->needs( [$reason] )
161           Inherited, see "Accessors" in Log::Report::Dispatcher
162
163       $obj->output($msg)
164           Returns the file-handle to write the log lines to. [1.10] This may
165           depend on the $msg (especially message context)
166
167       $obj->type()
168           Inherited, see "Accessors" in Log::Report::Dispatcher
169
170   File maintenance
171       $obj->rotate($filename|CODE)
172           [1.00] Move the current file to $filename, and start a new file.
173
174   Logging
175       Extends "Logging" in Log::Report::Dispatcher.
176
177       $obj->addSkipStack(@CODE)
178       Log::Report::Dispatcher::File->addSkipStack(@CODE)
179           Inherited, see "Logging" in Log::Report::Dispatcher
180
181       $obj->collectLocation()
182       Log::Report::Dispatcher::File->collectLocation()
183           Inherited, see "Logging" in Log::Report::Dispatcher
184
185       $obj->collectStack( [$maxdepth] )
186       Log::Report::Dispatcher::File->collectStack( [$maxdepth] )
187           Inherited, see "Logging" in Log::Report::Dispatcher
188
189       $obj->log(HASH-$of-%options, $reason, $message, $domain)
190           Inherited, see "Logging" in Log::Report::Dispatcher
191
192       $obj->skipStack()
193           Inherited, see "Logging" in Log::Report::Dispatcher
194
195       $obj->stackTraceLine(%options)
196       Log::Report::Dispatcher::File->stackTraceLine(%options)
197           Inherited, see "Logging" in Log::Report::Dispatcher
198
199       $obj->translate(HASH-$of-%options, $reason, $message)
200           Inherited, see "Logging" in Log::Report::Dispatcher
201

DETAILS

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

LICENSE

210       Copyrights 2007-2023 by [Mark Overmeer <markov@cpan.org>]. For other
211       contributors see ChangeLog.
212
213       This program is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
215
216
217
218perl v5.36.1                      2023-10-27  Log::Report::Dispatcher::File(3)