NAME

Log::Fu - Simplified and developer-friendly screen logging

DESCRIPTION

This is a simple interface for console logging. It provides a few functions, log_info, log_debug, log_warn, log_crit, and log_err. They all take strings as arguments, and can take as many arguments as you so desire (so any concatenation is done for you).

A message is printed to standard error (or to $target if specified), prefixed with the filename, line number, and originating subroutine of the message. A format string might become available in the future

It is also possible to configure per-package logging parameters and level limitations. To do this, simply provide an option hashref when using the module, as shown in the synopsis. Available levels are: debug info warn err crit

Since this module uses a very plain and simple interface, it is easy to adjust your program to override these functions to wrap a more complex logging interface in the future.

There is very little boilerplate code for you to write, and it will normally just do its thing.

SYNOPSIS

    use Log::Fu;
    
        log_debug("this is a debug level message");    
        log_info("this is an info-level message");
        log_debugf("this is a %s", "format string");

IMPORTING

Usually, doing the following should just work

    use Log::Fu;

This will allow a default level of INFO, and log messages to stderr.

If you need more configuration, you may pass a hashref of options during use. The keys recognized are as follows

level

This is the minimum level of severity to display. The available levels from least to most severe are debug, info, warn, err, crit

target

This specifies where to log the message or which action to take. This can be either a filehandle, in which case the messages will be printed to it, or it can be a code reference, in which case it will be called with the formatted message as its argument

EXPORTED SYMBOLS

The main exported functions begin with a log_ prefix, and are completed by a level specification. This is one of debug, info, warn, err or crit. In the examples, info is shown, but may be replaced with any of the specifiers.

log_info($string1, $string2, ..)

log_infof($format, $string...)

Logs a message to the target specified by the package at import time (STDERR by default). The first form will just concatenate its arguments together, while the second form using a printf-style format string.

If the level specified is below the level of importance specified during import-time the message will not be printed.

Configuration Package Variables

$Log::Fu::SHUSH

Set this to a true value to silence all logging output

$Log::Fu::LINE_PREFIX

if set, each new line (not message) will be prefixed by this string.

$Log::Fu::LINE_SUFFIX

If set, this will be placed at the end of each line.

$Log::Fu::TERM_CLEAR_LINE

If set to true, Log::Fu will print \033[0J after each line. Handy for use in conjunction with linefeed-like status bars

$Log::Fu::USE_COLOR

Set to one if it's detected that your terminal/output device supports colors. You can always set this to 0 to turn it off, or set LOG_FU_NO_COLOR in your environment. As of version 0.20, the ANSI_COLORS_DISABLED environment variable is supported as well.

Caller Information Display

By default, Log::Fu will print out unabbridged caller information which will look something like:

        [WARN] demo.pl:30 (ShortNamespace::echo): What about here
        

Often, caller information is unbearably long, and for this, an API has been provided which allows you to strip and shorten caller/namespace components.

For Log::Fu, caller information is divided into three categories, the namespace, the intermediate components, and the function basename.

The function My::Very::Long::Namespace::do_something has a top-level-namespace of My, a function basename of do_something, and its intermediate components are Very::Long::Namespace.

Currently, this is all accessed by a single function:

Log::Fu::Configure

This non-exported function will configure stripping/shortening options, or turn them off, depending on the options:

Synopsis:

        Log::Fu::Configure(
                Strip => 1,
                StripMoreIndicator => '~',
                StripComponents    => 2,
                StripTopLevelNamespace => 0
        );
        

Will configure Log::Fu to display at most two intermediate components, and to never shorten the top level namespace. For namespaces shortened, it will use the '~' character to indicate this.

The full list of options follow:

Strip

This is a boolean value. Set this to 0 to disable all stripping functions.

StripMoreIndicator

This is a string. When a component is stripped, it is suffixed with the value of this parameter. Something short like '~' (DOS-style) should suffice, and is the default.

StripMaxComponents

How many intermediate components to allow. If caller information has more than this number of intermediate components (excluding the top-level namespace and the function basename), they will be stripped, starting from the beginning.

The default value is 2

StripKeepChars

When an intermediate component is stripped, it will retain this many characters. The default is 2

StripTopLevelNamespace

This value is the maximum length of the top-level namespace before it is shortened. Set this to 0 (the default) to disable shortening of the top-level namespace

StripCallerWidth

The maximum allowable width for caller information before it is processed or stripped. Caller information under this limit is not shortened/stripped

StripSubBasename

The length of the function basename. If set, functions longer than this value will be shortened, with characters being chomped from the beginning of the name.

Set this to 0 (the default) to disable shortening of the function basename.

Log::Fu::AddHandler($prefix, $coderef)

If more fine-grained control is needed for the printing of debug information, this function can be used to add a handler for $prefix. The handler is passed one argument (the fully-qualified function name called), and should return a string with the new caller information.

Calls originating from packages which contain the string $prefix will be processed through this handler.

Log::Fu::DelHandler($prefix)

Unregister a handler for $prefix, added with "Log::Fu::AddHandler"

$Log::Fu::NO_STRIP, $ENV{LOG_FU_NO_STRIP}

Set these to true to disable all stripping/shortening

$Log::Fu::USE_WATCHDOG, $ENV{LOG_FU_WATCHDOG}

If set to true, Log::Fu will warn whenever its stripping/shortening configuration has been changed. This is useful to detect if some offending code is changing your logging preferences

PRIVATE SYMBOLS

These functions are subject to change and should not be used often. However they may be helpful in controlling logging when absolutely necessary

Log::Fu::set_log_level($pkgname, $levelstr)

Sets $pkgname's logging level to $levelstr. $levelstr is one of err, debug, info, warn, crit etc.

Log::Fu::start_syslog(@params)

Enables logging to syslog. @params are the options passed to "openlog" in Sys::Syslog

Log::Fu::stop_syslog()

Stops logging to syslog

Log::Fu::_logger($numeric_level_constant, $level_display, $stack_offset, @messages)

$numeric_level_constant is a constant defined in this module, and is currently one of LOG_[WARN|DEBUG|ERR|INFO|CRIT]. $level_display is how to pretty-print the level.

A not-so-obvious parameter is $stack_offset, which is the amount of stack frames _logger should backtrack to get caller() info. All wrappers use a value of 1.

Log::Fu::log_warn_with_offset($offset, @messages)

like log_*, but allows to specify an offset. Useful in $SIG{__WARN__} or DIE functions

BUGS

None known

COPYRIGHT

Copyright 2011 M. Nunberg

This module is dual-licensed as GPL/Perl Artistic. See README for details.

cpanm Log::Fu

perl -MCPAN -e shell
install Log::Fu