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");
        elog_debugf { die("This will not get evaluated") for (0..1_000) };

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

subs

If set to true, will apply the behavior and calling convention of the conditionally-evaluating e* functions to the non-prefix versions, allowing partial compatibility with Log::Contextual.

        use Log::Fu { level => "warn", subs => 1 };
        log_warnf { "This is a warning" };

function_prefix

If set, its value will be used as the prefix for all the exported function. Hence:

        use Log::Fu { prefix => 'logfu_', level => 'debug' };
        
        logfu_log_info("Hi");
        logfu_elog_warn { "bye" };
        

This option is useful if using several logging modules, or perhaps for migration.

In the future, we might actually try to make this into a regex or something, to customize the log names even more.

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

elog_info { $string1, $string2 };

elog_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

The *f suffix denotes that the function will take the arguments to be parameters for sprintf and be interpreted as a format string and its arguments.

New in v0.30

The e* variants take a CODE reference which will return a list of parameters, suitable for the non-e* variants.

The e* variants will not evaluate their arguments if the severity level is under the one specified; that is, the encapsulating subroutine will not be called. This is in the spirit of Log::Contextual

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.

$Log::Fu::FORCE_COLOR, $ENV{LOG_FU_FORCE_COLOR}

This forces color output, overriding any terminal or output detection scheme. This is handy when you do the following

        $ LOG_FU_FORCE_COLOR=1 ./my_script.pl 2>&1 | less -R
        

As it allows you to see large amounts of output in your color-capable pager.

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

SEVERITY DISPLAY

As of version 0.23, displaying of severity information (e.g. [INFO]) is disabled if colors are enabled. This is because the colors themselves uniquely identify the severity level.

$Log::Fu::DISPLAY_SEVERITY, $ENV{LOG_FU_DISPLAY_SEVERITY}

This option controls the printing of severity messages. If set to 0 (the default), then the default behavior mentioned above is assumed. If greater than zero, the severity level is always printed. If less than zero, then the severity level is never printed

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

TODO

Allow an option for user defined ~/.logfu preferences, so that presets can be selected.

COPYRIGHT

Copyright 2011-2012 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