1Debug::ShowStuff(3)   User Contributed Perl Documentation  Debug::ShowStuff(3)
2
3
4

NAME

6       Debug::ShowStuff - A collection of handy debugging routines for
7       displaying the values of variables with a minimum of coding.
8

SYNOPSIS

10       Here's a sampling of a few of my favorite functions in this module.
11
12        use Debug::ShowStuff ':all';
13
14        # display values of a hash or hash reference
15        showhash %hash;
16               showhash $hashref;
17
18        # display values of an array or array reference
19        showarr @arr;
20        showarr $arrref;
21
22        # show all the params received through CGI
23        showcgi();
24
25        # A particularly fancy utility: display STDERR at top of web page
26        my $warnings = showstderr;
27

INSTALLATION

29       "Debug::ShowStuff" can be installed with the usual routine:
30
31        perl Makefile.PL
32        make
33        make test
34        make install
35

DESCRIPTION

37       "Debug::ShowStuff" grew dynamically from my needs in debugging code.  I
38       found myself doing the same tasks over and over... displaying the keys
39       and values in a hash, displaying the elements in an array, displaying
40       the output of STDERR in a web page, etc.  "Debug::ShowStuff" began as
41       two or three of my favorite routines and grew as I added to that
42       collection.  Finally I decided to publish these tools in the hope that
43       other Perl programmers will find them useful.
44
45   Not for production work
46       "Debug::ShowStuff" is for debugging, not for production work. It does
47       not always output the actual value of something, but rather information
48       about the value. For example, the following code outputs the actual
49       value in the first line, but a note about the value in the second.
50
51        println 'my value';
52        println undef;
53
54       which outputs
55
56        my value
57        [undef]
58
59       I would discourage you from using "Debug::ShowStuff" in production
60       code.  "Debug::ShowStuff" is only for quick-n-dirty displays of
61       variable values in order to debug your code.
62
63   Text and web modes
64       The functions in "Debug::ShowStuff" are designed to output either in
65       plain text mode (like if you're running the script from a command
66       prompt), or in web mode (like from a CGI).  If the script appears to be
67       running in a CGI or other web mode (see the "inweb" function) then
68       values are output using HTML, with special HTML characters escaped for
69       proper display.  Othewise the values are output as they are.
70
71       Generally you won't need to bother telling "Debug::ShowStuff" if you're
72       in text or web mode... it figures it out on its own.
73
74   Dynamic output/return: different than previous versions
75       NOTE: The dynamic behavior of "show" functions has changed since
76       earlier versions of Debug::ShowStuff.  "show" functions now always
77       outputs to STDOUT or STDERR unless $Debug::ShowStuff::always_void is
78       set to false. By default $always_void is true.
79
80       If $always_void is false, then the following applies:
81
82       The functions that start with "show" dynamically either output to
83       STDOUT or STDERR or return a string, depending on the context in which
84       the functions are called.  For example, if you call showhash in a void
85       context:
86
87         showhash %myhash;
88
89       then the contents of %myhash are output to STDOUT.  On the other hand,
90       if the function is called in scalar context:
91
92         my $var = showhash(%myhash);
93
94       then the same string that would have been output to STDOUT is instead
95       returned and stored in $var.
96
97       By default, output is sent to STDOUT, not STDERR.  You can change the
98       default output to STDERR using the "setoutput" command.  See the docs
99       for that command for more detail.
100
101   Displaying "invisible" strings
102       To facilitate telling the difference between "[undef]" and an empty
103       string, functions output the strings "[undef]" and "[empty string]".
104       So, for example, this code:
105
106        println undef;
107        println "";
108
109       produces this:
110
111        [undef]
112        [empty string]
113

FUNCTION DESCRIPTIONS

