Stepping Through Your Script

So far, you've read about how to limit the possibility of errors appearing in your programs. If, after using the -w and the strict pragma, you still have a problem, it's time to use the debugger.

What is the debugger? Quite simply, it is an interactive environment that allows you to execute your script's statements one at a time. If necessary, you can display the lines of your script, view or alter variables, and even execute entirely new statements.

You start the debugger by using the -d command-line option. The following line

perl -w -d 08lst08.pl

starts the debugger and loads the script called 08lst08.pl.

If you want to invoke the debugger with no script, you need to perform a small bit of magic, like this

perl -d -e "1;"

to start debugger without any program.

This is a bit of magic because you haven't read about all the different command-line options available for the Perl interpreter (see next Chapter)

The -e option tells Perl to execute a single Perl statement. In this case the statement is 1;, which basically means do nothing. It does, however, stop the interpreter from looking for the name of a script file on the command line.

When the debugger starts, your screen will look something like this:

Loading DB routines from $RCSfile: perl5db.pl,v $$Revision: 4.1

$$Date: 92/08/07 18:24:07 $

Emacs support available.

Enter h for help.

main::(08lst08.pl:3):   my($codeRef);

  DB<1>

This message tells you that the debugger (DB) routines have been loaded. The DB<1> is a prompt that indicates that the debugger is waiting for input. The line number inside the angle brackets is the current execution line. The current execution line is that line that the debugger waits to execute.

One of the features of the debugger is the capability to insert breakpoints into your script. A breakpoint is an instruction that tells the debugger to stop, to display a prompt, and to wait for input. When the debugger first starts, there are no breakpoints defined for your program. See the section "Examples: Using Breakpoints" later in the chapter for more information.

You can use any of the commands listed in below while using the debugger. While some of the commands are demonstrated in the sections that follow the table, you can't hurt anything by experimenting with any or all of the commands on your own.

The Debugger Commands That Control Actions

a ACTION

-- This command tells the debugger to perform ACTION just before the current execution line is executed. Optionally, you can specify a line number. For example, a 10 print("$numFiles"); executes the print statement before line 10 is executed. If line 10 is inside a loop, the action is performed each time through the loop.

A

-- Deletes all actions.LLists all breakpoints and actions.

< ACTION

-- Forces the debugger to execute ACTION each time the debugger prompt is displayed. This command is great if you need to print the value of certain values each time you are prompted by the debugger.

> ACTION

-- Forces the debugger to execute ACTION after every debugger command you issue.

Commands That Involve Breakpoints

b

-- Sets a breakpoint at the current execution line. You can specify a line where the breakpoint should be set. For example, b 35 sets a breakpoint at line 35. You can also create a conditional breakpoint. For example, b 35 $numLines == 0 causes the debugger to stop at line 35 only if $numLines is equal to zero. Watch conditions can also be attached to functions; just use the function name instead of a line number.

d

-- Deletes the breakpoint from the current execution line. If you specify a line number, the breakpoint is deleted from that line.

D

-- Deletes all breakpoints.

L

-- Lists all breakpoints and actions.

Commands That Display Information

l

-- Lets you print out parts of your script. There are several flavors of this command that you can use:

• Using a plain l displays about 10 lines of your script.
• Using l 5+4 displays 4 lines of your script starting with line 5.
• Using l 4-7 displays lines 4 through 7 of your script.
• Using l 34 displays line 34 of your script.
• Using l foo displays roughly the first 10 lines of the foo() function.

L

-- Lists all breakpoints and actions.

p EXPR

-- Prints the result of evaluating EXPR to the display. It is a shorthand way of saying print DB::OUT (EXPR).

S

-- Lists all function names that are defined. The list will include any function defined in modules as well as those in your script.

T

-- Prints a stack trace. A stack trace displays a list of function calls and the line number where the calls were made.

V

-- Lists all variables that are currently defined from all packages and modules that are loaded. A better form of this command is V PACKAGE or V PACKAGE VARLIST where PACKAGE is the name of a loaded package or module, and VARLIST is a currently defined variable in PACKAGE. When specifying variable names, don't use the $, @, or % type specifiers.

w LINE

-- Displays about 10 lines centered around LINE. For example, if you use w 10, lines 7 to 16 might display.

X

-- Lists all variables in the current package. If you have stepped into a function that is in package foo, the variables in package foo are displayed, not those in main. You can also specify exactly which variables to display if needed. When specifying variable names, don't use the $, @, or % type specifiers.

-

-- Displays about 10 lines of your script that are before the current line. For example, if the current display line is 30, this command might display lines 19 to 29.

Commands That Control Execution

s

-- Steps through the lines in your script one at a time. It steps into any user-defined function that is called. While single-stepping is slow, you see exactly how your code is being executed.

N

-- Executes the next statement in your script. Although all function calls are executed, it does not follow the execution path inside a function. This command enables you to move quicker through the execution of your script than simply using the s command.

R

-- Executes the rest of the statements in the current function. The debugger pauses for input on the line following the line that made the function call.

C LINE

-- Executes the rest of the statements in your script unless a breakpoint is found before the script ends. You can optionally use this command to create a temporary break by specifying a line number after the c. Think of this command as continue until LINE.

No Command

-- Pressing the Enter key without specifying a command will make the debugger repeat the last n or s command that was used. This feature makes it a little easier to single-step through your script.

Commands That Work with the Debugger Command History

!

-- Re-executes the previous command. You can also specify the number of the previous command to execute. Use the H command to get a list of the previous commands. If you specify a negative number, like ! -2, the debugger counts backwards from the last executed command.

H

-- Lists all the debugger commands you have issued. Only commands that cause action are saved in the command history. This means that the l and T commands are not saved. You can limit the history viewed by specifying a negative number. For example, H -5 displays the last five commands you have issued.

Miscellaneous Commands

f FILENAME

-- Causes the debugger to switch to FILENAME. The file specified must have already been loaded via the use or require statements. Please note that some of the documentation that accompanies the Perl interpreter may indicate that f is the finish command. It used to be; however, the finish functionality is now accomplished by the r command.

Q

-- Quits the debugger. You can also use the Ctrl+D key sequence under UNIX and the Ctrl+Z key sequence under DOS and Windows.

T

-- Toggles trace mode on and off. Trace mode, when on, displays each script line as it is being executed. I don't recommend this option except for very short programs because the lines are displayed so quickly that you won't be able to read them.

/pattern/

-- Searches for pattern in the currently loaded file. If pattern is found, the current display line is changed to the line where pattern was found.

?pattern?

-- Searches backward for pattern in the currently loaded file. If pattern is found, the current display line is changed to the line where pattern was found.

=

-- Displays any aliases that are currently defined.

COMMAND

-- Any text that is not recognized as an alias or a debugger command is executed as a Perl statement.

As you can see, the debugger has quite a few commands to choose from, and it is very powerful. Most programmers will not need all of the functionality that the debugger has. If you learn to display script lines, to use breakpoints, and to display variables, you'll be well on your way to solving any logic problem that may arise.