From: Richard Foley Date: Wed, 9 Aug 2000 10:17:15 +0000 (+0200) Subject: Add Perl debugging tutorial, regen toc. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=108626240d40b101564eeaa420b6665df7a0654f;p=p5sagit%2Fp5-mst-13.2.git Add Perl debugging tutorial, regen toc. Subject: perldebtut.pod Message-id: <3991138B.262247B8@m.dasa.de> p4raw-id: //depot/perl@6599 --- diff --git a/MANIFEST b/MANIFEST index b9e15d5..ab16b20 100644 --- a/MANIFEST +++ b/MANIFEST @@ -1092,6 +1092,7 @@ pod/perlcompile.pod Info on using the Compiler suite pod/perldata.pod Data structure info pod/perldbmfilter.pod Info about DBM Filters pod/perldebguts.pod Debugger guts info +pod/perldebtut.pod Perl debugging tutorial pod/perldebug.pod Debugger info pod/perldelta.pod Changes since last version pod/perldiag.pod Diagnostic info diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL index 54853d3..131dac3 100644 --- a/pod/buildtoc.PL +++ b/pod/buildtoc.PL @@ -80,6 +80,7 @@ if (-d "pod") { perlrun perldiag perllexwarn + perldebtut perldebug perlvar diff --git a/pod/perl.pod b/pod/perl.pod index 0273dbf..998fe2f 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -34,6 +34,7 @@ For ease of access, the Perl manual has been split up into several sections: perlrun Perl execution and options perldiag Perl diagnostic messages perllexwarn Perl warnings and their control + perldebtut Perl debugging tutorial perldebug Perl debugging perlvar Perl predefined variables diff --git a/pod/perldebtut.pod b/pod/perldebtut.pod new file mode 100644 index 0000000..35eb89e --- /dev/null +++ b/pod/perldebtut.pod @@ -0,0 +1,698 @@ +=head1 NAME + +perldebtut - Perl debugging tutorial + +=head1 DESCRIPTION + +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. + +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 +day. +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: + + #!/usr/bin/perl + + $var1 = 'Hello World'; # always wanted to do that :-) + $var2 = "$varl\n"; + + print $var2; + exit; + +While this compiles and runs happily, it probably won't do what's expected, +namely it doesn't print "Hello World\n" at all; It will on the other hand do +exactly what it was told to do, computers being a bit that way inclined. That +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" + +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 +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. + +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 $var2 = "$varl\n"; + + print $var2; + exit; + +We then do (always a good idea) a syntax check before we try to run it again: + + > perl -c hello + 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) +variable, and simply changing $varl to $var1 solves the problem. + + +=head1 Looking at data and -w + +Ok, but how about when you want to really see your data, what's in that +dynamic variable, just before using it? + + #!/usr/bin/perl + use strict; + + my $key = 'welcome'; + my %data = ( + 'this' => qw(that), + 'tom' => qw(and jerry), + 'welcome' => q(Hello World), + 'zip' => q(welcome), + ); + my @data = keys %data; + + print "$data{$key}\n"; + exit; + +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: + + print "All OK\n" if grep($key, keys %data); + print "$data{$key}\n"; + 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 +line: + + > perl -d data + Default die handler restored. + + Loading DB routines from perl5db.pl version 1.07 + Editor support available. + + Enter h or `h h' for help, or `man perldebug' for more help. + + main::(./data:4): my $key = 'welcome'; + +Now, what we've done here is to launch the built-in perl debugger on our +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': + + DB<1> q + > + +That's it, you're back on home turf again. + +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. + +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): + + 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 + 1 #!/usr/bin/perl + 2: use strict; + 3 + 4==> my $key = 'welcome'; + 5: my %data = ( + 6 'this' => qw(that), + 7 'tom' => qw(and jerry), + 8 'welcome' => q(Hello World), + 9 'zip' => q(welcome), + 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 + 8 'welcome' => q(Hello World), + 9 'zip' => q(welcome), + 10 ); + 11: my @data = keys %data; + 12: print "All OK\n" if grep($key, keys %data); + 13: print "$data{$key}\n"; + 14: print "done: '$data{$key}'\n"; + 15: exit; + +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 '.': + + DB<6> . + 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': + + DB<6> s + main::(./data_a:5): my %data = ( + main::(./data_a:6): 'this' => qw(that), + main::(./data_a:7): 'tom' => qw(and jerry), + main::(./data_a:8): 'welcome' => q(Hello World), + main::(./data_a:9): 'zip' => q(welcome), + main::(./data_a:10): ); + +Now we can have a look at that first ($key) variable: + + DB<7> p $key + welcome + +line 13 is where the action is, so let's continue down to there via the letter +'c': + + 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! + + DB<10> p %data + Hello Worldziptomandwelcomejerrywelcomethisthat + + DB<11> p keys %data + Hello Worldtomwelcomejerrythis + +Reading the helpful manual (h h), the 'x' command looks promising: + + DB<12> x %data + 0 'Hello World' + 1 'zip' + 2 'tom' + 3 'and' + 4 'welcome' + 5 undef + 6 'jerry' + 7 'welcome' + 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 +this case, not particularly helpful. The trick here, is to use a B +to the data structure: + + DB<13> x \%data + 0 HASH(0x8194bc4) + 'Hello World' => 'zip' + 'jerry' => 'welcome' + 'this' => 'that' + 'tom' => 'and' + 'welcome' => undef + +The reference is truly dumped and we can finally see what we're dealing with. +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, +and saved us a lot of trouble: + + > perl -w data + Odd number of elements in hash assignment at ./data line 5. + +We fix our quoting: 'tom' => q(and jerry), and run it again, this time we get +our expected output: + + > perl -w data + Hello World + + +While we're here, take a closer look at the 'x' command, it's really useful +and will merrily dump out nested references, complete objects, partial objects +- justabout 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, +a zero: + + > perl -de 0 + Default die handler restored. + + Loading DB routines from perl5db.pl version 1.07 + Editor support available. + + Enter h or `h h' for help, or `man perldebug' for more help. + + main::(-e:1): 0 + +Now build an on-the-fly object over a couple of lines (note the backslash): + + DB<1> $obj = bless({'unique_id'=>'123', 'attr'=> \ + 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) + 'col' => 'black' + 'things' => ARRAY(0x828abb8) + 0 'this' + 1 'that' + 2 'etc' + 'unique_id' => 123 + DB<3> + +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 + other + scythe + the + theory + saw -> 6 + +If you want to see all the command history, an 'H': + + DB<5> H + 4: p 'saw -> '.($cnt += map { print "\t:\t$_\n" } grep(/the/, sort @data)) + 3: @data = qw(this that the other atheism leather theory scythe) + 2: x $obj + 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: '!': + + DB<5> !4 + p 'saw -> '.($cnt += map { print "$_\n" } grep(/the/, sort @data)) + atheism + leather + other + scythe + the + theory + saw -> 12 + + +=head1 Stepping through code + +Here's a simple program which converts between celsius and farenheit, it too +has a problem: + + #!/usr/bin/perl -w + use strict; + + my $arg = $ARGV[0] || '-c20'; + + if ($arg =~ /^\-(c|f)((\-|\+)*\d+(\.\d+)*)$/) { + my ($deg, $num) = ($1, $2); + my ($in, $out) = ($num, $num); + if ($deg eq 'c') { + $deg = 'f'; + $out = &c2f($num); + } else { + $deg = 'c'; + $out = &f2c($num); + } + $out = sprintf('%0.2f', $out); + $out =~ s/^((\-|\+)*\d+)\.0+$/$1/; + print "$out $deg\n"; + } else { + print "Usage: $0 -[c|f] num\n"; + } + exit; + + sub f2c { + my $f = shift; + my $c = 5 * $f - 32 / 9; + return $c; + } + + sub c2f { + my $c = shift; + my $f = 9 * $c / 5 + 32; + return $f; + } + + +For some reason, the farenheit 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 +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. + + Loading DB routines from perl5db.pl version 1.07 + Editor support available. + + Enter h or `h h' for help, or `man perldebug' for more help. + + main::(temp:4): my $arg = $ARGV[0] || '-c100'; + +We'll simply continue down to our pre-set breakpoint with a 'c': + + DB<1> c + main::(temp:10): if ($deg eq 'c') { + +Followed by a window command to see where we are: + + DB<2> w + 7: my ($deg, $num) = ($1, $2); + 8: my ($in, $out) = ($num, $num); + 9: $DB::single=2; + 10==> if ($deg eq 'c') { + 11: $deg = 'f'; + 12: $out = &c2f($num); + 13 } else { + 14: $deg = 'c'; + 15: $out = &f2c($num); + 16 } + +And a print to show what values we're currently using: + + DB<3> 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 + +There's no feedback from this, but you can see what breakpoints are set by +using the list 'L' command: + + DB<5> L + temp: + 17: print "$out $deg\n"; + break if (1) + +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': + + DB<6> 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; + +And have a look at the return value: + + DB<9> 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) + 162.944444444444 + + DB<11> p 5 * $f - (32 / 9) + 162.944444444444 + + DB<12> p (5 * $f) - 32 / 9 + 162.944444444444 + + DB<13> 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 + scalar context return from main::f2c: 0.722222222222221 + +Looks good, let's just continue off the end of the script: + + DB<16> 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, + h q, h R or h O to get additional info. + +A quick fix to the offending line (insert the missing parentheses) in the +actual program and we're finished. + + +=head1 Placeholder for a, w, t, T + +Actions, watch variables, stack traces on the TODO list. + + a + + W + + t + + T + + +=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 + rarest char + at 0 + 1: BOL(2) + 2: EXACTF (4) + 4: CURLYN[1] {0,32767}(14) + 6: NOTHING(8) + 8: EXACTF (0) + 12: WHILEM(0) + 13: NOTHING(14) + 14: EXACTF (16) + 16: EOL(17) + 17: END(0) + 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? :-) + + +=head1 Some ideas for output + +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 +your script: + + $|=1; + +To watch the tail of a dynamically growing logfile, (from the command line): + + tail -f $error_log + +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(@_) } } + +Various useful techniques for the redirection of STDOUT and STDERR filehandles +are explained in L and 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: + + > perl -d my_cgi.pl -nodebug + +Of course 'L' and L will tell you more. + + +=head1 GUIs + +The command line interface is tightly integrated with an B extension +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 +popup balloon, no more tiresome typing of 'x $varname' :-) + +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 + +We've seen how to encourage good coding practices with B and +B<-w>. We can run the perl debugger B to inspect your +data from within the perl debugger with the B