115   println
116       "println" was the original Debug::ShowStuff function.  It simply
117       outputs the given values.
118
119       In text mode it adds a newline to the end.
120
121       For example, this code:
122
123        println "hello world";
124
125       produces this output, including the newline:
126
127        hello world
128
129       In web mode it puts the output inside a <p> element. The values are
130       HTML escaped so that HTML-significant characters like < and > are
131       actually displayed as < and >.  The <p> element has CSS styles set so
132       that the characters are always black, the background is always white,
133       text is left-aligned, and the <p> element has a black border,
134       regardless of the styles of the surrounding elements. So, for example,
135       in web mode, the following code:
136
137        println 'whatever';
138
139       outputs the following HTML:
140
141        <p style="background-color:white;color:black;text-align:left">whatever</p>
142
143       Like other "show" functions, undef is output as the string "[undef]"
144       and an empty string is output as the string "[empty string]".
145
146       Values in the arguments array are output concatenated together with no
147       spaces in between.  Each value is evaluated independently for if it is
148       undef, empty string, or a string with visible content.  So, for
149       example, this code:
150
151        println "whatever", "", undef, "dude";
152
153       outputs this:
154
155        whatever[empty string][undef]dude
156
157   indent()
158       "indent()" is for situations where you're outputting a lot of stuff and
159       you want to tidy up the putput with indentation.  In text mode the
160       output is indented with 3 spaces per indentation level.  In web mode
161       the output is indented with 20px per indentation level.
162
163       "indent()" must be assigned to a variable or it has no effect.
164       "indent()" increases the indent level by one.  When the variable goes
165       out of scope, the indent level is decreased by one.
166
167       For example suppose you want to display the values of records from a
168       database.  You might loop through the records, outputting them like
169       this:
170
171        while (my $record = $sth->fetchrow_hashref) {
172           println $record->{'name_nick'};
173           my $indent = indent();
174           showhash $record;
175        }
176
177       That would produce output something like this:
178
179        Ricky
180          ---------------------------------------
181          name_first  = Rick
182          name_last   = Adams
183          ---------------------------------------
184
185        Dan
186          ---------------------------------------
187          name_first  = Daniel
188          name_last   = Bradley
189          ---------------------------------------
190
191       By default, three spaces are used to indent. To change that set
192       $Debug::ShowStuff::indent_tab to whatever string you want to use for
193       indentation.
194
195       option: bottom_space
196
197       The "bottom_space" option indicates to output an extra line at the
198       bottom of the indented output, just to give some extra division before
199       the next batch of code.  For example, the following code does not use
200       "bottom_space":
201
202        foreach my $name (qw[Larry Moe]) {
203           println $name;
204           my $indent = indent(bottom_space=>1);
205           println 'years: ', length($name);
206        }
207
208       and so produces the following output:
209
210        Larry
211           years: 5
212        Moe
213           years: 3
214
215       But this code:
216
217        foreach my $name (qw[Larry Moe]) {
218           println $name;
219           my $indent = indent(bottom_space=>1);
220           println 'years: ', length($name);
221        }
222
223       produces this output:
224
225        Larry
226           years: 5
227
228        Moe
229           years: 3
230
231   showstuff()
232       This function turns on/off most of the functions in this module, with
233       one important exception explained below.  The function also returns the
234       state of whether or not Debug::ShowStuff is on/off.
235
236       If a parameter is sent, that param is used to turn display on/off.  The
237       value is stored in the global variable $Debug::ShowStuff::active.
238
239       The function is also used by most subroutines to determine if they
240       should actually output anything.  $Debug::ShowStuff::active is not the
241       only criteria used to determine if Debug::ShowStuff is active.  The
242       algorithm is as follows:
243
244       - If the environment variable $ENV{'SHOWSTUFF'} is defined and false
245       then showstuff() returns false regardless of the state of $active.
246
247       - If the environment variable $ENV{'SHOWSTUFF'} is not defined or is
248       defined and true then showstuff() uses $Debug::ShowStuff::active to
249       determine on/off.
250
251       The purpose of this algorithm is to allow the use of debugging display
252       in situations where one perl script calls another, such as in
253       regression testing.
254
255       For example, suppose you have a script as follows:
256
257        #!/usr/bin/perl -w
258        use strict;
259        use Debug::ShowStuff ':all';
260
261        my ($rv);
262
263        println 'running my_function()';
264        $rv = my_function();
265        println 'the returned value is: ', $rv;
266
267        $rv or die 'error!';
268
269       The output of the script might look something like this:
270
271        running my_function()
272        1
273
274       Now suppose you call that and other scripts from some OTHER script, and
275       you don't want the screen cluttered with all that debugging, you just
276       want to see if all those scripts run successfully.  You could use
277       $ENV{'SHOWSTUFF'} to turn off showing stuff:
278
279        #!/usr/bin/perl -w
280        use strict;
281        use Debug::ShowStuff ':all';
282
283        my @tests = ("./script1.pl", "./script2.pl", "./script3.pl");
284        $ENV{'SHOWSTUFF'} = 0;
285
286        foreach my $test () {
287           system($test) and die "$test failed";
288        }
289
290       In that case, none of the stuff from the test scripts would be output.
291
292   printnorm
293       Works like println but doesn't add trailing newline.  In web
294       environment uses <span> instead of <p>.
295
296   showhash
297       Displays the keys and values in a hash.  Input is either a single hash
298       reference or a regular hash. The key=values pairs are sorted by the
299       names of the keys.
300
301       So, for example, the following code:
302
303        my %hash = (
304           Larry => 'curly headed guy',
305           Curly => 'funny bald guy',
306           Moe => 'guy in charge',
307        );
308
309        showhash %hash;
310
311       Produces the following output.  Notice that the keys are in alphabetic
312       order:
313
314        ---------------------------------------
315        Curly = funny bald guy
316        Larry = curly headed guy
317        Moe   = guy in charge
318        ---------------------------------------
319
320       This code, using a hash reference, produces exactly the same output:
321
322        my $hash = {
323           Larry => 'curly headed guy',
324           Curly => 'funny bald guy',
325           Moe => 'guy in charge',
326        };
327
328        showhash $hash;
329
330       If the hash is empty, then that fact is output.  So, this code:
331
332        showhash {};
333
334       produces this output:
335
336        ---------------------------------------
337        [empty hash]
338        ---------------------------------------
339
340       If an undef value is sent instead of a hashref, then that fact is
341       displayed instead of a hash.  For example consider the following code
342       that uses a variable that is undef:
343
344        my ($hash);
345        showhash $hash;
346
347       That code produces this output:
348
349        ---------------------------------------
350        Only one element input and it was undefined
351        ---------------------------------------
352
353       Optional arguments only come into play if the first argument is a
354       hashref.
355
356       option: title => "string"
357
358       If this option is sent, the string is displayed at the top of the
359       display of the hash values.  So this code:
360
361        my $hash = {
362           Larry => 'curly headed guy',
363           Curly => 'funny bald guy',
364           Moe => 'guy in charge',
365        };
366
367        showhash $hash, title=>'Stooges';
368
369       produces this output:
370
371        --- Stooges ---------------------------------
372        Curly = funny bald guy
373        Larry = curly headed guy
374        Moe   = guy in charge
375        ---------------------------------------------
376
377       option: line_cut => 1
378
379       If the "line_cut" option is sent, then each value is truncated after
380       the first newline if there is one. The fact that there is more output
381       is mentioned. So the following code:
382
383        my $hash = {
384           Larry => "curly\nheaded guy",
385           Curly => "funny\nbald guy",
386           Moe => "guy\nin charge",
387        };
388
389        showhash $hash, line_cut =>1;
390
391       produces this output.
392
393        ---------------------------------------
394        Curly = funny [more lines...]
395        Larry = curly [more lines...]
396        Moe   = guy [more lines...]
397        ---------------------------------------
398
399       Several other options do exactly the same thing: linecut, line_chop,
400       and first_line.
401
402   showarr, showarray
403       Displays the values of an array.  c<showarr> and c<showarray>
404
405       Each element is displayed in a table row (in web mode) or on a separate
406       line (in text mode).
407
408       If "showarray" receives exactly one argument, and if that item is an
409       array reference, then the routine assumes that you want to display the
410       elements in the referenced array. Therefore, the following blocks of
411       code display the same thing:
412
413          showarray @myarr;
414          showarray \@myarr;
415
416   showarraydiv
417       Works just like "showarray", except that in text mode displays a solid
418       line between each element of the array.
419
420   showscalar
421       Outputs the value of a scalar.  The name is slightly innaccurate: you
422       can input an array. The array will be joined together to form a single
423       scalar.
424
425       Actually, I hardly ever use "showscalar", but it seemed unbalanced to
426       have "showhash" and "showarray" without "showscalar".
427
428   showcgi
429       Displays the CGI parameter keys and values.  This sub always outputs
430       HTML.
431
432       There are several optional parameters, described in the following
433       sections.
434
435       option: q
436
437       The optional parameter "q", may be a CGI query object:
438
439          my $query = CGI->new();
440          showcgi q => $query;
441
442       If "q" is not sent, then a CGI object is created on the fly.
443
444       option: skipempty
445
446       If the optional parameter "skipempty" is true:
447
448          showcgi skipempty => 1;
449
450       then CGI params that are empty (i.e. do not have at least one non-space
451       character) are not displayed.
452
453       option: skip
454
455       "skip" sets a list of parameters to not display.  For example, if you
456       don't want to see the "choices" or "toppings" params, then call showcgi
457       like this:
458
459          showcgi skip => ['choices', 'toppings'];
460
461       Single item lists can be passed in directly without putting them in an
462       anonymous array:
463
464          showcgi skip => 'choices';
465
466   showref($ref, %options)
467       Displays a hash, array, or scalar references, treeing down through
468       other references it contains.  So, for example, the following code:
469
470        my $ob = {
471           name    => 'Raha',
472           email   => 'raha@idocs.com',
473           friends => [
474              'Shalom',
475              'Joe',
476              'Furocha',
477              ],
478           };
479
480        showref $ob;
481
482       produces the following output:
483
484          /-----------------------------------------------------------\
485          friends =
486             ARRAY
487                Shalom
488                Joe
489                Furocha
490          email = raha@idocs.com
491          name = Raha
492          \-----------------------------------------------------------/
493
494       The values of the hash or arrays being referenced are only displayed
495       once, so you're safe from infinite recursion.
496
497       There are several optional parameters, described in the following
498       sections.
499
500       option: maxhash
501
502       The "maxhash" option allows you to indicate the maximum number of hash
503       elements to display.  If a hash has more then "maxhash" elements then
504       none of them are displayed or recursed through, and instead an
505       indicator of how many elements there are is output.  So, for example,
506       the following command only displays the hash values if there are 10 or
507       fewer elements in the hash:
508
509          showref $myob, maxhash=>10;
510
511       If "maxhash" is not sent then there is no maximum.
512
513       option: maxarr
514
515       The "maxarr" option allows you to indicate the maximum number of array
516       elements to display.  If an array has more then "maxarr" elements then
517       none of them are displayed or recursed through, and instead an
518       indicator of how many elements there are is output.  If "maxarr" is not
519       sent then there is no maximum.
520
521       option: depth
522
523       The "depth" option allows you to indicate a maximum depth to display in
524       the tree. If "depth" is not sent then there is no maximum depth.
525
526       option: skip
527
528       A list of hash elements to skip.  Only applies to the top element and
529       only if it is a hash.
530
531       option: skipall
532
533       Works the same as "skip", but applies to all hashes in the structure,
534       not just the top-level hash.
535
536   printhr
537       Prints a horizontal rule.  Handy for dividing up multiple println's.
538
539       In text mode, the horizontal rule is a set of 80 dashes. In web mode,
540       the output is either a <hr> element or a <p> element, depending on the
541       title option (see "title" below).
542
543       So, for example, the following line outputs a simple horizontal rule:
544
545       option: title
546
547       If the "title"option is sent, the title is embedded in the horizontal
548       rule.  So, for example, the following code produces a horizontal rule
549       with with the string "test" embedded in it:
550
551        printhr title=>'test';
552
553       If only one param is sent, it is assumed that param is the title.  So
554       the' following code produces exactly the same thing as the example
555       above:
556
557        printhr 'test';
558
559       In web mode, a title changes the HTML element that is output.  If no
560       title is given then printhr outputs an <hr> element.  If a title is
561       given the output is "p" element with the title as the content. The <p>
562       element has a gray background and a black border.
563
564       option: dash
565
566       If the "dash"option is sent, the given character is used as the
567       separator.  This param only applies to text mode;
568
569   preln
570       Outputs the given values inside a <pre> element.  If not in a web
571       environment, works just like preln.
572
573   dieln
574       Works like the "die" command, except it always adds an end-of-line to
575       the input array so you never get those "at line blah-blah-blah"
576       additions.
577
578   devexit
579       Works like "dieln" except it prepends 'dev exit: ' to the end of the
580       string.  If no string is sent, just outputs "dev exit".
581
582   diearr
583       Displays an array, then dies using "dieln".
584
585   pressenter
586       For use at the command line.  Outputs a prompt to "press enter to
587       continue", then waits for you to do exactly that.
588
589   confirm
590       Prompts the user for a y or n.  Exits quietly if y is pressed.
591
592   httpheader
593       Outputs a text/html HTTP header.  Not useful if you're using mod_perl.
594
595   showstderr
596       This function allows you to see, in the web page produced by a CGI,
597       everything the CGI output to STDERR.
598
599       To use "showstderr", assign the return value of the function to a
600       variable that is scoped to the entire CGI script:
601
602         my $stderr = showstderr();
603
604       You need not do anything more with that variable.  The object reference
605       by your variable holds on to everything output to both STDOUT and
606       STDERR.  When the variable goes out of scope, the object outputs the
607       STDOUT content with the STDERR content at the top of the web page.
608
609   forcetext, forceweb, forcenone
610       By default, Debug::Showstuff guesses if it should be in text or web
611       mode. These functions are for when you want to explicitly tell
612       Debug::ShowStuff what mode it should be in.  "forcetext" forces text
613       mode.  "forceweb" forces web mode.  "forcenone" tells Debug::Showstuff
614       that you don't want to force either mode.
615
616   inweb
617       Returns a guess on if we're in a web environment.  The guess is pretty
618       simple: if the environment variable "REQUEST_URI" is true (in the
619       Perlish sense) then this function returns true.
620
621       If the global $Debug::ShowStuff::forceenv is defined, this function
622       returns the value of $Debug::ShowStuff::forceenv.
623
624   output_to_file($path)
625       Sends Debug::ShowStuff output to a file instead of to STDOUT or STDERR.
626       The value of this function must be assigned to a variable or it has no
627       effect.  Don't do anything with the returned value... it is NOT a file
628       handle.  The returned value is an object that, when it goes out of
629       scope, closes the output file handle.
630
631       For example, the following code will output to three files names
632       Larry.txt, Curly.txt, and Moe.txt:
633
634        foreach my $name (qw[Larry Curyl Moe]) {
635           my $output = output_to_file("$name.txt");
636           println $name;
637           println 'length: ', length($name);
638        }
639
640   setoutput
641       Sets the default output handle.  By default, routines in
642       "Debug::ShowStuff" output to STDOUT.  With this command you can set the
643       default output to STDERR, back to STDOUT, to a filehandle you specify,
644       or to a Debug::ShowStuff::SeparatePrint file handle.
645
646       The following command sets default output to STDERR:
647
648        setoutput 'stderr';
649
650       This command sets output back to STDOUT:
651
652        setoutput 'stdout';
653
654       This command sends output to a file handle of your choice:
655
656        setoutput $fh;
657
658       This command sends output to a Debug::ShowStuff::SeparatePrint file
659       handle.  This option is a good way to create a simple log file.  When
660       you print to this type of file handle, the file is opened separately
661       just for that write, an exclusive lock on the file is obtained, and the
662       end of the file is sought.
663
664       Note that the next parameter must be the path to the output file:
665
666        setoutput 'separateprint', $file_path;
667
668       option: new
669
670       If the "new" parameter is true, then the output file is open in non-
671       append mode, which means any existing contents are removed.
672
673   fixundef
674       Takes a single argument.  If that argument is undefined, returns an
675       empty string.  Otherwise returns the argument exactly as it is.
676
677   findininc
678       Given one or more file names, searches @INC for where they are located.
679       Returns an array of full file names.
680
681   showtainted(@values)
682       Given an array of values, shows which are tainted and which are not.
683       If the first argument is a hashref, displays the tainted status of each
684       element value.
685
686   showsth
687       Outputs a table of all rows in the given DBI statement handle.  Note
688       that this function "uses up" the statement handle.
689
690   showsql
691       showsql output the results of an SQL statement.  showsql takes three
692       parameters: the database handle, the SQL statement, and an array-ref of
693       parameters for the SQL statement.
694
695   explainsql
696       explainsql outputs the result of an SQL EXPLAIN call.  This function
697       works much like showsql.  The parameters are the database handle, the
698       SQL statement, and an array-ref of SQL parameters.  explainsql prepends
699       "EXPLAIN ANALYZE" to your SQL, runs the statement, then outputs the
700       results.
701
702       I have only used explainsql with PostGresql.  I would be interested
703       hear about how it works with other database management systems and how
704       it might be improved to work in those environments.
705
706   tempshowstuff
707       Temporarily turn showstuff on or off.  Create a variable in the lexical
708       scope where you want the tempoary change, like this:
709
710       my $temp = tempshowstuff(1)
711
712       When the variable goes out of scope, showstuff will revert back to its
713       previous state.
714
715   showisa
716       Outputs the ISA hierarchy of an object or class.  For example, the
717       following code outputs the ISA hierarchy for a Xapat object (Xapat is a
718       web server written in Perl and which uses Net::Server).
719
720        $xapat = Xapat->new(%opts);
721        showisa $xapat;
722
723       which outputs:
724
725        ------------------------------------
726        Xapat
727        Net::Server::HTTP
728        Net::Server::MultiType
729        Net::Server
730        ------------------------------------
731
732       Note that showisa loads Class::ISA, which is available on CPAN.
733
734   timer
735       This function is for when you want to display how long it took for your
736       code to run.  Assign the return value of this function to a variable.
737       When the variable goes out of scope then the difference between the
738       start and end time is displayed in seconds.  For example, the following
739       code:
740
741        do {
742           my $timer = timer();
743           sleep 3;
744        };
745
746       outputs this:
747
748        start timer
749        duration: 3 seconds
750
751       option: title
752
753       If you send the "title" option, then that title will be displayed with
754       the beginning and ending output.  For example, this code:
755
756        do {
757           my $timer = timer(title=>'my block');
758           sleep 3;
759        };
760
761       produces this output:
762
763        start timer - my block
764        duration - my block: 3 seconds
765
766       method: $timer->elapsed
767
768       Returns the difference between when the timer was started and the
769       current time.
770
771       method: $timer->silence
772
773       Turns off the timer so that it doesn't display anything when it dies.
774

TERMS AND CONDITIONS

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

AUTHORS

782       Miko O'Sullivan miko@idocs.com
783

VERSION

785       Version 1.00    May 29, 2003
786           Initial public release.
787
788       Version 1.01    May 29, 2003
789           Setting sort order of hash keys to case insensitive.
790
791       Version 1.10    Nov 6, 2010
792           After seven years, decided to update the version on CPAN.
793
794       Version 1.11    Nov 13, 2010
795           Fixed prerequisite requirement for MemHandle and Taint. Added
796           timer() functions.  Some minor documentation fixes and tidying up.
797
798       Version 1.12    Nov 29, 2010
799           Changing from using Taint module, which has had a lot of problems,
800           to Scalar::Util, which is more (but not completely) stable.
801
802       Version 1.13    Dec 1, 2010
803           Fixed bug in prerequisites for Scalar::Util.
804
805       Version 1.14    February 23, 2013
806           Added showsth, showsql, and explainsql.  Added the separateprint
807           option to setoutput.  Tidied up documentation.  Fixed problems with
808           prerequisites.  Probably added many other features since the last
809           time I uploaded this module, but can't remember tham all.
810
811
812
813perl v5.30.0                      2019-07-26               Debug::ShowStuff(3)
Impressum