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