NAME Debug::ShowStuff - A collection of handy debugging routines for displaying the values of variables with a minimum of coding. SYNOPSIS Here's a sampling of a few of my favorite functions in this module. use Debug::ShowStuff ':all'; # display values of a hash or hash reference showhash %hash; showhash $hashref; # display values of an array or array reference showarr @arr; showarr $arrref; # show all the params received through CGI showcgi(); # A particularly fancy utility: display STDERR at top of web page my $warnings = showstderr; INSTALLATION Debug::ShowStuff can be installed with the usual routine: perl Makefile.PL make make test make install DESCRIPTION Debug::ShowStuff grew dynamically from my needs in debugging code. I found myself doing the same tasks over and over... displaying the keys and values in a hash, displaying the elements in an array, displaying the output of STDERR in a web page, etc. Debug::ShowStuff began as two or three of my favorite routines and grew as I added to that collection. Finally I decided to publish these tools in the hope that other Perl programmers will find them useful. Not for production work Debug::ShowStuff is for debugging, not for production work. It does not always output the actual value of something, but rather information about the value. For example, the following code outputs the actual value in the first line, but a note about the value in the second. println 'my value'; println undef; which outputs my value [undef] I would discourage you from using Debug::ShowStuff in production code. Debug::ShowStuff is only for quick-n-dirty displays of variable values in order to debug your code. Text and web modes The functions in Debug::ShowStuff are designed to output either in plain text mode (like if you're running the script from a command prompt), or in web mode (like from a CGI). If the script appears to be running in a CGI or other web mode (see the inweb function) then values are output using HTML, with special HTML characters escaped for proper display. Othewise the values are output as they are. Generally you won't need to bother telling Debug::ShowStuff if you're in text or web mode... it figures it out on its own. Dynamic output/return: different than previous versions NOTE: The dynamic behavior of "show" functions has changed since earlier versions of Debug::ShowStuff. "show" functions now always outputs to STDOUT or STDERR unless $Debug::ShowStuff::always_void is set to false. By default $always_void is true. If $always_void is false, then the following applies: The functions that start with "show" dynamically either output to STDOUT or STDERR or return a string, depending on the context in which the functions are called. For example, if you call showhash in a void context: showhash %myhash; then the contents of %myhash are output to STDOUT. On the other hand, if the function is called in scalar context: my $var = showhash(%myhash); then the same string that would have been output to STDOUT is instead returned and stored in $var. By default, output is sent to STDOUT, not STDERR. You can change the default output to STDERR using the setoutput command. See the docs for that command for more detail. Displaying "invisible" strings To facilitate telling the difference between [undef] and an empty string, functions output the strings "[undef]" and "[empty string]". So, for example, this code: println undef; println ""; produces this: [undef] [empty string] FUNCTION DESCRIPTIONS println println was the original Debug::ShowStuff function. It simply outputs the given values. In text mode it adds a newline to the end. For example, this code: println "hello world"; produces this output, including the newline: hello world In web mode it puts the output inside a

element. The values are HTML escaped so that HTML-significant characters like < and > are actually displayed as < and >. The

element has CSS styles set so that the characters are always black, the background is always white, text is left-aligned, and the

element has a black border, regardless of the styles of the surrounding elements. So, for example, in web mode, the following code: println 'whatever'; outputs the following HTML:

whatever

