package Log::Message;
use strict;
use Params::Check qw[check];
use Log::Message::Item;
use Log::Message::Config;
use Locale::Maketext::Simple Style => 'gettext';
local $Params::Check::VERBOSE = 1;
BEGIN {
use vars qw[$VERSION @ISA $STACK $CONFIG];
$VERSION = 0.02;
$STACK = [];
}
=pod
=head1 NAME
Log::Message - A generic message storing mechanism;
=head1 SYNOPSIS
use Log::Message private => 0, config => '/our/cf_file';
my $log = Log::Message->new( private => 1,
level => 'log',
config => '/my/cf_file',
);
$log->store('this is my first message');
$log->store( message => 'message #2',
tag => 'MY_TAG',
level => 'carp',
extra => ['this is an argument to the handler'],
);
my @last_five_items = $log->retrieve(5);
my @items = $log->retrieve( tag => qr/my_tag/i,
message => qr/\d/,
remove => 1,
);
my @items = $log->final( level => qr/carp/, amount => 2 );
my $first_error = $log->first()
# croak with the last error on the stack
$log->final->croak;
# empty the stack
$log->flush();
=head1 DESCRIPTION
Log::Message is a generic message storage mechanism.
It allows you to store messages on a stack -- either shared or private
-- and assign meta-data to it.
Some meta-data will automatically be added for you, like a timestamp
and a stack trace, but some can be filled in by the user, like a tag
by which to identify it or group it, and a level at which to handle
the message (for example, log it, or die with it)
Log::Message also provides a powerful way of searching through items
by regexes on messages, tags and level.
=head1 Hierarchy
There are 4 modules of interest when dealing with the Log::Message::*
modules:
=over 4
=item Log::Message
Log::Message provides a few methods to manipulate the stack it keeps.
It has the option of keeping either a private or a public stack.
More on this below.
=item Log::Message::Item
These are individual message items, which are objects that contain
the user message as well as the meta-data described above.
See the L manpage to see how to extract this
meta-data and how to work with the Item objects.
You should never need to create your own Item objects, but knowing
about their methods and accessors is important if you want to write
your own handlers. (See below)
=item Log::Message::Handlers
These are a collection of handlers that will be called for a level
that is used on a L object.
For example, if a message is logged with the 'carp' level, the 'carp'
handler from L will be called.
See the L manpage for more explanation about how
handlers work, which one are available and how to create your own.
=item Log::Message::Config
Per Log::Message object, there is a configuration required that will
fill in defaults if the user did not specify arguments to override
them (like for example what tag will be set if none was provided),
L handles the creation of these configurations.
Configuration can be specified in 4 ways:
=over 4
=item *
As a configuration file when you C