An Introduction to the Perl Debugger

• s - single step
• n - steps carefully to avoid falling into a sub
• v - view some code around the current line
• c - continue processing until a break of some sort
• r - continue running until you do a return from the current sub
• x - displays value of variables (including arrays & hashes)
• b - sets a break point (uses line number or sub name)
• w - sets a watch expression
• T - displays a stack back trace
• L - list all the breaks
• B * - delete all breakpoints
• W * - delete all watch expressions
• R - restart

• m - lists all of an object's available methods

#!/usr/bin/perl -w

# ~/bin/contrived_perldb_demo         Fri Oct 20 19:02:56 2000

# Expected behavior: the variable "positive_guy" will
#   (1) increase all the time.
#   (2) will always be positive.
# (But there are bugs, and we'll use breakpoints and
# watchexpressions to track them down.)

use strict;
use vars qw($positive_guy $count $real_negative);

$positive_guy = 1; $count = 0;

while($count < 200) {
   $count++;
   $positive_guy++;
   dostuff();
   $positive_guy = jackitup($positive_guy);
   dostuff();
   $real_negative = evil_routine(\$positive_guy);
   dostuff();
}
print "Real negative should be down now: $real_negative\n";

sub dostuff {
   # doesn't really do much of anything
   print "The count is $count, and positive_guy is $positive_guy\n";
   1;
}

sub jackitup {
   my $n = shift;
   my $factor = 2;
   $n = $n/$factor;  # increase number by $factor
   return $n;
}

sub evil_routine {
   # sends $positive_guy negative, eventually
   my $pgr = shift;
   if ($count>100) {
      ${$pgr} = -100;
   }
   return ${$pgr};
}

1. increase all the time.
2. will always be positive.

The count is 1, and positive_guy is 2
The count is 1, and positive_guy is 1
The count is 1, and positive_guy is 1
The count is 2, and positive_guy is 2
The count is 2, and positive_guy is 1
The count is 2, and positive_guy is 1
The count is 3, and positive_guy is 2
The count is 3, and positive_guy is 1
The count is 3, and positive_guy is 1
The count is 4, and positive_guy is 2
The count is 4, and positive_guy is 1

The count is 100, and positive_guy is 1
The count is 100, and positive_guy is 1
The count is 101, and positive_guy is 2
The count is 101, and positive_guy is 1
The count is 101, and positive_guy is -100
The count is 102, and positive_guy is -99
The count is 102, and positive_guy is -49.5
The count is 102, and positive_guy is -100
The count is 103, and positive_guy is -99
The count is 103, and positive_guy is -49.5
The count is 103, and positive_guy is -100
The count is 104, and positive_guy is -99
The count is 104, and positive_guy is -49.5

    perl -d ~/bin/contrived_perldb_demo

• s - single step
• n - steps carefully to avoid falling into a sub
• c - continue processing until a break of some sort
• r - continue running until you do a return from the current sub
• w - shows a "window" of code around the current line
• b - sets a break point (uses line number *or* sub name)
• x - displays value of variables (*including* arrays & hashes)
• W - sets a watch expression
• T - displays a stack back trace
• L - list all the breaks
• D - delete all the breaks
• R - restart

perl -d ~/bin/contrived_perldb_demo

Loading DB routines from perl5db.pl version 1.0402
Emacs support available.

