Skip to content
Alex-Kent edited this page Apr 11, 2019 · 9 revisions

NAME

Log::Selective - Selective logging to the console.

VERSION

This document describes Log::Selective version 0.0.3

DESCRIPTION

Log::Selective is a logger with adjustable verbosity for commandline Perl programs. Different verbosity levels can have different colors and styles applied and specific functions or methods can get extra verbosity.

Additional functions are provided for displaying summaries of all warnings or errors encountered. Stack traces can been shown on demand or whenever there are warnings or errors.

USAGE

Basic usage

use Log::Selective;
set_verbosity( 1 );                # Only show messages at or below level 1

LOG( 0, "Normal output" );
LOG( 1, "Debug output" );
LOG( 2, "More debug output" );     # Not output to console
WARNING( "Foo looks funny" );
ERROR( "Bar not found" );

LOG( 0, "All done" );
show_warnings();                   # Show summary of warnings
show_errors();                     # Show summary of errors

Further examples can be found in the examples/ directory.

Non-Unix platforms

This module should be usable on Windows platforms by including the following in your script:

use Win32::Console::ANSI;

Note that use of this module on Windows has not been tested by the author.

Logging

Each time a logging call is made the Log::Selective compare's the message's log level to the current verbosity level. If the message's level is the same or lower than the current verbosity it is displayed, if not it is discarded.

Logging level 0 is for normal messages, level -1 is for warnings, and -2 is for errors. Levels 1 and greater are meant for more verbose or debug output with higher levels being more verbose. By default, stack traces use level -3.

By default the verbosity level is 0. This can be changed using set_verbosity(...) to set the verbosity to an arbitrary level, be_quiet() to only display warnings and errors, or be_silent() to disable all logging output. The current verbosity can be determined using get_verbosity().

The logging level for messages is specified via the logging call. For LOG(...) the logging level is explicitly specified in the call, for WARN(...) and WARNING(...) it is set to -1, and for ERROR(...) it is set to -2. Stack traces, whether explicitly or automatically generated, are output at level -3 by default; this can be changed using set_stack_trace_level(...).

When messages are logged using WARN(...) or WARNING(...) a copy of the message is saved to a list. The contents of this list can be displayed to the console (at the warning log level -1) using show_warnings(). Typically this will be done at the end of a program's run. Likewise, when messages are logged using ERROR(...) a copy of the message is saved to a separate list. The contents of this list can be displayed to the console (at the error log level -2) using show_errors(). The contents of the two lists can be retrieved using get_warnings() and get_errors().

Extra logging for select functions

Extra logging verbosity can be specified for specific functions or methods. This done using extra_logging(...) which is given an extended logging level along with a regex specifying which functions to show extra output for. For example:

sub A() {
    LOG( 3, "In A()" );
}

sub B() {
    LOG( 3, "In B()" );       # Not output to console
}

sub C() {
    LOG( 3, "In C()" );
}

sub D() {
    LOG( 1, "In D()" );
}

use Log::Selective;
set_verbosity(1);             # Normally only show levels 1 and below
extra_logging(3, 'A|C');      # Show up to level 3 for A() and C()

A(); B(); C(); D();

This outputs:

In A()
In C()
In D()

Stack traces

To get stack traces one can use:

# Immediately output a stack trace
stack_trace();

# Request stack traces when warnings or errors occur:
stack_trace_on_warnings();
stack_trace_on_errors();

The set_stack_trace_level(...) function can be used to control when and how stack traces are displayed.

The call stack can also be displayed in abbreviated form using call_trace().

Full stack traces and abbreviated stack traces can be gotten in list or string form using get_stack_trace() and get_call_trace(), respectively.

Output locations

By default, output is to the console using STDOUT for regular messages and STDERR for warnings, errors, and stack traces. The log_to(...), warnings_to(...), and errors_to(...) functions can be used to change this. For example, to write all output to STDOUT one could use:

log_to      (\*STDOUT);  # This is the default
warnings_to (\*STDOUT);
errors_to   (\*STDOUT);

Output colors and styles

The colors and styles used at each logging level can be set using set_style(...) with the available styles returned by get_styles( ). Custom colors and styling can also be specified for an individual message using the long form of LOG(...).

