use strict;
use warnings;
-our $VERSION = '0.00100';
+our $VERSION = '0.004001';
-require Exporter;
+my @levels = qw(debug trace warn info error fatal);
+
+use Exporter::Declare;
+use Exporter::Declare::Export::Generator;
use Data::Dumper::Concise;
+use Scalar::Util 'blessed';
+
+my @dlog = ((map "Dlog_$_", @levels), (map "DlogS_$_", @levels));
+
+my @log = ((map "log_$_", @levels), (map "logS_$_", @levels));
-BEGIN { our @ISA = qw(Exporter) }
-
-my @dlog = (qw(
- Dlog_debug DlogS_debug
- Dlog_trace DlogS_trace
- Dlog_warn DlogS_warn
- Dlog_info DlogS_info
- Dlog_error DlogS_error
- Dlog_fatal DlogS_fatal
- ));
-
-my @log = (qw(
- log_debug
- log_trace
- log_warn
- log_info
- log_error
- log_fatal
- ));
-
-our @EXPORT_OK = (
+eval {
+ require Log::Log4perl;
+ die if $Log::Log4perl::VERSION < 1.29;
+ Log::Log4perl->wrapper_register(__PACKAGE__)
+};
+
+# ____ is because tags must have at least one export and we don't want to
+# export anything but the levels selected
+sub ____ {}
+
+exports ('____',
@dlog, @log,
qw( set_logger with_logger )
);
-our %EXPORT_TAGS = (
- dlog => \@dlog,
- log => \@log,
- all => [@dlog, @log],
-);
+export_tag dlog => ('____');
+export_tag log => ('____');
+import_arguments qw(logger package_logger default_logger);
-sub import {
- my $package = shift;
- die 'Log::Contextual does not have a default import list'
- unless @_;
+sub before_import {
+ my ($class, $importer, $spec) = @_;
- for my $idx ( 0 .. $#_ ) {
- if ( $_[$idx] eq '-logger' ) {
- set_logger($_[$idx + 1]);
- splice @_, $idx, 2;
- last;
+ die 'Log::Contextual does not have a default import list'
+ if $spec->config->{default};
+
+ my @levels = @{$class->arg_levels($spec->config->{levels})};
+ for my $level (@levels) {
+ if ($spec->config->{log}) {
+ $spec->add_export("&log_$level", sub (&@) {
+ _do_log( $level => _get_logger( caller ), shift @_, @_)
+ });
+ $spec->add_export("&logS_$level", sub (&@) {
+ _do_logS( $level => _get_logger( caller ), $_[0], $_[1])
+ });
+ }
+ if ($spec->config->{dlog}) {
+ $spec->add_export("&Dlog_$level", sub (&@) {
+ my ($code, @args) = @_;
+ return _do_log( $level => _get_logger( caller ), sub {
+ local $_ = (@args?Data::Dumper::Concise::Dumper @args:'()');
+ $code->(@_)
+ }, @args );
+ });
+ $spec->add_export("&DlogS_$level", sub (&$) {
+ my ($code, $ref) = @_;
+ _do_logS( $level => _get_logger( caller ), sub {
+ local $_ = Data::Dumper::Concise::Dumper $ref;
+ $code->($ref)
+ }, $ref )
+ });
}
}
- $package->export_to_level(1, $package, @_);
}
-our $Get_Logger;
+sub arg_logger { $_[1] }
+sub arg_levels { $_[1] || [qw(debug trace warn info error fatal)] }
+sub arg_package_logger { $_[1] }
+sub arg_default_logger { $_[1] }
-sub set_logger {
- my $logger = $_[0];
- $logger = do { my $l = $logger; sub { $l } }
- if ref $logger ne 'CODE';
- $Get_Logger = $logger;
-}
-
-sub with_logger {
- my $logger = $_[0];
- $logger = do { my $l = $logger; sub { $l } }
- if ref $logger ne 'CODE';
- local $Get_Logger = $logger;
- $_[1]->();
-}
+sub after_import {
+ my ($class, $importer, $specs) = @_;
+ if (my $l = $class->arg_logger($specs->config->{logger})) {
+ set_logger($l)
+ }
+ if (my $l = $class->arg_package_logger($specs->config->{package_logger})) {
+ _set_package_logger_for($importer, $l)
+ }
-sub log_trace (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->trace($code->(@_))
- if $log->is_trace;
- @_
-}
-
-sub log_debug (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->debug($code->(@_))
- if $log->is_debug;
- @_
-}
-
-sub log_info (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->info($code->(@_))
- if $log->is_info;
- @_
+ if (my $l = $class->arg_default_logger($specs->config->{default_logger})) {
+ _set_default_logger_for($importer, $l)
+ }
}
-sub log_warn (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->warn($code->(@_))
- if $log->is_warn;
- @_
+our $Get_Logger;
+our %Default_Logger;
+our %Package_Logger;
+
+sub _set_default_logger_for {
+ my $logger = $_[1];
+ if(ref $logger ne 'CODE') {
+ die 'logger was not a CodeRef or a logger object. Please try again.'
+ unless blessed($logger);
+ $logger = do { my $l = $logger; sub { $l } }
+ }
+ $Default_Logger{$_[0]} = $logger
}
-sub log_error (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->error($code->(@_))
- if $log->is_error;
- @_
+sub _set_package_logger_for {
+ my $logger = $_[1];
+ if(ref $logger ne 'CODE') {
+ die 'logger was not a CodeRef or a logger object. Please try again.'
+ unless blessed($logger);
+ $logger = do { my $l = $logger; sub { $l } }
+ }
+ $Package_Logger{$_[0]} = $logger
}
-sub log_fatal (&@) {
- my $log = $Get_Logger->();
- my $code = shift;
- $log->fatal($code->(@_))
- if $log->is_fatal;
- @_
+sub _get_logger($) {
+ my $package = shift;
+ (
+ $Package_Logger{$package} ||
+ $Get_Logger ||
+ $Default_Logger{$package} ||
+ die q( no logger set! you can't try to log something without a logger! )
+ )->($package);
}
+sub set_logger {
+ my $logger = $_[0];
+ if(ref $logger ne 'CODE') {
+ die 'logger was not a CodeRef or a logger object. Please try again.'
+ unless blessed($logger);
+ $logger = do { my $l = $logger; sub { $l } }
+ }
-sub logS_trace (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->trace($code->($value))
- if $log->is_trace;
- $value
+ warn 'set_logger (or -logger) called more than once! This is a bad idea!'
+ if $Get_Logger;
+ $Get_Logger = $logger;
}
-sub logS_debug (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->debug($code->($value))
- if $log->is_debug;
- $value
+sub with_logger {
+ my $logger = $_[0];
+ if(ref $logger ne 'CODE') {
+ die 'logger was not a CodeRef or a logger object. Please try again.'
+ unless blessed($logger);
+ $logger = do { my $l = $logger; sub { $l } }
+ }
+ local $Get_Logger = $logger;
+ $_[1]->();
}
-sub logS_info (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->info($code->($value))
- if $log->is_info;
- $value
-}
+sub _do_log {
+ my $level = shift;
+ my $logger = shift;
+ my $code = shift;
+ my @values = @_;
-sub logS_warn (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->warn($code->($value))
- if $log->is_warn;
- $value
+ $logger->$level($code->(@_))
+ if $logger->${\"is_$level"};
+ @values
}
-sub logS_error (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->error($code->($value))
- if $log->is_error;
- $value
-}
+sub _do_logS {
+ my $level = shift;
+ my $logger = shift;
+ my $code = shift;
+ my $value = shift;
-sub logS_fatal (&$) {
- my $log = $Get_Logger->();
- my $code = shift;
- my $value = shift;
- $log->fatal($code->($value))
- if $log->is_fatal;
+ $logger->$level($code->($value))
+ if $logger->${\"is_$level"};
$value
}
-
-
-sub Dlog_trace (&@) {
- my $code = shift;
- my @values = @_;
- return log_trace {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-sub Dlog_debug (&@) {
- my $code = shift;
- my @values = @_;
- log_debug {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-sub Dlog_info (&@) {
- my $code = shift;
- my @values = @_;
- log_info {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-sub Dlog_warn (&@) {
- my $code = shift;
- my @values = @_;
- log_warn {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-sub Dlog_error (&@) {
- my $code = shift;
- my @values = @_;
- log_error {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-sub Dlog_fatal (&@) {
- my $code = shift;
- my @values = @_;
- log_fatal {
- do { local $_ = Data::Dumper::Concise::Dumper @values; $code->() };
- } @values
-}
-
-
-
-sub DlogS_trace (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_trace {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
-sub DlogS_debug (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_debug {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
-sub DlogS_info (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_info {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
-sub DlogS_warn (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_warn {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
-sub DlogS_error (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_error {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
-sub DlogS_fatal (&$) {
- my $code = $_[0];
- my $value = $_[1];
- logS_fatal {
- do { local $_ = Data::Dumper::Concise::Dumper $value; $code->() };
- } $value
-}
-
1;
__END__
=head1 SYNOPSIS
- use Log::Log4perl;
use Log::Contextual qw( :log :dlog set_logger with_logger );
+ use Log::Contextual::SimpleLogger;
+ use Log::Log4perl ':easy';
+ Log::Log4perl->easy_init($DEBUG);
+
- my $logger = sub { Log::Log4perl->get_logger };
+ my $logger = Log::Log4perl->get_logger;
- set_logger { $logger };
+ set_logger $logger;
log_debug { 'program started' };
});
}
+ foo();
+
+Beginning with version 1.008 L<Log::Dispatchouli> also works out of the box
+with C<Log::Contextual>:
+
+ use Log::Contextual qw( :log :dlog set_logger );
+ use Log::Dispatchouli;
+ my $ld = Log::Dispatchouli->new({
+ ident => 'slrtbrfst',
+ to_stderr => 1,
+ debug => 1,
+ });
+
+ set_logger $ld;
+
+ log_debug { 'program started' };
+
=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, take a look at L<Log::Dispatchouli>.
+overly complicated, try L<Log::Dispatchouli> (see L</SYNOPSIS> for example.)
-=head1 OPTIONS
+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.
+
+=head1 A WORK IN PROGRESS
+
+This module is certainly not complete, but we will not break the interface
+lightly, so I would say it's safe to use in production code. The main result
+from that at this point is that doing:
+
+ use Log::Contextual;
+
+will die as we do not yet know what the defaults should be. If it turns out
+that nearly everyone uses the C<:log> tag and C<:dlog> is really rare, we'll
+probably make C<:log> the default. But only time and usage will tell.
+
+=head1 IMPORT OPTIONS
+
+See L</SETTING DEFAULT IMPORT OPTIONS> for information on setting these project
+wide.
+
+=head2 -logger
When you import this module you may use C<-logger> as a shortcut for
L<set_logger>, for example:
BEGIN { $var_log = VarLogger->new }
use Log::Contextual qw( :dlog ), -logger => $var_log;
-=head1 A WORK IN PROGRESS
+=head2 -levels
-This module is certainly not complete, but we will not break the interface
-lightly, so I would say it's safe to use in production code. The main result
-from that at this point is that doing:
+The C<-levels> import option allows you to define exactly which levels your
+logger supports. So the default,
+C<< [qw(debug trace warn info error fatal)] >>, works great for
+L<Log::Log4perl>, but it doesn't support the levels for L<Log::Dispatch>. But
+supporting those levels is as easy as doing
- use Log::Contextual;
+ use Log::Contextual
+ -levels => [qw( debug info notice warning error critical alert emergency )];
-will die as we do not yet know what the defaults should be. If it turns out
-that nearly everyone uses the C<:log> tag and C<:dlog> is really rare, we'll
-probably make C<:log> the default. But only time and usage will tell.
+=head2 -package_logger
+
+The C<-package_logger> import option is similar to the C<-logger> import option
+except C<-package_logger> sets the the logger for the current package.
+
+Unlike L</-default_logger>, C<-package_logger> cannot be overridden with
+L</set_logger>.
+
+ package My::Package;
+ use Log::Contextual::SimpleLogger;
+ use Log::Contextual qw( :log ),
+ -package_logger => Log::Contextual::WarnLogger->new({
+ env_prefix => 'MY_PACKAGE'
+ });
+
+If you are interested in using this package for a module you are putting on
+CPAN we recommend L<Log::Contextual::WarnLogger> for your package logger.
+
+=head2 -default_logger
+
+The C<-default_logger> import option is similar to the C<-logger> import option
+except C<-default_logger> sets the the B<default> logger for the current package.
+
+Basically it sets the logger to be used if C<set_logger> is never called; so
+
+ package My::Package;
+ use Log::Contextual::SimpleLogger;
+ use Log::Contextual qw( :log ),
+ -default_logger => Log::Contextual::WarnLogger->new({
+ env_prefix => 'MY_PACKAGE'
+ });
+
+=head1 SETTING DEFAULT IMPORT OPTIONS
+
+Eventually you will get tired of writing the following in every single one of
+your packages:
+
+ use Log::Log4perl;
+ use Log::Log4perl ':easy';
+ BEGIN { Log::Log4perl->easy_init($DEBUG) }
+
+ use Log::Contextual -logger => Log::Log4perl->get_logger;
+
+You can set any of the import options for your whole project if you define your
+own C<Log::Contextual> subclass as follows:
+
+ package MyApp::Log::Contextual;
+
+ use base 'Log::Contextual';
+
+ use Log::Log4perl ':easy';
+ Log::Log4perl->easy_init($DEBUG)
+
+ sub arg_logger { $_[1] || Log::Log4perl->get_logger }
+ sub arg_levels { [qw(debug trace warn info error fatal custom_level)] }
+
+ # and *maybe* even these:
+ 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:
+
+ use MyApp::Log::Contextual -logger => $foo, -levels => [qw(bar baz biff)];
+
+Your C<arg_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: Ref|CodeRef $returning_logger
+Arguments: C<Ref|CodeRef $returning_logger>
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
-C<CodeRef> for you.
+C<CodeRef> for you. C<set_logger> is really meant only to be called from a
+top-level script. To avoid foot-shooting the function will warn if you call it
+more than once.
=head2 with_logger
}
};
-Arguments: Ref|CodeRef $returning_logger, CodeRef $to_execute
+Arguments: C<Ref|CodeRef $returning_logger, 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
+As with L</set_logger>, C<with_logger> will wrap C<$returning_logger> with a
C<CodeRef> if needed.
=head2 log_$level
-Import Tag: ":log"
+Import Tag: C<:log>
-Arguments: CodeRef $returning_message
+Arguments: C<CodeRef $returning_message, @args>
All of the following six functions work the same except that a different method
is called on the underlying C<$logger> object. The basic pattern is:
- sub log_$level (&) {
+ sub log_$level (&@) {
if ($logger->is_$level) {
- $logger->$level(shift->());
+ $logger->$level(shift->(@_));
}
+ @_
}
+Note that the function returns it's arguments. This can be used in a number of
+ways, but often it's convenient just for partial inspection of passthrough data
+
+ my @friends = log_trace {
+ 'friends list being generated, data from first friend: ' .
+ Dumper($_[0]->TO_JSON)
+ } generate_friend_list();
+
+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 };
log_fatal { '1 is never equal to 0!' };
+=head2 logS_$level
+
+Import Tag: C<:log>
+
+Arguments: C<CodeRef $returning_message, Item $arg>
+
+This is really just a special case of the L</log_$level> functions. It forces
+scalar context when that is what you need. Other than that it works exactly
+same:
+
+ my $friend = logS_trace {
+ 'I only have one friend: ' . Dumper($_[0]->TO_JSON)
+ } friend();
+
+See also: L</DlogS_$level>.
+
=head2 Dlog_$level
-Import Tag: ":dlog"
+Import Tag: C<:dlog>
-Arguments: CodeRef $returning_message, @args
+Arguments: C<CodeRef $returning_message, @args>
-All of the following six functions work the same as their L<log_$level>
+All of the following six functions work the same as their L</log_$level>
brethren, except they return what is passed into them and put the stringified
(with L<Data::Dumper::Concise>) version of their args into C<$_>. This means
you can do cool things like the following:
=head2 DlogS_$level
-Import Tag: ":dlog"
+Import Tag: C<:dlog>
-Arguments: CodeRef $returning_message, Item $arg
+Arguments: C<CodeRef $returning_message, Item $arg>
-All of the following six functions work the same as the related L<Dlog_$level>
-functions, except they only take a single scalar after the
-C<$returning_message> instead of slurping up (and also setting C<wantarray>)
-all the C<@args>
+Like L</logS_$level>, these functions are a special case of L</Dlog_$level>.
+They only take a single scalar after the C<$returning_message> instead of
+slurping up (and also setting C<wantarray>) all the C<@args>
my $pals_rs = DlogS_debug { "pals resultset: $_" }
$schema->resultset('Pals')->search({ perlers => 1 });
-=head3 DlogS_trace
-
- my ($foo, $bar) =
- DlogS_trace { "entered method foo with first arg $_" } $_[0], $_[1];
-
-=head3 DlogS_debug
-
- DlogS_debug { "random data structure: $_" } { foo => $bar };
-
-=head3 DlogS_info
-
- return DlogS_info { "html from method returned: $_" } "<html>...</html>";
-
-=head3 DlogS_warn
-
- DlogS_warn { "probably invalid value: $_" } $foo;
-
-=head3 DlogS_error
-
- DlogS_error { "non-numeric user input! ($_)" } $port;
-
-=head3 DlogS_fatal
-
- DlogS_fatal { '1 is never equal to 0!' } 'ZOMG ZOMG' if 1 == 0;
-
=head1 LOGGER INTERFACE
Because this module is ultimately pretty looking glue (glittery?) with the