NAME

Debug::Simple - Very simple debugging statements

SYNOPSIS

    use Debug::Simple;

    my %opt = (quiet => 0, debug => 4, verbose => 1, test => 0);
    Debug::Simple::debuglevels(\%opt);

    warning("This is a warning\m");
    debug(1, "This is a level 3 debug message\n");
    debug(2, "This is a level 2 debug message with a Dump", NAME => \%opt);
    verbose(1, "This is a verbose message\n");
    test('print "test code"');

DESCRIPTION

This module provides a very simple way to provide debug/verbose/warning messages. It is also trivially controlled via Getopt::Long.

The idea is to be able to put a bunch of debugging print statements throughout your code that you can enable or disable.

debuglevels(\%OPT)

debuglevels registers the hashref HASH as the place to read values used to control whether text is output to the screen or not. There are 4 values read from this hash: quiet, debug, verbose, and test.

quiet

If non-zero, this will repress all output from Debug::Simple

debug

This indicates the level of debug messages desired. A debug level of 4 prints all the debug messages from levels 1 to 4.

verbose

Like debug, this sets the level of verboseness. A verbose level of 3 prints all verbose messages from 1 to 3.

test

If non-zero, the code passed to test() will be printed to the screen instead of being executed.

warning(STRING)

warning prints the STRING to stdout in YELLOW unless the "quiet" level is non-zero (see debuglevels). STRING is prefaced with "Warning:".

debug(LEVEL, STRING, [NAME => REF])

debug prints a debugging message to stdout as long as LEVEL is at or below the "debug" level. (see <debuglevels).

The debug message is printed in BOLD. It starts with "Debug: ", then STRING, and then optionally uses Data::Dumper to dump a data structure referred to by REF. NAME is just a human readable name for REF passed to Data::Dumper.

verbose(LEVEL, STRING)

verbose prints STRING to stdout as long as LEVEL is at or below the "verbose" level. (see debuglevels).

test(CODE)

test executes CODE according to the "test" level. (see debuglevels). If the "test" level is non-zero the code is printed to stdout instead of being executed.

LEVELS

To make things marginally more useful, you can specify that a message can be printed to stdout based on more than one level by specifying a list of levels.

For instance, for debug you can also specify the "verbose" and "test" levels at which the debug message will be printed. In the following example, the debug message will be output at debug levels 1-2, verbose levels 1-3 or test level 1.

    &debug([2,3,1], "This is a debug message\n");

In this case, the message will be printed to stdout if the verbose level is 1-2 or test level 1.

    &verbose([2,1], "This is a verbose message\n");

EXAMPLE CODE

This example shows how Debug::Simple code can be tied in with GetOpt::Long.

    use Debug::Simple;
    use Getopt::Long;
    use Pod::Usage;

    pod2usage(2) unless GetOptions( $opt = {},
        qw(help debug:i quiet test verbose|v+) );
    pod2usage(1) if $opt->{help};
    $opt->{debug} = 1 if defined $opt->{debug} && !$opt->{debug};
    Debug::Simple::debuglevels($opt);

    debug(2, "Command line options ", OPT=>$opt);
    verbose(1, "Now on with the show\n");

    ...

AUTHOR

Behan Webster <behanw@websterwood.com<gt>

COPYRIGHT

Copyright (c) 2004-2008 Behan Webster. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.