Most terminals support coloring and styling. For those that don't one can use set_color_mode('off'); to force the use of plain text for all output.

By default all log messages have a newline (\n) appended. If you want to manually add newlines in your own code, call no_append_newlines() or append_newlines(0) to disable the automatic ones. To re-enable adding of newlines call append_newlines() or append_newlines(1).

Colors

16-color support (ANSI colors) is ubiquitous; to specify these colors use the constants provided by this module (see Constants, below).

Many terminals support 8-bit color. To specifiy this one should use ";NNN" where NNN is the decimal color to use (0..255). The available colors are:

0-7     -> Standard colors:
           BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, LIGHT_GREY *
           
8-15    -> Bright colors:
           DARK_GREY *, BRIGHT_RED, BRIGHT_GREEN, BRIGHT_YELLOW, 
           BRIGHT_BLUE, BRIGHT_MAGENTA, BRIGHT_CYAN, WHITE *
           
16-231  -> 216 color cube (6x6x6)
           The equation to determine the values is:
           16 + ( 36 * r ) + ( 6 * g ) + b
           where r, g, and b are in the range 0 to 5
           
232-255 -> 24 greyscale values (dark to light, excluding black and white)
           To determine the value given an intensity between 0.0 and 1.0:
           $value = int($intensity * 25.0);
           $value = ( $value <= 0 )  ? 0
                  : ( $value >= 25 ) ? 15
                  :                    $value + 231;

* Note: ANSI calls LIGHT_GREY "white", DARK_GREY "bright black", and WHITE 
        "bright white".

Not many terminals suport 24-bit color. To specify this one should use ";RRR;GGG;BBB" where RRR is the red component, GGG is the green component, and BBB is the blue component (all values are 0.255).

Constants

Note that these constants currently have similar values to the ANSI ones but this may change in future. The user should not rely on them having any particular value.

The following constants are used to specify text colors and styles:

  • To specify use of the default color:

      DEFAULT
    
  • Greys:

      BLACK         DARK_GREY       LIGHT_GREY        WHITE
    

    These correspond to the ANSI colors 'black', 'bright black', 'white', and 'bright white', respectively. The constant DARK_GRAY can also be used for DARK_GREY and LIGHT_GRAY can also be used for LIGHT_GREY.

  • Normal colors:

      RED           GREEN           YELLOW
      BLUE          MAGENTA         CYAN
    
  • Bright colors:

      BRIGHT_RED    BRIGHT_GREEN    BRIGHT_YELLOW
      BRIGHT_BLUE   BRIGHT_MAGENTA  BRIGHT_CYAN
    
  • Font weight:

      FAINT         NORMAL          BOLD
    

    Almost no terminals support FAINT

  • Underlining:

      UNDERLINE     NO_UNDERLINE
    
  • Italic:

      ITALIC        NO_ITALIC
    

    Very few terminals support ITALIC. The only one known to the author that does is rxvt (though using italics with it will remove any underlining).

  • Blink:

      BLINK         NO_BLINK
    

    Note that blink does not work in rxvt when a background color is specified. Some terminals stop blinking text when the window is not focused; with xterm blinking text might not be visible when the window does not have focus.

  • Inverse video:

      INVERSE       NO_INVERSE
    
  • Remove all styles:

      NO_STYLE
    

    This constant is be used to specify that normal-weight, unstyled text should be displayed.

Importing functions

Functions can always be called using a long form Log::Selective->function(). Likewise, constants can always be specified using a long form Log::Selective->CONSTANT. If a function or constant has been imported one can also use the short forms function() and CONSTANT, respectively.

To import everything in Log::Selective into your namespace use:

use Log::Selective;

One can also selectively import symbols using:

use Log::Selective qw( SYMBOLS );