and B commands. You can +walk through your code, set breakpoints with B and step through that code +with B or B, continue with B and return from a sub with B. Fairly +intuitive stuff when you get down to it. + +There is of course lots more to find out about, this has just scratched the +surface. The best way to learn more is to use perldoc to find out more about +the language, to read the on-line help (L is probably the next +place to go), and of course, experiment. + + +=head1 SEE ALSO + +L, +L, +L, +L, +L + + +=head1 AUTHOR + +Richard Foley Copyright (c) 2000 + + +=head1 CONTRIBUTORS + +Various people have made helpful suggestions and contributions, in particular: + +Ronald J Kimball + +Hugo + diff --git a/pod/perltoc.pod b/pod/perltoc.pod index bbd842a..c20160c 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -1019,6 +1019,38 @@ B<-w>, B<-W>, B<-X> =back +=head2 perldebtut - Perl debugging tutorial + +=over + +=item DESCRIPTION + +=item use strict + +=item Looking at data and -w + +=item Stepping through code + +=item Placeholder for a, w, t, T + +=item Regular expressions + +=item Some ideas for output + +=item CGI + +=item GUIs + +=item Summary + +=item SEE ALSO + +=item AUTHOR + +=item CONTRIBUTORS + +=back + =head2 perldebug - Perl debugging =over @@ -5395,8 +5427,8 @@ C<-Duse64bitint>, C<-Duselongdouble>, C<-Dusethreads>, C<-Duselargefiles> =item Suspicious Warnings -Whoa There, I, Win9x and C, Checking how std your stdio -is.., Compiler/Preprocessor defines +I, Win9x and C, Checking how std your stdio is.., +Compiler/Preprocessor defines =back @@ -7086,8 +7118,8 @@ B<:standard>, B<:all> =item PRAGMAS --any, -compile, -nosticky, -nph, -newstyle_urls, -oldstyle_urls, -autoload, --no_debug, -debug, -private_tempfiles +-any, -compile, -nosticky, -no_xhtml, -nph, -newstyle_urls, -oldstyle_urls, +-autoload, -no_debug, -debug, -private_tempfiles =item SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS @@ -7312,6 +7344,8 @@ other) error log =back +=item MAKING WARNINGS APPEAR AS HTML COMMENTS + =item CHANGE LOG =item AUTHORS @@ -7452,8 +7486,6 @@ B, B, B, B, B =back -=head2 CGI::Util - various utilities - =head2 CPAN - query, download and build perl modules from CPAN sites =over @@ -7478,7 +7510,7 @@ distribution, Signals =item The four C Classes: Author, Bundle, Module, Distribution -=item ProgrammerE<39>s interface +=item Programmer's interface expand($type,@things), Programming Examples @@ -7521,8 +7553,23 @@ optionE [shift|pop]>, Clist optionE =item WORKING WITH CPAN.pm BEHIND FIREWALLS +=over + +=item Three basic types of firewalls + http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade +=item Configuring lynx or ncftp for going throught the firewall + +=back + +=item FAQ + +I installed a new version of module X but CPAN keeps saying, I have +the old version installed, So why is UNINST=1 not the default?, When I +install bundles or multiple modules with one command there is too +much output to keep track of + =item BUGS =item AUTHOR @@ -9146,8 +9193,9 @@ rmscopy($from,$to[,$date_flag]) =item DESCRIPTION -C, C, C, C, C, -C, C, C, C +C, C, C, C, C, +C, C, C, C, +C, C =item CAVEAT @@ -9616,6 +9664,8 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =over +=item Object oriented interface + =item Documentation and help texts =item Storing options in a hash @@ -9630,10 +9680,11 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =item Configuring Getopt::Long -default, auto_abbrev, getopt_compat, require_order, permute, bundling -(default: reset), bundling_override (default: reset), ignore_case -(default: set), ignore_case_always (default: reset), pass_through (default: -reset), prefix, prefix_pattern, debug (default: reset) +default, posix_default, auto_abbrev, getopt_compat, require_order, permute, +bundling (default: disabled), bundling_override (default: disabled), +ignore_case (default: enabled), ignore_case_always (default: disabled), +pass_through (default: disabled), prefix, prefix_pattern, debug (default: +disabled) =item Return values and Errors @@ -9649,6 +9700,17 @@ reset), prefix, prefix_pattern, debug (default: reset) =back +=item Trouble Shooting + +=over + +=item Warning: Ignoring '!' modifier for short option + +=item GetOptions does not return a false result when an option is not +supplied + +=back + =item AUTHOR =item COPYRIGHT AND DISCLAIMER @@ -10799,7 +10861,13 @@ argument for =over, previous =item has no contents, preceding non-item paragraph(s), =item type mismatch (I vs. I), I unescaped CE> in paragraph, Unknown entity, No items in =over, No argument for =item, empty section in previous paragraph, Verbatim paragraph in NAME -section, Hyperlinks +section + +=item Hyperlinks + +collapsing newlines to blanks, ignoring leading/trailing whitespace in +link, (section) in '$page' deprecated, alternative text/node '%s' contains +non-escaped | or / =back @@ -10811,6 +10879,8 @@ section, Hyperlinks =back +Cnew( %options )> + C<$checker-Epoderror( @args )>, C<$checker-Epoderror( {%opts}, @args )> @@ -10838,9 +10908,39 @@ C<$checker-Ehyperlink()> =item DESCRIPTION -=item OPTIONS +=back + +=over + +=item C -B<-verbose>, B<-perl>, B<-script>, B<-inc> +C<-verbose =E 1>, C<-perl =E 1>, C<-script =E 1>, C<-inc =E +1> + +=back + +=over + +=item C + +=back + +=over + +=item C + +C<-inc =E 1>, C<-dirs =E [ $dir1, $dir2, ... ]>, C<-verbose =E +1> + +=back + +=over + +=item C + +=back + +=over =item AUTHOR @@ -10887,8 +10987,8 @@ commands, etc. =item DESCRIPTION -B, B, B, -B +package B, package B, package +B, package B =back @@ -10930,49 +11030,49 @@ B =over -=item B +=item Pod::Paragraph-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back =over -=item B +=item $pod_para-EB =back @@ -10984,67 +11084,67 @@ B =over -=item B +=item Pod::InteriorSequence-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item $pod_seq-EB =back =over -=item B +=item Pod::InteriorSequence::B =back @@ -11056,43 +11156,43 @@ B =over -=item B +=item Pod::ParseTree-EB =back =over -=item B +=item $ptree-EB =back =over -=item B +=item $ptree-EB =back =over -=item B +=item $ptree-EB =back =over -=item B +=item $ptree-EB =back =over -=item B +=item $ptree-EB =back =over -=item B +=item Pod::ParseTree::B =back @@ -11260,87 +11360,87 @@ EE%sE, Unknown sequence %s, Unmatched =back =item Pod::List -new() +Pod::List-Enew() =back -file() +$list-Efile() -start() +$list-Estart() -indent() +$list-Eindent() -type() +$list-Etype() -rx() +$list-Erx() -item() +$list-Eitem() -parent() +$list-Eparent() -tag() +$list-Etag() =over =item Pod::Hyperlink -new() +Pod::Hyperlink-Enew() =back -parse($string) +$link-Eparse($string) -markup($string) +$link-Emarkup($string) -text() +$link-Etext() -warning() +$link-Ewarning() -line(), file() +$link-Efile(), $link-Eline() -page() +$link-Epage() -node() +$link-Enode() -alttext() +$link-Ealttext() -type() +$link-Etype() -link() +$link-Elink() =over =item Pod::Cache -new() +Pod::Cache-Enew() =back -item() +$cache-Eitem() -find_page($name) +$cache-Efind_page($name) =over =item Pod::Cache::Item -new() +Pod::Cache::Item-Enew() =back -page() +$cacheitem-Epage() -description() +$cacheitem-Edescription() -path() +$cacheitem-Epath() -file() +$cacheitem-Efile() -nodes() +$cacheitem-Enodes() -find_node($name) +$cacheitem-Efind_node($name) -idx() +$cacheitem-Eidx() =over @@ -11589,6 +11689,31 @@ I|I =back +=head2 Pod::PlainText - Convert POD data to formatted ASCII text + +=over + +=item SYNOPSIS + +=item DESCRIPTION + +alt, indent, loose, sentence, width + +=item DIAGNOSTICS + +Bizarre space in item, Can't open %s for reading: %s, Unknown escape: %s, +Unknown sequence: %s, Unmatched =back + +=item RESTRICTIONS + +=item NOTES + +=item SEE ALSO + +=item AUTHOR + +=back + =head2 Pod::Plainer - Perl extension for converting Pod to old style Pod. =over @@ -12008,12 +12133,14 @@ closelog =item DIAGNOSTICS -Invalid attribute name %s, Identifier %s used only once: possible typo, No -comma allowed after filehandle, Bareword %s not allowed while "strict subs" -in use +Invalid attribute name %s, Name "%s" used only once: possible typo, No +comma allowed after filehandle, Bareword "%s" not allowed while "strict +subs" in use =item RESTRICTIONS +=item NOTES + =item AUTHORS =back