Enter h or `h h' for help.

main::(/home/doom/bin/contrived_perldb_demo:14):
14:     $positive_guy = 1; $count = 0;

  DB<1> w
11:     use strict;
12:     use vars qw($positive_guy $count $real_negative);
13
14==>   $positive_guy = 1; $count = 0;
15
16:     while($count < 200) {
17:        $count++;
18:        $positive_guy++;
19:        dostuff();
20:        $positive_guy = jackitup($positive_guy);
  DB<1>

  DB<1> s
main::(/home/doom/bin/contrived_perldb_demo:14):
14:     $positive_guy = 1; $count = 0;
  DB<1> s
main::(/home/doom/bin/contrived_perldb_demo:16):
16:     while($count < 200) {
  DB<1> s
main::(/home/doom/bin/contrived_perldb_demo:17):
17:        $count++;
  DB<1> s
main::(/home/doom/bin/contrived_perldb_demo:18):
18:        $positive_guy++;
  DB<1>

Run perldb (like this): perl ~/bin/contrived_perldb_demo

Starting emacs.

Typing emacs in a terminal window usually works.

There's a sample .emacs file in Appendix 1 below that you might like to try putting in your home directory ("C:\" under NT, as I remember it).

For VI addicts

If you're already familiar with the vi command set, you might like to ease the transition to emacs by doing a Alt x viper. Viper mode changes a lot of the key bindings to make emacs a little more vi-like. (Haven't played with this a lot, myself, so I can't vouch for it personally.)

Opening a file

Cntrl x d this runs "dired" the directory editor. Use this to get a listing of your working directory.

cursor (or mouse?) down to the file you're interested in. Doing a <RET> will open it. (Note, doing a <RET> on a directory takes you down into that directory.)

Running the debugger

Alt x perldb

perl code_to_be_debugged.pl

Note: debugger commands (discussed above) work in this window. A full list can be obtained with the debugger command h.

Scrolling a window.

"Page Down" and Cntrl v are equivalent.

"Page Up" and Alt v are equivalent.

Alt Cntrl v is useful for doing a "page down" in the other tiled window.

Alt Cntrl Shift v (now, don't laugh) is useful for doing a "page up" in the other tiled window.

Switching to another emacs sub-window.

Cntrl x o rotates among the open tiled emacs windows.

Clicking with a mouse pointer seems to work as well.

Text searches

Cntrl S takes you into interactive/iterative search feature. Type what you're looking for and it tries to jump you there... A <RET> (among other things) will terminate the search.

Getting out of mistakes

Cntrl G is the emacs break character. Hammering on the Cntrl G key will typically get you out of any crazy mode.

Cntrl x k will kill the current buffer. Sometimes I find it helpful to kill the debugger window completely so that I know I'm starting from scratch.

Insert mode

In emacs, you're always (almost) in insert mode. Just start typing.

If you're stuck in the many odd modes of this "non-modal" editor, try a bunch of control-Gs. You could also try hitting the INS key.

Saving a file

You can save the active titled window with a Cntrl x Cntrl s

You can save all open buffers with a Cntrl x s (note the subtle difference).

Finding out more.

Alt x help <RET> t gets you into an emacs tutorial

Alt x help <RET> i m emacs <RET> should get you to the emacs info nodes. If you don't know much about "info" just keep hitting the space bar. Alternately, you can read about info: Alt x help <RET> i m info <RET>.

Hint: if you don't know how to navigate from anywhere but the top, you can just kill the buffer (Cntrl x k) and start over to get back to the top.

     books                  quotes                       commoners

   |------------|         |-------------|              |------------|
   | title      | <-----> | title       |   /--------> | username   |
   | authors    |         | quotation   |   |   ^      | password   |
   | user_added | ----\   | page_number |   |   |      | email      |
   | when_added |    |    | chapter     |   |   |      | user_hash  |
   | [...]      |    |    | user_added  | --/   |      | [...]      |
   |            |    |    | when_added  |       |      |            |
   |            |    |    | [...]       |       |      |            |
   |            |    |    |             |       |      |            |
   |------------|    |    |-------------|       |      |------------|
                     |                          |
                     |                          |
                     \--------------------------/

sub but_welcome {

   # First: select a quotation randomly.
   my $sth = $dbh->prepare("select max(index) from quotations");
   $sth->execute();
   my @row = $sth->fetchrow_array;

   # The maximum index value for the quotations table:
   my $maxindy = $row[0];
   my $pick;

   # Select record randomly, make sure it's valid, if not, pick again:

   $pick = int( rand($maxindy) + 1 );  # random pick of number
                                       # from 1 to maxindy:

   $sth = $dbh->prepare("select $q_fields from $qtab where index=$pick");
   $sth->execute();

   my $hr;
   until ($hr = $sth->fetchrow_hashref) { # Read of quotation
                                          # with index = $pick failed.

      $pick = int( rand($maxindy) + 1 );  # random pick of a number
                                          # from 1 to maxindy:

      $sth = $dbh->prepare("select $q_fields from $qtab where index=$pick");
      $sth->execute();
   };

   %rec = (%rec, %{$hr});

   # And now, do the books look-up
   # (isn't this braindead? why not do it all in one SQL statement?)

   my $statement = "select $b_fields from $btab where title='$rec{title}'";
   my $sth_b = $dbh->prepare($statement);
   $sth_b->execute();

   # Add the newly read parameters to the existing values in %rec (if any):
   %rec = (%rec, %{$sth_b->fetchrow_hashref});

   $author = &nameswap($rec{'authors'});
   $translator = &nameswap($rec{'translator'});

    &form_welcome;
}

sub but_welcome {

   # First: select a quotation randomly.
   my $sth = $dbh->prepare("select max(index) from quotations");
   $sth->execute();
   my @row = $sth->fetchrow_array;

   # The maximum index value for the quotations table:
   my $maxindy = $row[0];
   my $pick;

   # Select record randomly, make sure it's valid, if not, pick again:

   my ($hr, $sql);
   do {
      $pick = int( rand($maxindy) + 1 );  # random pick of a number
                                          # from 1 to maxindy:
      # Doing query something like:
      # select * from quotations, books where
      #   index=262 and books.title = quotations.title;

      $sql = "select $q_fields, $b_fields from $qtab, $btab "
             . "where $qtab.index=$pick";
      $sth = $dbh->prepare($sql);
      $sth->execute();

   } until ($hr = $sth->fetchrow_hashref) ;

   # Add the newly read parameters to the existing values in %rec (if any):
   %rec = (%rec, %{$hr});

   $author = &nameswap($rec{'authors'});
   $translator = &nameswap($rec{'translator'});

   &form_welcome;
}

sub but_welcome {
   # First: select a quotation randomly.
   my $sth = $dbh->prepare("select max(index) from quotations");
   $sth->execute();
   my @row = $sth->fetchrow_array;

   # The maximum index value for the quotations table:
   my $maxindy = $row[0];
   my $pick;

   # Select record randomly, make sure it's valid, if not, pick again:

   my ($hr, $sql);
   do {
      $pick = int( rand($maxindy) + 1 );  # random pick of a number
                                          # from 1 to maxindy:

      # Doing query something like:
      # select * from quotations, books where
      #   index=262 and books.title = quotations.title;

      $sql = "select $q_fields, $b_fields from $qtab, $btab "
             . "where $qtab.index=$pick and $qtab.title = $btab.title";
      $sth = $dbh->prepare($sql);
      $sth->execute();

   } until ($hr = $sth->fetchrow_hashref) ;

   # Add the newly read parameters to the existing values in %rec (if any):
   %rec = (%rec, %{$hr});

   $author = &nameswap($rec{'authors'});
   $translator = &nameswap($rec{'translator'});

   &form_welcome;
}

• If you do an s when you wanted an n, you should realize that you can do a r to keep chugging to the end of the routine. Note that when you're using some external modules (which is like, always, since this is perl we're talking about), it's relatively easy to accidentally start single-stepping through someone else's code.
  
  
• In general the the perl debugger is a little finicky about how it's run from inside of emacs:
  
  
• If you're working on a CGI script, you will almost certainly have the taint flag enabled, which will give you a "too late to taint" error when you run perldb on it. -T is required to be in the first group of options fed into perl. You can do a #!/usr/bin/perl -dwT and run the command line debugger, but if you try to run a #!/usr/bin/perl -wT script using the emacs perldb command, you're stuck. The simplest (though not necessarily the most elegant) thing to do is just to manually remove the -T flag first, and restore it when you're done.
  
  
• Also, I have yet to find a way to do something as simple as run the emacs perl debugger on a script with the output piped to a file. You would think that you could just feed perldb something like perl ~/bin/myscript.pl > /tmp/output.txt but that doesn't work (it seems to just ignore the redirect). I typically just let the output show up in the debugging window: this certainly works, though it can be annoying when there's a lot of it.
  
  
• The perl dbugger gets confused sometimes and starts debugging itself. This can be kind of amusing, but isn't usually very productive: just kill it, and try again in a slightly different way until it works as expected.
  
  
• It's tempting to use the capital X command rather than the lowercase x that I've been recommending, because X does a better job of pretty printing. I keep it off of my recommended list because it doesn't handle things like the @_ array right. I also find it confusing to switch between the two, because the syntax is a little different: It's x @array versus X array.
  
  
• A quick glance at the docs gives one the impression that the V command is identical to X, but it isn't at all. I hate the V command myself. It dumps far too much information to the screen. For example, you do not want to accidentally do a V if you've slurped a half megabyte file into a variable.
  
  

;; A simple .emacs file, recommened for the home directories
;; of people experimenting with ESC x perldb
;;    -- Joe Brenner, doom@kzsu.stanford.edu

; A convenient way to jump to a given line number, using control-x L
(global-set-key "\C-xL" 'goto-line)

; RMS is clearly a mix of genius and insanity, and if you
; want an example of the "insanity" part, go no farther than
; the fact that Control-H is the default help command.
; Backspace for help?  Let's try ESC h instead.

; This is courtesy of coleman@twinsun.com (Mike Coleman):
; Fix stupid EMACS problem.
;
(global-set-key "\C-h" 'delete-backward-char)
(global-set-key "\C-?" 'delete-backward-char)
(setq search-delete-char ?\^h)
(define-key esc-map "h" 'help-command)
(define-key esc-map "?" 'help-command)
(define-key esc-map "\C-h" 'backward-kill-word)
(define-key help-map "\M-h" 'help-for-help)
(define-key help-map "\M-?" 'help-for-help)

;; a subshell inside of emacs (ESC x shell) has a lot of
;; silly Control-Ms echoed to it, unless you do this
;; (courtesy of the NT (!) emacs FAQ):

(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m nil t)


;; Turns on syntax coloring for perl code by default.

(add-hook 'perl-mode-hook 'turn-on-font-lock)

use constant DEBUG => 1;  # Turns on debugging statements to error_log (STDERR)
use constant VERSION => "0.95pre";

BEGIN {
   $_ = scalar localtime;
   my $datestamp = "\nRunning program $0 " . VERSION . ": " . $_ . "\n";
   print_debug($datestamp);

   sub print_debug {
      (DEBUG) && print STDERR "$_[0]";
   }
}

my $function = (caller(0))[3]; # courtesy of recipe 10.4, perl cookbook
&print_debug("Running sub $function .\n");

   if (DEBUG) {
       print STDERR "hash from querying the quotations and books tables:\n";
       foreach my $key (keys %rec) {
          print STDERR "Value of rec for key $key is: ";
          ($rec{$key}) && print STDERR "$rec{$key}";
          print STDERR "\n";
       }
    }