Badger::Log(3pm)

📦
version 0.16 · 4 versions
, in debian trixie, ubuntu noble, ubuntu resolute

💖 Badger::Log 💖

okay bestie, gather round — this is Badger::Log(3pm), the little logging module that comes with Badger. It's a log for errors, warnings and other messages, and it is adorably simple on purpose.

✨ SYNOPSIS ✨

use Badger::Log;

my $log = Badger::Log->new({
    debug => 0,      # ignore debug messages
    info  => 1,      # print info messages
    warn  => \@warn, # add warnings to list
    error => $log2,  # delegate errors to $log2
    fatal => sub {   # custom fatal error handler
        my $message = shift;
        print "FATAL ERROR: $message\n";
    },
});

$log->debug('a debug message');
$log->info('an info message');
$log->warn('a warning message');
$log->error('an error message');
$log->fatal('a fatal error message');

🌸 DESCRIPTION 🌸

So this module defines a simple base class for logging messages that your application generates. It is intentionally very simple in design — like, it gives you the bare minimum in functionality, and the possibility for extension by subclassing. That's the whole vibe. 🎀

ngl, it offers little, if anything, over the many other fine logging modules available from CPAN. 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 "out of the box". iykyk. ✨

There are five message categories:

  • debug — A debugging message.
  • info — A message providing some general information.
  • warn — A warning message.
  • error — An error message.
  • fatal — A fatal error message.

🎀 CONFIGURATION OPTIONS 🎀

debug

Flag to indicate if debugging messages should be generated and output. The default value is 0. It can be set to 1 to enable debugging messages, or to one of the other reference values described in the documentation for the new() method. 💅

info

Flag to indicate if information messages should be generated and output. The default value is 0. It can be set to 1 to enable information messages, or to one of the other reference values described in the documentation for the new() method.

warn

Flag to indicate if warning messages should be generated and output. The default value is 1. It can be set to 0 to disable warning messages, or to one of the other reference values described in the documentation for the new() method.

error

Flag to indicate if error messages should be generated and output. The default value is 1. It can be set to 0 to disable error messages, or to one of the other reference values described in the documentation for the new() method.

fatal

Flag to indicate if fatal messages should be generated and output. The default value is 1. It can be set to 0 to disable fatal error messages (at your own peril), or to one of the other reference values described in the documentation for the new() method.

format

This option can be used to define a different log message format. ✨

my $log = Badger::Log->new(
    format => '[<level>] [<time>] <message>',
);

The default message format is:

[<time>] [<system>] [<level>] <message>

The <XXX> snippets are replaced with their equivalent values:

time        The current local time
system      A system identifier, defaults to 'Badger'
level       The message level: debug, info, warn, error or fatal
message     The log message itself

The format can also be set using a $FORMAT package variable in a subclass of Badger::Log.

package Your::Log::Module;
use base 'Badger::Log';
our $FORMAT = '[<level>] [<time>] <message>';
1;

system

A system identifier which is inserted into each message via the <system> snippet. See format for further information. The default value is "Badger". 🦡

my $log = Badger::Log->new(
    system => 'MyApp',
);

The system identifier can also be set using a $SYSTEM package variable in a subclass of Badger::Log.

package Your::Log::Module;
use base 'Badger::Log';
our $SYSTEM = 'MyApp';
1;

strftime

This option can be used to set the format for the timestamp added to messages via the <time> snippet.

my $log = Badger::Log->new(
    strftime => '%a %b %d %Y',
);

The format string is passed to the format() method of Badger::Timestamp. 🕰️

💅 METHODS 💅

new(%options)

Constructor method which creates a new Badger::Log object. It accepts a list of named parameters or reference to hash of configuration options that define how each message type should be handled. main character energy fr fr.

my $log = Badger::Log->new({
    debug => 0,      # ignore debug messages
    info  => 1,      # print info messages
    warn  => \@warn, # add warnings to list
    error => $log2,  # delegate errors to $log2
    fatal => sub {   # custom fatal error handler
        my $message = shift;
        print "FATAL ERROR: $message\n";
    },
});

Each message type can be set to 0 to ignore messages or 1 to have them printed to STDERR. 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 log() method (to which the message is delegated). 👑

debug($message)

Generate a debugging message.

$log->debug('The cat sat on the mat');

info($message)

Generate an information message.

$log->info('The pod doors are closed');

warn($message)

Generate a warning message.

$log->warn('The pod doors are opening');

error($message)

Generate an error message.

$log->error("I'm sorry Dave, I can't do that');

fatal($message)

Generate a fatal error message.

$log->fatal('HAL is dead, aborting mission');

debug_msg($format,@args)

This method uses the message() 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. 🦋

package Your::Log;
use base 'Badger::Log';

our $MESSAGES = {
    denied => "Denied attempt by %s to %s",
};

1;

You can now use your logging module like so:

use Your::Log;
my $log = Your::Log->new;

$log->debug_msg( denied => 'Arthur', 'make tea' );

The log message generated will look something like this:

# TODO

info_msg($format,@args)

This method uses the message() method inherited from Badger::Base to generate an info message from the arguments provided. See debug_msg() for an example of using message formats.

warn_msg($format,@args)

This method uses the message() method inherited from Badger::Base to generate a warning message from the arguments provided. See debug_msg() for an example of using message formats.

error_msg($format,@args)

This method uses the message() method inherited from Badger::Base to generate an error message from the arguments provided. See debug_msg() for an example of using message formats.

fatal_msg($format,@args)

This method uses the message() method inherited from Badger::Base to generate a fatal error message from the arguments provided. See debug_msg() for an example of using message formats.

log($level, $message)

This is the general-purpose logging method that the above methods call. ✨

$log->log( info => 'star child is here' );

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.

my $debug = $log->level('debug');

When called with two arguments it sets the action for the log level to the second argument. 💖

$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

enable($level)

This method can be used to enable one or more logging levels.

$log->enable('debug', 'info', 'warn');

disable($level)

This method can be used to disable one or more logging levels.

$log->disable('error', 'fatal');

🧚 INTERNAL METHODS 🧚

_error_msg($format,@args)

The error_msg() method redefines the error_msg() method inherited from Badger::Base (which can be considered both a bug and a feature 👀). The internal _error_msg() method effectively bypasses the new method and performs the same functionality as the base class method, in throwing an error as an exception.

_fatal_msg($format,@args)

As per _error_msg(), this method provides access to the functionality of the fatal_msg() method in Badger::Base.

👑 AUTHOR 👑

Andy Wardley <http://wardley.org/>

Copyright (C) 2005-2022 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🫶 SEE ALSO 🫶

Badger::Log::File

and that's the whole page bestie, slay 💅 — this beauty shipped as perl v5.36.0, dated 2023-08-28, and yes, it's Badger::Log(3pm). periodt. ✨

📦 where this page comes from