ptkdb(3)

NAME

Devel::ptkdb - Perl debugger using a Tk GUI

DESCRIPTION

ptkdb is a debugger for perl that uses perlTk for a user
interface.: Features include:

Hot Variable Inspection
Breakpoint Control Panel
Expression List
Subroutine Tree

SYNOPSIS

To debug a script using ptkdb invoke perl like this:
                perl -d:ptkdb myscript.pl

Usage

perl -d:ptkdb myscript.pl

Code Pane

Line Numbers: Line numbers are presented on the left side of the; window. Lines that
have lines through them are not breakable. Lines that; are plain text
are breakable. Clicking on these line numbers will; insert a
breakpoint on that line and change the line number; color to
$ENV{'PTKDB_BRKPT_COLOR'} (Defaults to Red). Clicking; on the number
again will remove the breakpoint. If you disable the; breakpoint with
the controls on the BrkPt notebook page the color; will change to
$ENV{'PTKDB_DISABLEDBRKPT_COLOR'}(Defaults to Green).
Cursor Motion: If you place the cursor over a variable (i.e. $myVar,
@myVar, or %myVar) and pause for a second the debugger
will evaluate the current value of the variable and
pop a balloon up with the evaluated result. This fea_ ture is not available with Tk400.; If Data::Dumper(standard with perl5.00502)is available
it will be used to format the result. If there is an
active selection, the text of that selection will be
evaluated.

Notebook Pane

Exprs: This is a list of expressions that are evaluated each; time the
debugger stops. The results of the expresssion are pre; sented
heirarchically for expression that result in hashes or; lists. Double
clicking on such an expression will cause it to col; lapse; double
clicking again will cause the expression to expand. Ex; pressions are
entered through B<Enter Expr> entry, or by Alt-E when; text is
selected in the code pane.; The B<Quick Expr> entry, will take an expression, eval; uate it, and
replace the entries contents with the result. The re; sult is also
transfered to the 'clipboard' for pasting.
Subs: Displays a list of all the packages invoked with the; script
heirarchially. At the bottom of the heirarchy are the; subroutines
within the packages. Double click on a package to ex; pand
it. Subroutines are listed by their full package names.
BrkPts: Presents a list of the breakpoints current in use. The; pushbutton
allows a breakpoint to be 'disabled' without removing; it. Expressions
can be applied to the breakpoint. If the expression; evaluates to be
'true'(results in a defined value that is not 0) the; debugger will
stop the script. Pressing the 'Goto' button will set; the text pane
to that file and line where the breakpoint is set.; Pressing the
'Delete' button will delete the breakpoint.

Menus

File Menu

About...: Presents a dialog box telling you about the version of
ptkdb. It recovers your OS name, version of perl,
version of Tk, and some other information
Open: Presents a list of files that are part of the invoked
perl script. Selecting a file from this list will pre
sent this file in the text window.
Save Config...: Requires Data::Dumper. Prompts for a filename to save
the configuration to. Saves the breakpoints, expres
sions, eval text and window geometry. If the name
given as the default is used and the script is rein
voked, this configuration will be reloaded automati
cally.

B<NOTE:> You may find this

