Debug - interface for providing debug information
This module is supposed to be used by all project modules. This will ensure,
the debug information from anywhere is systematized and can be catched,
handled and logged uniformly. The actual logging is done by DebugLogger
modules.
* $ON - must be set externally
* $HANDLER - [un]set by set_handler, used by Debug::print()
* $MONITORED_PACKAGES - hash, must be set externally
* $MONITORED_PACKAGES_PREV - hash of arrays, used by {pop|push}_monitored
In module X::Y, providing debug info:
package X::Y;
use Debug;
...
sub some_function {
# This always forces debug info
Debug::print('X::Y::some_function called!');
# This produces debug info, when caller wants X::Y to provide it
Debug::put('X::Y::some_function still here!');
...
}
In script, wanting to log debug info (to stdout) from module X::Y:
use X::Y;
use DebugLogger::Stdout;
Debug::Logger::Stderr->new->monitor('X::Y')->show_time->start;
...
X::Y::some_function();
the DebugLogger manpage, the DebugLogger::Stdout manpage, the DebugLogger::File manpage.
This function can be used by module to produce debug info, given in parameter.
If user handler was previously defined by set_handler, it is called with
one parameter: joined with empty delimiter original parameters, otherwise
default_handler is called.
Default handler prints debug info to stderr (unix) or stdout (win/dos) with ``[Debug] '' prefix for every line. Also at the very beggining, printed line: ``[Starting debugging output]''. In CGI environment there may be a need to use html output instead of plain text, then set $ENV{DEBUG_USING_HTML}.
push_monitored gets new monitoring flag value.
is_monitored and pop_monitored return current monitoring flag value.
These two are equivalent:
Debug::put(@d);
Debug::print(@d) if Debug::is_monitored();
print function.
If the parameter starts from a lower letter, then it is appended to the caller, i.e. if My::Package calls put_as(``names'', ``message'') then it is the same as put_as(``My::Package::names'', ``message'').
print function, but the first parameter is package name.
# 1-st example
Debug::set_handler { print STDERR "[Debug] $_[0]\n"; };
# 2-nd example
my $handler = sub { insert_html("\n<P>" . CGI::escapeHTML($_[0])); };
Debug::set_handler($handler);
# 3-rd example Debug::set_handler(undef);