/ 
MooX-Role-Chatty-1.01
River stage one • 2 direct dependents • 2 total dependents
/ MooX::Role::Chatty

NAME

MooX::Role::Chatty - Simple way to generate progress messages

SYNOPSIS

package My::Worker;
use Moo 2;
with 'MooX::Role::Chatty';

sub munge_widget {
  ...
  # Produce informational message
  $self->remark("Starting to munge widget #$ct\n") if $self->verbose;
  ...
  # More detailed trace; output only if $self->verbose >= 2
  $self->remark({ level => 2,
                  message => "Munging step 3 yielded $result\n" });
  # Ditto for level 3, with simple formatting
  $self->remark({ level => 3,
                  message => [ "Munging params: %d, %d, %s\n",
                               $gain, $threshold, $algorithm ] });
}

# Or use Log::Any-style API with compatible logger
sub munge_widget_more {
  ...
  $self->logger->notice("Starting to munge widget #$ct\n");
  ...
  $self->logger->info("Munging step 3 yielded $result\n");
  $self->logger->debugf("Munging params: %d, %d, %s\n",
                         $gain, $threshold, $algorithm);
  # Logs even when $self->verbose == 0
  $self->logger->emergency("The sky is falling!")
}

# Elsewhere
my $worker = My::Worker->new(verbose => 2, ...);
$worker->munge_widget(...);  # Sit back and watch log

DESCRIPTION

One of the common uses for logging packages is providing feedback to the user about the progress of long-running operations, or about details of what the program is doing to aid in debugging. MooX::Role::Chatty aims to provide a few simple, lightweight tools you can use to make this job a bit easier. It does not provide logging facilities itself, just a way to connect to them, and to let the user specify how much information she wants to see.

In keeping with the idea of TMTOWTDI, there are a few different ways to use MooX::Role::Chatty. The simplest is to examine the "verbose" attribute directly in your code, and call "remark" whenever you want to say something based on the current verbosity level. If you prefer labelling your logging calls by name, you can also call "logger" to get at the logging engine, on which you can call any of the logging methods it supports.

MANAGING LOGGERS

MooX::Role::Chatty tries to make the common cases easy. To that end, you don't need to worry about setting up "logger" if you don't want to. If you haven't explicitly set this attribute, the first time you need it (by calling "logger" or "remark") a default logger will be instantiated for you. This logger is a Log::Any::Proxy, so you can call any of the methods supported by Log::Any to generate messages. A corollary of this behavior is that you have to have Log::Any installed, or a fatal error occurs.

A brief timestamp is prepended to each line of the message. The logger is connected to a Log::Any::Adapter::Carp adapter that passes on logged messages but suppresses file/line information. The result is that log messages are sent to STDERR, though you can redirect them via $SIG{__WARN__} if you want.

The "verbose" attribute determines the level of logging: a level of 1 corresponds to a log level of notice, 2 to info, and so on. Although less common, you can also go the other way: -1 corresponds to warn, -2 to error, etc. A "verbose" level of 0 is special: it suppresses any output from "remark", and of the Log::Any levels only emergency will produce output.

If you want to use the default Log::Any::Proxy, but not the default output adapter, you're free to register your own adapter to deal with the MooX::Role::Chatty category. If you do, though, you need to manage the adapter if you change "verbose", since Log::Any doesn't provide an API to update the log_level of an existing adapter.

Finally, if Log::Any isn't your favorite among the plethora of logging packages available, you can set "logger" yourself, to any object that responds to info and warn methods. Most of the more established Perl logging packages fill the bill, like Log::Dispatch or Log::Log4perl, in addition to Log::Any. For that matter, if you like the behavior of Log::Any but want output from your module to be different from MooX::Role::Chatty logging elsewhere in your application, you can use an instance of an adapter class directly. Again, if you set "logger" directly, it's your responsibility to update the logger's behavior as appropriate if you reset "verbose".

ATTRIBUTES

verbose

The level of output logged. Higher values typically indicate that more detailed information should be provided.

For the behavior of the default logger in response to different "verbose" settings, see "MANAGING LOGGERS".

Defaults to 0, and can be updated.

logger
get_logger

The logging engine to be used for output.

The default is described above in "MANAGING LOGGERS".

Although you usually won't want to, you can update "logger", or clear it via clear_logger. In the latter case, if you output a message before setting "logger", a new default logger will be instantiated.

The "get_logger" alias is provided for ease of use by writers accustomed to Log::Any; it is identical to "logger".

METHODS

In addition to the attribute accessors, one method is provided:

remark($info)

If "verbose" is non-zero, produce a log message, based on the contents of $info as described below. This message is output output at the notice log level (or info if "logger" doesn't respond to notice).

  • If $info is a hash reference, check the value associated with the level key against "verbose". If level is less than "verbose", do nothing. Otherwise, use the value associated with the message key as the log message in place of $info (subject to the two rules below).

    Note: It's important, but sometimes confusing, to keep in mind the difference between the target verbosity level (which is what level specifies), and the actual call to the logger, which is always at the notice (or info) log level. In other words, saying level => -3 does NOT get you a call to critical.

  • If $info is a simple scalar, use it as the log message.

  • If $info is an array reference, use the contents as arguments to format a message. For a Log::Any-based logger, they're simply passed to noticef. Otherwise, they're passed to "sprintf" in perfunc, and the result passed to notice (or info).

EXPORT

None.

SEE ALSO

MooX::Role::Logger, an even more lightweight way for your code to use Log::Any.

Log::Any, Log::Any::Adapter::Carp

BUGS AND CAVEATS

Are there, for certain, but have yet to be cataloged.

VERSION

version 1.01

AUTHOR

Charles Bailey <cbail@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Charles Bailey

This software may be used under the terms of the Artistic License version 2 or the GNU Lesser General Public License version 3, as the user prefers.