preferable to using
Restore Config...: Requires Data::Dumper. Prompts for a filename to
restore a configuration saved with the "Save Con
fig..." menu item.
Goto Line...: Prompts for a line number. Pressing the "Okay" but
ton sends the window to the line number entered. item
Find Text...; Prompts for text to search for. Options include for
ward search, backwards search, and regular expression
searching.
Quit: Causes the debugger and the target script to exit.
Control Menu
Run The debugger allows the script to run to the next: breakpoint or until the script exits. item Run To
Here; Runs the debugger until it comes to wherever the
insertion cursor in text window is placed.
Set Breakpoint: Sets a breakpoint on the line at the insertion cur
sor. item Clear Breakpoint; Remove a breakpoint on the at the insertion cursor.
Clear All Breakpoints: Removes all current breakpoints
Step Over: Causes the debugger to step over the next line. If
the line is a subroutine call it steps over the call,
stopping when the subroutine returns.
Step In: Causes the debugger to step into the next line. If
the line is a subroutine call it steps into the sub
routine, stopping at the first executable line within
the subroutine.
Return: Runs the script until it returns from the currently
executing subroutine.
Restart: Saves the breakpoints and expressions in a temporary
file and restarts the script from the beginning. CAU
TION: This feature will not work properly with debug
ging of CGI Scripts.
Stop On Warning: When "-w" is enabled the debugger will stop when warn
ings such as, "Use of uninitialized value at
undef_warn.pl line N" are encountered. The debugger
will stop on the NEXT line of execution since the
error can't be detected until the current line has
executed.; This feature can be turned on at startup by adding:; $DB::ptkdb::stop_on_warning = 1 ;; to a .ptkdbrc file
Data Menu
Enter Expression: When an expression is entered in the "Enter Expres
sion:" text box, selecting this item will enter the
expression into the expression list. Each time the
debugger stops this expression will be evaluated and
its result updated in the list window.
Delete Expression: Deletes the highlighted expression in the expression; window.
Delete All Expressions: Delete all expressions in the expression window.
Expression Eval Window: Pops up a two pane window. Expressions of virtually
unlimitted length can be entered in the top pane.
Pressing the 'Eval' button will cause the expression
to be evaluated and its placed in the lower pane. If
Data::Dumper is available it will be used to format
the resulting text. Undo is enabled for the text in
the upper pane.; HINT: You can enter multiple expressions by sepa
rating them with commas.
Use Data::Dumper for Eval Window: Enables or disables the use of Data::Dumper for for
matting the results of expressions in the Eval win
dow.
Stack Menu
Maintains a list of the current subroutine stack each time the debugger stops. Selecting an item from this menu will set the text in the code window to that particular subour tine entry point.
Bookmarks Menu
Maintains a list of bookmarks. The booksmarks are saved in ~/.ptkdb_bookmarks
Add Bookmark: Adds a bookmark to the bookmark list.

Options

Here is a list of the current active XResources options. Several of these can be overridden with environmental variables. Resources can be added to .Xresources or .Xde faults depending on your X configuration. To enable these resources you must either restart your X server or use the xrdb -override resFile command. xfontsel can be used to select fonts.: /*
* Perl Tk Debugger XResources.
* Note... These resources are subject to; change.
*
* Use 'xfontsel' to select different; fonts.
*
* Append these resource to ~/.Xdefaults; ~/.Xresources
* and use xrdb -override ~/.Xdefaults; ~/.Xresources
* to activate them.
*/
/* Set Value to se to place scrollbars on; the right side of windows
CAUTION: extra whitespace at the end of the
line is causing: failures with Tk800.011.; sw -> puts scrollbars on left, se puts; scrollars on the right; */
ptkdb*scrollbars: sw
/* controls where the code pane is orient; ed, down the left side, or across the top */
/* values can be set to left, right, top,; bottom */
ptkdb*codeside: left; /*
* Background color for the balloon
* CAUTION: For certain versions of Tk; trailing
* characters after the color produces an; error
*/
ptkdb.frame2.frame1.rotext.balloon.back; ground: green
ptkdb.frame2.frame1.rotext.balloon.font:; fixed; /* Hot Variable Balloon Font */; ptkdb.frame*font: fixed; /* Menu Bar */
ptkdb.frame.menubutton.font: fixed; /* File menu */
ptkdb.frame2.frame1.rotext.font: fixed; /* Code Pane */
ptkdb.notebook.datapage.frame1.hlist.font:; fixed /* Expression Notebook Page */; ptkdb.notebook.subspage*font: fixed; /* Subroutine Notebook Page */
ptkdb.notebook.brkptspage*entry.font:; fixed /* Delete Breakpoint Buttons */
ptkdb.notebook.brkptspage*button.font:; fixed /* Breakpoint Expression Entries */
ptkdb.notebook.brkptspage*button1.font:; fixed /* Breakpoint Expression Entries */
ptkdb.notebook.brkptspage*checkbut; ton.font: fixed /* Breakpoint Checkbuttons */
ptkdb.notebook.brkptspage*label.font:; fixed /* Breakpoint Checkbuttons */; ptkdb.toplevel.frame.textundo.font: fixed; /* Eval Expression Entry Window */
ptkdb.toplevel.frame1.text.font: fixed; /* Eval Expression Results Window */
ptkdb.toplevel.button.font: fixed; /* "Eval..." Button */
ptkdb.toplevel.button1.font: fixed; /* "Clear Eval" Button */
ptkdb.toplevel.button2.font: fixed; /* "Clear Results" Button */
ptkdb.toplevel.button3.font: fixed; /* "Clear Dismiss" Button */; /*
* Background color for where the debugger; has stopped
*/
ptkdb*stopcolor: blue; /*
* Background color for set breakpoints
*/
ptkdb*breaktagcolor*background: yellow
ptkdb*disabledbreaktagcolor*background:; white
/*
* Font for where the debugger has stopped
*/
ptkdb*stopfont: -*-fixed; bold-*-*-*-*-*-*-*-*-*-*-*; /*
* Background color for the search tag
*/
ptkdb*searchtagcolor: green