Like other "show" functions, undef is output as the string "[undef]" and an empty string is output as the string "[empty string]". Values in the arguments array are output concatenated together with no spaces in between. Each value is evaluated independently for if it is undef, empty string, or a string with visible content. So, for example, this code: println "whatever", "", undef, "dude"; outputs this: whatever[empty string][undef]dude indent() indent() is for situations where you're outputting a lot of stuff and you want to tidy up the putput with indentation. In text mode the output is indented with 3 spaces per indentation level. In web mode the output is indented with 20px per indentation level. indent() must be assigned to a variable or it has no effect. indent() increases the indent level by one. When the variable goes out of scope, the indent level is decreased by one. For example suppose you want to display the values of records from a database. You might loop through the records, outputting them like this: while (my $record = $sth->fetchrow_hashref) { println $record->{'name_nick'}; my $indent = indent(); showhash $record; } That would produce output something like this: Ricky --------------------------------------- name_first = Rick name_last = Adams --------------------------------------- Dan --------------------------------------- name_first = Daniel name_last = Bradley --------------------------------------- By default, three spaces are used to indent. To change that set $Debug::ShowStuff::indent_tab to whatever string you want to use for indentation. option: bottom_space The bottom_space option indicates to output an extra line at the bottom of the indented output, just to give some extra division before the next batch of code. For example, the following code does not use bottom_space: foreach my $name (qw[Larry Moe]) { println $name; my $indent = indent(bottom_space=>1); println 'years: ', length($name); } and so produces the following output: Larry years: 5 Moe years: 3 But this code: foreach my $name (qw[Larry Moe]) { println $name; my $indent = indent(bottom_space=>1); println 'years: ', length($name); } produces this output: Larry years: 5 Moe years: 3 showstuff() This function turns on/off most of the functions in this module, with one important exception explained below. The function also returns the state of whether or not Debug::ShowStuff is on/off. If a parameter is sent, that param is used to turn display on/off. The value is stored in the global variable $Debug::ShowStuff::active. The function is also used by most subroutines to determine if they should actually output anything. $Debug::ShowStuff::active is not the only criteria used to determine if Debug::ShowStuff is active. The algorithm is as follows: - If the environment variable $ENV{'SHOWSTUFF'} is defined and false then showstuff() returns false regardless of the state of $active. - If the environment variable $ENV{'SHOWSTUFF'} is not defined or is defined and true then showstuff() uses $Debug::ShowStuff::active to determine on/off. The purpose of this algorithm is to allow the use of debugging display in situations where one perl script calls another, such as in regression testing. For example, suppose you have a script as follows: #!/usr/bin/perl -w use strict; use Debug::ShowStuff ':all'; my ($rv); println 'running my_function()'; $rv = my_function(); println 'the returned value is: ', $rv; $rv or die 'error!'; The output of the script might look something like this: running my_function() 1 Now suppose you call that and other scripts from some OTHER script, and you don't want the screen cluttered with all that debugging, you just want to see if all those scripts run successfully. You could use $ENV{'SHOWSTUFF'} to turn off showing stuff: #!/usr/bin/perl -w use strict; use Debug::ShowStuff ':all'; my @tests = ("./script1.pl", "./script2.pl", "./script3.pl"); $ENV{'SHOWSTUFF'} = 0; foreach my $test () { system($test) and die "$test failed"; } In that case, none of the stuff from the test scripts would be output. printnorm Works like println but doesn't add trailing newline. In web environment uses instead of

