#名稱

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 將在下一陳述停止，則為 true。
#$DB::signal: 訊號標記。如果偵測到訊號，將設定為 true 值。客戶端可以檢查此標記以中止耗時的作業。
#$DB::trace: 如果 API 正在追蹤子常式呼叫，則此標記設定為 true。
#@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 gsar@activestate.com

此程式碼大量改編自 perl5db.pl 的早期版本，該版本歸功於 Larry Wall 和 Perl Porters。

目錄

#名稱

#語法

#說明

#全域變數

#API 方法

#用戶端回呼方法

#BUGS

#AUTHOR