Environmental Variables

PTKDB_BRKPT_COLOR: Sets the background color of a set breakpoint
PTKDB_DISABLEDBRKPT_COLOR: Sets the background color of a disabled breakpoint
PTKDB_CODE_FONT: Sets the font of the Text in the code pane.
PTKDB_CODE_SIDE: Sets which side the code pane is packed onto.
Defaults to 'left'. Can be set to 'left', 'right',
'top', 'bottom'.; Overrides the Xresource ptkdb*codeside: side.
PTKDB_EXPRESSION_FONT: Sets the font used in the expression notebook page.
PTKDB_EVAL_FONT: Sets the font used in the Expression Eval Window
PTKDB_EVAL_DUMP_INDENT: Sets the value used for Data::Dumper 'indent' set; ting. See man Data::Dumper
PTKDB_SCROLLBARS_ONRIGHT: A non-zero value Sets the scrollbars of all windows; to be on the
right side of the window. Useful for Windows users; using ptkdb in an
XWindows environment.
PTKDB_LINENUMBER_FORMAT: Sets the format of line numbers on the left side of
the window. Default value is %05d. useful if you
have a script that contains more than 99999 lines.
PTKDB_DISPLAY: Sets the X display that the ptkdb window will appear
on when invoked. Useful for debugging CGI scripts on
remote systems.
PTKDB_BOOKMARKS_PATH: Sets the path of the bookmarks file. Default is
$ENV{'HOME'}/.ptkdb_bookmarks
PTKDB_STOP_TAG_COLOR: Sets the color that highlights the line where the
debugger is stopped

FILES

If this file is present in ~/ or in the directory where
perl is invoked the file will be read and executed as a
perl script before the debugger makes its initial stop at
startup. There are several 'api' calls that can be used
with such scripts. There is an internal variable
$DB::no_stop_at_start that may be set to non-zero to pre
vent the debugger from stopping at the first line of the
script. This is useful for debugging CGI scripts.

There is a system ptkdbrc file in $PRE
FIX/lib/perl5/$VERS/Devel/ptkdbrc

brkpt($fname, @lines): Sets breakspoints on the list of lines in $fname. A
warning message is generated if a line is not break
able.
condbrkpt($fname, @($line, $expr) ): Sets conditional breakpoints in $fname on pairs of
$line and $expr. A warning message is generated if a
line is not breakable. NOTE: the validity of the
expression will not be determined until execution of
that particular line.
brkonsub(@names): Sets a breakpoint on each subroutine name listed. A
warning message is generated if a subroutine does not
exist. NOTE: for a script with no other packages the
default package is "main::" and the subroutines would
be "main::mySubs".
brkonsub_regex(@regExprs): Uses the list of @regExprs as a list of regular
expressions to set breakpoints. Sets breakpoints on
every subroutine that matches any of the listed regu
lar expressions.
textTagConfigure(tag, ?option?, ?value?): Allows the user to format the text in the code window.
The option value pairs are the same values as the
option for the tagConfigure method documented in
Tk::Text. Currently the following tags are in effect:

