DESCRIPTION

You want debugging? No, you want sophisticated, full-featured, on-demand debugging, and you don't want to take it out when you release the code because you might need it again later, but you also don't want it to take up any space or cause any slowdown of your production application. Sound impossible? Nah. Just use Debuggit.

Documentation

This POD explains just the basics of using Debuggit. For full details, see Debuggit::Manual.

EXPORTS

DEBUG

DEBUG is a constant integer set to whatever value you choose:

use Debuggit DEBUG => 2;

or to 0 if you don't choose:

use Debuggit;

Actually, failure to specify a value only defaults to 0 the first time in a program this is seen. Subsequent times (e.g. in modules included by the main script), DEBUG will be set to the first value passed in. In this way, you can set DEBUG in the main script and have it "fall through" to all included modules. See "The DEBUG Constant" in Debuggit::Manual for full details.

Functions exported

FUNCTIONS

debuggit

Use this function to conditionally print debugging output. If the first argument is a positive integer, the output is printed only if DEBUG is set to that number or higher. The remaining arguments are concatenated with spaces, a newline is appended, and the results are printed to STDERR. Some minor formatting is done to help distinguish undef values and values with leading or trailing spaces. To get further details, or to learn how to override any of those things, see "The debuggit function" in Debuggit::Manual.

add_func

remove_func

DIAGNOSTICS

Cannot redefine DEBUG; original value of %s is used

It means you did something like this:

use Debuggit DEBUG => 2;
use Debuggit DEBUG => 3;

only probably not nearly so obvious. Debuggit tries to be very tolerant of multiple imports into the same package, but the DEBUG symbol is a constant function and can't be redefined without engendering severe wonkiness, so Debuggit won't do it. As long as you pass the same value for DEBUG, that's okay. But if the second (or more) value is different from the first, then you will get the original value regardless. At least this way you'll be forewarned.

PERFORMANCE

Debuggit is designed to be left in your code, even when running in production environments. Because of this, it needs to disappear entirely when debugging is turned off. It can achieve this unlikely goal via the use of a compile-time constant. Please see "Performance Considerations" in Debuggit::Manual for full details.

BUGS and CAVEATS

Once you set DEBUG, you can't change it. Even if you try, you get the original value. See "DIAGNOSTICS".

Doing:

debuggit(0 => "in production mode");

never prints anything, even when DEBUG is 0. That's because debuggit is guaranteed to be an empty function when debugging is turned off.

Doing:

debuggit($var, "is the value");

is inherently dangerous. If $var is a positive integer, debuggit would interpret it as a debug level, and not print it. So, either do this:

debuggit(1 => $var, "is the value");

or this:

debuggit("the value is", $var);

Or, to look at it another way, you can pass a value as the first arg to print, or you can leave off a debugging level altogether, but don't try to do both at once.

That's all I know of. However, lacking omniscience, I welcome bug reports.

SUPPORT

Debuggit is on GitHub at barefootcoder/debuggit. Feel free to fork and submit patches. Please note that I develop via TDD (Test-Driven Development), so a patch that includes a failing test is much more likely to get accepted (or least likely to get accepted more quickly).

If you just want to report a problem or request a feature, that's okay too. You can create an issue on GitHub, or a bug in CPAN's RT (at http://rt.cpan.org). Or just send an email to bug-Debuggit@rt.cpan.org.