. showhash Displays the keys and values in a hash. Input is either a single hash reference or a regular hash. The key=values pairs are sorted by the names of the keys. So, for example, the following code: my %hash = ( Larry => 'curly headed guy', Curly => 'funny bald guy', Moe => 'guy in charge', ); showhash %hash; Produces the following output. Notice that the keys are in alphabetic order: --------------------------------------- Curly = funny bald guy Larry = curly headed guy Moe = guy in charge --------------------------------------- This code, using a hash reference, produces exactly the same output: my $hash = { Larry => 'curly headed guy', Curly => 'funny bald guy', Moe => 'guy in charge', }; showhash $hash; If the hash is empty, then that fact is output. So, this code: showhash {}; produces this output: --------------------------------------- [empty hash] --------------------------------------- If an undef value is sent instead of a hashref, then that fact is displayed instead of a hash. For example consider the following code that uses a variable that is undef: my ($hash); showhash $hash; That code produces this output: --------------------------------------- Only one element input and it was undefined --------------------------------------- Optional arguments only come into play if the first argument is a hashref. option: title => "string" If this option is sent, the string is displayed at the top of the display of the hash values. So this code: my $hash = { Larry => 'curly headed guy', Curly => 'funny bald guy', Moe => 'guy in charge', }; showhash $hash, title=>'Stooges'; produces this output: --- Stooges --------------------------------- Curly = funny bald guy Larry = curly headed guy Moe = guy in charge --------------------------------------------- option: line_cut => 1 If the line_cut option is sent, then each value is truncated after the first newline if there is one. The fact that there is more output is mentioned. So the following code: my $hash = { Larry => "curly\nheaded guy", Curly => "funny\nbald guy", Moe => "guy\nin charge", }; showhash $hash, line_cut =>1; produces this output. --------------------------------------- Curly = funny [more lines...] Larry = curly [more lines...] Moe = guy [more lines...] --------------------------------------- Several other options do exactly the same thing: linecut, line_chop, and first_line. showarr, showarray Displays the values of an array. c and c Each element is displayed in a table row (in web mode) or on a separate line (in text mode). If showarray receives exactly one argument, and if that item is an array reference, then the routine assumes that you want to display the elements in the referenced array. Therefore, the following blocks of code display the same thing: showarray @myarr; showarray \@myarr; showarraydiv Works just like showarray, except that in text mode displays a solid line between each element of the array. showscalar Outputs the value of a scalar. The name is slightly innaccurate: you can input an array. The array will be joined together to form a single scalar. Actually, I hardly ever use showscalar, but it seemed unbalanced to have showhash and showarray without showscalar. showcgi Displays the CGI parameter keys and values. This sub always outputs HTML. There are several optional parameters, described in the following sections. option: q The optional parameter q, may be a CGI query object: my $query = CGI->new(); showcgi q => $query; If q is not sent, then a CGI object is created on the fly. option: skipempty If the optional parameter skipempty is true: showcgi skipempty => 1; then CGI params that are empty (i.e. do not have at least one non-space character) are not displayed. option: skip skip sets a list of parameters to not display. For example, if you don't want to see the choices or toppings params, then call showcgi like this: showcgi skip => ['choices', 'toppings']; Single item lists can be passed in directly without putting them in an anonymous array: showcgi skip => 'choices'; showref($ref, %options) Displays a hash, array, or scalar references, treeing down through other references it contains. So, for example, the following code: my $ob = { name => 'Raha', email => 'raha@idocs.com', friends => [ 'Shalom', 'Joe', 'Furocha', ], }; showref $ob; produces the following output: /-----------------------------------------------------------\ friends = ARRAY Shalom Joe Furocha email = raha@idocs.com name = Raha \-----------------------------------------------------------/ The values of the hash or arrays being referenced are only displayed once, so you're safe from infinite recursion. There are several optional parameters, described in the following sections. option: maxhash The maxhash option allows you to indicate the maximum number of hash elements to display. If a hash has more then maxhash elements then none of them are displayed or recursed through, and instead an indicator of how many elements there are is output. So, for example, the following command only displays the hash values if there are 10 or fewer elements in the hash: showref $myob, maxhash=>10; If maxhash is not sent then there is no maximum. option: maxarr The maxarr option allows you to indicate the maximum number of array elements to display. If an array has more then maxarr elements then none of them are displayed or recursed through, and instead an indicator of how many elements there are is output. If maxarr is not sent then there is no maximum. option: depth The depth option allows you to indicate a maximum depth to display in the tree. If depth is not sent then there is no maximum depth. option: skip A list of hash elements to skip. Only applies to the top element and only if it is a hash. option: skipall Works the same as skip, but applies to all hashes in the structure, not just the top-level hash. printhr Prints a horizontal rule. Handy for dividing up multiple println's. In text mode, the horizontal rule is a set of 80 dashes. In web mode, the output is either a


