.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Log::Dispatch 3"
.TH Log::Dispatch 3 "2009-09-22" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Log::Dispatch \- Dispatches messages to one or more outputs
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Log::Dispatch;
.Ve
.PP
.Vb 9
\&   # Simple API
\&   #
\&   my $log =
\&       Log::Dispatch->new
\&           ( outputs =>
\&                 [ [ 'File',   min_level => 'debug', filename => 'logfile' ],
\&                   [ 'Screen', min_level => 'warning' ],
\&                 ],
\&           );
.Ve
.PP
.Vb 1
\&   $log->info('Blah, blah');
.Ve
.PP
.Vb 14
\&   # More verbose API
\&   #
\&   my $log = Log::Dispatch->new();
\&   $log->add( Log::Dispatch::File->new
\&                         ( name      => 'file1',
\&                           min_level => 'debug',
\&                           filename  => 'logfile'
\&                         )
\&                   );
\&   $log->add( Log::Dispatch::Screen->new
\&                         ( name      => 'screen',
\&                           min_level => 'warning',
\&                         )
\&                   );
.Ve
.PP
.Vb 1
\&   $log->log( level => 'info', message => 'Blah, blah' );
.Ve
.PP
.Vb 2
\&   my $sub = sub { my %p = @_; return reverse $p{message}; };
\&   my $reversing_dispatcher = Log::Dispatch->new( callbacks => $sub );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module manages a set of Log::Dispatch::* output objects that can be
logged to via a unified interface.
.PP
The idea is that you create a Log::Dispatch object and then add various
logging objects to it (such as a file logger or screen logger).  Then you
call the \f(CW\*(C`log\*(C'\fR method of the dispatch object, which passes the message to
each of the objects, which in turn decide whether or not to accept the
message and what to do with it.
.PP
This makes it possible to call single method and send a message to a
log file, via email, to the screen, and anywhere else, all with very
little code needed on your part, once the dispatching object has been
created.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
The constructor (\f(CW\*(C`new\*(C'\fR) takes the following parameters:
.IP "* outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )" 4
.IX Item "outputs( [ [ class, params, ... ], [ class, params, ... ], ... ] )"
This parameter is a reference to a list of lists. Each inner list consists of
a class name and a set of constructor params. The class is automatically
prefixed with 'Log::Dispatch::' unless it begins with '+', in which case the
string following '+' is taken to be a full classname. e.g.
.Sp
.Vb 2
\&    outputs => [ [ 'File',          min_level => 'debug', filename => 'logfile' ],
\&                 [ '+My::Dispatch', min_level => 'info' ] ]
.Ve
.Sp
For each inner list, a new output object is created and added to the
dispatcher (via \*(L"add\*(R").
.Sp
See \*(L"\s-1OUTPUT\s0 \s-1CLASSES\s0\*(R" for the parameters that can be used when creating an
output object.
.IP "* callbacks( \e& or [ \e&, \e&, ... ] )" 4
.IX Item "callbacks( & or [ &, &, ... ] )"
This parameter may be a single subroutine reference or an array
reference of subroutine references.  These callbacks will be called in
the order they are given and passed a hash containing the following keys:
.Sp
.Vb 1
\& ( message => $log_message, level => $log_level )
.Ve
.Sp
In addition, any key/value pairs passed to a logging method will be
passed onto your callback.
.Sp
The callbacks are expected to modify the message and then return a
single scalar containing that modified message.  These callbacks will
be called when either the \f(CW\*(C`log\*(C'\fR or \f(CW\*(C`log_to\*(C'\fR methods are called and
will only be applied to a given message once.  If they do not return
the message then you will get no output.  Make sure to return the
message!
.SH "METHODS"
.IX Header "METHODS"
.Sh "Logging"
.IX Subsection "Logging"
.IP "* log( level => $, message => $ or \e& )" 4
.IX Item "log( level => $, message => $ or & )"
Sends the message (at the appropriate level) to all the
output objects that the dispatcher contains (by calling the
\&\f(CW\*(C`log_to\*(C'\fR method repeatedly).
.Sp
This method also accepts a subroutine reference as the message
argument. This reference will be called only if there is an output
that will accept a message of the specified level.
.IP "* debug (message), info (message), ..." 4
.IX Item "debug (message), info (message), ..."
You may call any valid log level (including valid abbreviations) as a method
with a single argument that is the message to be logged.  This is converted
into a call to the \f(CW\*(C`log\*(C'\fR method with the appropriate level.
.Sp
For example:
.Sp
.Vb 1
\& $log->alert('Strange data in incoming request');
.Ve
.Sp
translates to:
.Sp
.Vb 1
\& $log->log( level => 'alert', message => 'Strange data in incoming request' );
.Ve
.Sp
These methods act like Perl's \f(CW\*(C`print\*(C'\fR built-in when given a list of
arguments.  Thus, the following calls are equivalent:
.Sp
.Vb 2
\& my @array = ('Something', 'bad', 'is', here');
\& $log->alert(@array);
.Ve
.Sp
.Vb 2
\& my $scalar = "@array";
\& $log->alert($scalar);
.Ve
.IP "* log_and_die( level => $, message => $ or \e& )" 4
.IX Item "log_and_die( level => $, message => $ or & )"
Has the same behavior as calling \f(CW\*(C`log()\*(C'\fR but calls
\&\f(CW\*(C`_die_with_message()\*(C'\fR at the end.
.IP "* log_and_croak( level => $, message => $ or \e& )" 4
.IX Item "log_and_croak( level => $, message => $ or & )"
This method adjusts the \f(CW$Carp::CarpLevel\fR scalar so that the croak
comes from the context in which it is called.
.IP "* _die_with_message( message => $, carp_level => $ )" 4
.IX Item "_die_with_message( message => $, carp_level => $ )"
This method is used by \f(CW\*(C`log_and_die\*(C'\fR and will either \fIdie()\fR or \fIcroak()\fR
depending on the value of \f(CW\*(C`message\*(C'\fR: if it's a reference or it ends
with a new line then a plain die will be used, otherwise it will
croak.
.Sp
You can throw exception objects by subclassing this method.
.Sp
If the \f(CW\*(C`carp_level\*(C'\fR parameter is present its value will be added to
the current value of \f(CW$Carp::CarpLevel\fR.
.IP "* log_to( name => $, level => $, message => $ )" 4
.IX Item "log_to( name => $, level => $, message => $ )"
Sends the message only to the named object. Note: this will not properly
handle a subroutine reference as the message.
.ie n .IP "* add_callback( $code )" 4
.el .IP "* add_callback( \f(CW$code\fR )" 4
.IX Item "add_callback( $code )"
Adds a callback (like those given during construction). It is added to the end
of the list of callbacks. Note that this can also be called on individual
output objects.
.Sh "Log levels"
.IX Subsection "Log levels"
.ie n .IP "* level_is_valid( $string )" 4
.el .IP "* level_is_valid( \f(CW$string\fR )" 4
.IX Item "level_is_valid( $string )"
Returns true or false to indicate whether or not the given string is a
valid log level.  Can be called as either a class or object method.
.ie n .IP "* would_log( $string )" 4
.el .IP "* would_log( \f(CW$string\fR )" 4
.IX Item "would_log( $string )"
Given a log level, returns true or false to indicate whether or not
anything would be logged for that log level.
.Sh "Output objects"
.IX Subsection "Output objects"
.IP "* add( Log::Dispatch::* \s-1OBJECT\s0 )" 4
.IX Item "add( Log::Dispatch::* OBJECT )"
Adds a new output object to the dispatcher.  If an object
of the same name already exists, then that object is replaced, with
a warning if \f(CW$^W\fR is true.
.IP "* remove($)" 4
.IX Item "remove($)"
Removes the object that matches the name given to the remove method.
The return value is the object being removed or undef if no object
matched this.
.ie n .IP "* output( $name )" 4
.el .IP "* output( \f(CW$name\fR )" 4
.IX Item "output( $name )"
Returns the output object of the given name.  Returns undef or an empty
list, depending on context, if the given output does not exist.
.SH "OUTPUT CLASSES"
.IX Header "OUTPUT CLASSES"
An output class \- e.g. Log::Dispatch::File or
Log::Dispatch::Screen \- implements a particular way
of dispatching logs. Many output classes come with this distribution,
and others are available separately on \s-1CPAN\s0.
.PP
The following common parameters can be used when creating an output class.
All are optional. Most output classes will have additional parameters beyond
these, see their documentation for details.
.IP "* name ($)" 4
.IX Item "name ($)"
A name for the object (not the filename!). This is useful if you want to
refer to the object later, e.g. to log specifically to it or remove it.
.Sp
By default a unique name will be generated.  You should not depend on the
form of generated names, as they may change.
.IP "* min_level ($)" 4
.IX Item "min_level ($)"
The minimum logging level this object will accept. Required.
.IP "* max_level ($)" 4
.IX Item "max_level ($)"
The maximum logging level this object will accept.  By default
the maximum is the highest possible level (which means functionally that the
object has no maximum).
.IP "* callbacks( \e& or [ \e&, \e&, ... ] )" 4
.IX Item "callbacks( & or [ &, &, ... ] )"
This parameter may be a single subroutine reference or an array
reference of subroutine references.  These callbacks will be called in
the order they are given and passed a hash containing the following keys:
.Sp
.Vb 1
\& ( message => $log_message, level => $log_level )
.Ve
.Sp
The callbacks are expected to modify the message and then return a
single scalar containing that modified message.  These callbacks will
be called when either the \f(CW\*(C`log\*(C'\fR or \f(CW\*(C`log_to\*(C'\fR methods are called and
will only be applied to a given message once.  If they do not return
the message then you will get no output.  Make sure to return the
message!
.IP "* newline (0|1)" 4
.IX Item "newline (0|1)"
If true, a callback will be added to the end of the callbacks list that adds
a newline to the end of each message. Default is false, but some
output classes may decide to make the default true. See \*(L"\s-1NEWLINES\s0\*(R" for more details.
.SH "LOG LEVELS"
.IX Header "LOG LEVELS"
The log levels that Log::Dispatch uses are taken directly from the
syslog man pages (except that I expanded them to full words).  Valid
levels are:
.IP "debug" 4
.IX Item "debug"
.PD 0
.IP "info" 4
.IX Item "info"
.IP "notice" 4
.IX Item "notice"
.IP "warning" 4
.IX Item "warning"
.IP "error" 4
.IX Item "error"
.IP "critical" 4
.IX Item "critical"
.IP "alert" 4
.IX Item "alert"
.IP "emergency" 4
.IX Item "emergency"
.PD
.PP
Alternately, the numbers 0 through 7 may be used (debug is 0 and emergency is
7). The syslog standard of 'err', 'crit', and 'emerg' is also acceptable. We
also allow 'warn' as a synonym for 'warning'.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
This module was designed to be easy to subclass. If you want to handle
messaging in a way not implemented in this package, you should be able to add
this with minimal effort. It is generally as simple as subclassing
Log::Dispatch::Output and overriding the \f(CW\*(C`new\*(C'\fR and \f(CW\*(C`log_message\*(C'\fR
methods. See the Log::Dispatch::Output docs for more details.
.PP
If you would like to create your own subclass for sending email then
it is even simpler.  Simply subclass Log::Dispatch::Email and
override the \f(CW\*(C`send_email\*(C'\fR method.  See the Log::Dispatch::Email
docs for more details.
.PP
The logging levels that Log::Dispatch uses are borrowed from the standard
\&\s-1UNIX\s0 syslog levels, except that where syslog uses partial words (\*(L"err\*(R")
Log::Dispatch also allows the use of the full word as well (\*(L"error\*(R").
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
.Sh "Log::Dispatch::DBI"
.IX Subsection "Log::Dispatch::DBI"
Written by Tatsuhiko Miyagawa.  Log output to a database table.
.Sh "Log::Dispatch::FileRotate"
.IX Subsection "Log::Dispatch::FileRotate"
Written by Mark Pfeiffer.  Rotates log files periodically as part of
its usage.
.Sh "Log::Dispatch::File::Stamped"
.IX Subsection "Log::Dispatch::File::Stamped"
Written by Eric Cholet.  Stamps log files with date and time
information.
.Sh "Log::Dispatch::Jabber"
.IX Subsection "Log::Dispatch::Jabber"
Written by Aaron Straup Cope.  Logs messages via Jabber.
.Sh "Log::Dispatch::Tk"
.IX Subsection "Log::Dispatch::Tk"
Written by Dominique Dumont.  Logs messages to a Tk window.
.Sh "Log::Dispatch::Win32EventLog"
.IX Subsection "Log::Dispatch::Win32EventLog"
Written by Arthur Bergman.  Logs messages to the Windows event log.
.Sh "Log::Log4perl"
.IX Subsection "Log::Log4perl"
An implementation of Java's log4j \s-1API\s0 in Perl, using Log::Dispatch to
do the actual logging.  Created by Mike Schilli and Kevin Goess.
.Sh "Log::Dispatch::Config"
.IX Subsection "Log::Dispatch::Config"
Written by Tatsuhiko Miyagawa.  Allows configuration of logging via a
text file similar (or so I'm told) to how it is done with log4j.
Simpler than Log::Log4perl.
.Sh "Log::Agent"
.IX Subsection "Log::Agent"
A very different \s-1API\s0 for doing many of the same things that
Log::Dispatch does.  Originally written by Raphael Manfredi.
.SH "SUPPORT"
.IX Header "SUPPORT"
Please submit bugs and patches to the \s-1CPAN\s0 \s-1RT\s0 system at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log%3A%3ADispatch
or via email at bug\-log\-dispatch@rt.cpan.org.
.PP
Support questions can be sent to me at my email address, shown below.
.PP
The code repository is at http://hg.urth.org/hg/Log\-Dispatch.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, <autarch@urth.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1999\-2009 David Rolsky.  All rights reserved.  This program is
free software; you can redistribute it and/or modify it under the same terms
as Perl itself.
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included with
this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Log::Dispatch::ApacheLog, Log::Dispatch::Email,
Log::Dispatch::Email::MailSend, Log::Dispatch::Email::MailSender,
Log::Dispatch::Email::MailSendmail, Log::Dispatch::Email::MIMELite,
Log::Dispatch::File, Log::Dispatch::File::Locked,
Log::Dispatch::Handle, Log::Dispatch::Output, Log::Dispatch::Screen,
Log::Dispatch::Syslog