view release on metacpan or  search on metacpan

inc/bundle/Log/Message.pm  view on Meta::CPAN

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<Log::Message::Item> 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<Log::Message::Item> object.
For example, if a message is logged with the 'carp' level, the 'carp'
handler from L<Log::Message::Handlers> will be called.
See the L<Log::Message::Handlers> 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<Log::Message::Config> handles the creation of these configurations.

Configuration can be specified in 4 ways:

=over 4

=item *

As a configuration file when you C<use Log::Message>

=item *

As arguments when you C<use Log::Message>

=item *

As a configuration file when you create a new L<Log::Message> object.
(The config will then only apply to that object if you marked it as
private)

=item *

As arguments when you create a new Log::Message object.

You should never need to use the L<Log::Message::Config> module yourself,
as this is transparently done by L<Log::Message>, but its manpage does
provide an explanation of how you can create a config file.

=back

=back

=head1 Options

When using Log::Message, or creating a new Log::Message object, you can
supply various options to alter its behaviour.
Of course, there are sensible defaults should you choose to omit these
options.

Below an explanation of all the options and how they work.

=over 4

=item config

The path to a configuration file to be read.
See the manpage of L<Log::Message::Config> for the required format

These options will be overridden by any explicit arguments passed.

=item private

Whether to create, by default, private or shared objects.
If you choose to create shared objects, all Log::Message objects will
use the same stack.

This means that even though every module may make its own $log object
they will still be sharing the same error stack on which they are
putting errors and from which they are retrieving.

This can be useful in big projects.

If you choose to create a private object, then the stack will of
course be private to this object, but it will still fall back to the
shared config should no private config or overriding arguments be
provided.

=item verbose

Log::Message makes use of another module to validate its arguments,
which is called L<Params::Check>, which is a lightweight, yet
powerful input checker and parser. (See the L<Params::Check>
manpage for details).

The verbose setting will control whether this module will
generate warnings if something improper is passed as input, or merely
silently returns undef, at which point Log::Message will generate a
warning.

It's best to just leave this at its default value, which is '1'

=item tag

The tag to add to messages if none was provided. If neither your
config, nor any specific arguments supply a tag, then Log::Message will
set it to 'NONE'