view release on metacpan or  search on metacpan

lib/MooX/Role/Chatty.pm  view on Meta::CPAN

  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

=head1 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.
L<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 L<MooX::Role::Chatty>.  The simplest is to examine the
L</verbose> attribute directly in your code, and call L</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 L</logger> to get at the logging engine, on which
you can call any of the logging methods it supports.

=head2 MANAGING LOGGERS

L<MooX::Role::Chatty> tries to make the common cases easy.  To that
end, you don't need to worry about setting up L</logger> if you don't
want to.  If you haven't explicitly set this attribute, the first time
you need it (by calling L</logger> or L</remark>) a default logger
will be instantiated for you.  This logger is a L<Log::Any::Proxy>, so
you can call any of the methods supported by L<Log::Any> to generate
messages.  A corollary of this behavior is that you have to have
L<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 L<Log::Any::Adapter::Carp> adapter that passes
on logged messages but suppresses file/line information.  The result
is that log messages are sent to F<STDERR>, though you can redirect
them via C<$SIG{__WARN__}> if you want.

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

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

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

=head2 ATTRIBUTES

=over 4

=item 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
L</verbose> settings, see L</MANAGING LOGGERS>.

Defaults to C<0>, and can be updated.

=item logger

=item get_logger

The logging engine to be used for output.

The default is described above in L<MANAGING LOGGERS>.

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