'code'

Format for code in the text pane
'stoppt'

Format applied to the line where the debugger is currently

stopped
'breakableLine' For

mat applied to line numbers where the code is 'breakable'
'nonbreakableLine' Format ap

plied to line numbers where the code is no breakable
'breaksetLine' For

mat applied to line numbers were a breakpoint is set
'breakdisabledLine' Format ap

plied to line numbers were a disabled breakpoint is set
'search_tag'

Format applied to text when located by a search.
Example:
# # Turns off the overstrike on lines that you can't
set a breakpoint on # and makes the text color yellow. #: textTagConfigure('nonbreakableLine',; -overstrike => 0, -foreground => "yellow") ;
add_exprs(@exprList): Add a list of expressions to the 'Exprs' window. NOTE:
use the single quote character � to prevent the
expression from being "evaluated" in the string con
text.

Example:

#
# Adds the $_ and @_ expressions to

the active list
#

add_exprs('$_', '@_') ;

NOTES

Debugging Other perlTk Applications

ptkdb can be used to debug other perlTk applications if
some cautions are observed. Basically, do not click the
mouse in the application's window(s) when you've entered
the debugger and do not click in the debugger's window(s)
while the application is running. Doing either one is not
necessarily fatal, but it can confuse things that are
going on and produce unexpected results.

Be aware that most perlTk applications have a central
event loop. User actions, such as mouse clicks, key
presses, window exposures, etc will generate 'events' that
the script will process. When a perlTk application is run
ning, its 'MainLoop' call will accept these events and
then dispatch them to appropriate callbacks associated
with the appropriate widgets.

Ptkdb has its own event loop that runs whenever you've
stopped at a breakpoint and entered the debugger. However,
it can accept events that are generated by other perlTk
windows and dispatch their callbacks. The problem here is
that the application is supposed to be 'stopped', and log
ically the application should not be able to process
events.

A future version of ptkdb will have an extension that will
'filter' events so that application events are not pro
cessed while the debugger is active, and debugger events
will not be processed while the target script is active.

Debugging CGI Scripts

One advantage of ptkdb over the builtin debugger(-d) is
that it can be used to debug CGI perl scripts as they run
on a web server. Be sure that that your web server's perl
instalation includes Tk.

Change your: #! /usr/local/bin/perl
to: #! /usr/local/bin/perl -d:ptkdb
TIP: You can debug scripts remotely if you're using a unix based Xserver and where you are authoring the script has an Xserver. The Xserver can be another unix workstation, a Macintosh or Win32 platform with an appropriate XWindows package. In your script insert the following BEGIN sub routine:: sub BEGIN {
$ENV{'DISPLAY'} = "myHostname:0.0"

;; }
Be sure that your web server has permission to open win dows on your Xserver (see the xhost manpage).
Access your web page with your browswer and 'submit' the script as normal. The ptkdb window should appear on myHostname's monitor. At this point you can start debug ging your script. Be aware that your browser may timeout waiting for the script to run.
To expedite debugging you may want to setup your break points in advance with a .ptkdbrc file and use the $DB::no_stop_at_start variable. NOTE: for debugging web scripts you may have to have the .ptkdbrc file installed in the server account's home directory (~www) or whatever username your webserver is running under. Also try installing a .ptkdbrc file in the same directory as the target script.

KNOWN PROBLEMS

Breakpoint Controls: If the size of the right hand pane is too small the
breakpoint controls are not visible. The break
points are still there, the window may have to be
enlarged in order for them to be visible.
Balloons and Tk400: The Balloons in Tk400 will not work with ptkdb. All
other functions are supported, but the Balloons
require Tk800 or higher.

AUTHOR

Andrew E. Page, aep@world.std.com

ACKNOWLEDGEMENTS

Matthew Persico For suggestions, and beta test
ing.

docs.sk

comprehensive documentation repository

Most Viewed