1Debug::ShowStuff(3) User Contributed Perl Documentation Debug::ShowStuff(3)
2
6 Debug::ShowStuff - A collection of handy debugging routines for
7 displaying the values of variables with a minimum of coding.
8
10 Here's a sampling of a few of my favorite functions in this module.
11 use Debug::ShowStuff ':all';
13 # display values of a hash or hash reference
15 showhash %hash;
16 showhash $hashref;
17 # display values of an array or array reference
19 showarr @arr;
20 showarr $arrref;
21 # show all the params received through CGI
23 showcgi();
24 # A particularly fancy utility: display STDERR at top of web page
26 my $warnings = showstderr;
27
29 "Debug::ShowStuff" can be installed with the usual routine:
30 perl Makefile.PL
32 make
33 make test
34 make install
35
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 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 println 'my value';
52 println undef;
53 which outputs
55 my value
57 [undef]
58 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 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 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 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 If $always_void is false, then the following applies:
81 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 showhash %myhash;
88 then the contents of %myhash are output to STDOUT. On the other hand,
90 if the function is called in scalar context:
91 my $var = showhash(%myhash);
93 then the same string that would have been output to STDOUT is instead
95 returned and stored in $var.
96 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 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 println undef;
107 println "";
108 produces this:
110 [undef]
112 [empty string]
113
115 println
116 "println" was the original Debug::ShowStuff function. It simply
117 outputs the given values.
118 In text mode it adds a newline to the end.
120 For example, this code:
122 println "hello world";
124 produces this output, including the newline:
126 hello world
128 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 println 'whatever';
138 outputs the following HTML:
140 <p style="background-color:white;color:black;text-align:left">whatever</p>
142 Like other "show" functions, undef is output as the string "[undef]"
144 and an empty string is output as the string "[empty string]".
145 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 println "whatever", "", undef, "dude";
152 outputs this:
154 whatever[empty string][undef]dude
156 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 "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 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 while (my $record = $sth->fetchrow_hashref) {
172 println $record->{'name_nick'};
173 my $indent = indent();
174 showhash $record;
175 }
176 That would produce output something like this:
178 Ricky
180 ---------------------------------------
181 name_first = Rick
182 name_last = Adams
183 ---------------------------------------
184 Dan
186 ---------------------------------------
187 name_first = Daniel
188 name_last = Bradley
189 ---------------------------------------
190 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 option: bottom_space
196 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 foreach my $name (qw[Larry Moe]) {
203 println $name;
204 my $indent = indent(bottom_space=>1);
205 println 'years: ', length($name);
206 }
207 and so produces the following output:
209 Larry
211 years: 5
212 Moe
213 years: 3
214 But this code:
216 foreach my $name (qw[Larry Moe]) {
218 println $name;
219 my $indent = indent(bottom_space=>1);
220 println 'years: ', length($name);
221 }
222 produces this output:
224 Larry
226 years: 5
227 Moe
229 years: 3
230 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 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 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 - If the environment variable $ENV{'SHOWSTUFF'} is defined and false
245 then showstuff() returns false regardless of the state of $active.
246 - 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 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 For example, suppose you have a script as follows:
256 #!/usr/bin/perl -w
258 use strict;
259 use Debug::ShowStuff ':all';
260 my ($rv);
262 println 'running my_function()';
264 $rv = my_function();
265 println 'the returned value is: ', $rv;
266 $rv or die 'error!';
268 The output of the script might look something like this:
270 running my_function()
272 1
273 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 #!/usr/bin/perl -w
280 use strict;
281 use Debug::ShowStuff ':all';
282 my @tests = ("./script1.pl", "./script2.pl", "./script3.pl");
284 $ENV{'SHOWSTUFF'} = 0;
285 foreach my $test () {
287 system($test) and die "$test failed";
288 }
289 In that case, none of the stuff from the test scripts would be output.
291 printnorm
293 Works like println but doesn't add trailing newline. In web
294 environment uses <span> instead of <p>.
295 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 So, for example, the following code:
302 my %hash = (
304 Larry => 'curly headed guy',
305 Curly => 'funny bald guy',
306 Moe => 'guy in charge',
307 );
308 showhash %hash;
310 Produces the following output. Notice that the keys are in alphabetic
312 order:
313 ---------------------------------------
315 Curly = funny bald guy
316 Larry = curly headed guy
317 Moe = guy in charge
318 ---------------------------------------
319 This code, using a hash reference, produces exactly the same output:
321 my $hash = {
323 Larry => 'curly headed guy',
324 Curly => 'funny bald guy',
325 Moe => 'guy in charge',
326 };
327 showhash $hash;
329 If the hash is empty, then that fact is output. So, this code:
331 showhash {};
333 produces this output:
335 ---------------------------------------
337 [empty hash]
338 ---------------------------------------
339 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 my ($hash);
345 showhash $hash;
346 That code produces this output:
348 ---------------------------------------
350 Only one element input and it was undefined
351 ---------------------------------------
352 Optional arguments only come into play if the first argument is a
354 hashref.
355 option: title => "string"
357 If this option is sent, the string is displayed at the top of the
359 display of the hash values. So this code:
360 my $hash = {
362 Larry => 'curly headed guy',
363 Curly => 'funny bald guy',
364 Moe => 'guy in charge',
365 };
366 showhash $hash, title=>'Stooges';
368 produces this output:
370 --- Stooges ---------------------------------
372 Curly = funny bald guy
373 Larry = curly headed guy
374 Moe = guy in charge
375 ---------------------------------------------
376 option: line_cut => 1
378 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 my $hash = {
384 Larry => "curly\nheaded guy",
385 Curly => "funny\nbald guy",
386 Moe => "guy\nin charge",
387 };
388 showhash $hash, line_cut =>1;
390 produces this output.
392 ---------------------------------------
394 Curly = funny [more lines...]
395 Larry = curly [more lines...]
396 Moe = guy [more lines...]
397 ---------------------------------------
398 Several other options do exactly the same thing: linecut, line_chop,
400 and first_line.
401 showarr, showarray
403 Displays the values of an array. c<showarr> and c<showarray>
404 Each element is displayed in a table row (in web mode) or on a separate
406 line (in text mode).
407 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 showarray @myarr;
414 showarray \@myarr;
415 showarraydiv
417 Works just like "showarray", except that in text mode displays a solid
418 line between each element of the array.
419 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 Actually, I hardly ever use "showscalar", but it seemed unbalanced to
426 have "showhash" and "showarray" without "showscalar".
427 showcgi
429 Displays the CGI parameter keys and values. This sub always outputs
430 HTML.
431 There are several optional parameters, described in the following
433 sections.
434 option: q
436 The optional parameter "q", may be a CGI query object:
438 my $query = CGI->new();
440 showcgi q => $query;
441 If "q" is not sent, then a CGI object is created on the fly.
443 option: skipempty
445 If the optional parameter "skipempty" is true:
447 showcgi skipempty => 1;
449 then CGI params that are empty (i.e. do not have at least one non-space
451 character) are not displayed.
452 option: skip
454 "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 showcgi skip => ['choices', 'toppings'];
460 Single item lists can be passed in directly without putting them in an
462 anonymous array:
463 showcgi skip => 'choices';
465 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 my $ob = {
471 name => 'Raha',
472 email => 'raha@idocs.com',
473 friends => [
474 'Shalom',
475 'Joe',
476 'Furocha',
477 ],
478 };
479 showref $ob;
481 produces the following output:
483 /-----------------------------------------------------------\
485 friends =
486 ARRAY
487 Shalom
488 Joe
489 Furocha
490 email = raha@idocs.com
491 name = Raha
492 \-----------------------------------------------------------/
493 The values of the hash or arrays being referenced are only displayed
495 once, so you're safe from infinite recursion.
496 There are several optional parameters, described in the following
498 sections.
499 option: maxhash
501 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 showref $myob, maxhash=>10;
510 If "maxhash" is not sent then there is no maximum.
512 option: maxarr
514 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 option: depth
522 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 option: skip
527 A list of hash elements to skip. Only applies to the top element and
529 only if it is a hash.
530 option: skipall
532 Works the same as "skip", but applies to all hashes in the structure,
534 not just the top-level hash.
535 printhr
537 Prints a horizontal rule. Handy for dividing up multiple println's.
538 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 So, for example, the following line outputs a simple horizontal rule:
544 option: title
546 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 printhr title=>'test';
552 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 printhr 'test';
558 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 option: dash
565 If the "dash"option is sent, the given character is used as the
567 separator. This param only applies to text mode;
568 preln
570 Outputs the given values inside a <pre> element. If not in a web
571 environment, works just like preln.
572 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 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 diearr
583 Displays an array, then dies using "dieln".
584 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 confirm
590 Prompts the user for a y or n. Exits quietly if y is pressed.
591 httpheader
593 Outputs a text/html HTTP header. Not useful if you're using mod_perl.
594 showstderr
596 This function allows you to see, in the web page produced by a CGI,
597 everything the CGI output to STDERR.
598 To use "showstderr", assign the return value of the function to a
600 variable that is scoped to the entire CGI script:
601 my $stderr = showstderr();
603 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 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 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 If the global $Debug::ShowStuff::forceenv is defined, this function
622 returns the value of $Debug::ShowStuff::forceenv.
623 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 For example, the following code will output to three files names
632 Larry.txt, Curly.txt, and Moe.txt:
633 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 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 The following command sets default output to STDERR:
647 setoutput 'stderr';
649 This command sets output back to STDOUT:
651 setoutput 'stdout';
653 This command sends output to a file handle of your choice:
655 setoutput $fh;
657 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 Note that the next parameter must be the path to the output file:
665 setoutput 'separateprint', $file_path;
667 option: new
669 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 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 findininc
678 Given one or more file names, searches @INC for where they are located.
679 Returns an array of full file names.
680 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 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 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 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 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 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 my $temp = tempshowstuff(1)
711 When the variable goes out of scope, showstuff will revert back to its
713 previous state.
714 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 $xapat = Xapat->new(%opts);
721 showisa $xapat;
722 which outputs:
724 ------------------------------------
726 Xapat
727 Net::Server::HTTP
728 Net::Server::MultiType
729 Net::Server
730 ------------------------------------
731 Note that showisa loads Class::ISA, which is available on CPAN.
733 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 do {
742 my $timer = timer();
743 sleep 3;
744 };
745 outputs this:
747 start timer
749 duration: 3 seconds
750 option: title
752 If you send the "title" option, then that title will be displayed with
754 the beginning and ending output. For example, this code:
755 do {
757 my $timer = timer(title=>'my block');
758 sleep 3;
759 };
760 produces this output:
762 start timer - my block
764 duration - my block: 3 seconds
765 method: $timer->elapsed
767 Returns the difference between when the timer was started and the
769 current time.
770 method: $timer->silence
772 Turns off the timer so that it doesn't display anything when it dies.
774
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
782 Miko O'Sullivan miko@idocs.com
783
785 Version 1.00 May 29, 2003
786 Initial public release.
787 Version 1.01 May 29, 2003
789 Setting sort order of hash keys to case insensitive.
790 Version 1.10 Nov 6, 2010
792 After seven years, decided to update the version on CPAN.
793 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 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 Version 1.13 Dec 1, 2010
803 Fixed bug in prerequisites for Scalar::Util.
804 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.
810perl v5.28.1 2013-03-20 Debug::ShowStuff(3)