NAME

Log::Log4perl::Shortcuts - shortcut functions to make log4perl even easier

VERSION

version 0.021

OVERVIEW

Provides an easy-to-use wrapper for Log::Log4perl.

SYNOPSIS

Instead of this:

  use Log::Log4perl;

  sub do_something {
    my $logger = Log::Log4perl->get_logger('my.category');

    $log->info('I am doing something.');
  }

You can save some keystrokes and do this:

  use Log::Log4perl::Shortcuts qw(:all);

  sub do_something {
    logi('I am doing something.', 'my.category');
  }

DESCRIPTION

This modules provides shortcut functions for the standard log levels provided by Log::Log4perl plus some additional functionality to make it more convenient.

All functions can be imported into your module or script with the :all import tag or they can be individually imported.

Log level functions

There are the six log level functions provided, one for each of the standard log levels provided by the Log4perl module. Each of them accepts an argument for the log message plus an optional category argument.

The $category arguments, if supplied, are appended to the name of the calling package where the log command was invoked. For example, if logi('Info log entry', 'my_category') is called from package Foo::Bar, the log entry will be made with the category:

The $options arguments, if avaiable, supply addition options to the loge and logf functions. If { show_callers => 1 } is supplied, a stack trace will be printed out below the error or fatal message.

  Foo::Bar.my_category

Functions

logt ($msg, [$category])

Prints a message to the trace logger when the log level is set to TRACE or above.

logd ($msg, [$category])

Print messages when the log level is set to DEBUG or above. $category argument is optional.

$msg is intended to be a scalar variable or reference to a data structure which will be output as a message after getting passed through Data::Dumper.

logi ($msg, [$category])

Prints a message to the info logger when the log level is set to INFO or above.

logw ($msg, [$category])

Prints a message to the warn logger when the log level is set to WARN or above.

loge ($msg, [$category], [{ $options => value, ... }])

Prints a message to the error logger when the log level is set to ERROR or above.

logf ($msg, [$category], [{ $options => value, ... }])

Prints a message to the fatal logger when the log level is set to FATAL or above.

Special Functions

logc ([$category])

Prints call stack when log level is set to TRACE or above. Note that no message argument is used by this function.

set_log_config ($file, ['MODULE::NAME'])

Changes the log configuration file to the path and/or file name specified with $file.

Log::Log4perl::Shortcuts will first try to locate the config file on your hard drive using the $file argument by itself. If that's not successful, it will attempt to locate the file in the log_config directory within your module's shared directory. If that fails, the log_config directory for Log::Log4perl::Shortcuts will be searched. This directory can be found in Log-Log4perl-Shortcuts directory that File::UserConfig installed in your home directory when you installed Log::Log4perl::Shortcuts.

You can also supply the name of another module installed on your system which has its logs located in a log_config directory within that module's shared directory.

set_log_level ($log_level)

Change the log level. Should be one of 'trace', 'debug', 'info', 'warn', 'error', or 'fatal'.

CONFIGURATION AND ENVIRONMENT

Custom log configuration files work seamlessly when Log::Log4perl::Shortcuts is being called from within a module that uses the File::UserConfig module to create a directory in your home directory for placing configuration files. If this is the case, place your custom log files into your module's log_config directory so your custom log files can be found. On a Mac, by default, this directory is found in the Application Support/Your-Module-Name in your user's home directory.

You may still use Log::Log4perl::Shortcuts with a custom log file without using the File::UserConfig module, but you will need to specify the complete path to the custom log file when calling the set_log_config function or place your custom log configuration files in the Log-Log4perl-Shortcuts/log_config directory found in your home directory.

REQUIRES

• Carp

• Data::Dumper

• Exporter

• File::UserConfig

• Log::Log4perl

• Log::Log4perl::Level

• Module::Data

• Path::Tiny

SUPPORT

Perldoc

You can find documentation for this module with the perldoc command.

  perldoc Log::Log4perl::Shortcuts

Websites

The following websites have more information about this module, and may be of help to you. As always, in addition to those websites please use your favorite search engine to discover more resources.

• MetaCPAN

  A modern, open-source CPAN search engine, useful to view POD in HTML format.

  https://metacpan.org/release/Log-Log4perl-Shortcuts

Source Code

The code is open to the world, and available for you to hack on. Please feel free to browse it and play with it, or whatever. If you want to contribute patches, please send me a diff or prod me to pull from your repository :)

https://github.com/sdondley/Log-Log4perl-Shortcuts

  git clone git://github.com/sdondley/Log-Log4perl-Shortcuts.git

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at https://github.com/sdondley/Log-Log4perl-Shortcuts/issues.

INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

AUTHOR

Steve Dondley <s@dondley.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2018 by Steve Dondley.

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

cpanm Log::Log4perl::Shortcuts

perl -MCPAN -e shell
install Log::Log4perl::Shortcuts