use strict;
use warnings;
-our $VERSION = '0.00305';
+our $VERSION = '0.004201';
my @levels = qw(debug trace warn info error fatal);
$Get_Logger ||
$Default_Logger{$package} ||
die q( no logger set! you can't try to log something without a logger! )
- )->($package);
+ )->($package, { caller_level => 3 });
}
sub set_logger {
use Log::Log4perl ':easy';
Log::Log4perl->easy_init($DEBUG);
-
my $logger = Log::Log4perl->get_logger;
set_logger $logger;
log_debug { 'program started' };
sub foo {
- with_logger(Log::Contextual::SimpleLogger->new({
- levels => [qw( trace debug )]
- }) => sub {
+
+ my $minilogger = Log::Contextual::SimpleLogger->new({
+ levels => [qw( trace debug )]
+ });
+
+ with_logger $minilogger => sub {
log_trace { 'foo entered' };
my ($foo, $bar) = Dlog_trace { "params for foo: $_" } @_;
# ...
log_trace { 'foo left' };
- });
+ };
}
foo();
=head1 DESCRIPTION
-This module is a simple interface to extensible logging. It is bundled with a
-really basic logger, L<Log::Contextual::SimpleLogger>, but in general you
-should use a real logger instead of that. For something more serious but not
-overly complicated, try L<Log::Dispatchouli> (see L</SYNOPSIS> for example.)
+Major benefits:
+
+=over 2
+
+=item * Efficient
+
+The logging functions take blocks, so if a log level is disabled, the
+block will not run:
+
+ # the following won't run if debug is off
+ log_debug { "the new count in the database is " . $rs->count };
+
+Similarly, the C<D> prefixed methods only C<Dumper> the input if the level is
+enabled.
+
+=item * Handy
+
+The logging functions return their arguments, so you can stick them in
+the middle of expressions:
+
+ for (log_debug { "downloading:\n" . join qq(\n), @_ } @urls) { ... }
+
+=item * Generic
+
+C<Log::Contextual> is an interface for all major loggers. If you log through
+C<Log::Contextual> you will be able to swap underlying loggers later.
+
+=item * Powerful
-The reason for this module is to abstract your logging interface so that
-logging is as painless as possible, while still allowing you to switch from one
-logger to another.
+C<Log::Contextual> chooses which logger to use based on L<< user defined C<CodeRef>s|/LOGGER CODEREF >>.
+Normally you don't need to know this, but you can take advantage of it when you
+need to later
+
+=item * Scalable
+
+If you just want to add logging to your extremely basic application, start with
+L<Log::Contextual::SimpleLogger> and then as your needs grow you can switch to
+L<Log::Dispatchouli> or L<Log::Dispatch> or L<Log::Log4perl> or whatever else.
+
+=back
+
+This module is a simple interface to extensible logging. It exists to
+abstract your logging interface so that logging is as painless as possible,
+while still allowing you to switch from one logger to another.
+
+It is bundled with a really basic logger, L<Log::Contextual::SimpleLogger>,
+but in general you should use a real logger instead of that. For something
+more serious but not overly complicated, try L<Log::Dispatchouli> (see
+L</SYNOPSIS> for example.)
=head1 A WORK IN PROGRESS
use Log::Log4perl ':easy';
Log::Log4perl->easy_init($DEBUG)
- sub arg_logger { $_[1] || Log::Log4perl->get_logger }
+ sub arg_default_logger { $_[1] || Log::Log4perl->get_logger }
sub arg_levels { [qw(debug trace warn info error fatal custom_level)] }
- # and *maybe* even these:
+ # or maybe instead of default_logger
sub arg_package_logger { $_[1] }
- sub arg_default_logger { $_[1] }
-Note the C<< $_[1] || >> in C<arg_logger>. All of these methods are passed the
-values passed in from the arguments to the subclass, so you can either throw
-them away, honor them, die on usage, or whatever. To be clear, if you define
-your subclass, and someone uses it as follows:
+ # and almost definitely not this, which is only here for completeness
+ sub arg_logger { $_[1] }
+
+Note the C<< $_[1] || >> in C<arg_default_logger>. All of these methods are
+passed the values passed in from the arguments to the subclass, so you can
+either throw them away, honor them, die on usage, or whatever. To be clear,
+if you define your subclass, and someone uses it as follows:
- use MyApp::Log::Contextual -logger => $foo, -levels => [qw(bar baz biff)];
+ use MyApp::Log::Contextual -default_logger => $foo,
+ -levels => [qw(bar baz biff)];
-Your C<arg_logger> method will get C<$foo> and your C<arg_levels>
+Your C<arg_default_logger> method will get C<$foo> and your C<arg_levels>
will get C<[qw(bar baz biff)]>;
=head1 FUNCTIONS
my $logger = WarnLogger->new;
set_logger $logger;
-Arguments: C<Ref|CodeRef $returning_logger>
+Arguments: L</LOGGER CODEREF>
C<set_logger> will just set the current logger to whatever you pass it. It
expects a C<CodeRef>, but if you pass it something else it will wrap it in a
}
};
-Arguments: C<Ref|CodeRef $returning_logger, CodeRef $to_execute>
+Arguments: L</LOGGER CODEREF>, C<CodeRef $to_execute>
C<with_logger> sets the logger for the scope of the C<CodeRef> C<$to_execute>.
As with L</set_logger>, C<with_logger> will wrap C<$returning_logger> with a
Arguments: C<CodeRef $returning_message, @args>
-All of the following six functions work the same except that a different method
+C<log_$level> functions all work the same except that a different method
is called on the underlying C<$logger> object. The basic pattern is:
sub log_$level (&@) {
If you want complete inspection of passthrough data, take a look at the
L</Dlog_$level> functions.
-=head3 log_trace
-
- log_trace { 'entered method foo with args ' join q{,}, @args };
-
-=head3 log_debug
+Which functions are exported depends on what was passed to L</-levels>. The
+default (no C<-levels> option passed) would export:
- log_debug { 'entered method foo' };
+=over 2
-=head3 log_info
+=item log_trace
- log_info { 'started process foo' };
+=item log_debug
-=head3 log_warn
+=item log_info
- log_warn { 'possible misconfiguration at line 10' };
+=item log_warn
-=head3 log_error
+=item log_error
- log_error { 'non-numeric user input!' };
+=item log_fatal
-=head3 log_fatal
-
- log_fatal { '1 is never equal to 0!' };
+=back
=head2 logS_$level
"fRUE"
"fiSMBoC"
-=head3 Dlog_trace
-
- my ($foo, $bar) = Dlog_trace { "entered method foo with args: $_" } @_;
-
-=head3 Dlog_debug
-
- Dlog_debug { "random data structure: $_" } { foo => $bar };
+Which functions are exported depends on what was passed to L</-levels>. The
+default (no C<-levels> option passed) would export:
-=head3 Dlog_info
+=over 2
- return Dlog_info { "html from method returned: $_" } "<html>...</html>";
+=item Dlog_trace
-=head3 Dlog_warn
+=item Dlog_debug
- Dlog_warn { "probably invalid value: $_" } $foo;
+=item Dlog_info
-=head3 Dlog_error
+=item Dlog_warn
- Dlog_error { "non-numeric user input! ($_)" } $port;
+=item Dlog_error
-=head3 Dlog_fatal
+=item Dlog_fatal
- Dlog_fatal { '1 is never equal to 0!' } 'ZOMG ZOMG' if 1 == 0;
+=back
=head2 DlogS_$level
my $pals_rs = DlogS_debug { "pals resultset: $_" }
$schema->resultset('Pals')->search({ perlers => 1 });
+=head1 LOGGER CODEREF
+
+Anywhere a logger object can be passed, a coderef is accepted. This is so
+that the user can use different logger objects based on runtime information.
+The logger coderef is passed the package of the caller the caller level the
+coderef needs to use if it wants more caller information. The latter is in
+a hashref to allow for more options in the future.
+
+The following is an example that uses the information passed to the logger
+coderef. It sets the global logger to C<$l3>, the logger for the C<A1>
+package to C<$l1>, except the C<lol> method in C<A1> which uses the C<$l2>
+logger and lastly the logger for the C<A2> package to C<$l2>.
+
+ my $complex_dispatcher = do {
+
+ my $l1 = ...;
+ my $l2 = ...;
+ my $l3 = ...;
+
+ my %registry = (
+ -logger => $l3,
+ A1 => {
+ -logger => $l1,
+ lol => $l2,
+ },
+ A2 => { -logger => $l2 },
+ );
+
+ sub {
+ my ( $package, $info ) = @_;
+
+ my $logger = $registry{'-logger'};
+ if (my $r = $registry{$package}) {
+ $logger = $r->{'-logger'} if $r->{'-logger'};
+ my (undef, undef, undef, $sub) = caller($info->{caller_level});
+ $sub =~ s/^\Q$package\E:://g;
+ $logger = $r->{$sub} if $r->{$sub};
+ }
+ return $logger;
+ }
+ };
+
+ set_logger $complex_dispatcher;
+
=head1 LOGGER INTERFACE
Because this module is ultimately pretty looking glue (glittery?) with the
=head1 COPYRIGHT
-Copyright (c) 2010 the Log::Contextual L</AUTHOR> and L</DESIGNER> as listed
+Copyright (c) 2012 the Log::Contextual L</AUTHOR> and L</DESIGNER> as listed
above.
=head1 LICENSE
projects / p5sagit/Log-Contextual.git / blobdiff