NAME

Debug::Show - display variables helpfully for debugging

SYNOPSIS

        use Debug::Show qw(debug=hide);   # normally
        use Debug::Show qw(debug=show);   # while debugging

        debug $foo, $bar->{baz};

DESCRIPTION

This module provides a facility for displaying variable values for debugging purposes. Statements in the code determine what values are displayed. Whether the statements actually cause debugging output depends on the manner in which Debug::Show was invoked, so the debug statements can remain permanently in the code, normally inactive. When inactive, the debug statements impose no runtime overhead.

When the debug statements are active, each value displayed is labelled with the expression used to generate it. This saves the bother of manually applying labels.

FUNCTIONS

These functions are not exported in the normal way. See below for how to import. The functions may be referenced directly by fully qualified name (e.g., Debug::Show::debug_show).

debug_show(EXPR, ...)

Display (via warn) the values of all the argument expressions. There may be any number of argument expressions. Each value is deeply serialised (by means of Data::Dumper), and is labelled with source for the expression that evaluated to it (generated by B::Deparse). All the expresssions are evaluated in scalar context, so say \%foo rather than %foo if you want to display the contents of a hash. The entire display consists of a single line.

debug_hide(EXPR, ...)

Do nothing. Calls to this function are excised at compile time, so there is no overhead from evaluating the argument expressions or calling the subroutine.

PACKAGE METHOD

This method is meant to be invoked on the Debug::Show package. It will normally be accessed through the use facility.

Debug::Show->import("debug=show")

Puts the subroutine "debug_show" into the caller's namespace under the name "debug".

Debug::Show->import("debug=hide")

Puts the subroutine "debug_hide" into the caller's namespace under the name "debug".

BUGS

The operation of this module depends on B::Generate. That module has been found to interact badly with other B:: modules in some cases. This module includes workarounds for known bugs, but others may lurk.

Because the expression source in the output is generated by B::Deparse, it cannot be expected to match the original source character-for-character. It will normally be equivalent source. In some obscure cases the deparser generates incorrect output; that is a bug in B::Deparse. The kinds of expression that confuse the deparser are relatively unlikely to occur with expressions being displayed for debugging.

The shenanigans that take place with the debug functions at compile time will make B::Deparse produce incorrect output for the debug statements.

When hiding debug output, the ops corresponding to the debug expressions, which ought to be freed, are instead leaked. This is because freeing them has been observed to cause memory corruption. The cause of this is currently unknown. The leakage should have negligible impact, unless debug statements occur in code that is repeatedly generated dynamically.

SEE ALSO

B::Deparse, Data::Dumper

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2011 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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