X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperldebtut.pod;h=a38349bbe77947a9cfd9f09e1b5bd9227829258b;hb=d7d7d533fb289d8ec4fa1b5fb02f927ed0cb90cc;hp=35eb89ebe562ff100f69d0060d1b238595d73ebe;hpb=108626240d40b101564eeaa420b6665df7a0654f;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perldebtut.pod b/pod/perldebtut.pod index 35eb89e..a38349b 100644 --- a/pod/perldebtut.pod +++ b/pod/perldebtut.pod @@ -6,7 +6,7 @@ perldebtut - Perl debugging tutorial A (very) lightweight introduction in the use of the perl debugger, and a pointer to existing, deeper sources of information on the subject of debugging -perl programs. +perl programs. There's an extraordinary number of people out there who don't appear to know anything about using the perl debugger, though they use the language every @@ -16,15 +16,16 @@ This is for them. =head1 use strict -There's a few things you can do to make your life a lot more straightforward -when it comes to debugging perl programs. To demonstrate, here's a simple -script with a problem: +First of all, there's a few things you can do to make your life a lot more +straightforward when it comes to debugging perl programs, without using the +debugger at all. To demonstrate, here's a simple script, named "hello", with +a problem: #!/usr/bin/perl - + $var1 = 'Hello World'; # always wanted to do that :-) $var2 = "$varl\n"; - + print $var2; exit; @@ -35,9 +36,9 @@ is, it will print out a newline character, and you'll get what looks like a blank line. It looks like there's 2 variables when (because of the typo) there's really 3: - $var1 = 'Hello World' - $varl = undef - $var2 = "\n" + $var1 = 'Hello World'; + $varl = undef; + $var2 = "\n"; To catch this kind of problem, we can force each variable to be declared before use by pulling in the strict module, by putting 'use strict;' after the @@ -45,23 +46,23 @@ first line of the script. Now when you run it, perl complains about the 3 undeclared variables and we get four error messages because one variable is referenced twice: - + Global symbol "$var1" requires explicit package name at ./t1 line 4. Global symbol "$var2" requires explicit package name at ./t1 line 5. Global symbol "$varl" requires explicit package name at ./t1 line 5. Global symbol "$var2" requires explicit package name at ./t1 line 7. - Execution of ./t1 aborted due to compilation errors. + Execution of ./hello aborted due to compilation errors. Luvverly! and to fix this we declare all variables explicitly and now our script looks like this: #!/usr/bin/perl use strict; - + my $var1 = 'Hello World'; - my $varl = ''; + my $varl = undef; my $var2 = "$varl\n"; - + print $var2; exit; @@ -71,11 +72,11 @@ We then do (always a good idea) a syntax check before we try to run it again: hello syntax OK And now when we run it, we get "\n" still, but at least we know why. Just -getting this script to compile has exposed the '$varl' (with the letter 'l) +getting this script to compile has exposed the '$varl' (with the letter 'l') variable, and simply changing $varl to $var1 solves the problem. -=head1 Looking at data and -w +=head1 Looking at data and -w and v Ok, but how about when you want to really see your data, what's in that dynamic variable, just before using it? @@ -97,7 +98,7 @@ dynamic variable, just before using it? Looks OK, after it's been through the syntax check (perl -c scriptname), we run it and all we get is a blank line again! Hmmmm. - + One common debugging approach here, would be to liberally sprinkle a few print statements, to add a check just before we print out our data, and another just after: @@ -107,15 +108,15 @@ after: print "done: '$data{$key}'\n"; And try again: - + > perl data All OK - + done: '' After much staring at the same piece of code and not seeing the wood for the trees for some time, we get a cup of coffee and try another approach. That -is, we bring in the cavalry by giving perl the C<-d> switch on the command +is, we bring in the cavalry by giving perl the 'B<-d>' switch on the command line: > perl -d data @@ -133,65 +134,77 @@ script. It's stopped at the first line of executable code and is waiting for input. Before we go any further, you'll want to know how to quit the debugger: use -just the letter 'q', not the words 'quit' or 'exit': +just the letter 'B', not the words 'quit' or 'exit': DB<1> q > - + That's it, you're back on home turf again. + +=head1 help + Fire the debugger up again on your script and we'll look at the help menu. -There's a couple of ways of calling help: a simple 'h' will get you a long -scrolled list of help, '|h' (pipe-h) will pipe the help through your pager -('more' or 'less' probably), and finally, 'h h' (h-space-h) will give you a -helpful mini-screen snapshot: - - DB<1> h h - List/search source lines: Control script execution: - l [ln|sub] List source code T Stack trace - - or . List previous/current line s [expr] Single step [in expr] - w [line] List around line n [expr] Next, steps over subs - f filename View source in file Repeat last n or s - /pattern/ ?patt? Search forw/backw r Return from subroutine - v Show versions of modules c [ln|sub] Continue until position - Debugger controls: L List -break/watch/actions - O [...] Set debugger options t [expr] Toggle trace [trace expr] - <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint - ! [N|pat] Redo a previous command d [ln] or D Delete a/all breakpoints - H [-num] Display last num commands a [ln] cmd Do cmd before line - = [a val] Define/list an alias W expr Add a watch expression - h [db_cmd] Get help on command A or W Delete all actions/watch - |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess - q or ^D Quit R Attempt a restart - Data Examination: expr Execute perl code, also see: s,n,t expr - x|m expr Evals expr in array context, dumps the result or lists methods. - p expr Print expression (uses script's current package). - S [[!]pat] List subroutine names [not] matching pattern - V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern. - X [Vars] Same as "V current_package [Vars]". - For more help, type h cmd_letter, or run man perldebug for all docs. - +There's a couple of ways of calling help: a simple 'B' will get the summary +help list, 'B<|h>' (pipe-h) will pipe the help through your pager (which is +(probably 'more' or 'less'), and finally, 'B' (h-space-h) will give you +the entire help screen. Here is the summary page: + +DB<1>h + + List/search source lines: Control script execution: + l [ln|sub] List source code T Stack trace + - or . List previous/current line s [expr] Single step [in expr] + v [line] View around line n [expr] Next, steps over subs + f filename View source in file Repeat last n or s + /pattern/ ?patt? Search forw/backw r Return from subroutine + M Show module versions c [ln|sub] Continue until position + Debugger controls: L List break/watch/actions + o [...] Set debugger options t [expr] Toggle trace [trace expr] + <[<]|{[{]|>[>] [cmd] Do pre/post-prompt b [ln|event|sub] [cnd] Set breakpoint + ! [N|pat] Redo a previous command B ln|* Delete a/all breakpoints + H [-num] Display last num commands a [ln] cmd Do cmd before line + = [a val] Define/list an alias A ln|* Delete a/all actions + h [db_cmd] Get help on command w expr Add a watch expression + h h Complete help page W expr|* Delete a/all watch exprs + |[|]db_cmd Send output to pager ![!] syscmd Run cmd in a subprocess + q or ^D Quit R Attempt a restart + Data Examination: expr Execute perl code, also see: s,n,t expr + x|m expr Evals expr in list context, dumps the result or lists methods. + p expr Print expression (uses script's current package). + S [[!]pat] List subroutine names [not] matching pattern + V [Pk [Vars]] List Variables in Package. Vars can be ~pattern or !pattern. + X [Vars] Same as "V current_package [Vars]". + y [n [Vars]] List lexicals in higher scope . Vars same as V. + For more help, type h cmd_letter, or run man perldebug for all docs. + More confusing options than you can shake a big stick at! It's not as bad as it looks and it's very useful to know more about all of it, and fun too! -There's a couple of useful ones to know about straight away: -You wouldn't think we're using any libraries at all at the moment, but 'v' -will show which modules are currently loaded, by the debugger as well your -script. 'V' and 'X' show variables in the program by package scope and can be -constrained by pattern. 'S' shows all subroutines (by pattern): +There's a couple of useful ones to know about straight away. You wouldn't +think we're using any libraries at all at the moment, but 'B' will show +which modules are currently loaded, and their version number, while 'B' +will show the methods, and 'B' shows all subroutines (by pattern) as +shown below. 'B' and 'B' show variables in the program by package +scope and can be constrained by pattern. DB<2>S str dumpvar::stringify strict::bits strict::import strict::unimport - -Remember we're in our tiny program with a problem, we want to have a look at -where we are, and what our data looks like. First of all let's have a window -on our present position (the first line of code), via the letter 'w': - DB<3> w +Using 'X' and cousins requires you not to use the type identifiers ($@%), just +the 'name': + + DM<3>X ~err + FileHandle(stderr) => fileno(2) + +Remember we're in our tiny program with a problem, we should have a look at +where we are, and what our data looks like. First of all let's view some code +at our present position (the first line of code in this case), via 'B': + + DB<4> v 1 #!/usr/bin/perl 2: use strict; 3 @@ -204,9 +217,9 @@ on our present position (the first line of code), via the letter 'w': 10 ); At line number 4 is a helpful pointer, that tells you where you are now. To -see more code, type 'w' again: - - DB<3> w +see more code, type 'v' again: + + DB<4> v 8 'welcome' => q(Hello World), 9 'zip' => q(welcome), 10 ); @@ -216,23 +229,23 @@ see more code, type 'w' again: 14: print "done: '$data{$key}'\n"; 15: exit; -And if you wanted to list line 5 again, type 'l 5', note the space: +And if you wanted to list line 5 again, type 'l 5', (note the space): DB<4> l 5 5: my %data = ( - + In this case, there's not much to see, but of course normally there's pages of -stuff to wade through. To reset your view to the line we're about to execute, -type a lone period '.': +stuff to wade through, and 'l' can be very useful. To reset your view to the +line we're about to execute, type a lone period '.': - DB<6> . + DB<5> . main::(./data_a:4): my $key = 'welcome'; - + The line shown is the one that is about to be executed B, it hasn't -happened yet. So while we can print a variable with the letter 'p', at this -point all we'd get is an empty (undefined) value back. What we need to do is -to step to the next executable statement with an 's': - +happened yet. So while we can print a variable with the letter 'B

