view release on metacpan or  search on metacpan

pod/perldebug.pod  view on Meta::CPAN

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 L<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

pod/perldebug.pod  view on Meta::CPAN

of the 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 L<Term::ReadKey> and one of the C<Term::ReadLine::*> modules from CPAN (such as
L<Term::ReadLine::Gnu>, L<Term::ReadLine::Perl>, ...) you will
have full editing capabilities much like those 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, including
lexical variables in the current scope if the L<PadWalker> module
is installed.

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 GNU'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.

Recent versions of Emacs come with a
start file for making B<emacs> act like a
syntax-directed editor that understands (some of) Perl's syntax.
See L<perlfaq3>.

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,
invoke your script with a colon and a package argument given to the
B<-d> flag.  Perl's alternative debuggers include a Perl profiler,
L<Devel::NYTProf>, which is available separately as a CPAN
distribution.  To profile your Perl program in the file F<mycode.pl>,
just type:

    $ perl -d:NYTProf mycode.pl

When the script terminates the profiler will create a database of the
profile information that you can turn into reports using the profiler's
tools. See <perlperf> for details.

=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.