DB (Perl in a Nutshell, 2nd Edition)

8.51. DB

$DB_HASH: Stores key/data pairs in data files; equivalent to other hashing packages such as DBM, NDBM, ODBM, GDBM, and SDBM.
$DB::sub: Name of current executing subroutine.
%DB::sub: The keys of this hash are the names of all the known subroutines. Each value is an encoded string that has the sprintf format ("%s:%d-%d", filename, fromline, toline).
$DB::single: Single-step flag. Will be true if the API will stop at the next statement.
$DB::signal: Signal flag. Will be true if a signal was caught.
$DB::trace: This flag is set to true if the API is tracing through subroutine calls.
@DB::args: Contains the arguments of current subroutine, or the @ARGV array if in the toplevel context.
@DB::dbline: List of lines in currently loaded file.
%DB::dbline: Actions in current file (keys are line numbers). The values are strings that have the sprintf format ("%s\000%s", breakcondition, actioncode).
$DB::package: Package namespace of currently executing code.
$DB::filename: Currently loaded filename.
$DB::subname: Fully qualified name of currently executing subroutine.
$DB::lineno: Line number that will be executed next.

8.51.1. API Methods

The following are methods in the DB base class. A client must access these methods by inheritance, since the API keeps track of clients through the inheritance mechanism.

CLIENT->register( ): Registers a client object/package
CLIENT->evalcode(STRING): eval s STRING in executing code context
CLIENT->skippkg('Skip::Me'): Asks DB not to stop in these packages
CLIENT->run( ): Runs some more (until a breakpt is reached)
CLIENT->step( ): Single step
CLIENT->next( ): Steps over
CLIENT->done( ): Deregisters from the debugging API

8.51.2. Client Callback Methods

The following "virtual" methods are called by the API at appropriate points. The API provides only empty versions of these methods by default, but they can be defined by the client as needed.

CLIENT->init( ): Called after debug API initializes itself.
CLIENT->prestop([STRING]): Usually inherited from DB package. If no arguments are passed, returns the prestop action string.
CLIENT->stop( ): Called when execution stops, with the filename and line number as arguments.
CLIENT->idle( ): Called while stopped, e.g., in a client event loop.
CLIENT->poststop([STRING]): Usually inherited from DB package. If no arguments are passed, returns the poststop action string.
CLIENT->evalcode(STRING): Usually inherited from DB package. Asks for a STRING to be eval ed in executing code context.
CLIENT->cleanup( ): Called just before exit.
CLIENT->output(LIST): Called when API must show a message (warnings, errors etc.).