Reset xxx_convert to empty string if none of 3 utilities is found
[perl.git] / pod / perldebtut.pod
1 =head1 NAME
2
3 perldebtut - Perl debugging tutorial
4
5 =head1 DESCRIPTION
6
7 A (very) lightweight introduction in the use of the perl debugger, and a
8 pointer to existing, deeper sources of information on the subject of debugging
9 perl programs.  
10
11 There's an extraordinary number of people out there who don't appear to know
12 anything about using the perl debugger, though they use the language every
13 day.  
14 This is for them.  
15
16
17 =head1 use strict
18
19 First of all, there's a few things you can do to make your life a lot more
20 straightforward when it comes to debugging perl programs, without using the
21 debugger at all.  To demonstrate, here's a simple script, named "hello", with
22 a problem:
23
24         #!/usr/bin/perl
25
26         $var1 = 'Hello World'; # always wanted to do that :-)
27         $var2 = "$varl\n";
28
29         print $var2; 
30         exit;
31
32 While this compiles and runs happily, it probably won't do what's expected,
33 namely it doesn't print "Hello World\n" at all;  It will on the other hand do
34 exactly what it was told to do, computers being a bit that way inclined.  That
35 is, it will print out a newline character, and you'll get what looks like a
36 blank line.  It looks like there's 2 variables when (because of the typo)
37 there's really 3:
38
39         $var1 = 'Hello World';
40         $varl = undef;
41         $var2 = "\n";
42
43 To catch this kind of problem, we can force each variable to be declared
44 before use by pulling in the strict module, by putting 'use strict;' after the
45 first line of the script.
46
47 Now when you run it, perl complains about the 3 undeclared variables and we
48 get four error messages because one variable is referenced twice:
49
50  Global symbol "$var1" requires explicit package name at ./t1 line 4.
51  Global symbol "$var2" requires explicit package name at ./t1 line 5.
52  Global symbol "$varl" requires explicit package name at ./t1 line 5.
53  Global symbol "$var2" requires explicit package name at ./t1 line 7.
54  Execution of ./hello aborted due to compilation errors.     
55
56 Luvverly! and to fix this we declare all variables explicitly and now our
57 script looks like this: 
58
59         #!/usr/bin/perl
60         use strict;
61
62         my $var1 = 'Hello World';
63         my $varl = undef;
64         my $var2 = "$varl\n";
65
66         print $var2; 
67         exit;
68
69 We then do (always a good idea) a syntax check before we try to run it again:
70
71         > perl -c hello
72         hello syntax OK 
73
74 And now when we run it, we get "\n" still, but at least we know why.  Just
75 getting this script to compile has exposed the '$varl' (with the letter 'l')
76 variable, and simply changing $varl to $var1 solves the problem.
77
78
79 =head1 Looking at data and -w and v
80
81 Ok, but how about when you want to really see your data, what's in that
82 dynamic variable, just before using it?
83
84         #!/usr/bin/perl 
85         use strict;
86
87         my $key = 'welcome';
88         my %data = (
89                 'this' => qw(that), 
90                 'tom' => qw(and jerry),
91                 'welcome' => q(Hello World),
92                 'zip' => q(welcome),
93         );
94         my @data = keys %data;
95
96         print "$data{$key}\n";
97         exit;                               
98
99 Looks OK, after it's been through the syntax check (perl -c scriptname), we
100 run it and all we get is a blank line again!  Hmmmm.
101
102 One common debugging approach here, would be to liberally sprinkle a few print
103 statements, to add a check just before we print out our data, and another just
104 after:
105
106         print "All OK\n" if grep($key, keys %data);
107         print "$data{$key}\n";
108         print "done: '$data{$key}'\n";
109
110 And try again:
111
112         > perl data
113         All OK     
114
115         done: ''
116
117 After much staring at the same piece of code and not seeing the wood for the
118 trees for some time, we get a cup of coffee and try another approach.  That
119 is, we bring in the cavalry by giving perl the 'B<-d>' switch on the command
120 line:
121
122         > perl -d data 
123         Default die handler restored.
124
125         Loading DB routines from perl5db.pl version 1.07
126         Editor support available.
127
128         Enter h or `h h' for help, or `man perldebug' for more help.
129
130         main::(./data:4):     my $key = 'welcome';   
131
132 Now, what we've done here is to launch the built-in perl debugger on our
133 script.  It's stopped at the first line of executable code and is waiting for
134 input.
135
136 Before we go any further, you'll want to know how to quit the debugger: use
137 just the letter 'B<q>', not the words 'quit' or 'exit':
138
139         DB<1> q
140         >
141
142 That's it, you're back on home turf again.
143
144
145 =head1 help
146
147 Fire the debugger up again on your script and we'll look at the help menu. 
148 There's a couple of ways of calling help: a simple 'B<h>' will get the summary 
149 help list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is 
150 (probably 'more' or 'less'), and finally, 'B<h h>' (h-space-h) will give you 
151 the entire help screen.  Here is the summary page:
152
153 DB<1>h
154
155  List/search source lines:               Control script execution:
156   l [ln|sub]  List source code            T           Stack trace
157   - or .      List previous/current line  s [expr]    Single step
158                                                                [in expr]
159   v [line]    View around line            n [expr]    Next, steps over
160                                                                     subs
161   f filename  View source in file         <CR/Enter>  Repeat last n or s
162   /pattern/ ?patt?   Search forw/backw    r           Return from
163                                                               subroutine
164   M           Show module versions        c [ln|sub]  Continue until
165                                                                 position
166  Debugger controls:                       L           List break/watch/
167                                                                  actions
168   o [...]     Set debugger options        t [expr]    Toggle trace
169                                                             [trace expr]
170   <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set
171                                                               breakpoint
172   ! [N|pat]   Redo a previous command     B ln|*      Delete a/all
173                                                              breakpoints
174   H [-num]    Display last num commands   a [ln] cmd  Do cmd before line
175   = [a val]   Define/list an alias        A ln|*      Delete a/all
176                                                                  actions
177   h [db_cmd]  Get help on command         w expr      Add a watch
178                                                               expression
179   h h         Complete help page          W expr|*    Delete a/all watch
180                                                                    exprs
181   |[|]db_cmd  Send output to pager        ![!] syscmd Run cmd in a
182                                                               subprocess
183   q or ^D     Quit                        R           Attempt a restart
184  Data Examination:     expr     Execute perl code, also see: s,n,t expr
185   x|m expr       Evals expr in list context, dumps the result or lists
186                                                                 methods.
187   p expr         Print expression (uses script's current package).
188   S [[!]pat]     List subroutine names [not] matching pattern
189   V [Pk [Vars]]  List Variables in Package.  Vars can be ~pattern or
190                                                                !pattern.
191   X [Vars]       Same as "V current_package [Vars]".
192   y [n [Vars]]   List lexicals in higher scope <n>.  Vars same as V.
193  For more help, type h cmd_letter, or run man perldebug for all docs. 
194
195 More confusing options than you can shake a big stick at!  It's not as bad as
196 it looks and it's very useful to know more about all of it, and fun too!
197
198 There's a couple of useful ones to know about straight away.  You wouldn't
199 think we're using any libraries at all at the moment, but 'B<M>' will show
200 which modules are currently loaded, and their version number, while 'B<m>' 
201 will show the methods, and 'B<S>' shows all subroutines (by pattern) as 
202 shown below.  'B<V>' and 'B<X>' show variables in the program by package 
203 scope and can be constrained by pattern. 
204
205         DB<2>S str 
206         dumpvar::stringify
207         strict::bits
208         strict::import
209         strict::unimport  
210
211 Using 'X' and cousins requires you not to use the type identifiers ($@%), just
212 the 'name':
213
214         DM<3>X ~err
215         FileHandle(stderr) => fileno(2)    
216
217 Remember we're in our tiny program with a problem, we should have a look at
218 where we are, and what our data looks like. First of all let's view some code 
219 at our present position (the first line of code in this case), via 'B<v>':
220
221         DB<4> v
222         1       #!/usr/bin/perl
223         2:      use strict;
224         3
225         4==>    my $key = 'welcome';
226         5:      my %data = (
227         6               'this' => qw(that),
228         7               'tom' => qw(and jerry),
229         8               'welcome' => q(Hello World),
230         9               'zip' => q(welcome),
231         10      );                                 
232
233 At line number 4 is a helpful pointer, that tells you where you are now.  To
234 see more code, type 'v' again:
235
236         DB<4> v
237         8               'welcome' => q(Hello World),
238         9               'zip' => q(welcome),
239         10      );
240         11:     my @data = keys %data;
241         12:     print "All OK\n" if grep($key, keys %data);
242         13:     print "$data{$key}\n";
243         14:     print "done: '$data{$key}'\n";
244         15:     exit;      
245
246 And if you wanted to list line 5 again, type 'l 5', (note the space):
247
248         DB<4> l 5
249         5:      my %data = (
250
251 In this case, there's not much to see, but of course normally there's pages of
252 stuff to wade through, and 'l' can be very useful.  To reset your view to the
253 line we're about to execute, type a lone period '.':
254
255         DB<5> .
256         main::(./data_a:4):     my $key = 'welcome';  
257
258 The line shown is the one that is about to be executed B<next>, it hasn't
259 happened yet.  So while we can print a variable with the letter 'B<p>', at
260 this point all we'd get is an empty (undefined) value back.  What we need to
261 do is to step through the next executable statement with an 'B<s>':
262
263         DB<6> s
264         main::(./data_a:5):     my %data = (
265         main::(./data_a:6):             'this' => qw(that),
266         main::(./data_a:7):             'tom' => qw(and jerry),
267         main::(./data_a:8):             'welcome' => q(Hello World),
268         main::(./data_a:9):             'zip' => q(welcome),
269         main::(./data_a:10):    );   
270
271 Now we can have a look at that first ($key) variable:
272
273         DB<7> p $key 
274         welcome 
275
276 line 13 is where the action is, so let's continue down to there via the letter
277 'B<c>', which by the way, inserts a 'one-time-only' breakpoint at the given
278 line or sub routine:
279
280         DB<8> c 13
281         All OK
282         main::(./data_a:13):    print "$data{$key}\n";
283
284 We've gone past our check (where 'All OK' was printed) and have stopped just
285 before the meat of our task.  We could try to print out a couple of variables
286 to see what is happening:
287
288         DB<9> p $data{$key}
289
290 Not much in there, lets have a look at our hash:
291
292         DB<10> p %data
293         Hello Worldziptomandwelcomejerrywelcomethisthat 
294
295         DB<11> p keys %data
296         Hello Worldtomwelcomejerrythis  
297
298 Well, this isn't very easy to read, and using the helpful manual (B<h h>), the
299 'B<x>' command looks promising:
300
301         DB<12> x %data
302         0  'Hello World'
303         1  'zip'
304         2  'tom'
305         3  'and'
306         4  'welcome'
307         5  undef
308         6  'jerry'
309         7  'welcome'
310         8  'this'
311         9  'that'     
312
313 That's not much help, a couple of welcomes in there, but no indication of
314 which are keys, and which are values, it's just a listed array dump and, in
315 this case, not particularly helpful.  The trick here, is to use a B<reference>
316 to the data structure:
317
318         DB<13> x \%data
319         0  HASH(0x8194bc4)
320            'Hello World' => 'zip'
321            'jerry' => 'welcome'
322            'this' => 'that'
323            'tom' => 'and'
324            'welcome' => undef  
325
326 The reference is truly dumped and we can finally see what we're dealing with. 
327 Our quoting was perfectly valid but wrong for our purposes, with 'and jerry'
328 being treated as 2 separate words rather than a phrase, thus throwing the
329 evenly paired hash structure out of alignment.
330
331 The 'B<-w>' switch would have told us about this, had we used it at the start,
332 and saved us a lot of trouble: 
333
334         > perl -w data
335         Odd number of elements in hash assignment at ./data line 5.    
336
337 We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get
338 our expected output:
339
340         > perl -w data
341         Hello World
342
343
344 While we're here, take a closer look at the 'B<x>' command, it's really useful
345 and will merrily dump out nested references, complete objects, partial objects
346 - just about whatever you throw at it:
347
348 Let's make a quick object and x-plode it, first we'll start the debugger:
349 it wants some form of input from STDIN, so we give it something non-committal,
350 a zero:
351
352  > perl -de 0
353  Default die handler restored.
354
355  Loading DB routines from perl5db.pl version 1.07
356  Editor support available.
357
358  Enter h or `h h' for help, or `man perldebug' for more help.
359
360  main::(-e:1):   0
361
362 Now build an on-the-fly object over a couple of lines (note the backslash):
363
364  DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \
365  cont:  {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
366
367 And let's have a look at it:
368
369         DB<2> x $obj
370  0  MY_class=HASH(0x828ad98)
371                 'attr' => HASH(0x828ad68)
372         'col' => 'black'
373         'things' => ARRAY(0x828abb8)
374                 0  'this'
375                 1  'that'
376                 2  'etc'
377                 'unique_id' => 123       
378         DB<3>
379
380 Useful, huh?  You can eval nearly anything in there, and experiment with bits
381 of code or regexes until the cows come home:
382
383  DB<3> @data = qw(this that the other atheism leather theory scythe)
384
385  DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
386  atheism
387  leather
388  other
389  scythe
390  the
391  theory
392  saw -> 6
393
394 If you want to see the command History, type an 'B<H>':
395
396  DB<5> H
397  4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data))
398  3: @data = qw(this that the other atheism leather theory scythe)
399  2: x $obj
400  1: $obj = bless({'unique_id'=>'123', 'attr'=>
401  {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class')
402  DB<5>
403
404 And if you want to repeat any previous command, use the exclamation: 'B<!>':
405
406  DB<5> !4
407  p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data))
408  atheism
409  leather
410  other
411  scythe
412  the
413  theory
414  saw -> 12
415
416 For more on references see L<perlref> and L<perlreftut>
417
418
419 =head1 Stepping through code
420
421 Here's a simple program which converts between Celsius and Fahrenheit, it too
422 has a problem:
423
424  #!/usr/bin/perl -w
425  use strict;
426
427  my $arg = $ARGV[0] || '-c20';
428
429  if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) {
430         my ($deg, $num) = ($1, $2);
431         my ($in, $out) = ($num, $num);
432         if ($deg eq 'c') {
433                 $deg = 'f';
434                 $out = &c2f($num);
435         } else {
436                 $deg = 'c';
437                 $out = &f2c($num);
438         }
439         $out = sprintf('%0.2f', $out);
440         $out =~ s/^((\-|\+)*\d+)\.0+$/$1/;
441         print "$out $deg\n";
442  } else {
443         print "Usage: $0 -[c|f] num\n";
444  }
445  exit;
446
447  sub f2c {
448         my $f = shift;
449         my $c = 5 * $f - 32 / 9;
450         return $c;
451  }
452
453  sub c2f {
454         my $c = shift;
455         my $f = 9 * $c / 5 + 32;
456         return $f;
457  }
458
459
460 For some reason, the Fahrenheit to Celsius conversion fails to return the
461 expected output.  This is what it does:
462
463  > temp -c0.72
464  33.30 f
465
466  > temp -f33.3
467  162.94 c
468
469 Not very consistent!  We'll set a breakpoint in the code manually and run it
470 under the debugger to see what's going on.  A breakpoint is a flag, to which
471 the debugger will run without interruption, when it reaches the breakpoint, it
472 will stop execution and offer a prompt for further interaction.  In normal
473 use, these debugger commands are completely ignored, and they are safe - if a
474 little messy, to leave in production code.
475
476         my ($in, $out) = ($num, $num);
477         $DB::single=2; # insert at line 9!
478         if ($deg eq 'c') 
479                 ...
480
481         > perl -d temp -f33.3
482         Default die handler restored.
483
484         Loading DB routines from perl5db.pl version 1.07
485         Editor support available.
486
487         Enter h or `h h' for help, or `man perldebug' for more help.
488
489         main::(temp:4): my $arg = $ARGV[0] || '-c100';     
490
491 We'll simply continue down to our pre-set breakpoint with a 'B<c>':
492
493         DB<1> c
494         main::(temp:10):                if ($deg eq 'c') {   
495
496 Followed by a view command to see where we are:
497
498         DB<1> v
499         7:              my ($deg, $num) = ($1, $2);
500         8:              my ($in, $out) = ($num, $num);
501         9:              $DB::single=2;
502         10==>           if ($deg eq 'c') {
503         11:                     $deg = 'f';
504         12:                     $out = &c2f($num);
505         13              } else {
506         14:                     $deg = 'c';
507         15:                     $out = &f2c($num);
508         16              }                             
509
510 And a print to show what values we're currently using:
511
512         DB<1> p $deg, $num
513         f33.3
514
515 We can put another break point on any line beginning with a colon, we'll use
516 line 17 as that's just as we come out of the subroutine, and we'd like to
517 pause there later on:
518
519         DB<2> b 17
520
521 There's no feedback from this, but you can see what breakpoints are set by
522 using the list 'L' command:
523
524         DB<3> L
525         temp:
526                 17:            print "$out $deg\n";
527                 break if (1)     
528
529 Note that to delete a breakpoint you use 'B'.
530
531 Now we'll continue down into our subroutine, this time rather than by line
532 number, we'll use the subroutine name, followed by the now familiar 'v':
533
534         DB<3> c f2c
535         main::f2c(temp:30):             my $f = shift;  
536
537         DB<4> v
538         24:     exit;
539         25
540         26      sub f2c {
541         27==>           my $f = shift;
542         28:             my $c = 5 * $f - 32 / 9; 
543         29:             return $c;
544         30      }
545         31
546         32      sub c2f {
547         33:             my $c = shift;   
548
549
550 Note that if there was a subroutine call between us and line 29, and we wanted
551 to B<single-step> through it, we could use the 'B<s>' command, and to step
552 over it we would use 'B<n>' which would execute the sub, but not descend into
553 it for inspection.  In this case though, we simply continue down to line 29:
554
555         DB<4> c 29  
556         main::f2c(temp:29):             return $c;
557
558 And have a look at the return value:
559
560         DB<5> p $c
561         162.944444444444
562
563 This is not the right answer at all, but the sum looks correct.  I wonder if
564 it's anything to do with operator precedence?  We'll try a couple of other
565 possibilities with our sum:
566
567         DB<6> p (5 * $f - 32 / 9)
568         162.944444444444
569
570         DB<7> p 5 * $f - (32 / 9) 
571         162.944444444444
572
573         DB<8> p (5 * $f) - 32 / 9
574         162.944444444444
575
576         DB<9> p 5 * ($f - 32) / 9
577         0.722222222222221
578
579 :-) that's more like it!  Ok, now we can set our return variable and we'll
580 return out of the sub with an 'r':
581
582         DB<10> $c = 5 * ($f - 32) / 9
583
584         DB<11> r
585         scalar context return from main::f2c: 0.722222222222221
586
587 Looks good, let's just continue off the end of the script:
588
589         DB<12> c
590         0.72 c 
591         Debugged program terminated.  Use q to quit or R to restart,
592         use O inhibit_exit to avoid stopping after program termination,
593         h q, h R or h O to get additional info.   
594
595 A quick fix to the offending line (insert the missing parentheses) in the
596 actual program and we're finished.
597
598
599 =head1 Placeholder for a, w, t, T
600
601 Actions, watch variables, stack traces etc.: on the TODO list.
602
603         a 
604
605         w 
606
607         t 
608
609         T
610
611
612 =head1 REGULAR EXPRESSIONS
613
614 Ever wanted to know what a regex looked like?  You'll need perl compiled with
615 the DEBUGGING flag for this one:
616
617   > perl -Dr -e '/^pe(a)*rl$/i'
618   Compiling REx `^pe(a)*rl$'
619   size 17 first at 2
620   rarest char
621    at 0
622      1: BOL(2)
623      2: EXACTF <pe>(4)
624      4: CURLYN[1] {0,32767}(14)
625      6:   NOTHING(8)
626      8:   EXACTF <a>(0)
627     12:   WHILEM(0)
628     13: NOTHING(14)
629     14: EXACTF <rl>(16)
630     16: EOL(17)
631     17: END(0)
632   floating `'$ at 4..2147483647 (checking floating) stclass
633     `EXACTF <pe>' anchored(BOL) minlen 4
634   Omitting $` $& $' support.
635
636   EXECUTING...
637
638   Freeing REx: `^pe(a)*rl$'
639
640 Did you really want to know? :-)
641 For more gory details on getting regular expressions to work, have a look at
642 L<perlre>, L<perlretut>, and to decode the mysterious labels (BOL and CURLYN,
643 etc. above), see L<perldebguts>.
644
645
646 =head1 OUTPUT TIPS
647
648 To get all the output from your error log, and not miss any messages via
649 helpful operating system buffering, insert a line like this, at the start of
650 your script:
651
652         $|=1;   
653
654 To watch the tail of a dynamically growing logfile, (from the command line):
655
656         tail -f $error_log
657
658 Wrapping all die calls in a handler routine can be useful to see how, and from
659 where, they're being called, L<perlvar> has more information:
660
661     BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } }
662
663 Various useful techniques for the redirection of STDOUT and STDERR filehandles
664 are explained in L<perlopentut> and L<perlfaq8>.
665
666
667 =head1 CGI
668
669 Just a quick hint here for all those CGI programmers who can't figure out how
670 on earth to get past that 'waiting for input' prompt, when running their CGI
671 script from the command-line, try something like this:
672
673         > perl -d my_cgi.pl -nodebug 
674
675 Of course L<CGI> and L<perlfaq9> will tell you more.
676
677
678 =head1 GUIs
679
680 The command line interface is tightly integrated with an B<emacs> extension
681 and there's a B<vi> interface too.  
682
683 You don't have to do this all on the command line, though, there are a few GUI
684 options out there.  The nice thing about these is you can wave a mouse over a
685 variable and a dump of its data will appear in an appropriate window, or in a
686 popup balloon, no more tiresome typing of 'x $varname' :-)
687
688 In particular have a hunt around for the following:
689
690 B<ptkdb> perlTK based wrapper for the built-in debugger
691
692 B<ddd> data display debugger
693
694 B<PerlDevKit> and B<PerlBuilder> are NT specific
695
696 NB. (more info on these and others would be appreciated).
697
698
699 =head1 SUMMARY
700
701 We've seen how to encourage good coding practices with B<use strict> and
702 B<-w>.  We can run the perl debugger B<perl -d scriptname> to inspect your
703 data from within the perl debugger with the B<p> and B<x> commands.  You can
704 walk through your code, set breakpoints with B<b> and step through that code
705 with B<s> or B<n>, continue with B<c> and return from a sub with B<r>.  Fairly
706 intuitive stuff when you get down to it.  
707
708 There is of course lots more to find out about, this has just scratched the
709 surface.  The best way to learn more is to use perldoc to find out more about
710 the language, to read the on-line help (L<perldebug> is probably the next
711 place to go), and of course, experiment.  
712
713
714 =head1 SEE ALSO
715
716 L<perldebug>, 
717 L<perldebguts>, 
718 L<perldiag>,
719 L<perlrun>
720
721
722 =head1 AUTHOR
723
724 Richard Foley <richard.foley@rfi.net> Copyright (c) 2000
725
726
727 =head1 CONTRIBUTORS
728
729 Various people have made helpful suggestions and contributions, in particular:
730
731 Ronald J Kimball <rjk@linguist.dartmouth.edu>
732
733 Hugo van der Sanden <hv@crypt0.demon.co.uk>
734
735 Peter Scott <Peter@PSDT.com>
736