New module: Debug_Messages

Austin Schutz tex at
Sat Dec 2 23:31:24 CST 2000

Who: me
When: now
What: New debugging module

	This module is one of my favorite pieces of my own code, which
I haven't released to the public until now for fear that everyone would
tear it apart and tell me what a dork I am for releasing it because there
are similar tools, etc. etc. etc. Anyway, I figured by letting a few people
try it on this small list that I could get some feedback before going further
with it.

	There's a few different ways of using this module, so if the first
bit doesn't seem interesting to you, please keep reading.

	Debug_Messages (better name suggestions are welcome) is a debugging
and error reporting swiss army knife. It allows you to:

	-debug variables and entire perl object structures quickly and
	-trace the execution of your code, in part or in full.
	-do more effective and concise error handling. 
	-pinpoint how your code is executed. 
	-provide debugging facilities to the users of your code.
	-do all of the above in any of syslog, stderr, or
		stdout in html format.

	Ok, did you get all that?
	There's a longer explanation of what the module is/does below.


	Because there is no existing tool that is as complete in its
utility, and because it provides a clean and consistent error reporting
device. It's very different (and better, IMO) than anything you might
think is similar, e.g. Carp.

	Please let me know what you think.


perldoc Debug_Messages:

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)


       A module for concise error reporting, process tracing,
       variable debugging.  Multiple destinations are easy, so
       you can send output to a web page, syslog, or STDERR
       without extra code. Debugging code is very easy to use and
       may be left in the final version of scripts without
       creating a lot of overhead.

       You should really look at the docs on each sub to have an
       idea what can be done with this module.

       use Debug_Messages;

       use Debug_Messages ':standard';

               :standard includes everything that can be imported.

               The following can be imported from Debug_Messages:


       The following special variables affect the behavior of


               debug is handy for displaying non-error messages.
       debug prints a marker, followed by separate indented lines for each
       message, e.g.:

       $Debug = 2;

       sub test {

         debug "hello";



       debug 2: ./ line 8, package main: main::test():

               Note that debug in this case would print _nothing_ if $Debug
       were less than 2 or undefined. See the next example for clarification.

2/Dec/2000             perl 5.005, patch 03                     1

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)

               One of the handy things this allows you to do is create a trace
       of the execution of your program, e.g.:

       use Debug_Messages ':standard';

       $Debug = 4;

       sub a {
         b(); }

       sub b {
         c(); }

       sub c {
         print "hi there\n"; }



       debug 2: line 8, package main: main::a() debug 3: line 13, package main: main::b() debug 4:
       line 18, package main: main::c() hi there

               The number after 'debug' refers to the recursive 'depth' of the
       call. If you set $Debug = a smaller number, you will only see lines
       that are of lower depth. Here's the output with Debug set to 3:

       debug 2: line 8, package main: main::a() debug 3: line 13, package main: main::b() hi there

               Notice that the variable set is $main::Debug. Debugging level
       is set per package, so you can debug or not debug each package. See
       the Special Variables section for more information.


               Will return an array representing a subroutine stack trace. Ex.:

       sub a { b(); }

       sub b { c(); }

       sub c { print( map( " ".$_."\n", trace())); }



