Net::IMP::Debug(3)

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.

rxvar => \$myDEBUG_RX
    This makes the local $DEBUG_RX variable an alias for $myDEBUG_RX. $myDEBUG_RX 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.