The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.

NAME

Log::Tiny - Log data with as little code as possible

VERSION

Version 1.1

SYNOPSIS

This module aims to be a light-weight implementation *similiar* to Log::Log4perl for logging data to a file.

Its use is very straight forward:

use Log::Tiny;

my $log = Log::Tiny->new( 'myapp.log' ) or 
  die 'Could not log! (' . Log::Tiny->errstr . ')';

foreach ( 1 .. 20 ) { 
    $log->DEBUG( "Performing extensive computations on $_" ) if $DEBUG;
    unless ( extensively_compute( $_ ) ) {
        $log->WARN( 
            "Investigating error (this may take a while)..." 
        );
        $log->ERROR( find_error() );
        save_state();
        exit 1;
    } else {
        $log->INFO( "Everything's A-OK!" );
    }
}

FUNCTIONS

new

Create a new Log::Tiny object. You must define a log file to append to, and, optionally, a format.

format

You may, at any time, change the format. The log format is similiar in style to the sprintf you know and love; and, as a peek inside the source of this module will tell you, sprintf is used internally. However, be advised that these log formats are not sprintf.

Interpolated data are specified by an percent sign ( % ), followed by a character. A literal percent sign can be specified via two in succession ( %% ). You may use any of the formatting attributes as noted in perlfunc, under "sprintf" (perldoc -f sprintf).

Internally, the format routine uses a data structure (hash) that can be seen near the beggining of this package. Any unrecognized interpolation variables will be returned literally. This means that, assuming $format{d} does not exist, "%d" in your format will result in "%d" being outputted to the log file. No interpolation will occur.

You may, of course, decide to modify the format data structure. I have done my best to ensure a wide range of variables for your usage, however. They are (currently) as follows:

c => category       => The method called (see below for more info)
C => lcategory      => lowercase category
f => program_file   => Value of $0
F => caller_file    => Calling file
g => gmtime         => Output of scalar L<gmtime> (localized date string)
L => caller_line    => Calling line
m => message        => Message sent to the log method
n => newline        => Value of $/
o => osname         => Value of $^O
p => pid            => Value of $$
P => caller_pkg     => Calling package
r => runtime        => Seconds the current process has been running for
S => caller_sub     => Calling subroutine
t => localtime      => Output of scalar L<localtime> (localized date 
                       string)
T => unix_time      => Time since epoch (L<time>)
u => effective_uid  => Value of $>
U => real_uid       => Value of $<
v => long_perl_ver  => Value of $] (5.008008)
V => short_perl_ver => A "short" string for the version ("5.8.8")

See perlvar for information on the used global variables, and perlfunc (under "caller") or perldoc -f caller for information on the "calling" variables. Oh, and make sure you add %n if you want newines.

WHATEVER_YOU_WANT (log a message)

This method is whatever you want it to be. Any method called on a Log::Tiny object that is not reserved will be considered an attempt to log in the category named the same as the method that was caleld. Currently, only in-use methods are reserved; However, to account for expansion, please only use uppercase categories. See formats above for information on customizing the log messages.

errstr

Called as a class method, Log::Tiny-errstr > reveals the error that Log::Tiny encountered in creation or invocation.

log_only

Log only the given categories

AUTHOR

Jordan M. Adler, <jmadler at cpan.org>

BUGS

Please report any bugs or feature requests to bug-log-tiny at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Log-Tiny. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Log::Tiny

You can also look for information at:

ACKNOWLEDGEMENTS

Much thanks to Michael Schilli CPAN:mschilli for his great work on Log::Log4perl, of which this module's formatting concept is largely based upon.

COPYRIGHT & LICENSE

Copyright 2007-2022 Jordan M. Adler, all rights reserved.

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