.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Log::Dispatch::Config 3pm"
.TH Log::Dispatch::Config 3pm "2022-06-15" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Log::Dispatch::Config \- Log4j for Perl
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Log::Dispatch::Config;
\&  Log::Dispatch::Config\->configure(\*(Aq/path/to/log.conf\*(Aq);
\&
\&  my $dispatcher = Log::Dispatch::Config\->instance;
\&  $dispatcher\->debug(\*(Aqthis is debug message\*(Aq);
\&  $dispatcher\->emergency(\*(Aqsomething *bad* happened!\*(Aq);
\&
\&  # automatic reloading conf file, when modified
\&  Log::Dispatch::Config\->configure_and_watch(\*(Aq/path/to/log.conf\*(Aq);
\&
\&  # or if you write your own config parser:
\&  use Log::Dispatch::Configurator::XMLSimple;
\&
\&  my $config = Log::Dispatch::Configurator::XMLSimple\->new(\*(Aqlog.xml\*(Aq);
\&  Log::Dispatch::Config\->configure($config);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Log::Dispatch::Config is a subclass of Log::Dispatch and provides a
way to configure Log::Dispatch object with configulation file
(default, in AppConfig format). I mean, this is log4j for Perl, not
with all \s-1API\s0 compatibility though.
.SH "METHOD"
.IX Header "METHOD"
This module has a class method \f(CW\*(C`configure\*(C'\fR which parses config file
for later creation of the Log::Dispatch::Config singleton instance.
(Actual construction of the object is done in the first \f(CW\*(C`instance\*(C'\fR
call).
.PP
So, what you should do is call \f(CW\*(C`configure\*(C'\fR method once in somewhere
(like \f(CW\*(C`startup.pl\*(C'\fR in mod_perl), then you can get configured
dispatcher instance via \f(CW\*(C`Log::Dispatch::Config\->instance\*(C'\fR.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
Here is an example of the config file:
.PP
.Vb 1
\&  dispatchers = file screen
\&
\&  file.class = Log::Dispatch::File
\&  file.min_level = debug
\&  file.filename = /path/to/log
\&  file.mode = append
\&  file.format = [%d] [%p] %m at %F line %L%n
\&
\&  screen.class = Log::Dispatch::Screen
\&  screen.min_level = info
\&  screen.stderr = 1
\&  screen.format = %m
.Ve
.PP
In this example, config file is written in AppConfig format. See
Log::Dispatch::Configurator::AppConfig for details.
.PP
See \*(L"\s-1PLUGGABLE CONFIGURATOR\*(R"\s0 for other config parsing scheme.
.SS "\s-1GLOBAL PARAMETERS\s0"
.IX Subsection "GLOBAL PARAMETERS"
.IP "dispatchers" 4
.IX Item "dispatchers"
.Vb 1
\&  dispatchers = file screen
.Ve
.Sp
\&\f(CW\*(C`dispatchers\*(C'\fR defines logger names, which will be split by spaces.
If this parameter is unset, no logging is done.
.IP "format" 4
.IX Item "format"
.Vb 1
\&  format = [%d] [%p] %m at %F line %L%n
.Ve
.Sp
\&\f(CW\*(C`format\*(C'\fR defines log format. Possible conversions format are
.Sp
.Vb 8
\&  %d    datetime string (ctime(3))
\&  %p    priority (debug, info, warning ...)
\&  %m    message string
\&  %F    filename
\&  %L    line number
\&  %P    package
\&  %n    newline (\en)
\&  %%    % itself
.Ve
.Sp
Note that datetime (%d) format is configurable by passing \f(CW\*(C`strftime\*(C'\fR
fmt in braket after \f(CW%d\fR. (I know it looks quite messy, but its
compatible with Java Log4j ;)
.Sp
.Vb 1
\&  format = [%d{%Y%m%d}] %m  # datetime is now strftime "%Y%m%d"
.Ve
.Sp
If you have Time::Piece, this module uses its \f(CW\*(C`strftime\*(C'\fR
implementation, otherwise \s-1POSIX.\s0
.Sp
\&\f(CW\*(C`format\*(C'\fR defined here would apply to all the log messages to
dispatchers. This parameter is \fBoptional\fR.
.Sp
See \*(L"\s-1CALLER STACK\*(R"\s0 for details about package, line number and
filename.
.SS "\s-1PARAMETERS FOR EACH DISPATCHER\s0"
.IX Subsection "PARAMETERS FOR EACH DISPATCHER"
Parameters for each dispatcher should be prefixed with \*(L"name.\*(R", where
\&\*(L"name\*(R" is the name of each one, defined in global \f(CW\*(C`dispatchers\*(C'\fR
parameter.
.PP
You can also use \f(CW\*(C`.ini\*(C'\fR style grouping like:
.PP
.Vb 3
\&  [foo]
\&  class = Log::Dispatch::File
\&  min_level = debug
.Ve
.PP
See Log::Dispatch::Configurator::AppConfig for details.
.IP "class" 4
.IX Item "class"
.Vb 1
\&  screen.class = Log::Dispatch::Screen
.Ve
.Sp
\&\f(CW\*(C`class\*(C'\fR defines class name of Log::Dispatch subclasses. This
parameter is \fBessential\fR.
.IP "format" 4
.IX Item "format"
.Vb 1
\&  screen.format = \-\- %m \-\-
.Ve
.Sp
\&\f(CW\*(C`format\*(C'\fR defines log format which would be applied only to the
dispatcher. Note that if you define global \f(CW\*(C`format\*(C'\fR also, \f(CW%m\fR is
double formated (first global one, next each dispatcher one). This
parameter is \fBoptional\fR.
.IP "(others)" 4
.IX Item "(others)"
.Vb 2
\&  screen.min_level = info
\&  screen.stderr = 1
.Ve
.Sp
Other parameters would be passed to the each dispatcher
construction. See Log::Dispatch::* manpage for the details.
.SH "SINGLETON"
.IX Header "SINGLETON"
Declared \f(CW\*(C`instance\*(C'\fR method would make \f(CW\*(C`Log::Dispatch::Config\*(C'\fR class
singleton, so multiple calls of \f(CW\*(C`instance\*(C'\fR will all result in
returning same object.
.PP
.Vb 2
\&  my $one = Log::Dispatch::Config\->instance;
\&  my $two = Log::Dispatch::Config\->instance; # same as $one
.Ve
.PP
See GoF Design Pattern book for Singleton Pattern.
.PP
But in practice, in persistent environment like mod_perl, lifetime of
Singleton instance becomes sometimes messy. If you want to reload
singleton object manually, call \f(CW\*(C`reload\*(C'\fR method.
.PP
.Vb 1
\&  Log::Dispatch::Config\->reload;
.Ve
.PP
And, if you want to reload object on the fly, as you edit \f(CW\*(C`log.conf\*(C'\fR
or something like that, what you should do is to call
\&\f(CW\*(C`configure_and_watch\*(C'\fR method on Log::Dispatch::Config instead of
\&\f(CW\*(C`configure\*(C'\fR. Then \f(CW\*(C`instance\*(C'\fR call will check mtime of configuration
file, and compares it with instanciation time of singleton object. If
config file is newer than last instanciation, it will automatically
reload object.
.SH "NAMESPACE COLLISION"
.IX Header "NAMESPACE COLLISION"
If you use Log::Dispatch::Config in multiple projects on the same perl
interpreter (like mod_perl), namespace collision would be a
problem. Bizzare thing will happen when you call
\&\f(CW\*(C`Log::Dispatch::Config\->configure\*(C'\fR multiple times with differenct
argument.
.PP
In such cases, what you should do is to define your own logger class.
.PP
.Vb 3
\&  package My::Logger;
\&  use Log::Dispatch::Config;
\&  use base qw(Log::Dispatch::Config);
.Ve
.PP
Or make wrapper for it. See POE::Component::Logger implementation
by Matt Sergeant.
.SH "PLUGGABLE CONFIGURATOR"
.IX Header "PLUGGABLE CONFIGURATOR"
If you pass filename to \f(CW\*(C`configure\*(C'\fR method call, this module handles
the config file with AppConfig. You can change config parsing scheme
by passing another pluggable configurator object.
.PP
Here is a way to declare new configurator class. The example below is
hardwired version equivalent to the one above in \*(L"\s-1CONFIGURATION\*(R"\s0.
.IP "\(bu" 4
Inherit from Log::Dispatch::Configurator.
.Sp
.Vb 2
\&  package Log::Dispatch::Configurator::Hardwired;
\&  use base qw(Log::Dispatch::Configurator);
.Ve
.Sp
Declare your own \f(CW\*(C`new\*(C'\fR constructor. Stub \f(CW\*(C`new\*(C'\fR method is defined in
Configurator base class, but you want to put parsing method in your
own constructor. In this example, we just bless reference. Note that
your object should be blessed hash.
.Sp
.Vb 1
\&  sub new { bless {}, shift }
.Ve
.IP "\(bu" 4
Implement two required object methods \f(CW\*(C`get_attrs_global\*(C'\fR and
\&\f(CW\*(C`get_attrs\*(C'\fR.
.Sp
\&\f(CW\*(C`get_attrs_global\*(C'\fR should return hash reference of global parameters.
\&\f(CW\*(C`dispatchers\*(C'\fR should be an array reference of names of dispatchers.
.Sp
.Vb 7
\&  sub get_attrs_global {
\&      my $self = shift;
\&      return {
\&          format => undef,
\&          dispatchers => [ qw(file screen) ],
\&      };
\&  }
.Ve
.Sp
\&\f(CW\*(C`get_attrs\*(C'\fR accepts name of a dispatcher and should return hash
reference of parameters associated with the dispatcher.
.Sp
.Vb 10
\&  sub get_attrs {
\&      my($self, $name) = @_;
\&      if ($name eq \*(Aqfile\*(Aq) {
\&          return {
\&              class     => \*(AqLog::Dispatch::File\*(Aq,
\&              min_level => \*(Aqdebug\*(Aq,
\&              filename  => \*(Aq/path/to/log\*(Aq,
\&              mode      => \*(Aqappend\*(Aq,
\&              format  => \*(Aq[%d] [%p] %m at %F line %L%n\*(Aq,
\&          };
\&      }
\&      elsif ($name eq \*(Aqscreen\*(Aq) {
\&          return {
\&              class     => \*(AqLog::Dispatch::Screen\*(Aq,
\&              min_level => \*(Aqinfo\*(Aq,
\&              stderr    => 1,
\&              format  => \*(Aq%m\*(Aq,
\&          };
\&      }
\&      else {
\&          die "invalid dispatcher name: $name";
\&      }
\&  }
.Ve
.IP "\(bu" 4
Implement optional \f(CW\*(C`needs_reload\*(C'\fR and \f(CW\*(C`reload\*(C'\fR
methods. \f(CW\*(C`needs_reload\*(C'\fR should return boolean value if the object is
stale and needs reloading itself. This method will be triggered when
you configure logging object with \f(CW\*(C`configure_and_watch\*(C'\fR method.
.Sp
Stub config file mtime based \f(CW\*(C`needs_reload\*(C'\fR method is declared in
Log::Dispatch::Configurator, so if your config class is based on
filesystem files, you do not need to reimplement this.
.Sp
If you do not need \fIsingleton-ness\fR at all, always return true.
.Sp
.Vb 1
\&  sub needs_reload { 1 }
.Ve
.Sp
\&\f(CW\*(C`reload\*(C'\fR method should redo parsing of the config file. Configurator
base class has a stub null \f(CW\*(C`reload\*(C'\fR method, so you should better
override it.
.Sp
See Log::Dispatch::Configurator::AppConfig source code for details.
.IP "\(bu" 4
That's all. Now you can plug your own configurator (Hardwired) into
Log::Dispatch::Config. What you should do is to pass configurator
object to \f(CW\*(C`configure\*(C'\fR method call instead of config file name.
.Sp
.Vb 2
\&  use Log::Dispatch::Config;
\&  use Log::Dispatch::Configurator::Hardwired;
\&
\&  my $config = Log::Dispatch::Configurator::Hardwired\->new;
\&  Log::Dispatch::Config\->configure($config);
.Ve
.SH "CALLER STACK"
.IX Header "CALLER STACK"
When you call logging method from your subroutines / methods, caller
stack would increase and thus you can't see where the log really comes
from.
.PP
.Vb 2
\&  package Logger;
\&  my $Logger = Log::Dispatch::Config\->instance;
\&
\&  sub logit {
\&      my($class, $level, $msg) = @_;
\&      $Logger\->$level($msg);
\&  }
\&
\&  package main;
\&  Logger\->logit(\*(Aqdebug\*(Aq, \*(Aqfoobar\*(Aq);
.Ve
.PP
You can adjust package variable \f(CW$Log::Dispatch::Config::CallerDepth\fR
to increase the caller stack depth. The default value is 0.
.PP
.Vb 5
\&  sub logit {
\&      my($class, $level, $msg) = @_;
\&      local $Log::Dispatch::Config::CallerDepth = 1;
\&      $Logger\->$level($msg);
\&  }
.Ve
.PP
Note that your log caller's namespace should not match against
\&\f(CW\*(C`/^Log::Dispatch/\*(C'\fR, which makes this module confusing.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tatsuhiko Miyagawa <miyagawa@bulknews.net> with much help from
Matt Sergeant <matt@sergeant.org>.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Dispatch::Configurator::AppConfig, Log::Dispatch,
AppConfig, POE::Component::Logger