NAME

Debug::Message - Eases the use of debug print with level, indentation and color.

SYNOPSIS

    use Debug::Message;
    use Log::Dispatch;
    use Log::Dispatch::Screen;

    my $dispatcher = Log::Dispatch->new;
    $dispatcher->add( Log::Dispatch::Screen->new( name => 'screen',
                                                  min_level => '0' ));

    my $info = Debug::Message->new(1);
    $info->add_dispatcher($dispatcher);
    $info->print("print");
    $info->yellow("warn");
    $info->red("err");
    $info->printcn("error message", 'bold red');

    my $critical = Debug::Message->new(5);
    $critical->add_dispatcher($dispatcher);
    $critical->redn("err");

For disabling the debugging simply do not attach any dispatchers.

    $critical->disable;  # Will detach the attached backend

DESCRIPTION

There was no module for simple debug messages supporting debug/verbosity levels and indentation. So this is the one, that is supposed to take this place.

This module is an art of frontend to Log::Dispatch as Log::Dispatch itself supports levels, but no colors and the function's calling is tedious.

There are some methods defined. Each outputs a different color, optionally it can add a newline after the messaage. They dispatch the messages to all added dispatchers, but generaly only one will be needed as the Log::Dispatch itself can have more backends.

DETAILS

In theory the use is simple. You have to create some Debug::Message objects. Each of these with different importance level. You connect them to the same Log::Dispatch.

Then you set the min_level of Log::Dispatch according to the command line or what ever. Only those messages, wich have enough high level (larger or equal to the Log::Dispatche's one) are outputed. For more complicated scenarios refer to Log::Dispatch(3).

Constructors

   use Debug::Message;
   my $debug = Debug::Message->new( $importance );

Will constuct and return new instance of Debug::Message with importance level set to $importance. The level is a number in range from 0 to 7.

Output functions

print( $message, ... );

printc( $message, ..., $colorspecs );

COLOR( $message, ... );

FUNCTIONn( $mssage, ... );

All functions output is effected by the indentation level. The print() function will output an uncolored string. The COLOR fuctions output a colorizes string. The COLOR can be one of blue, magenta, yellow, red, green. The FUNCTIONn (printn, yellown, etc.) add a trailing newline to the messgage. And finaly the printc() function colorizes its message according to $colorspecs.

$message

Is a string to send to connected dispatcher modules (Log::Dispatch(3)).

$colorspecs

Is color according to Term::ANSIColor(3) man page.

Properties functions

add_dispatcher( $dispatcher );

Adds an output module to the object.

$dispatcher

This is the Log::Dispatch(3) object to connect to.

disable();

Unsets the dispatcher thus disables the debugging. Returns the former dispatcher.

Indentation level TODO, BUT WORKING

level( $level );

Assigns a level $level and returns a new value. If $level is omited nothing is set and the old value is returned

inc( $number );

Increases level by $number. If $number is omited the function behaves as if it was one. The new level value is returned.

dec( $number );

Decreases level by $number. If $number is omited the function behaves as if it was one. The new value of level is returned.

TODO

• test and retreve the user's ideas

• somehow connect with a preprocessor to remove the debug-related calls in working environment

NOTES

The best experience is to copy the initial setup from the synopsis. It saves a lot of writing. Or from here; the more complicated one.

    ### Set-up debuggung facilities
    use Debug::Message;
    use Log::Dispatch;
    use Log::Dispatch::Screen;

    our $Verbosity_Level = '0';
    my $dispatcher = Log::Dispatch->new;
    $dispatcher->add( Log::Dispatch::Screen->new( name => 'screen',
                                                  min_level => $Verbosity_Level ));
    my $info = Debug::Message->new(2);
    $info->add_dispatcher($dispatcher);
    my $data = Debug::Message->new(0);
    $data->add_dispatcher($dispatcher);
    my $warning = Debug::Message->new(4);
    $warning->add_dispatcher($dispatcher);

WARNINGS

BUGS

No known. The new found please report on <ondra@elfove.cz>

HISTORY

12.8.2006

Some of the ideas evolved: Colors insted of semantics in function names. Initial release 0.51.

8.8.2006

Continued writing after a long pause. Rewritten much of the code.

14.10.2003.

I began writing with many nice ideals on mind.

cpanm Debug::Message

perl -MCPAN -e shell
install Debug::Message