内容

名称
概要
描述
错误
作者

#名称

DB - Perl 调试 API 的编程接口

#概要

package CLIENT;
use DB;
@ISA = qw(DB);

# these (inherited) methods can be called by the client

CLIENT->register()      # register a client package name
CLIENT->done()          # de-register from the debugging API
CLIENT->skippkg('hide::hide')  # ask DB not to stop in this package
CLIENT->cont([WHERE])       # run some more (until BREAK or 
                            # another breakpointt)
CLIENT->step()              # single step
CLIENT->next()              # step over
CLIENT->ret()               # return from current subroutine
CLIENT->backtrace()         # return the call stack description
CLIENT->ready()             # call when client setup is done
CLIENT->trace_toggle()      # toggle subroutine call trace mode
CLIENT->subs([SUBS])        # return subroutine information
CLIENT->files()             # return list of all files known to DB
CLIENT->lines()             # return lines in currently loaded file
CLIENT->loadfile(FILE,LINE) # load a file and let other clients know
CLIENT->lineevents()        # return info on lines with actions
CLIENT->set_break([WHERE],[COND])
CLIENT->set_tbreak([WHERE])
CLIENT->clr_breaks([LIST])
CLIENT->set_action(WHERE,ACTION)
CLIENT->clr_actions([LIST])
CLIENT->evalcode(STRING)  # eval STRING in executing code's context
CLIENT->prestop([STRING]) # execute in code context before stopping
CLIENT->poststop([STRING])# execute in code context before resuming

# These methods will be called at the appropriate times.
# Stub versions provided do nothing.
# None of these can block.

CLIENT->init()          # called when debug API inits itself
CLIENT->stop(FILE,LINE) # when execution stops
CLIENT->idle()          # while stopped (can be a client event loop)
CLIENT->cleanup()       # just before exit
CLIENT->output(LIST)    # called to print any output that
                        # the API must show

#描述

Perl 调试信息不仅经常被调试器使用，而且也经常被需要一些“特殊”信息来正确执行其工作的模块使用，例如分析器。

此模块抽象并提供所有 Perl 内部调试功能的钩子，以便各种 Perl 调试器实现（或想要简单地获取“特权”调试数据的包）都可以从此通用代码的开发中受益。目前被 Swat（perl/Tk GUI 调试器）使用。

请注意，多个“前端”可以同时连接到此调试 API。这旨在促进诸如同时使用命令行和 GUI 进行调试、调试调试器等操作。[听起来不错，但这需要一些严肃的支持 - GSAR]

特别是，此 API 不提供以下功能

数据显示
命令处理
命令别名管理
用户界面（tty 或图形）

这些旨在由此 API 的客户端执行的服务。

此模块试图在 use strict; 方面保持干净，并在启用警告时。

#全局变量

以下“公共”全局名称可供此 API 的客户端读取。请注意，这些应被视为“只读”。

#$DB::sub: 当前执行子例程的名称。
#%DB::sub: 此哈希的键是所有已知子例程的名称。每个值都是一个编码字符串，具有 sprintf(3) 格式 ("%s:%d-%d", filename, fromline, toline)。
#$DB::single: 单步执行标志。如果 API 将在下一条语句处停止，则为真。
#$DB::signal: 信号标志。如果捕获到信号，则设置为真值。客户端可以检查此标志以中止耗时的操作。
#$DB::trace: 如果 API 正在跟踪子例程调用，则此标志设置为真。
#@DB::args: 包含当前子例程的参数，或在顶层上下文中包含 @ARGV 数组。
#@DB::dbline: 当前加载文件中行的列表。
#%DB::dbline: 当前文件中的操作（键是行号）。值是具有 sprintf(3) 格式 ("%s\000%s", breakcondition, actioncode) 的字符串。
#$DB::package: 当前执行代码的包命名空间。
#$DB::filename: 当前加载的文件名。
#$DB::subname: 当前正在执行的子程序的完全限定名称。
#$DB::lineno: 将要执行的下一行的行号。

#API 方法

以下是 DB 基类中的方法。客户端必须通过继承来访问这些方法（*不能*直接调用它们），因为 API 通过继承机制跟踪客户端。

#CLIENT->register(): 注册客户端对象/包
#CLIENT->evalcode(STRING): 在执行代码上下文中评估 STRING
#CLIENT->skippkg('D::hide'): 要求 DB 不要在这些包中停止
#CLIENT->run(): 继续运行（直到遇到断点）
#CLIENT->step(): 单步执行
#CLIENT->next(): 步过
#CLIENT->done(): 从调试 API 中注销

#客户端回调方法

以下“虚拟”方法可以由客户端定义。它们将在适当的时候由 API 调用。请注意，除非另有说明，否则调试 API 仅定义这些方法的空、无功能的默认版本。

#CLIENT->init(): 在调试 API 初始化自身后调用。
#CLIENT->prestop([STRING]): 通常从 DB 包继承。如果没有传递参数，则返回 prestop 操作字符串。
#CLIENT->stop(): 在执行停止时调用（带参数文件、行）。
#CLIENT->idle(): 在停止时调用（可以是客户端事件循环）。
#CLIENT->poststop([STRING]): 通常从 DB 包继承。如果没有传递参数，则返回 poststop 操作字符串。
#CLIENT->evalcode(STRING): 通常从 DB 包继承。要求在执行代码上下文中对 STRING 进行 eval。
#CLIENT->cleanup(): 在退出之前调用。
#CLIENT->output(LIST): 当 API 需要显示消息（警告、错误等）时调用。

#BUGS

此模块定义的接口缺少 perl 调试功能的一些后期添加。因此，此接口应被视为高度实验性，并且可能会发生变化。

#AUTHOR

Gurusamy Sarathy [email protected]

此代码大量改编自 Larry Wall 和 Perl 维护者早期版本的 perl5db.pl。