Any desired functions or constants to import should be listed in SYMBOLS (space-delimited). In addition, the following shortcuts are available:

  • :constants - Color and style constants

    These are as described in Constants, above.

  • :loggers - Logging functions

    These are:

      LOG    WARN    WARNING    ERROR
    
  • :minimal - Logging functions and basic functions

    These are the logging functions plus:

      set_verbosity    show_warnings
      get_verbosity    show_errors
      set_color_mode   stack_trace
      extra_logging    call_trace
    
  • :typical - Constants, logging functions, and basic functions

    This is the same as :constants :minimal

  • :all - All constants and functions (this is the default)

    Everything included by :typical plus the following functions:

      log_to              stack_trace_on_warnings
      warnings_to         stack_trace_on_errors
      errors_to           no_stack_trace_on_warnings
      be_quiet            no_stack_trace_on_errors
      be_silent           set_stack_trace_level
      append_newlines     get_stack_trace
      no_append_newlines  get_call_trace
      no_extra_logging    get_warnings
      get_styles          get_errors
      set_style           unbuffer_output
      get_style           
    

For example to import all of the logging functions plus set_verbosity use:

use Log::Selective qw( :loggers set_verbosity );

FUNCTIONS

Logging

LOG( $level, $message, $fore, $back, \@style )

Selectively write a message to the console

WARN( $message )

Write a warning message to the console.

ERROR( $message )

Write a error message to the console

show_warnings( )

Write saved warning messages to the console

show_errors( )

Write saved error messages to the console

get_warnings( )

Returns the list of saved warning messages

get_errors( )

Returns the list of saved error messages

Verbosity

set_verbosity( $level )

Set the level of logging verbosity

get_verbosity( )

Returns the current level of logging verbosity

be_quiet( )

Only output warnings, errors, and (by default) stack traces

be_silent( )

Do not output anything.

extra_logging( $verbosity, $pattern )

Selectively use a higher logging level

no_extra_logging( )

Do not perform extra logging

Colors and styles

set_color_mode( $mode )

Choose when colors and styles are used

get_styles( )

Get names of available styles

set_style( $style_name )

set_style( \%style_definition )

Specify the colors and styles used at each log level

get_style( )

Returns the name of the current style

append_newlines($switch)

Choose whether to append newlines to log messages

no_append_newlines( )

Do not append newlines to strings passed to logging functions

Output file handles

log_to( $handle )

Specify handle to write normal log output to

warnings_to( $handle )

Specify handle to write warnings to

errors_to( $handle )

Specify handle to write errors (and, by default, stack traces) to

unbuffer_output( )

Unbuffer the current log, warning, and error file handles

Stack traces

stack_trace($message)

Writes a stack trace to the console

get_stack_trace( )

Returns a stack trace as a list

call_trace( )

Writes an abbreviated stack trace to the console

get_call_trace( )

Return an abbreviated call trace as a string

set_stack_trace_level( $level )

Control how stack traces are displayed

stack_trace_on_warnings($switch)

Control whether warnings generate stack traces

no_stack_trace_on_warnings( )

Do not show a stack trace after warnings.

stack_trace_on_errors($switch)

Control whether errors generate stack traces

no_stack_trace_on_errors( )

Do not show a stack trace after errors

LOG( ... )

LOG( $level, $message );
LOG( $level, $message, $fore, $back, @style );

Selectively write a message to the console

The specified $message will only be displayed if the specified log $level is either of:

  • No higher than the current logging verbosity (as set with set_verbosity(...))
  • No higher than the current extra logging verbosity and the calling functions match the extra logging pattern. See extra_logging(...) for details.

The message shown will be colored and styled as appropriate for its level.

Output coloring and styling will only be done if the current color mode is 'on' or is 'auto' and the output is going to a terminal. The colors and styles used at each level can be specified using set_colors(...).

To specify specific colors and styling for a single log message one can use the second (longer) syntax of this function. The $fore and $back colors are as described in the Colors section, above. Any custom styling can be passed via @style (note that this is not a reference) with the styles being as described in Constants, above. Any colors or styles that would normally be used for a given log message will remain in effect unless explicitly overridden.

WARN( ... )

WARN( $message );
WARNING( $message );

Write a warning message to the console.

Logging is done via LOG(...) so all of its effects apply. The log level used is -1. Optionally, a stack trace will be output after the message; see stack_trace_on_warnings(...).

All warnings will be saved to a list irrespective of whether they are displayed. The list can be output to the console using show_warnings( ); this can be useful for showing an error summary at the end of a program's run. The list can also be retrieved using get_warnings( ).

ERROR( ... )

ERROR( $message );

Write a error message to the console

Logging is done via LOG(...) so all of its effects apply. The log level used is -2. Optionally, a stack trace will be output after the message; see stack_trace_on_errors(...).

