Debug::ShowStuff version 1.11
=========================

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 nested structures
            showref $reference
        
            # 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

    You can also just copy ShowStuff.pm into the Debug/ directory of one of
    your library trees.

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
    hackers will find them useful.

    "Debug::ShowStuff" is intended for debugging, not for production work. I
    would discourage anyone from using "Debug::ShowStuff" in
    ready-for-primetime code. "Debug::ShowStuff" is only for quick-n-dirty
    displays of variable values in order to debug your code.

    These functions display values the way I personally like them displayed.
    Your preferences may be different. I encourage you to modify
    "Debug::ShowStuff" to suit your own needs.

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 the
    last version of Debug::ShowStuff. "show" functions now always output 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
  showstuff()
    This function turns on/off most of the functions in this module, with
    one import 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. $active is not the only criteria used
    to determine if Debug::ShowStuff is active. The algorithm is as follows:

    - If the environment variable SHOWSTUFF is defined and false then this
    function returns false regardless of the state of $active.

    - If the environment variable $ENV{'SHOWSTUFF'} is not defined or is
    defined and true then $active is used to determine on/off.

    The purpose of this algorithm is to allow the used of debugging display
    in a regression test but turn off those displays when a lot of tests are
    run at once and only pass/fail information is needed from the regtest.

    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.

  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 <p> element. The values are HTML
    escaped so that HTML-significant characters like < and > are actually
    displayed as < and >. The <p> element has CSS styles set so that the
    characters are always black, the background is always white, text is
    left-aligned, and the <p> 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:

     <p style="background-color:white;color:black;text-align:left">whatever</p>

    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

  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 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.

    option: line_cut => 1

    If the "line_cut" option is sent, then each value is truncated after the
    first newline if there is one.

  showarr, showarray
    Displays the values of an array. c<showarr> and c<showarray>

    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 an <hr> tag, unless the "title" option is
    sent, in which case the output is "p" element with the title as the
    content. The <p> element has a gray background and a black border.

    option: title

    If the "title"option is sent, the titleis embedded in the horizontal
    rule.

  printnorm
    Works like println but doesn't add trailing newline. In web environment
    uses <span> instead of <p>.

  preln
    Outputs the given values inside a <pre> element. Always outputs HTML.

  dieln
    Works just 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.

  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.

  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::forceweb is defined, this function
    returns the value of $Debug::ShowStuff::forceweb.

  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, or back to STDOUT. The following command sets
    default output to STDERR:

       setoutput 'stderr';

    This command sets output back to STDOUT:

       setoutput 'stdout';

    When default output is set to STDERR then the global
    $Debug::ShowStuff::forceplain is set to true, which means that functions
    in this module always output in text mode, not web mode.

  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.

    NOTE: The text mode version of this function has not been fully
    implemented.

  indent()
    "indent()" is for situations where you're outputting a lot of stuff and
    you want to tidy up the list by indenting some of the output. Currently
    "indent()" only has an effect in text mode. It does nothing in web mode.

    "indent()" b<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
       name_middle = Horatio
       name_nick   = Ricky
       salary      = $15,000
       ---------------------------------------

     Dan
       ---------------------------------------
       name_first  = Daniel
       name_last   = Bradley
       name_middle = [undef]
       name_nick   = Dan
       salary      = $250,000
       ---------------------------------------

    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 'length: ', length($name);
     }

    and so produces the following output:

     Larry
        length: 5
     Moe
        length: 3

    But this code:

     foreach my $name (qw[Larry Moe]) {
        println $name;
        my $indent = indent(bottom_space=>1);
        println 'length: ', length($name);
     }

    produces this output:

     Larry
        length: 5

     Moe
        length: 3

timer();
    This function is useful 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

TERMS AND CONDITIONS
    Copyright (c) 2010 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.