Debian Codegraph @

upstream/debian-unstable/man1/perldebtut.1

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