Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perldebtut.1

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