-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Log::Selective - Selective logging to the console.
This document describes Log::Selective version 0.0.3
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.
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.
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.
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 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()
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.
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);
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).
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).
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 WHITEThese correspond to the ANSI colors 'black', 'bright black', 'white', and 'bright white', respectively. The constant
DARK_GRAYcan also be used forDARK_GREYandLIGHT_GRAYcan also be used forLIGHT_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 BOLDAlmost no terminals support
FAINT -
Underlining:
UNDERLINE NO_UNDERLINE -
Italic:
ITALIC NO_ITALICVery few terminals support
ITALIC. The only one known to the author that does isrxvt(though using italics with it will remove any underlining). -
Blink:
BLINK NO_BLINKNote that blink does not work in
rxvtwhen a background color is specified. Some terminals stop blinking text when the window is not focused; withxtermblinking text might not be visible when the window does not have focus. -
Inverse video:
INVERSE NO_INVERSE -
Remove all styles:
NO_STYLEThis constant is be used to specify that normal-weight, unstyled text should be displayed.
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 constantsThese are as described in Constants, above.
-
:loggers- Logging functionsThese are:
LOG WARN WARNING ERROR -
:minimal- Logging functions and basic functionsThese 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 functionsThis is the same as
:constants :minimal -
:all- All constants and functions (this is the default)Everything included by
:typicalplus 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 );
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
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
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
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_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( $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( $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( $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( );
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( );
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.
@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).
@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( $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.
$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( );
Only output warnings, errors, and (by default) stack traces
Sets verbosity to -1.
be_silent( );
Do not output anything.
Sets verbosity to -999.
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( );
Do not perform extra logging
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'.
@style_names = get_styles( );
Get names of available styles
Returns a list of available style names.
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
undefin 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 areFAINT,NORMAL, andBOLDfor the font weight, andUNDERLINE,ITALIC, andBLINKfor text effects. For example, bold blinking text would be specified as:BOLD | BLINK
$style_name = get_style( );
Returns the name of the current style
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( );
Do not append newlines to strings passed to logging functions
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( $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( $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 the current log, warning, and error file handles
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(...).
@stack_trace = get_stack_trace( );
Return a stack trace as a list
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(...).
$call_trace = get_call_trace( );
Return an abbreviated call trace as a string
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( $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( );
Do not show a stack trace after warnings.
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( );
Do not show a stack trace after errors
- Tests need to be written.
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 [email protected].
-
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
Alex Kent Hajnal [email protected] https://alephnull.net/software
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.