NAME

Net::IMP::Debug - provide debugging functions

SYNOPSIS

    # within Net::IMP packages
    use Net::IMP::Debug;
    ...
    debug('some msg');
    debug('got msg="%s" count=%d',$msg,$count);
    $DEBUG && debug('some msg');

    # outside of Net::IMP
    use Net::IMP;
    Net::IMP->set_debug(1,qr{::Pattern});

    # or integrate it into existing debugging framework
    # $myDebug needs to be global, not lexical!
    use myDebug qw(my_debug $myDEBUG);
    use Net::IMP::Debug var => \$myDEBUG, sub => \&my_debug;

DESCRIPTION

Net::IMP::Debug provides debugging functions for use inside the Net::IMP packages. It provides a way to debug only some packages and to make the internal debugging use an external debug function for output.

The following API is defined for internal use:

debug($message) | debug($format,@args)

Create a debug message. It can be used with a single $message or sprintf-like with $format and @args.

If message gets dynamically generated in an expensive way, it is better to call debug only if $DEBUG is true, so that the message only gets generated on active debugging.

If no external debug function is set (see below), the function will write the message to STDERR, prefixed with subroutine name and line number. If an external debug function is set, it will call this function with the debug message, maintaining the calling stack (e.g. using goto).

This function gets exported by default.

$DEBUG

This variable is true if debugging is on, else false. It gets exported by default.

$DEBUG_RX

This variable can contain a regex. If set, only debugging within packages matching the regex will be enabled, but only if c<$DEBUG> is also true.

This variable can be exported.

For external use the set_debug function is provided.

$class->set_debug(onoff,regex)

With this function one can enable/disable debugging.

If onoff is defined it will enable (if true) or disable (if false) debugging.

If regex is given it will be used as a filter to decide, which packages can write debug messages. If explicitly given as undef the value will be reset.

To integrate the debugging of Net::IMP with other debugging frameworks one has to call

  Net::IMP::Debug var => \$myDEBUG, sub => \&my_debug;

as early as possible (before any modules using Net::IMPs debug functionality get loaded).

var => \$myDEBUG

This make the local $DEBUG variable an alias for $myDEBUG. $myDEBUG needs to be a global variable, lexical variables will not work.

sub => \&my_debug

This will call my_debug with the debug message instead of using the builtin implementation.

AUTHOR

Steffen Ullrich <sullr@cpan.org>

COPYRIGHT

Copyright by Steffen Ullrich.

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