oracular (3) Log::Contextual::WarnLogger.3pm.gz

NAME

       Log::Contextual::WarnLogger - logger for libraries using Log::Contextual

VERSION

       version 0.009001

SYNOPSIS

         package My::Package;
         use Log::Contextual::WarnLogger;
         use Log::Contextual qw( :log ),
           -default_logger => Log::Contextual::WarnLogger->new({
             env_prefix => 'MY_PACKAGE',
             levels => [ qw(debug info notice warning error critical alert emergency) ],
           });

         # warns '[info] program started' if $ENV{MY_PACKAGE_TRACE} is set
         log_info { 'program started' }; # no-op because info is not in levels
         sub foo {
           # warns '[debug] entered foo' if $ENV{MY_PACKAGE_DEBUG} is set
           log_debug { 'entered foo' };
           ...
         }

DESCRIPTION

       This module is a simple logger made for libraries using Log::Contextual.  We recommend the use of this
       logger as your default logger as it is simple and useful for most users, yet users can use "set_logger"
       in Log::Contextual to override your choice of logger in their own code thanks to the way Log::Contextual
       works.

METHODS

   new
       Arguments: "Dict[ env_prefix => Str, levels => List ] $conf"

         my $l = Log::Contextual::WarnLogger->new({ env_prefix => 'BAR' });

       or:

         my $l = Log::Contextual::WarnLogger->new({
           env_prefix => 'BAR',
           levels => [ 'level1', 'level2' ],
         });

       Creates a new logger object where "env_prefix" defines what the prefix is for the environment variables
       that will be checked for the log levels.

       The log levels may be customized, but if not defined, these are used:

       trace
       debug
       info
       warn
       error
       fatal

       For example, if "env_prefix" is set to "FREWS_PACKAGE" the following environment variables will be used:

         FREWS_PACKAGE_UPTO

         FREWS_PACKAGE_TRACE
         FREWS_PACKAGE_DEBUG
         FREWS_PACKAGE_INFO
         FREWS_PACKAGE_WARN
         FREWS_PACKAGE_ERROR
         FREWS_PACKAGE_FATAL

       Note that "UPTO" is a convenience variable.  If you set "FOO_UPTO=TRACE" it will enable all log levels.
       Similarly, if you set it to "FATAL" only fatal will be enabled.

   $level
       Arguments: @anything

       All of the following six methods work the same.  The basic pattern is:

         sub $level {
           my $self = shift;

           warn "[$level] " . join qq{\n}, @_;
             if $self->is_$level;
         }

       trace

         $l->trace( 'entered method foo with args ' join q{,}, @args );

       debug

         $l->debug( 'entered method foo' );

       info

         $l->info( 'started process foo' );

       warn

         $l->warn( 'possible misconfiguration at line 10' );

       error

         $l->error( 'non-numeric user input!' );

       fatal

         $l->fatal( '1 is never equal to 0!' );

       If different levels are specified, appropriate functions named for your custom levels work as you expect.

       Note: "fatal" does not call "die" for you, see "EXCEPTIONS AND ERROR HANDLING" in Log::Contextual

   is_$level
       All of the following six functions just return true if their respective environment variable is enabled.

       is_trace

         say 'tracing' if $l->is_trace;

       is_debug

         say 'debuging' if $l->is_debug;

       is_info

         say q{info'ing} if $l->is_info;

       is_warn

         say 'warning' if $l->is_warn;

       is_error

         say 'erroring' if $l->is_error;

       is_fatal

         say q{fatal'ing} if $l->is_fatal;

       If different levels are specified, appropriate is_$level functions work as you would expect.

BUGS

       Please report any bugs or feature requests on the bugtracker website
       <https://github.com/haarg/Log-Contextual/issues>

       When submitting a bug or request, please include a test-file or a patch to an existing test-file that
       illustrates the bug or desired feature.

AUTHOR

       Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2024 by Arthur Axel "fREW" Schmidt.

       This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5
       programming language system itself.