2/Dec/2000             perl 5.005, patch 03                     2

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)

        ./ line 5, package main: main::c()
        ./ line 4, package main: main::b()
        ./ line 3, package main: main::a()
        ./ line 6, package main: (not in a sub)

               trace is mostly used like:

       debug( trace );

               which would output:

       debug 4: ./ line 7, package main: main::c():
           ./ line 7, package main: main::c()
           ./ line 6, package main: main::b()
           ./ line 5, package main: main::a()
           ./ line 8, package main: (not in a sub)


               Like trace, but by default only returns the first line.
       Typically you would just call marker();. It will create a trace of
       calls starting with whatever the starting depth is. This is handy if
       you have a sub that wants to report a marker of its parent. Ex:

       sub test {
         report(); } sub report {
         print "Marker from test:".marker(1); }

               marker(), which is the first line printed by debug(),
       is a string, or array of strings, containing the following:

       $filename line $line_number, package $package $I<sub>(
       @sub_args )


       "./ line 5, package main: main::a()"

       where $filename is the file containing the marker() line,
       $line_number is the line in $filename where marker() was
       called, $package is the package in scope where marker()
       was called, $sub is the name of the sub being executed
       where marker was called, and @sub_args are the arguments
       which were passed to $sub when it was called.

       vprint(\variable, 'variable name',

2/Dec/2000             perl 5.005, patch 03                     3

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)

               Print a marker, followed by the name and contents of variable.
       Both the name of the variable and $recursive_display_depth are optional.
       vprint needs to be passed B<_a_reference_to_> the variable in question,
       indicated as \variable above. 'variable' can be a variable of any type,
       or a reference to a variable of any type. vprint knows how to deal with
       SCALARs, ARRAYs, HASHes, GLOBs, and CODE refs. I wasn't sure to to
       represent a generic variable reference, so I chose \variable. Sorry
       for the confusion.

               'variable name' is optional. It's not trivial to have vprint
       be able to tell what the name of a variable is with only its reference
       to go by, so you have to pass it if you want the name printed in vprint's
       output. Otherwise vprint will print '(no name passed)'.

               $recursive_display_depth refers to how deep within the variable /
       object you want to go displaying the contents of references. Default is
       20, which is pretty deep.


               Like debug but will always print, not just when $Debug is set.


               Set error messages for the current location. This is extremely
       handy for giving detailed information about why something failed. Ex.:

       sub get_filehandle {
         my($filename) = shift;
         unless( open(FILE, $filename)) {
           eappend( "couldn't open file", $!);
           return undef;
         return \*FILE; }

       sub process_file {
         my($filename) = shift;
         unless( defined($file = get_filehandle($filename))) {
           eappend( "Couldn't get filehandle" );
           return undef;
        ...  }

       unless(defined(process_file($my_file))) {
         eappend( "Couldn't process $my_file");
         exit; }

2/Dec/2000             perl 5.005, patch 03                     4

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)

               This is extremely handy method for a few reasons.

               First, the error isn't necessarily printed by any of the subs that get
       called. This is important if you are writing a module where someone else may
       not want you crapping your error messages to the screen. It's up to them to
       do it. eappend() merely stores the errors.

               Second, errors are extremely verbose and printed (by eprint)
       in a very easy to read fashion pinpointing the exact location and nature of the

               Third, calling subs get to decide whether or not an error is
       catastrophic or ignorable.

               Fourth, Debug_Messages can print messages to several locations
       (or none!) depending on the whim of the user. Maybe error messages should
       be printed to syslog, or maybe they should be totally ignored. Or maybe
       the errors should be in html because the user has a web application.

               Fifth, there are probably other reasons I can't think of right now.


               print errors to all configured places, then clear errors. See the
       special variables section for details. Returns the errors as a string
       as would be printed to STDERR if
       $Debug_Messages::Debug_Styles->{stderr} is set.


               clears $Debug_Messages::Errors; Useful if you have caught and
       ignored an error, or dealt with the error manually.


               close syslog handle. Useful if you want to change the syslog
       facility. Close the log, which will automatically be reopened the next time a
       message is printed. See special variables for syslog vars.

       Special Variables

               $Debug_Messages::Errors is an array reference containing
       the stack of the last error messages and their "depth". More on this in
       the 'Internals' section.

2/Dec/2000             perl 5.005, patch 03                     5

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)

               $Debug_Messages::Debug_Styles is a hash ref containing the different
       output styles currently selected, e.g.:

       $Debug_Messages::Debug_Styles = {
         'stderr' => 1,
         'html' => 1,
         'syslog' => 1 }

       will turn on all styles of printing. 'stderr', 'html', and
       'syslog' are the currently supported styles.
            $Debug_Messages::Indent_String, normally set to ' ' x
       8, is the string used to format errors printed to STDERR.

               $Debug_Messages::Auto_Clear_Errors, if set, eprint() will
       clear the $Debug_Messages::Errors variable after printing errors.
       Set to 1 by default.

               $Debug_Messages::Syslog_Facility is the facility syslog uses for
       syslog messages. Default is 'local3'. Do close_log();
       if you want to change the facility.

               $Debug_Messages::Syslog_Debug_Priority is the priority used for debug
       messages. Default is 'debug'.

               $Debug_Messages::Syslog_Error_Priority is the priority used for error
       messages. Default is 'err'.

               $Debug_Messages::Print_Args is used to determine whether or not to
       print the arguments to a sub in marker(). Not putting in the args can be
       useful in the situation where you don't want the user to see them, e.g.
       you pass a password to a routine. marker will then print the number
       of args passed to the sub.

               $Debug is the depth of debug calls that will be printed when debug
       is called. If unset no debugging messages will be printed. Notice that
       Debug can be set B<In the caller's package> or in main::. This is an extremely
       important point. The reason for this is to make it possible to only debug
       messages from a certain package, if the user so wishes. If
       the caller's $Debug is set, its value will have precedence over
       $Debug_Messages::$Debug, which has precedence over $main::Debug.

       Setting $Debug to a large number and putting debug; at the
       top of each of your subs will generate a call trace when
       your program is run.

               $Syslog_SockType is set to 'unix' by default. This is the type
       of socket Sys::Syslog will use when Debug_Messages internally calls
       setlogsock(). This only applies if you are logging to syslog, naturally.
       See perldoc Sys::Syslog for clarification.

2/Dec/2000             perl 5.005, patch 03                     6

Debug_Messages(User Contributed Perl DocumentaDebug_Messages(3pm)


               The $Debug_Messages::Errors variable contains the output from
       eappend. It looks is an arrayref that looks like:

         [ $depth, [ @messages ] ],
         [ $depth2, [ @messages2] ],
         [$depthN, [ @messagesN] ] ]

               Where each depth is how far back caller($depth) could go before coming
       up undefined. The messages are the messages (including a marker as the
       first item in the array) passed to eappend.

               In practice having a single variable to hold all errors seems to work
       well. It is much more convenient than having one per package or
       using a scheme like blessing a 'Debug_Messages' object and doing


               My experience with Sys::syslog::openlog() is that is returns undef
       even when it succeeds. Syslog may silently fail, and I'm not really sure
       what to do about that.

               'recursive depth' is used by using caller() until it returns undef.
       See perldoc caller() for the limitations of caller().


               Austin Schutz (tex at

2/Dec/2000             perl 5.005, patch 03                     7


More information about the Pdx-pm-list mailing list