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

cpanm Log::Stack

perl -MCPAN -e shell
install Log::Stack