Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sdondley/log-log4perl-shortcuts


https://github.com/sdondley/log-log4perl-shortcuts

logging logs perl perl5 perl5-module

Last synced: 16 days ago
JSON representation

Awesome Lists containing this project

README

        

# NAME

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

# VERSION

version 0.024

# OVERVIEW

Provides an easy-to-use wrapper for [Log::Log4perl](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/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](https://metacpan.org/pod/Carp)
- [Data::Dumper](https://metacpan.org/pod/Data::Dumper)
- [Exporter](https://metacpan.org/pod/Exporter)
- [File::UserConfig](https://metacpan.org/pod/File::UserConfig)
- [Log::Log4perl](https://metacpan.org/pod/Log::Log4perl)
- [Log::Log4perl::Level](https://metacpan.org/pod/Log::Log4perl::Level)
- [Module::Data](https://metacpan.org/pod/Module::Data)
- [Path::Tiny](https://metacpan.org/pod/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](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](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](https://github.com/sdondley/Log-Log4perl-Shortcuts/issues).

# INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

# AUTHOR

Steve Dondley

# 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.