element or a

element, depending on the title option (see "title" below). So, for example, the following line outputs a simple horizontal rule: option: title If the titleoption is sent, the title is embedded in the horizontal rule. So, for example, the following code produces a horizontal rule with with the string "test" embedded in it: printhr title=>'test'; If only one param is sent, it is assumed that param is the title. So the' following code produces exactly the same thing as the example above: printhr 'test'; In web mode, a title changes the HTML element that is output. If no title is given then printhr outputs an


element. If a title is given the output is p element with the title as the content. The

element has a gray background and a black border. option: dash If the dashoption is sent, the given character is used as the separator. This param only applies to text mode; preln Outputs the given values inside a

 element. If not in a web
    environment, works just like preln.

 dieln

    Works like the die command, except it always adds an end-of-line to the
    input array so you never get those "at line blah-blah-blah" additions.

 devexit

    Works like dieln except it prepends 'dev exit: ' to the end of the
    string. If no string is sent, just outputs "dev exit".

 diearr

    Displays an array, then dies using dieln.

 pressenter

    For use at the command line. Outputs a prompt to "press enter to
    continue", then waits for you to do exactly that.

 confirm

    Prompts the user for a y or n. Exits quietly if y is pressed.

 httpheader

    Outputs a text/html HTTP header. Not useful if you're using mod_perl.

 showstderr

    This function allows you to see, in the web page produced by a CGI,
    everything the CGI output to STDERR.

    To use showstderr, assign the return value of the function to a
    variable that is scoped to the entire CGI script:

      my $stderr = showstderr();

    You need not do anything more with that variable. The object reference
    by your variable holds on to everything output to both STDOUT and
    STDERR. When the variable goes out of scope, the object outputs the
    STDOUT content with the STDERR content at the top of the web page.

 forcetext, forceweb, forcenone

    By default, Debug::Showstuff guesses if it should be in text or web
    mode. These functions are for when you want to explicitly tell
    Debug::ShowStuff what mode it should be in. forcetext forces text mode.
    forceweb forces web mode. forcenone tells Debug::Showstuff that you
    don't want to force either mode.

 inweb

    Returns a guess on if we're in a web environment. The guess is pretty
    simple: if the environment variable REQUEST_URI is true (in the Perlish
    sense) then this function returns true.

    If the global $Debug::ShowStuff::forceenv is defined, this function
    returns the value of $Debug::ShowStuff::forceenv.

 output_to_file($path)

    Sends Debug::ShowStuff output to a file instead of to STDOUT or STDERR.
    The value of this function must be assigned to a variable or it has no
    effect. Don't do anything with the returned value... it is NOT a file
    handle. The returned value is an object that, when it goes out of
    scope, closes the output file handle.

    For example, the following code will output to three files names
    Larry.txt, Curly.txt, and Moe.txt:

     foreach my $name (qw[Larry Curyl Moe]) {
        my $output = output_to_file("$name.txt");
        println $name;
        println 'length: ', length($name);
     }

 setoutput

    Sets the default output handle. By default, routines in
    Debug::ShowStuff output to STDOUT. With this command you can set the
    default output to STDERR, back to STDOUT, to a filehandle you specify,
    or to a Debug::ShowStuff::SeparatePrint file handle.

    The following command sets default output to STDERR:

     setoutput 'stderr';

    This command sets output back to STDOUT:

     setoutput 'stdout';

    This command sends output to a file handle of your choice:

     setoutput $fh;

    This command sends output to a Debug::ShowStuff::SeparatePrint file
    handle. This option is a good way to create a simple log file. When you
    print to this type of file handle, the file is opened separately just
    for that write, an exclusive lock on the file is obtained, and the end
    of the file is sought.

    Note that the next parameter must be the path to the output file:

     setoutput 'separateprint', $file_path;

    option: new

    If the new parameter is true, then the output file is open in
    non-append mode, which means any existing contents are removed.

 fixundef

    Takes a single argument. If that argument is undefined, returns an
    empty string. Otherwise returns the argument exactly as it is.

 findininc

    Given one or more file names, searches @INC for where they are located.
    Returns an array of full file names.

 showtainted(@values)

    Given an array of values, shows which are tainted and which are not. If
    the first argument is a hashref, displays the tainted status of each
    element value.

 showsth

    Outputs a table of all rows in the given DBI statement handle. Note
    that this function "uses up" the statement handle.

 showsql

    showsql output the results of an SQL statement. showsql takes three
    parameters: the database handle, the SQL statement, and an array-ref of
    parameters for the SQL statement.

 explainsql

    explainsql outputs the result of an SQL EXPLAIN call. This function
    works much like showsql. The parameters are the database handle, the
    SQL statement, and an array-ref of SQL parameters. explainsql prepends
    "EXPLAIN ANALYZE" to your SQL, runs the statement, then outputs the
    results.

    I have only used explainsql with PostGresql. I would be interested hear
    about how it works with other database management systems and how it
    might be improved to work in those environments.

 tempshowstuff

    Temporarily turn showstuff on or off. Create a variable in the lexical
    scope where you want the tempoary change, like this:

    my $temp = tempshowstuff(1)

    When the variable goes out of scope, showstuff will revert back to its
    previous state.

 showisa

    Outputs the ISA hierarchy of an object or class. For example, the
    following code outputs the ISA hierarchy for a Xapat object (Xapat is a
    web server written in Perl and which uses Net::Server).

     $xapat = Xapat->new(%opts);
     showisa $xapat;

    which outputs:

     ------------------------------------
     Xapat
     Net::Server::HTTP
     Net::Server::MultiType
     Net::Server
     ------------------------------------

    Note that showisa loads Class::ISA, which is available on CPAN.

 timer

    This function is for when you want to display how long it took for your
    code to run. Assign the return value of this function to a variable.
    When the variable goes out of scope then the difference between the
    start and end time is displayed in seconds. For example, the following
    code:

     do {
        my $timer = timer();
        sleep 3;
     };

    outputs this:

     start timer
     duration: 3 seconds

    option: title

    If you send the title option, then that title will be displayed with
    the beginning and ending output. For example, this code:

     do {
        my $timer = timer(title=>'my block');
        sleep 3;
     };

    produces this output:

     start timer - my block
     duration - my block: 3 seconds

    method: $timer->elapsed

    Returns the difference between when the timer was started and the
    current time.

    method: $timer->silence

    Turns off the timer so that it doesn't display anything when it dies.

TERMS AND CONDITIONS

    Copyright (c) 2010-2013 by Miko O'Sullivan. All rights reserved. This
    program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself. This software comes with NO
    WARRANTY of any kind.

AUTHORS

    Miko O'Sullivan miko@idocs.com

VERSION

    Version 1.00 May 29, 2003

      Initial public release.

    Version 1.01 May 29, 2003

      Setting sort order of hash keys to case insensitive.

    Version 1.10 Nov 6, 2010

      After seven years, decided to update the version on CPAN.

    Version 1.11 Nov 13, 2010

      Fixed prerequisite requirement for MemHandle and Taint. Added timer()
      functions. Some minor documentation fixes and tidying up.

    Version 1.12 Nov 29, 2010

      Changing from using Taint module, which has had a lot of problems, to
      Scalar::Util, which is more (but not completely) stable.

    Version 1.13 Dec 1, 2010

      Fixed bug in prerequisites for Scalar::Util.

    Version 1.14 February 23, 2013

      Added showsth, showsql, and explainsql. Added the separateprint
      option to setoutput. Tidied up documentation. Fixed problems with
      prerequisites. Probably added many other features since the last time
      I uploaded this module, but can't remember tham all.