/ 
Log-Stack-0.001
River stage zero No dependents
/ Log::Stack

NAME

Log::Stack - Cache log messages and throw them later

VERSION

version 0.001

SYNOPSIS

my $logger = Log::Stack->new($target);

$logger->log($level => $message);

# ...later:
$logger->throw;
# which simply calls $target->log(...) for each cached message

METHODS

new

my $logger = Log::Stack->new($target, %defaults);

For $target see "LOGGING TARGET".

For %defaults see "DEFAULT VALUES".

Hint: $target may be omitted, but then /throw requires a target at last.

set

Set or override a default value for %extra_arguments in "log"

$logger->set($key => $val);
$logger->set($key1 => $val2, $key2 => $val2, ...);

See also "DEFAULT VALUES".

log

Cache a log message, with support for optional additional arguments

$logger->log($level, $message, %extra_arguments);

See also "DEFAULT VALUES".

throw

Push all cached messages to the log target, specified in the constructor:

$logger->throw;

If the target was absent in the constructor, this method requires the target at this point or it will croak:

$logger->throw($target);

Or use another target, regardless of the target specified in the constructor:

my $logger = Log::Stack->new($target1);
# use here (and only here) another target:
$logger->throw($target2);

If there are no cached messages, this method does almost nothing.

flush

Discard all cached messages.

$logger->flush;

hook

$logger->hook($name, $coderef);

Currently these hooks are defined:

  • init

    Called when the first attemp to "log" is made, even after "throw" and "flush".

  • before

    Called in "throw" when cached messages are available and before they are sent to the target.

  • after

    Called in "throw" after cached messages are sent to the target.

  • cleanup

    Called in "throw" and "flush" after messages are sent or flushed.

DEFAULT VALUES

If logging defaults are defined, the %extra_arguments hash in "log" is filled with these defaults (specified in the constructor or later with "set").

Whenever a default value is a CodeRef, the CodeRef will be called with $level and $message as arguments:

my $logger = Log::Stack->new($target,
    hint => sub {
        my ($level, $msg) = @_;
        return "the level is $level.";
    }
);
$logger->log(alert => "Caveat!");
# The cached arguments are now:
('alert' => 'Caveat', 'hint' => 'the level is alert.');

This is useful for setting the real timestamp:

my $logger = Log::Stack->new($target,
    time => \&CORE::time,
);

Or set an unique id in order to group messages together:

$logger->set(id => get_some_random_number());
$logger->log(...);
$logger->throw;

$logger->set(id => get_another_random_number());
$logger->log(...);
$logger->throw;

The defaults are NOT resseted after "throw" or "discard". Use hooks instead:

$logger->hook(init => sub {
    shift->set(id => get_unique_id());
});

LOGGING TARGET

The logging target must be a blessed reference which has a method called log or simply a CodeRef. That's all.

This should apply to most logging engines, like Log::Log4perl, Log::Dispatch, Log::Radis, AnyEvent::Log, ...

For Log::Any this CodeRef may help:

$target = sub {
    my ($level, $msg) = @_;
    $log_any->$level($msg) if $log_any->can($level);
};

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/zurborg/liblog-stack-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

David Zurborg <zurborg@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by David Zurborg.

This is free software, licensed under:

The ISC License