NAME

Log::MixedColor - Outputs messages in multiple colors

VERSION

version 1.000

SYNOPSIS

Output log messages in color while emphasizing parts of the message in a different color. Although colour codes witin a message string can be done manually, this module is providing a simplified approach to colour logging hopefully saving time and code (and colour codes can also be inserted manually if required - i.e. they won't be stripped).

    use Log::MixedColor;
    my $log = Log::MixedColor->new;

    $log->verbose(1);
    $log->info_msg( "This is a " . $log->quote('general info') . " message." );

    $log->debug(1);
    $log->debug_msg( "This is a " . $log->q('debug') . " message" );

There are four types of messages:

• info_msg (or info) - displayed when debug or verbose are turned on

• debug_msg (or dmsg) - displayed when debug is turned on

• err_msg (or err) - displayed all the time on STDERR

• fatal_msg (or fatal) - displayed all the time on STDERR and will cause the script to exit

The debug and verbose methods are intended so that the script utilising this module can pass the command line option values specifying whether to operate the script logging in verbose or debug mode.

    use Getopt::Std;
    use Log::MixedColor;

    our( $opt_v, $opt_d );
    getopts('vd');

    my $log = Log::MixedColor->new( verbose => $opt_v, debug => $opt_d );

    $log->info_msg( "This is a " . $log->quote('general info') . " message." );
    $log->debug_msg( "This is a " . $log->q('debug') . " message" );

The debug log messages will only display when the script is run with -d and the verbose messages will be display when the script is run with -d or -v.

METHODS

new

Create the Log::MixedColor object. The following can be set at creation time (defaults shown):

    my $log = Log::MixedColor->new( 
        verbose        => 0,
        debug          => 0,
        fatal_is_fatal => 1
    );

which is equivalent to:

    my $log = Log::MixedColor->new;

verbose

Put the log object in verbose mode.

    $log->verbose(1);

v

Alias for verbose.

debug

Put the log object in debug mode.

    $log->debug(1);

d

Alias for debug.

quote

Quote a portion of the message in a different color to the rest of the message

    $log->debug_msg( "This is a ".$log->quote('quoted bit')." inside a message." );

Alternatively, instead of using this method, you could just use the quoting strings directly, e.g.:

    $log->debug_msg( "This is a %%quoted bit## inside a message." );

q

Alias for quote.

quote_start

Sets the string used to denote the start of the text to be quoted in a different color. Default shown

    $log->quote_start( '%%' );

It needs to be different from that specified by quote_end.

quote_end

Sets the string used to denote the end of the text to be quoted in a different color. Default shown.

    $log->quote_end( '##' );

It needs to be different from that specified by quote_start.

info_msg

Display a message on STDOUT when the log object is in debug or verbose mode.

    $log->info_msg( "This is a " . $log->quote('general') . " message." );

info

Alias for info_msg.

debug_msg

Display a message on STDOUT when the log object is in debug mode.

    $log->debug_msg( "This is a " . $log->quote('low level') . " message." );

dmsg

Alias for debug_msg.

err_msg

Display a message on STDERR.

    $log->err_msg( "This is a " . $log->quote('warning') . " message." );

err

Alias for err_msg.

warn

Alias for err_msg.

fatal_err

Display a message on STDERR and then exit the script.

    $log->fatal_err( "This is a ".$log->quote('critical')." message so we have to stop.", 2 );

The optional second argument is the exit code the script will exit with. It defaults to 1.

The exit feature can be turned off by setting $log->fatal_is_fatal to false.

fatal

Alias for fatal_err.

fatal_is_fatal

Determines whether the fatal_msg method actually causes the script to exit. It will by default.

    $log->fatal_is_fatal(0);

Turning it off will make it equivalent to err_msg, but might be helpful when developing a script during which time you may not want it to be fatal, but you do when your script goes into production.

COLORS

To customise the colors, pass the color strings as recognised by Term::ANSIColor to the following relevant methods or set the equivalent properties as part of new (the default is shown in brackets):

• info_color (green)

• debug_color (magenta)

• err_color (red)

• info_quote_color (black on_white)

• debug_quote_color (blue)

• err_quote_color (yellow)

The fatal_err method will use the same colours as the err_msg method.

Message Prefixes

To allow for language variations and individual preferences the prefix before the output message can be customised with the following methods (defaults shown in brackets):

• info_prefix (Info:)

• debug_prefix (Debug:)

• err_prefix (Error:)

The fatal_err method will use the same prefix as the err_msg method.

BUGS/FEATURES

Please report any bugs or feature requests in the issues section of GitHub: https://github.com/Q-Technologies/perl-Log-MixedColor. Ideally, submit a Pull Request.

AUTHOR

Matthew Mallard <mqtech@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Matthew Mallard.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Log::MixedColor

perl -MCPAN -e shell
install Log::MixedColor