move tlperl.straw to tlperl

git-svn-id: svn://tug.org/texlive/trunk@18210 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 0 insertions, 1174 deletions

diff --git a/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod b/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod
deleted file mode 100755
index c37c5cfbb2c..00000000000
--- a/Master/tlpkg/tlperl.straw/lib/pods/perldebug.pod
+++ /dev/null
@@ -1,1174 +0,0 @@
-=head1 NAME
-X<debug> X<debugger>
-
-perldebug - Perl debugging
-
-=head1 DESCRIPTION
-
-First of all, have you tried using the B<-w> switch?
-
-
-If you're new to the Perl debugger, you may prefer to read
-L<perldebtut>, which is a tutorial introduction to the debugger .
-
-=head1 The Perl Debugger
-
-If you invoke Perl with the B<-d> switch, your script runs under the
-Perl source debugger.  This works like an interactive Perl
-environment, prompting for debugger commands that let you examine
-source code, set breakpoints, get stack backtraces, change the values of
-variables, etc.  This is so convenient that you often fire up
-the debugger all by itself just to test out Perl constructs
-interactively to see what they do.  For example:
-X<-d>
-
-    $ perl -d -e 42
-
-In Perl, the debugger is not a separate program the way it usually is in the
-typical compiled environment.  Instead, the B<-d> flag tells the compiler
-to insert source information into the parse trees it's about to hand off
-to the interpreter.  That means your code must first compile correctly
-for the debugger to work on it.  Then when the interpreter starts up, it
-preloads a special Perl library file containing the debugger.
-
-The program will halt I<right before> the first run-time executable
-statement (but see below regarding compile-time statements) and ask you
-to enter a debugger command.  Contrary to popular expectations, whenever
-the debugger halts and shows you a line of code, it always displays the
-line it's I<about> to execute, rather than the one it has just executed.
-
-Any command not recognized by the debugger is directly executed
-(C<eval>'d) as Perl code in the current package.  (The debugger
-uses the DB package for keeping its own state information.)
-
-Note that the said C<eval> is bound by an implicit scope. As a
-result any newly introduced lexical variable or any modified
-capture buffer content is lost after the eval. The debugger is a
-nice environment to learn Perl, but if you interactively experiment using
-material which should be in the same scope, stuff it in one line.
-
-For any text entered at the debugger prompt, leading and trailing whitespace
-is first stripped before further processing.  If a debugger command
-coincides with some function in your own program, merely precede the
-function with something that doesn't look like a debugger command, such
-as a leading C<;> or perhaps a C<+>, or by wrapping it with parentheses
-or braces.
-
-=head2 Calling the debugger
-
-There are several ways to call the debugger:
-
-=over 4
-
-=item perl -d program_name
-
-On the given program identified by C<program_name>.
-
-=item perl -d -e 0 
-
-Interactively supply an arbitrary C<expression> using C<-e>.
-
-=item perl -d:Ptkdb program_name
-
-Debug a given program via the C<Devel::Ptkdb> GUI.
-
-=item perl -dt threaded_program_name
-
-Debug a given program using threads (experimental).
-
-=back
-
-=head2 Debugger Commands
-
-The interactive debugger understands the following commands:
-
-=over 12
-
-=item h
-X<debugger command, h>
-
-Prints out a summary help message
-
-=item h [command]
-
-Prints out a help message for the given debugger command.
-
-=item h h
-
-The special argument of C<h h> produces the entire help page, which is quite long.
-
-If the output of the C<h h> command (or any command, for that matter) scrolls
-past your screen, precede the command with a leading pipe symbol so
-that it's run through your pager, as in
-
-    DB> |h h
-
-You may change the pager which is used via C<o pager=...> command.
-
-
-=item p expr
-X<debugger command, p>
-
-Same as C<print {$DB::OUT} expr> in the current package.  In particular,
-because this is just Perl's own C<print> function, this means that nested
-data structures and objects are not dumped, unlike with the C<x> command.
-
-The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
-where STDOUT may be redirected to.
-
-=item x [maxdepth] expr
-X<debugger command, x>
-
-Evaluates its expression in list context and dumps out the result in a
-pretty-printed fashion.  Nested data structures are printed out
-recursively, unlike the real C<print> function in Perl.  When dumping
-hashes, you'll probably prefer 'x \%h' rather than 'x %h'.
-See L<Dumpvalue> if you'd like to do this yourself.
-
-The output format is governed by multiple options described under
-L<"Configurable Options">.
-
-If the C<maxdepth> is included, it must be a numeral I<N>; the value is
-dumped only I<N> levels deep, as if the C<dumpDepth> option had been
-temporarily set to I<N>.
-
-=item V [pkg [vars]]
-X<debugger command, V>
-
-Display all (or some) variables in package (defaulting to C<main>)
-using a data pretty-printer (hashes show their keys and values so
-you see what's what, control characters are made printable, etc.).
-Make sure you don't put the type specifier (like C<$>) there, just
-the symbol names, like this:
-
-    V DB filename line
-
-Use C<~pattern> and C<!pattern> for positive and negative regexes.
-
-This is similar to calling the C<x> command on each applicable var.
-
-=item X [vars]
-X<debugger command, X>
-
-Same as C<V currentpackage [vars]>.
-
-=item y [level [vars]]
-X<debugger command, y>
-
-Display all (or some) lexical variables (mnemonic: C<mY> variables)
-in the current scope or I<level> scopes higher.  You can limit the
-variables that you see with I<vars> which works exactly as it does
-for the C<V> and C<X> commands.  Requires the C<PadWalker> module
-version 0.08 or higher; will warn if this isn't installed.  Output
-is pretty-printed in the same style as for C<V> and the format is
-controlled by the same options.
-
-=item T
-X<debugger command, T> X<backtrace> X<stack, backtrace>
-
-Produce a stack backtrace.  See below for details on its output.
-
-=item s [expr]
-X<debugger command, s> X<step>
-
-Single step.  Executes until the beginning of another
-statement, descending into subroutine calls.  If an expression is
-supplied that includes function calls, it too will be single-stepped.
-
-=item n [expr]
-X<debugger command, n>
-
-Next.  Executes over subroutine calls, until the beginning
-of the next statement.  If an expression is supplied that includes
-function calls, those functions will be executed with stops before
-each statement.
-
-=item r
-X<debugger command, r>
-
-Continue until the return from the current subroutine.
-Dump the return value if the C<PrintRet> option is set (default).
-
-=item <CR>
-
-Repeat last C<n> or C<s> command.
-
-=item c [line|sub]
-X<debugger command, c>
-
-Continue, optionally inserting a one-time-only breakpoint
-at the specified line or subroutine.
-
-=item l
-X<debugger command, l>
-
-List next window of lines.
-
-=item l min+incr
-
-List C<incr+1> lines starting at C<min>.
-
-=item l min-max
-
-List lines C<min> through C<max>.  C<l -> is synonymous to C<->.
-
-=item l line
-
-List a single line.
-
-=item l subname
-
-List first window of lines from subroutine.  I<subname> may
-be a variable that contains a code reference.
-
-=item -
-X<debugger command, ->
-
-List previous window of lines.
-
-=item v [line]
-X<debugger command, v>
-
-View a few lines of code around the current line.
-
-=item .
-X<debugger command, .>
-
-Return the internal debugger pointer to the line last
-executed, and print out that line.
-
-=item f filename
-X<debugger command, f>
-
-Switch to viewing a different file or C<eval> statement.  If I<filename>
-is not a full pathname found in the values of %INC, it is considered
-a regex.
-
-C<eval>ed strings (when accessible) are considered to be filenames:
-C<f (eval 7)> and C<f eval 7\b> access the body of the 7th C<eval>ed string
-(in the order of execution).  The bodies of the currently executed C<eval>
-and of C<eval>ed strings that define subroutines are saved and thus
-accessible.
-
-=item /pattern/
-
-Search forwards for pattern (a Perl regex); final / is optional.
-The search is case-insensitive by default.
-
-=item ?pattern?
-
-Search backwards for pattern; final ? is optional.
-The search is case-insensitive by default.
-
-=item L [abw]
-X<debugger command, L>
-
-List (default all) actions, breakpoints and watch expressions
-
-=item S [[!]regex]
-X<debugger command, S>
-
-List subroutine names [not] matching the regex.
-
-=item t
-X<debugger command, t>
-
-Toggle trace mode (see also the C<AutoTrace> option).
-
-=item t expr
-X<debugger command, t>
-
-Trace through execution of C<expr>.
-See L<perldebguts/"Frame Listing Output Examples"> for examples.
-
-=item b
-X<breakpoint>
-X<debugger command, b>
-
-Sets breakpoint on current line
-
-=item b [line] [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the given line.  If a condition
-is specified, it's evaluated each time the statement is reached: a
-breakpoint is taken only if the condition is true.  Breakpoints may
-only be set on lines that begin an executable statement.  Conditions
-don't use C<if>:
-
-    b 237 $x > 30
-    b 237 ++$count237 < 11
-    b 33 /pattern/i
-
-=item b subname [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the first line of the named subroutine.  I<subname> may
-be a variable containing a code reference (in this case I<condition>
-is not supported).
-
-=item b postpone subname [condition]
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint at first line of subroutine after it is compiled.
-
-=item b load filename
-X<breakpoint>
-X<debugger command, b>
-
-Set a breakpoint before the first executed line of the I<filename>,
-which should be a full pathname found amongst the %INC values.
-
-=item b compile subname
-X<breakpoint>
-X<debugger command, b>
-
-Sets a breakpoint before the first statement executed after the specified
-subroutine is compiled.
-
-=item B line
-X<breakpoint>
-X<debugger command, B>
-
-Delete a breakpoint from the specified I<line>.
-
-=item B *
-X<breakpoint>
-X<debugger command, B>
-
-Delete all installed breakpoints.
-
-=item a [line] command
-X<debugger command, a>
-
-Set an action to be done before the line is executed.  If I<line> is
-omitted, set an action on the line about to be executed.
-The sequence of steps taken by the debugger is
-
-  1. check for a breakpoint at this line
-  2. print the line if necessary (tracing)
-  3. do any actions associated with that line
-  4. prompt user if at a breakpoint or in single-step
-  5. evaluate line
-
-For example, this will print out $foo every time line
-53 is passed:
-
-    a 53 print "DB FOUND $foo\n"
-
-=item A line
-X<debugger command, A>
-
-Delete an action from the specified line.
-
-=item A *
-X<debugger command, A>
-
-Delete all installed actions.
-
-=item w expr
-X<debugger command, w>
-
-Add a global watch-expression. Whenever a watched global changes the
-debugger will stop and display the old and new values.
-
-=item W expr
-X<debugger command, W>
-
-Delete watch-expression
-
-=item W *
-X<debugger command, W>
-
-Delete all watch-expressions.
-
-=item o
-X<debugger command, o>
-
-Display all options
-
-=item o booloption ...
-X<debugger command, o>
-
-Set each listed Boolean option to the value C<1>.
-
-=item o anyoption? ...
-X<debugger command, o>
-
-Print out the value of one or more options.
-
-=item o option=value ...
-X<debugger command, o>
-
-Set the value of one or more options.  If the value has internal
-whitespace, it should be quoted.  For example, you could set C<o
-pager="less -MQeicsNfr"> to call B<less> with those specific options.
-You may use either single or double quotes, but if you do, you must
-escape any embedded instances of same sort of quote you began with,
-as well as any escaping any escapes that immediately precede that
-quote but which are not meant to escape the quote itself.  In other
-words, you follow single-quoting rules irrespective of the quote;
-eg: C<o option='this isn\'t bad'> or C<o option="She said, \"Isn't
-it?\"">.
-
-For historical reasons, the C<=value> is optional, but defaults to
-1 only where it is safe to do so--that is, mostly for Boolean
-options.  It is always better to assign a specific value using C<=>.
-The C<option> can be abbreviated, but for clarity probably should
-not be.  Several options can be set together.  See L<"Configurable Options">
-for a list of these.
-
-=item < ?
-X<< debugger command, < >>
-
-List out all pre-prompt Perl command actions.
-
-=item < [ command ]
-X<< debugger command, < >>
-
-Set an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backslashing the newlines.
-
-=item < *
-X<< debugger command, < >>
-
-Delete all pre-prompt Perl command actions.
-
-=item << command
-X<< debugger command, << >>
-
-Add an action (Perl command) to happen before every debugger prompt.
-A multi-line command may be entered by backwhacking the newlines.
-
-=item > ?
-X<< debugger command, > >>
-
-List out post-prompt Perl command actions.
-
-=item > command
-X<< debugger command, > >>
-
-Set an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script.  A multi-line
-command may be entered by backslashing the newlines (we bet you
-couldn't have guessed this by now).
-
-=item > *
-X<< debugger command, > >>
-
-Delete all post-prompt Perl command actions.
-
-=item >> command
-X<<< debugger command, >> >>>
-
-Adds an action (Perl command) to happen after the prompt when you've
-just given a command to return to executing the script.  A multi-line
-command may be entered by backslashing the newlines.
-
-=item { ?
-X<debugger command, {>
-
-List out pre-prompt debugger commands.
-
-=item { [ command ]
-
-Set an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered in the customary fashion.
-
-Because this command is in some senses new, a warning is issued if
-you appear to have accidentally entered a block instead.  If that's
-what you mean to do, write it as with C<;{ ... }> or even
-C<do { ... }>.
-
-=item { *
-X<debugger command, {>
-
-Delete all pre-prompt debugger commands.
-
-=item {{ command
-X<debugger command, {{>
-
-Add an action (debugger command) to happen before every debugger prompt.
-A multi-line command may be entered, if you can guess how: see above.
-
-=item ! number
-X<debugger command, !>
-
-Redo a previous command (defaults to the previous command).
-
-=item ! -number
-X<debugger command, !>
-
-Redo number'th previous command.
-
-=item ! pattern
-X<debugger command, !>
-
-Redo last command that started with pattern.
-See C<o recallCommand>, too.
-
-=item !! cmd
-X<debugger command, !!>
-
-Run cmd in a subprocess (reads from DB::IN, writes to DB::OUT) See
-C<o shellBang>, also.  Note that the user's current shell (well,
-their C<$ENV{SHELL}> variable) will be used, which can interfere
-with proper interpretation of exit status or signal and coredump
-information.
-
-=item source file
-X<debugger command, source>
-
-Read and execute debugger commands from I<file>.
-I<file> may itself contain C<source> commands.
-
-=item H -number
-X<debugger command, H>
-
-Display last n commands.  Only commands longer than one character are
-listed.  If I<number> is omitted, list them all.
-
-=item q or ^D
-X<debugger command, q>
-X<debugger command, ^D>
-
-Quit.  ("quit" doesn't work for this, unless you've made an alias)
-This is the only supported way to exit the debugger, though typing
-C<exit> twice might work.
-
-Set the C<inhibit_exit> option to 0 if you want to be able to step
-off the end the script.  You may also need to set $finished to 0
-if you want to step through global destruction.
-
-=item R
-X<debugger command, R>
-
-Restart the debugger by C<exec()>ing a new session.  We try to maintain
-your history across this, but internal settings and command-line options
-may be lost.
-
-The following setting are currently preserved: history, breakpoints,
-actions, debugger options, and the Perl command-line
-options B<-w>, B<-I>, and B<-e>.
-
-=item |dbcmd
-X<debugger command, |>
-
-Run the debugger command, piping DB::OUT into your current pager.
-
-=item ||dbcmd
-X<debugger command, ||>
-
-Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
-
-=item = [alias value]
-X<debugger command, =>
-
-Define a command alias, like
-
-    = quit q
-
-or list current aliases.
-
-=item command
-
-Execute command as a Perl statement.  A trailing semicolon will be
-supplied.  If the Perl statement would otherwise be confused for a
-Perl debugger, use a leading semicolon, too.
-
-=item m expr
-X<debugger command, m>
-
-List which methods may be called on the result of the evaluated
-expression.  The expression may evaluated to a reference to a
-blessed object, or to a package name.
-
-=item M
-X<debugger command, M>
-
-Displays all loaded modules and their versions
-
-
-=item man [manpage]
-X<debugger command, man>
-
-Despite its name, this calls your system's default documentation
-viewer on the given page, or on the viewer itself if I<manpage> is
-omitted.  If that viewer is B<man>, the current C<Config> information
-is used to invoke B<man> using the proper MANPATH or S<B<-M>
-I<manpath>> option.  Failed lookups of the form C<XXX> that match
-known manpages of the form I<perlXXX> will be retried.  This lets
-you type C<man debug> or C<man op> from the debugger.
-
-On systems traditionally bereft of a usable B<man> command, the
-debugger invokes B<perldoc>.  Occasionally this determination is
-incorrect due to recalcitrant vendors or rather more felicitously,
-to enterprising users.  If you fall into either category, just
-manually set the $DB::doccmd variable to whatever viewer to view
-the Perl documentation on your system.  This may be set in an rc
-file, or through direct assignment.  We're still waiting for a
-working example of something along the lines of:
-
-    $DB::doccmd = 'netscape -remote http://something.here/';
-
-=back
-
-=head2 Configurable Options
-
-The debugger has numerous options settable using the C<o> command,
-either interactively or from the environment or an rc file.
-(./.perldb or ~/.perldb under Unix.)
-
-
-=over 12
-
-=item C<recallCommand>, C<ShellBang>
-X<debugger option, recallCommand>
-X<debugger option, ShellBang>
-
-The characters used to recall command or spawn shell.  By
-default, both are set to C<!>, which is unfortunate.
-
-=item C<pager>
-X<debugger option, pager>
-
-Program to use for output of pager-piped commands (those beginning
-with a C<|> character.)  By default, C<$ENV{PAGER}> will be used.
-Because the debugger uses your current terminal characteristics
-for bold and underlining, if the chosen pager does not pass escape
-sequences through unchanged, the output of some debugger commands
-will not be readable when sent through the pager.
-
-=item C<tkRunning>
-X<debugger option, tkRunning>
-
-Run Tk while prompting (with ReadLine).
-
-=item C<signalLevel>, C<warnLevel>, C<dieLevel>
-X<debugger option, signalLevel> X<debugger option, warnLevel>
-X<debugger option, dieLevel>
-
-Level of verbosity.  By default, the debugger leaves your exceptions
-and warnings alone, because altering them can break correctly running
-programs.  It will attempt to print a message when uncaught INT, BUS, or
-SEGV signals arrive.  (But see the mention of signals in L<BUGS> below.)
-
-To disable this default safe mode, set these values to something higher
-than 0.  At a level of 1, you get backtraces upon receiving any kind
-of warning (this is often annoying) or exception (this is
-often valuable).  Unfortunately, the debugger cannot discern fatal
-exceptions from non-fatal ones.  If C<dieLevel> is even 1, then your
-non-fatal exceptions are also traced and unceremoniously altered if they
-came from C<eval'ed> strings or from any kind of C<eval> within modules
-you're attempting to load.  If C<dieLevel> is 2, the debugger doesn't
-care where they came from:  It usurps your exception handler and prints
-out a trace, then modifies all exceptions with its own embellishments.
-This may perhaps be useful for some tracing purposes, but tends to hopelessly
-destroy any program that takes its exception handling seriously.
-
-=item C<AutoTrace>
-X<debugger option, AutoTrace>
-
-Trace mode (similar to C<t> command, but can be put into
-C<PERLDB_OPTS>).
-
-=item C<LineInfo>
-X<debugger option, LineInfo>
-
-File or pipe to print line number info to.  If it is a pipe (say,
-C<|visual_perl_db>), then a short message is used.  This is the
-mechanism used to interact with a slave editor or visual debugger,
-such as the special C<vi> or C<emacs> hooks, or the C<ddd> graphical
-debugger.
-
-=item C<inhibit_exit>
-X<debugger option, inhibit_exit>
-
-If 0, allows I<stepping off> the end of the script.
-
-=item C<PrintRet>
-X<debugger option, PrintRet>
-
-Print return value after C<r> command if set (default).
-
-=item C<ornaments>
-X<debugger option, ornaments>
-
-Affects screen appearance of the command line (see L<Term::ReadLine>).
-There is currently no way to disable these, which can render
-some output illegible on some displays, or with some pagers.
-This is considered a bug.
-
-=item C<frame>
-X<debugger option, frame>
-
-Affects the printing of messages upon entry and exit from subroutines.  If
-C<frame & 2> is false, messages are printed on entry only. (Printing
-on exit might be useful if interspersed with other messages.)
-
-If C<frame & 4>, arguments to functions are printed, plus context
-and caller info.  If C<frame & 8>, overloaded C<stringify> and
-C<tie>d C<FETCH> is enabled on the printed arguments.  If C<frame
-& 16>, the return value from the subroutine is printed.
-
-The length at which the argument list is truncated is governed by the
-next option:
-
-=item C<maxTraceLen>
-X<debugger option, maxTraceLen>
-
-Length to truncate the argument list when the C<frame> option's
-bit 4 is set.
-
-=item C<windowSize>
-X<debugger option, windowSize>
-
-Change the size of code list window (default is 10 lines).
-
-=back
-
-The following options affect what happens with C<V>, C<X>, and C<x>
-commands:
-
-=over 12
-
-=item C<arrayDepth>, C<hashDepth>
-X<debugger option, arrayDepth> X<debugger option, hashDepth>
-
-Print only first N elements ('' for all).
-
-=item C<dumpDepth>
-X<debugger option, dumpDepth>
-
-Limit recursion depth to N levels when dumping structures.
-Negative values are interpreted as infinity.  Default: infinity.
-
-=item C<compactDump>, C<veryCompact>
-X<debugger option, compactDump> X<debugger option, veryCompact>
-
-Change the style of array and hash output.  If C<compactDump>, short array
-may be printed on one line.
-
-=item C<globPrint>
-X<debugger option, globPrint>
-
-Whether to print contents of globs.
-
-=item C<DumpDBFiles>
-X<debugger option, DumpDBFiles>
-
-Dump arrays holding debugged files.
-
-=item C<DumpPackages>
-X<debugger option, DumpPackages>
-
-Dump symbol tables of packages.
-
-=item C<DumpReused>
-X<debugger option, DumpReused>
-
-Dump contents of "reused" addresses.
-
-=item C<quote>, C<HighBit>, C<undefPrint>
-X<debugger option, quote> X<debugger option, HighBit>
-X<debugger option, undefPrint>
-
-Change the style of string dump.  The default value for C<quote>
-is C<auto>; one can enable double-quotish or single-quotish format
-by setting it to C<"> or C<'>, respectively.  By default, characters
-with their high bit set are printed verbatim.
-
-=item C<UsageOnly>
-X<debugger option, UsageOnly>
-
-Rudimentary per-package memory usage dump.  Calculates total
-size of strings found in variables in the package.  This does not
-include lexicals in a module's file scope, or lost in closures.
-
-=back
-
-After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
-environment variable and parses this as the remainder of a "O ..."
-line as one might enter at the debugger prompt.  You may place the
-initialization options C<TTY>, C<noTTY>, C<ReadLine>, and C<NonStop>
-there.
-
-If your rc file contains:
-
-  parse_options("NonStop=1 LineInfo=db.out AutoTrace");
-
-then your script will run without human intervention, putting trace
-information into the file I<db.out>.  (If you interrupt it, you'd
-better reset C<LineInfo> to F</dev/tty> if you expect to see anything.)
-
-=over 12
-
-=item C<TTY>
-X<debugger option, TTY>
-
-The TTY to use for debugging I/O.
-
-=item C<noTTY>
-X<debugger option, noTTY>
-
-If set, the debugger goes into C<NonStop> mode and will not connect to a TTY.  If
-interrupted (or if control goes to the debugger via explicit setting of
-$DB::signal or $DB::single from the Perl script), it connects to a TTY
-specified in the C<TTY> option at startup, or to a tty found at
-runtime using the C<Term::Rendezvous> module of your choice.
-
-This module should implement a method named C<new> that returns an object
-with two methods: C<IN> and C<OUT>.  These should return filehandles to use
-for debugging input and output correspondingly.  The C<new> method should
-inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
-startup, or C<"$ENV{HOME}/.perldbtty$$"> otherwise.  This file is not
-inspected for proper ownership, so security hazards are theoretically
-possible.
-
-=item C<ReadLine>
-X<debugger option, ReadLine>
-
-If false, readline support in the debugger is disabled in order
-to debug applications that themselves use ReadLine.
-
-=item C<NonStop>
-X<debugger option, NonStop>
-
-If set, the debugger goes into non-interactive mode until interrupted, or
-programmatically by setting $DB::signal or $DB::single.
-
-=back
-
-Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
-
-    $ PERLDB_OPTS="NonStop frame=2" perl -d myprogram
-
-That will run the script B<myprogram> without human intervention,
-printing out the call tree with entry and exit points.  Note that
-C<NonStop=1 frame=2> is equivalent to C<N f=2>, and that originally,
-options could be uniquely abbreviated by the first letter (modulo
-the C<Dump*> options).  It is nevertheless recommended that you
-always spell them out in full for legibility and future compatibility.
-
-Other examples include
-
-    $ PERLDB_OPTS="NonStop LineInfo=listing frame=2" perl -d myprogram
-
-which runs script non-interactively, printing info on each entry
-into a subroutine and each executed line into the file named F<listing>.
-(If you interrupt it, you would better reset C<LineInfo> to something
-"interactive"!)
-
-Other examples include (using standard shell syntax to show environment
-variable settings):
-
-  $ ( PERLDB_OPTS="NonStop frame=1 AutoTrace LineInfo=tperl.out"
-      perl -d myprogram )
-
-which may be useful for debugging a program that uses C<Term::ReadLine>
-itself.  Do not forget to detach your shell from the TTY in the window that
-corresponds to F</dev/ttyXX>, say, by issuing a command like
-
-  $ sleep 1000000
-
-See L<perldebguts/"Debugger Internals"> for details.
-
-=head2 Debugger input/output
-
-=over 8
-
-=item Prompt
-
-The debugger prompt is something like
-
-    DB<8>
-
-or even
-
-    DB<<17>>
-
-where that number is the command number, and which you'd use to
-access with the built-in B<csh>-like history mechanism.  For example,
-C<!17> would repeat command number 17.  The depth of the angle
-brackets indicates the nesting depth of the debugger.  You could
-get more than one set of brackets, for example, if you'd already
-at a breakpoint and then printed the result of a function call that
-itself has a breakpoint, or you step into an expression via C<s/n/t
-expression> command.
-
-=item Multiline commands
-
-If you want to enter a multi-line command, such as a subroutine
-definition with several statements or a format, escape the newline
-that would normally end the debugger command with a backslash.
-Here's an example:
-
-      DB<1> for (1..4) {         \
-      cont:     print "ok\n";   \
-      cont: }
-      ok
-      ok
-      ok
-      ok
-
-Note that this business of escaping a newline is specific to interactive
-commands typed into the debugger.
-
-=item Stack backtrace
-X<backtrace> X<stack, backtrace>
-
-Here's an example of what a stack backtrace via C<T> command might
-look like:
-
-    $ = main::infested called from file `Ambulation.pm' line 10
-    @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
-    $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
-
-The left-hand character up there indicates the context in which the
-function was called, with C<$> and C<@> meaning scalar or list
-contexts respectively, and C<.> meaning void context (which is
-actually a sort of scalar context).  The display above says
-that you were in the function C<main::infested> when you ran the
-stack dump, and that it was called in scalar context from line
-10 of the file I<Ambulation.pm>, but without any arguments at all,
-meaning it was called as C<&infested>.  The next stack frame shows
-that the function C<Ambulation::legs> was called in list context
-from the I<camel_flea> file with four arguments.  The last stack
-frame shows that C<main::pests> was called in scalar context,
-also from I<camel_flea>, but from line 4.
-
-If you execute the C<T> command from inside an active C<use>
-statement, the backtrace will contain both a C<require> frame and
-an C<eval>) frame.
-
-=item Line Listing Format
-
-This shows the sorts of output the C<l> command can produce:
-
-    DB<<13>> l
-  101:                @i{@i} = ();
-  102:b               @isa{@i,$pack} = ()
-  103                     if(exists $i{$prevpack} || exists $isa{$pack});
-  104             }
-  105
-  106             next
-  107==>              if(exists $isa{$pack});
-  108
-  109:a           if ($extra-- > 0) {
-  110:                %isa = ($pack,1);
-
-Breakable lines are marked with C<:>.  Lines with breakpoints are
-marked by C<b> and those with actions by C<a>.  The line that's
-about to be executed is marked by C<< ==> >>.
-
-Please be aware that code in debugger listings may not look the same
-as your original source code.  Line directives and external source
-filters can alter the code before Perl sees it, causing code to move
-from its original positions or take on entirely different forms.
-
-=item Frame listing
-
-When the C<frame> option is set, the debugger would print entered (and
-optionally exited) subroutines in different styles.  See L<perldebguts>
-for incredibly long examples of these.
-
-=back
-
-=head2 Debugging compile-time statements
-
-If you have compile-time executable statements (such as code within
-BEGIN, UNITCHECK and CHECK blocks or C<use> statements), these will
-I<not> be stopped by debugger, although C<require>s and INIT blocks
-will, and compile-time statements can be traced with C<AutoTrace>
-option set in C<PERLDB_OPTS>).  From your own Perl code, however, you
-can transfer control back to the debugger using the following
-statement, which is harmless if the debugger is not running:
-
-    $DB::single = 1;
-
-If you set C<$DB::single> to 2, it's equivalent to having
-just typed the C<n> command, whereas a value of 1 means the C<s>
-command.  The C<$DB::trace>  variable should be set to 1 to simulate
-having typed the C<t> command.
-
-Another way to debug compile-time code is to start the debugger, set a
-breakpoint on the I<load> of some module:
-
-    DB<7> b load f:/perllib/lib/Carp.pm
-  Will stop on load of `f:/perllib/lib/Carp.pm'.
-
-and then restart the debugger using the C<R> command (if possible).  One can use C<b
-compile subname> for the same purpose.
-
-=head2 Debugger Customization
-
-The debugger probably contains enough configuration hooks that you
-won't ever have to modify it yourself.  You may change the behaviour
-of debugger from within the debugger using its C<o> command, from
-the command line via the C<PERLDB_OPTS> environment variable, and
-from customization files.
-
-You can do some customization by setting up a F<.perldb> file, which
-contains initialization code.  For instance, you could make aliases
-like these (the last one is one people expect to be there):
-
-    $DB::alias{'len'}  = 's/^len(.*)/p length($1)/';
-    $DB::alias{'stop'} = 's/^stop (at|in)/b/';
-    $DB::alias{'ps'}   = 's/^ps\b/p scalar /';
-    $DB::alias{'quit'} = 's/^quit(\s*)/exit/';
-
-You can change options from F<.perldb> by using calls like this one;
-
-    parse_options("NonStop=1 LineInfo=db.out AutoTrace=1 frame=2");
-
-The code is executed in the package C<DB>.  Note that F<.perldb> is
-processed before processing C<PERLDB_OPTS>.  If F<.perldb> defines the
-subroutine C<afterinit>, that function is called after debugger
-initialization ends.  F<.perldb> may be contained in the current
-directory, or in the home directory.  Because this file is sourced
-in by Perl and may contain arbitrary commands, for security reasons,
-it must be owned by the superuser or the current user, and writable
-by no one but its owner.
-
-You can mock TTY input to debugger by adding arbitrary commands to
-@DB::typeahead. For example, your F<.perldb> file might contain:
-
-    sub afterinit { push @DB::typeahead, "b 4", "b 6"; }
-
-Which would attempt to set breakpoints on lines 4 and 6 immediately
-after debugger initialization. Note that @DB::typeahead is not a supported
-interface and is subject to change in future releases.
-
-If you want to modify the debugger, copy F<perl5db.pl> from the
-Perl library to another name and hack it to your heart's content.
-You'll then want to set your C<PERL5DB> environment variable to say
-something like this:
-
-    BEGIN { require "myperl5db.pl" }
-
-As a last resort, you could also use C<PERL5DB> to customize the debugger
-by directly setting internal variables or calling debugger functions.
-
-Note that any variables and functions that are not documented in
-this document (or in L<perldebguts>) are considered for internal
-use only, and as such are subject to change without notice.
-
-=head2 Readline Support / History in the debugger
-
-As shipped, the only command-line history supplied is a simplistic one
-that checks for leading exclamation points.  However, if you install
-the Term::ReadKey and Term::ReadLine modules from CPAN (such as
-Term::ReadLine::Gnu, Term::ReadLine::Perl, ...) you will
-have full editing capabilities much like GNU I<readline>(3) provides.
-Look for these in the F<modules/by-module/Term> directory on CPAN.
-These do not support normal B<vi> command-line editing, however.
-
-A rudimentary command-line completion is also available.
-Unfortunately, the names of lexical variables are not available for
-completion.
-
-Without Readline support you may see the symbols "^[[A", "^[[C", "^[[B",
-"^[[D"", "^H", ... when using the arrow keys and/or the backspace key.
-
-=head2 Editor Support for Debugging
-
-If you have the FSF's version of B<emacs> installed on your system,
-it can interact with the Perl debugger to provide an integrated
-software development environment reminiscent of its interactions
-with C debuggers.
-
-Perl comes with a start file for making B<emacs> act like a
-syntax-directed editor that understands (some of) Perl's syntax.
-Look in the I<emacs> directory of the Perl source distribution.
-
-A similar setup by Tom Christiansen for interacting with any
-vendor-shipped B<vi> and the X11 window system is also available.
-This works similarly to the integrated multiwindow support that
-B<emacs> provides, where the debugger drives the editor.  At the
-time of this writing, however, that tool's eventual location in the
-Perl distribution was uncertain.
-
-Users of B<vi> should also look into B<vim> and B<gvim>, the mousey
-and windy version, for coloring of Perl keywords.
-
-Note that only perl can truly parse Perl, so all such CASE tools
-fall somewhat short of the mark, especially if you don't program
-your Perl as a C programmer might.
-
-=head2 The Perl Profiler
-X<profile> X<profiling> X<profiler>
-
-If you wish to supply an alternative debugger for Perl to run, just
-invoke your script with a colon and a package argument given to the
-B<-d> flag.  The most popular alternative debuggers for Perl is the
-Perl profiler.  Devel::DProf is included with the standard Perl
-distribution.  To profile your Perl program in the file F<mycode.pl>,
-just type:
-
-    $ perl -d:DProf mycode.pl
-
-When the script terminates the profiler will dump the profile
-information to a file called F<tmon.out>.  A tool like B<dprofpp>,
-also supplied with the standard Perl distribution, can be used to
-interpret the information in that profile.  More powerful profilers,
-such as C<Devel::NYTProf> are available from the CPAN.
-
-=head1 Debugging regular expressions
-X<regular expression, debugging>
-X<regex, debugging> X<regexp, debugging>
-
-C<use re 'debug'> enables you to see the gory details of how the Perl
-regular expression engine works. In order to understand this typically
-voluminous output, one must not only have some idea about how regular
-expression matching works in general, but also know how Perl's regular
-expressions are internally compiled into an automaton. These matters
-are explored in some detail in
-L<perldebguts/"Debugging regular expressions">.
-
-=head1 Debugging memory usage
-X<memory usage>
-
-Perl contains internal support for reporting its own memory usage,
-but this is a fairly advanced concept that requires some understanding
-of how memory allocation works.
-See L<perldebguts/"Debugging Perl memory usage"> for the details.
-
-=head1 SEE ALSO
-
-You did try the B<-w> switch, didn't you?
-
-L<perldebtut>,
-L<perldebguts>,
-L<re>,
-L<DB>,
-L<Devel::DProf>,
-L<dprofpp>,
-L<Dumpvalue>,
-and
-L<perlrun>.
-
-When debugging a script that uses #! and is thus normally found in
-$PATH, the -S option causes perl to search $PATH for it, so you don't
-have to type the path or C<which $scriptname>.
-
-  $ perl -Sd foo.pl
-
-=head1 BUGS
-
-You cannot get stack frame information or in any fashion debug functions
-that were not compiled by Perl, such as those from C or C++ extensions.
-
-If you alter your @_ arguments in a subroutine (such as with C<shift>
-or C<pop>), the stack backtrace will not show the original values.
-
-The debugger does not currently work in conjunction with the B<-W>
-command-line switch, because it itself is not free of warnings.
-
-If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
-from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
-handler, then you won't be able to CTRL-C your way back to the debugger,
-because the debugger's own C<$SIG{INT}> handler doesn't understand that
-it needs to raise an exception to longjmp(3) out of slow syscalls.