.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Badger::Log 3pm"
.TH Badger::Log 3pm "2023-08-28" "perl v5.36.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"
Badger::Log \- log for errors, warnings and other messages
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Badger::Log;
\&
\&    my $log = Badger::Log\->new({
\&        debug => 0,      # ignore debug messages
\&        info  => 1,      # print info messages
\&        warn  => \e@warn, # add warnings to list
\&        error => $log2,  # delegate errors to $log2
\&        fatal => sub {   # custom fatal error handler
\&            my $message = shift;
\&            print "FATAL ERROR: $message\en";
\&        },
\&    });
\&
\&    $log\->debug(\*(Aqa debug message\*(Aq);
\&    $log\->info(\*(Aqan info message\*(Aq);
\&    $log\->warn(\*(Aqa warning message\*(Aq);
\&    $log\->error(\*(Aqan error message\*(Aq);
\&    $log\->fatal(\*(Aqa fatal error message\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module defines a simple base class module for logging messages
generated by an application.  It is intentionally very simple in design,
providing the bare minimum in functionality with the possibility for
extension by subclassing.
.PP
It offers little, if anything, over the many other fine logging modules
available from \s-1CPAN.\s0  It exists to provide a basic logging facility
that integrates cleanly with, and can be bundled up with the other Badger
modules so that you've got something that works \*(L"out of the box\*(R".
.PP
There are five message categories:
.IP "debug" 4
.IX Item "debug"
A debugging message.
.IP "info" 4
.IX Item "info"
A message providing some general information.
.IP "warn" 4
.IX Item "warn"
A warning message.
.IP "error" 4
.IX Item "error"
An error message.
.IP "fatal" 4
.IX Item "fatal"
A fatal error message.
.SH "CONFIGURATION OPTIONS"
.IX Header "CONFIGURATION OPTIONS"
.SS "debug"
.IX Subsection "debug"
Flag to indicate if debugging messages should be generated and output.
The default value is \f(CW0\fR.  It can be set to \f(CW1\fR to enable debugging
messages or to one of the other reference values described in the
documentation for the \fBnew()\fR method.
.SS "info"
.IX Subsection "info"
Flag to indicate if information messages should be generated and output.
The default value is \f(CW0\fR.  It can be set to \f(CW1\fR to enable information
messages or to one of the other reference values described in the
documentation for the \fBnew()\fR method.
.SS "warn"
.IX Subsection "warn"
Flag to indicate if warning messages should be generated and output.
The default value is \f(CW1\fR.  It can be set to \f(CW0\fR to disable warning
messages or to one of the other reference values described in the
documentation for the \fBnew()\fR method.
.SS "error"
.IX Subsection "error"
Flag to indicate if error messages should be generated and output.
The default value is \f(CW1\fR. It can be set to \f(CW0\fR to disable error
messages or to one of the other reference values described in the
documentation for the \fBnew()\fR method.
.SS "fatal"
.IX Subsection "fatal"
Flag to indicate if fatal messages should be generated and output. The default
value is \f(CW1\fR. It can be set to \f(CW0\fR to disable fatal error messages (at your
own peril) or to one of the other reference values described in the
documentation for the \fBnew()\fR method.
.SS "format"
.IX Subsection "format"
This option can be used to define a different log message format.
.PP
.Vb 3
\&    my $log = Badger::Log\->new(
\&        format => \*(Aq[<level>] [<time>] <message>\*(Aq,
\&    );
.Ve
.PP
The default message format is:
.PP
.Vb 1
\&    [<time>] [<system>] [<level>] <message>
.Ve
.PP
The \f(CW\*(C`<XXX>\*(C'\fR snippets are replaced with their equivalent values:
.PP
.Vb 4
\&    time        The current local time
\&    system      A system identifier, defaults to \*(AqBadger\*(Aq
\&    level       The message level: debug, info, warn, error or fatal
\&    message     The log message itself
.Ve
.PP
The format can also be set using a \f(CW$FORMAT\fR package variable in a subclass
of \f(CW\*(C`Badger::Log\*(C'\fR.
.PP
.Vb 4
\&    package Your::Log::Module;
\&    use base \*(AqBadger::Log\*(Aq;
\&    our $FORMAT = \*(Aq[<level>] [<time>] <message>\*(Aq;
\&    1;
.Ve
.SS "system"
.IX Subsection "system"
A system identifier which is inserted into each message via the
\&\f(CW\*(C`<system>\*(C'\fR snippet.  See format for further information.
The default value is \f(CW\*(C`Badger\*(C'\fR.
.PP
.Vb 3
\&    my $log = Badger::Log\->new(
\&        system => \*(AqMyApp\*(Aq,
\&    );
.Ve
.PP
The system identifier can also be set using a \f(CW$SYSTEM\fR package variable in a
subclass of \f(CW\*(C`Badger::Log\*(C'\fR.
.PP
.Vb 4
\&    package Your::Log::Module;
\&    use base \*(AqBadger::Log\*(Aq;
\&    our $SYSTEM = \*(AqMyApp\*(Aq;
\&    1;
.Ve
.SS "strftime"
.IX Subsection "strftime"
This option can be used to set the format for the timestamp added to messages
via the via the \f(CW\*(C`<time<gt\*(C'\fR> snippet.
.PP
.Vb 3
\&    my $log = Badger::Log\->new(
\&        strftime => \*(Aq%a %b %d %Y\*(Aq,
\&    );
.Ve
.PP
The format string is passed to the \fBformat()\fR
method of Badger::Timestamp.
.SH "METHODS"
.IX Header "METHODS"
.SS "new(\e%options)"
.IX Subsection "new(%options)"
Constructor method which creates a new \f(CW\*(C`Badger::Log\*(C'\fR object.  It
accepts a list of named parameters or reference to hash of
configuration options that define how each message type should be
handled.
.PP
.Vb 10
\&    my $log = Badger::Log\->new({
\&        debug => 0,      # ignore debug messages
\&        info  => 1,      # print info messages
\&        warn  => \e@warn, # add warnings to list
\&        error => $log2,  # delegate errors to $log2
\&        fatal => sub {   # custom fatal error handler
\&            my $message = shift;
\&            print "FATAL ERROR: $message\en";
\&        },
\&    });
.Ve
.PP
Each message type can be set to \f(CW0\fR to ignore messages or \f(CW1\fR to
have them printed to \f(CW\*(C`STDERR\*(C'\fR.  They can also be set to reference a list
(the message is appended to the list), a subroutine (which is called,
passing the message as an argument), or any object which implements a
\&\fBlog()\fR method (to which the message is delegated).
.SS "debug($message)"
.IX Subsection "debug($message)"
Generate a debugging message.
.PP
.Vb 1
\&    $log\->debug(\*(AqThe cat sat on the mat\*(Aq);
.Ve
.SS "info($message)"
.IX Subsection "info($message)"
Generate an information message.
.PP
.Vb 1
\&    $log\->info(\*(AqThe pod doors are closed\*(Aq);
.Ve
.SS "warn($message)"
.IX Subsection "warn($message)"
Generate a warning message.
.PP
.Vb 1
\&    $log\->warn(\*(AqThe pod doors are opening\*(Aq);
.Ve
.SS "error($message)"
.IX Subsection "error($message)"
Generate an error message.
.PP
.Vb 1
\&    $log\->error("I\*(Aqm sorry Dave, I can\*(Aqt do that\*(Aq);
.Ve
.SS "fatal($message)"
.IX Subsection "fatal($message)"
Generate a fatal error message.
.PP
.Vb 1
\&    $log\->fatal(\*(AqHAL is dead, aborting mission\*(Aq);
.Ve
.SS "debug_msg($format,@args)"
.IX Subsection "debug_msg($format,@args)"
This method uses the \fBmessage()\fR method inherited
from Badger::Base to generate a debugging message from the arguments
provided.  To use this facility you first need to create your own logging
subclass which defines the message formats that you want to use.
.PP
.Vb 2
\&    package Your::Log;
\&    use base \*(AqBadger::Log\*(Aq;
\&
\&    our $MESSAGES = {
\&        denied => "Denied attempt by %s to %s",
\&    };
\&
\&    1;
.Ve
.PP
You can now use your logging module like so:
.PP
.Vb 2
\&    use Your::Log;
\&    my $log = Your::Log\->new;
\&
\&    $log\->debug_msg( denied => \*(AqArthur\*(Aq, \*(Aqmake tea\*(Aq );
.Ve
.PP
The log message generated will look something like this:
.PP
# \s-1TODO\s0
.SS "info_msg($format,@args)"
.IX Subsection "info_msg($format,@args)"
This method uses the \fBmessage()\fR method inherited
from Badger::Base to generate an info message from the arguments
provided.  See \fBdebug_msg()\fR for an example of using message formats.
.SS "warn_msg($format,@args)"
.IX Subsection "warn_msg($format,@args)"
This method uses the \fBmessage()\fR method inherited
from Badger::Base to generate a warning message from the arguments
provided.  See \fBdebug_msg()\fR for an example of using message formats.
.SS "error_msg($format,@args)"
.IX Subsection "error_msg($format,@args)"
This method uses the \fBmessage()\fR method inherited
from Badger::Base to generate an error message from the arguments
provided.  See \fBdebug_msg()\fR for an example of using message formats.
.SS "fatal_msg($format,@args)"
.IX Subsection "fatal_msg($format,@args)"
This method uses the \fBmessage()\fR method inherited
from Badger::Base to generate a fatal error message from the arguments
provided.  See \fBdebug_msg()\fR for an example of using message formats.
.ie n .SS "log($level, $message)"
.el .SS "log($level, \f(CW$message\fP)"
.IX Subsection "log($level, $message)"
This is the general-purpose logging method that the above methods call.
.PP
.Vb 1
\&    $log\->log( info => \*(Aqstar child is here\*(Aq );
.Ve
.ie n .SS "level($level, $action)"
.el .SS "level($level, \f(CW$action\fP)"
.IX Subsection "level($level, $action)"
This method is used to get or set the action for a particular level.
When called with a single argument, it returns the current action
for that level.
.PP
.Vb 1
\&    my $debug = $log\->level(\*(Aqdebug\*(Aq);
.Ve
.PP
When called with two arguments it sets the action for the log level
to the second argument.
.PP
.Vb 5
\&    $log\->level( debug => 0 );      # disable
\&    $log\->level( info  => 1 );      # enable
\&    $log\->level( warn  => $list );  # push to list
\&    $log\->level( error => $code );  # call code
\&    $log\->level( fatal => $log2 );  # delegate to another log
.Ve
.SS "enable($level)"
.IX Subsection "enable($level)"
This method can be used to enable one or more logging levels.
.PP
.Vb 1
\&    $log\->enable(\*(Aqdebug\*(Aq, \*(Aqinfo\*(Aq, \*(Aqwarn\*(Aq);
.Ve
.SS "disable($level)"
.IX Subsection "disable($level)"
This method can be used to disable one or more logging levels.
.PP
.Vb 1
\&    $log\->disable(\*(Aqerror\*(Aq, \*(Aqfatal\*(Aq);
.Ve
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
.SS "_error_msg($format,@args)"
.IX Subsection "_error_msg($format,@args)"
The \fBerror_msg()\fR method redefines the \fBerror_msg()\fR
method inherited from Badger::Base (which can be considered both a bug and
a feature).  The internal \f(CW\*(C`_error_msg()\*(C'\fR method effectively bypasses the
new method and performs the same functionality as the base class method, in
throwing an error as an exception.
.SS "_fatal_msg($format,@args)"
.IX Subsection "_fatal_msg($format,@args)"
As per \fB_error_msg()\fR, this method provides access to the functionality
of the \fBfatal_msg()\fR method in Badger::Base.
.SH "AUTHOR"
.IX Header "AUTHOR"
Andy Wardley <http://wardley.org/>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2005\-2022 Andy Wardley.  All Rights Reserved.
.PP
This module 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"
Badger::Log::File