', at +this point all we'd get is an empty (undefined) value back. What we need to +do is to step through the next executable statement with an 'B': + DB<6> s main::(./data_a:5): my %data = ( main::(./data_a:6): 'this' => qw(that), @@ -247,27 +260,29 @@ Now we can have a look at that first ($key) variable: welcome line 13 is where the action is, so let's continue down to there via the letter -'c': +'B', which by the way, inserts a 'one-time-only' breakpoint at the given +line or sub routine: DB<8> c 13 All OK main::(./data_a:13): print "$data{$key}\n"; - + We've gone past our check (where 'All OK' was printed) and have stopped just before the meat of our task. We could try to print out a couple of variables to see what is happening: DB<9> p $data{$key} - -Nothing! - + +Not much in there, lets have a look at our hash: + DB<10> p %data Hello Worldziptomandwelcomejerrywelcomethisthat DB<11> p keys %data Hello Worldtomwelcomejerrythis - -Reading the helpful manual (h h), the 'x' command looks promising: + +Well, this isn't very easy to read, and using the helpful manual (B), the +'B' command looks promising: DB<12> x %data 0 'Hello World' @@ -281,8 +296,8 @@ Reading the helpful manual (h h), the 'x' command looks promising: 8 'this' 9 'that' -That's not much help, a couple of welcome's in there, but no indication of -which are keys, and which are values, it's just a straight array dump and, in +That's not much help, a couple of welcomes in there, but no indication of +which are keys, and which are values, it's just a listed array dump and, in this case, not particularly helpful. The trick here, is to use a B to the data structure: @@ -299,7 +314,7 @@ Our quoting was perfectly valid but wrong for our purposes, with 'and jerry' being treated as 2 separate words rather than a phrase, thus throwing the evenly paired hash structure out of alignment. -The '-w' switch would have told us about this, had we used it at the start, +The 'B<-w>' switch would have told us about this, had we used it at the start, and saved us a lot of trouble: > perl -w data @@ -312,12 +327,12 @@ our expected output: Hello World -While we're here, take a closer look at the 'x' command, it's really useful +While we're here, take a closer look at the 'B' command, it's really useful and will merrily dump out nested references, complete objects, partial objects -- justabout whatever you throw at it: +- just about whatever you throw at it: -Let's make a quick object and x-plode it, first we'll start the the debugger: -it wants some form of input from STDIN, so we give it something non-commital, +Let's make a quick object and x-plode it, first we'll start the debugger: +it wants some form of input from STDIN, so we give it something non-committal, a zero: > perl -de 0 @@ -336,7 +351,7 @@ Now build an on-the-fly object over a couple of lines (note the backslash): cont: {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class') And let's have a look at it: - + DB<2> x $obj 0 MY_class=HASH(0x828ad98) 'attr' => HASH(0x828ad68) @@ -352,7 +367,7 @@ Useful, huh? You can eval nearly anything in there, and experiment with bits of code or regexes until the cows come home: DB<3> @data = qw(this that the other atheism leather theory scythe) - + DB<4> p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data)) atheism leather @@ -362,7 +377,7 @@ of code or regexes until the cows come home: theory saw -> 6 -If you want to see all the command history, an 'H': +If you want to see the command History, type an 'B': DB<5> H 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data)) @@ -371,8 +386,8 @@ If you want to see all the command history, an 'H': 1: $obj = bless({'unique_id'=>'123', 'attr'=> {'col' => 'black', 'things' => [qw(this that etc)]}}, 'MY_class') DB<5> - -And if you want to repeat any previous command, use the exclamation: '!': + +And if you want to repeat any previous command, use the exclamation: 'B': DB<5> !4 p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data)) @@ -384,10 +399,12 @@ And if you want to repeat any previous command, use the exclamation: '!': theory saw -> 12 +For more on references see L and L + =head1 Stepping through code -Here's a simple program which converts between celsius and farenheit, it too +Here's a simple program which converts between Celsius and Fahrenheit, it too has a problem: #!/usr/bin/perl -w @@ -426,27 +443,27 @@ has a problem: } -For some reason, the farenheit to celsius conversion fails to return the +For some reason, the Fahrenheit to Celsius conversion fails to return the expected output. This is what it does: > temp -c0.72 33.30 f - + > temp -f33.3 162.94 c - + Not very consistent! We'll set a breakpoint in the code manually and run it under the debugger to see what's going on. A breakpoint is a flag, to which -the debugger will run without interuption, when it reaches the breakpoint, it +the debugger will run without interruption, when it reaches the breakpoint, it will stop execution and offer a prompt for further interaction. In normal use, these debugger commands are completely ignored, and they are safe - if a little messy, to leave in production code. - + my ($in, $out) = ($num, $num); $DB::single=2; # insert at line 9! if ($deg eq 'c') ... - + > perl -d temp -f33.3 Default die handler restored. @@ -457,14 +474,14 @@ little messy, to leave in production code. main::(temp:4): my $arg = $ARGV[0] || '-c100'; -We'll simply continue down to our pre-set breakpoint with a 'c': +We'll simply continue down to our pre-set breakpoint with a 'B': DB<1> c main::(temp:10): if ($deg eq 'c') { -Followed by a window command to see where we are: - - DB<2> w +Followed by a view command to see where we are: + + DB<1> v 7: my ($deg, $num) = ($1, $2); 8: my ($in, $out) = ($num, $num); 9: $DB::single=2; @@ -478,19 +495,19 @@ Followed by a window command to see where we are: And a print to show what values we're currently using: - DB<3> p $deg, $num + DB<1> p $deg, $num f33.3 - + We can put another break point on any line beginning with a colon, we'll use line 17 as that's just as we come out of the subroutine, and we'd like to pause there later on: - - DB<4> b 17 - + + DB<2> b 17 + There's no feedback from this, but you can see what breakpoints are set by using the list 'L' command: - DB<5> L + DB<3> L temp: 17: print "$out $deg\n"; break if (1) @@ -498,62 +515,64 @@ using the list 'L' command: Note that to delete a breakpoint you use 'd' or 'D'. Now we'll continue down into our subroutine, this time rather than by line -number, we'll use the subroutine name, followed by the now familiar 'w': +number, we'll use the subroutine name, followed by the now familiar 'v': - DB<6> c f2c + DB<3> c f2c main::f2c(temp:30): my $f = shift; - DB<7> w - 27 } - 28 - 29 sub f2c { - 30==> my $f = shift; - 31: my $c = 5 * $f - 32 / 9; - 32: return $c; - 33 } - 34 - - -Note that if there was a subroutine call between us and line 32, and we didn't -want to single-step through it, we could use the next command 'n', which would -execute the sub, but not descend into it for inspection. In this case though, -we simply single step down to line 32: - - DB<8> s 32 - main::f2c(temp:28): return $c; - + DB<4> v + 24: exit; + 25 + 26 sub f2c { + 27==> my $f = shift; + 28: my $c = 5 * $f - 32 / 9; + 29: return $c; + 30 } + 31 + 32 sub c2f { + 33: my $c = shift; + + +Note that if there was a subroutine call between us and line 29, and we wanted +to B through it, we could use the 'B' command, and to step +over it we would use 'B' which would execute the sub, but not descend into +it for inspection. In this case though, we simply continue down to line 29: + + DB<4> c 29 + main::f2c(temp:29): return $c; + And have a look at the return value: - DB<9> p $c + DB<5> p $c 162.944444444444 This is not the right answer at all, but the sum looks correct. I wonder if it's anything to do with operator precedence? We'll try a couple of other possibilities with our sum: - DB<10> p (5 * $f - 32 / 9) + DB<6> p (5 * $f - 32 / 9) 162.944444444444 - - DB<11> p 5 * $f - (32 / 9) + + DB<7> p 5 * $f - (32 / 9) 162.944444444444 - - DB<12> p (5 * $f) - 32 / 9 + + DB<8> p (5 * $f) - 32 / 9 162.944444444444 - - DB<13> p 5 * ($f - 32) / 9 + + DB<9> p 5 * ($f - 32) / 9 0.722222222222221 :-) that's more like it! Ok, now we can set our return variable and we'll return out of the sub with an 'r': - DB<14> $c = 5 * ($f - 32) / 9 - - DB<15> r + DB<10> $c = 5 * ($f - 32) / 9 + + DB<11> r scalar context return from main::f2c: 0.722222222222221 - + Looks good, let's just continue off the end of the script: - DB<16> c + DB<12> c 0.72 c Debugged program terminated. Use q to quit or R to restart, use O inhibit_exit to avoid stopping after program termination, @@ -565,22 +584,22 @@ actual program and we're finished. =head1 Placeholder for a, w, t, T -Actions, watch variables, stack traces on the TODO list. +Actions, watch variables, stack traces etc.: on the TODO list. a - - W - + + w + t - + T -=head1 Regular expressions +=head1 REGULAR EXPRESSIONS Ever wanted to know what a regex looked like? You'll need perl compiled with the DEBUGGING flag for this one: - + > perl -Dr -e '/^pe(a)*rl$/i' Compiling REx `^pe(a)*rl$' size 17 first at 2 @@ -599,15 +618,18 @@ the DEBUGGING flag for this one: floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF ' anchored(BOL) minlen 4 Omitting $` $& $' support. - + EXECUTING... Freeing REx: `^pe(a)*rl$' Did you really want to know? :-) +For more gory details on getting regular expressions to work, have a look at +L, L, and to decode the mysterious labels (BOL and CURLYN, +etc. above), see L. -=head1 Some ideas for output +=head1 OUTPUT TIPS To get all the output from your error log, and not miss any messages via helpful operating system buffering, insert a line like this, at the start of @@ -622,20 +644,21 @@ To watch the tail of a dynamically growing logfile, (from the command line): Wrapping all die calls in a handler routine can be useful to see how, and from where, they're being called, L has more information: - BEGIN { $SIG{__DIE__} = sub { use Carp; Carp::confess(@_) } } + BEGIN { $SIG{__DIE__} = sub { require Carp; Carp::confess(@_) } } Various useful techniques for the redirection of STDOUT and STDERR filehandles -are explained in L and L and L +are explained in L and L. =head1 CGI -Just a hint here for all those CGI programmers who can't figure out how on -earth to get past that 'waiting for input' prompt, try something like this: +Just a quick hint here for all those CGI programmers who can't figure out how +on earth to get past that 'waiting for input' prompt, when running their CGI +script from the command-line, try something like this: > perl -d my_cgi.pl -nodebug -Of course 'L' and L will tell you more. +Of course L and L will tell you more. =head1 GUIs @@ -645,7 +668,7 @@ and there's a B interface too. You don't have to do this all on the command line, though, there are a few GUI options out there. The nice thing about these is you can wave a mouse over a -variable and a dump of it's data will appear in an appropriate window, or in a +variable and a dump of its data will appear in an appropriate window, or in a popup balloon, no more tiresome typing of 'x $varname' :-) In particular have a hunt around for the following: @@ -653,13 +676,13 @@ In particular have a hunt around for the following: B perlTK based wrapper for the built-in debugger B data display debugger - + B and B are NT specific NB. (more info on these and others would be appreciated). -=head1 Summary +=head1 SUMMARY We've seen how to encourage good coding practices with B and B<-w>. We can run the perl debugger B to inspect your @@ -694,5 +717,7 @@ Various people have made helpful suggestions and contributions, in particular: Ronald J Kimball -Hugo +Hugo van der Sanden + +Peter Scott