All error messages will be saved to a list irrespective of whether they are displayed. The list can be output to the console using show_errors( ); this can be useful for showing an error summary at the end of a program's run. The list can also be retrieved using get_errors( ).

show_warnings( )

show_warnings( );

Write saved error messages to the console

All warnings logged using WARN(...) or WARNING(...) are saved to a list. This function outputs that list to the console; this can be useful for showing a warning summary at the end of a program's run.

show_errors( )

show_errors( );

Write saved error messages to the console

All error messages logged using ERROR(...) are saved to a list. This function outputs that list to the console; this can be useful for showing an error summary at the end of a program's run.

get_warnings( )

@warnings = get_warnings( );
$warnings = get_warnings( );

Returns the list of saved warning messages

All warnings logged using WARN(...) or WARNING(...) are saved to a list. This function returns either that list (when called in list context) or a reference to that list (when called in scalar context).

get_errors( )

@errors = get_errors( );
$errors = get_errors( );

Returns the list of error messages

All error messages logged using ERROR(...) are saved to a list. This function returns either that list (when called in list context) or a reference to that list (when called in scalar context).

set_verbosity( ... )

set_verbosity( $level );

Set the level of logging verbosity

$level

The verbosity level

Only log messages at or below this level will be output. Higher number result in more console output.

Message levels:

-999   None
  -3   Stack traces (by default)
  -2   Errors
  -1   Warnings
   0   Normal output
  >0   Verbose output

The default logging verbosity is 0.

get_verbosity( )

$level = get_verbosity( );

Return the current level of logging verbosity

This can be useful to only call show_warnings() and show_errors() at elevated logging levels:

if ( get_verbosity() > 0 ) {
     show_warnings();
     show_errors();
}

be_quiet( )

be_quiet( );

Only output warnings, errors, and (by default) stack traces

Sets verbosity to -1.

be_silent( )

be_silent( );

Do not output anything.

Sets verbosity to -999.

extra_logging( ... )

extra_logging( $verbosity, $pattern );

Selectively use a higher logging level

This function sets the logging level to at least $verbosity when the name of the current function (or one of its callers) matches the regex $pattern.

Each time LOG(...) is called a list of callers is contructed and concatenated into a string. Extra logging is then done if that string matches the regex /(?:$pattern)/. For example, if a() is called from the top level of the script which the calls, in turn, b() and Some::Module::c() which in turn calls Log::Selective::LOG(...) then the string constructed will be "main::a main::b Some::Module::c". The string used at a particular point in one's program can be determined using a call to call_trace().

By default no extra logging is done.

no_extra_logging( )

no_extra_logging( );

Do not perform extra logging

set_color_mode( ... )

set_color_mode( $mode );

Choose when colors and styles are used

$mode

'auto' - Automatically decide whether to use colors and styles

If output is going to a terminal then colors and styles are used otherwise they are not

'on' - Always use colors and styles

'off' - Never use colors and styles

By default the color mode is 'auto'.

get_styles( )

@style_names = get_styles( );

Get names of available styles

Returns a list of available style names.

set_style( ... )

set_style( $style_name );

set_style( \%style_definition );

Specify the colors and styles used at each log level

$style_name

String naming the style to use.

Use get_styles( ) to determine which styles are available.

%style_definition

Reference to hash describing the style to use.

The keys to the hash are level definitions. Each is a numeric levels (e.g. -2, 0, 3), the value <0 (for all undefined levels below 0), or the value >0 (for all undefined levels above 0).

The values are references to three-element arrays. The first element is the foreground color and the second element is the background color. Colors are either constants or strings as described in the Constants and Colors sections, above. Colors can also be specified as undef in which case the default foreground or background color will be used.

The third element is the bitwise OR of the constants describing the style (see Constants, above). To specify no particular style use NO_STYLE. Available style constants are FAINT, NORMAL, and BOLD for the font weight, and UNDERLINE, ITALIC, and BLINK for text effects. For example, bold blinking text would be specified as:

BOLD | BLINK

get_style( )

$style_name = get_style( );

Returns the name of the current style

append_newlines( ... )

append_newlines( );
append_newlines( $switch );

If $switch is omitted then append newlines to strings passed to logging functions.

If $switch is TRUE then append newlines to strings passed to logging functions.

If $switch is FALSE then do not append newlines to strings passed to logging functions.

By default newlines are appended to strings passed to logging functions.

no_append_newlines( )

no_append_newlines( );

Do not append newlines to strings passed to logging functions

log_to( ... )

log_to( $handle );

Specify handle to write normal log output to

$mode

Reference to a writable file handle

Defaults to \*STDOUT.

Technically, this option sets the handle used for all messages at levels 0 and above.

warnings_to( ... )

warnings_to( $handle );

Specify handle to write warnings to

$mode

Reference to a writable file handle

Defaults to \*STDERR.

Technically, this option sets the handle used for all messages at level -1.

errors_to( ... )

errors_to( $handle );

Specify handle to write errors (and, by default, stack traces) to

$mode

Reference to a writable file handle

Defaults to \*STDERR.

Technically, this option sets the handle used for all messages at levels -2 and below.

unbuffer_output( )

unbuffer_output( );

Unbuffer the current log, warning, and error file handles

stack_trace( ... )

stack_trace( );
stack_trace( $message );

Writes a stack trace to the console

If a $message is provided then it will be output before the stack trace is shown. If none is provided then "Stack trace:\n" will be output instead.

By default output is done at log level -3; this can be changed using set_stack_trace_level(...).

get_stack_trace( )

@stack_trace = get_stack_trace( );

Return a stack trace as a list

call_trace( )

call_trace( );

Writes an abbreviated stack trace to the console

The string displayed is the same as is used by LOG(...) when determining whether to display extra logging.

When called from the top level of the program the output will be the empty string.

By default output is done at log level -3; this can be changed using set_stack_trace_level(...).

get_call_trace( )

$call_trace = get_call_trace( );

Return an abbreviated call trace as a string

set_stack_trace_level( ... )

set_stack_trace_level( $level );

Control how stack traces are displayed

If $level is undef then the level of the last LOG(...) output is used for stack traces.

If $level is defined then the specified level will be used for all stack traces.

By default the stack trace level is -3.

stack_trace_on_warnings( ... )

stack_trace_on_warnings( );
stack_trace_on_warnings( $switch );

Control whether warnings generate stack traces

If $switch is omitted then show a stack trace after all warnings.

If $switch is TRUE then show a stack trace after all warnings.

If $switch is FALSE then do not show a stack trace after warnings.

By default stack traces are not shown after warnings.

no_stack_trace_on_warnings( )

no_stack_trace_on_warnings( );

Do not show a stack trace after warnings.

stack_trace_on_errors( ... )

stack_trace_on_errors( );
stack_trace_on_errors( $switch );

Control whether errors generate stack traces

If $switch is omitted then show a stack trace after all errors.

If $switch is TRUE then show a stack trace after all errors.

If $switch is FALSE then do not show a stack trace after errors.

By default stack traces are not shown after errors.

no_stack_trace_on_errors( )

no_stack_trace_on_errors( );

Do not show a stack trace after errors

BUGS AND DEFICIENCIES

Known issues

  • Tests need to be written.

Reporting bugs

Please submit any bugs or feature requests either to bug-geo-index at rt.cpan.org, through CPAN's web interface, or through Github. In any case I will receive notification when you do and you will be automatically notified of progress on your submission as it takes place. Any other comments can be sent to akh@cpan.org.

VERSION HISTORY

  • 0.0.3 (2019-04-11)
    Bug fixes, added functions

    • Fixed typos in docs
    • Bug fixes in LOG(), WARN(), ERROR(), and set_style()
    • Added get_style()
    • Added unbuffer_output()
    • Updated examples/getopt_long.pl
  • 0.0.2 (2019-04-10)
    Added styles, examples

    • get_styles( ): New function
    • set_style( ... ): New function
    • set_colors( ... ): Removed function
    • LOG( ... ): Rewrote color and style code
    • Added detailed usage examples
  • 0.0.1 (2018-04-08)
    Initial release

AUTHOR

Alex Kent Hajnal  akh@cpan.org  https://alephnull.net/software

COPYRIGHT

Log::Selective

Copyright 2019 Alexander Hajnal, All rights reserved

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.