DB

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
  • Глобальные переменные
  • Методы API
  • Методы обратного вызова клиента
• ОШИБКИ
• АВТОР

ИМЯ

DB — программный интерфейс к API отладки Perl

СИНОПСИС

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.

Обратите внимание, что несколько «передних концов» могут одновременно подключаться к этому API отладки. Это призвано облегчить одновременную отладку с помощью командной строки и графического интерфейса, отладку отладчиков и т. д. [Звучит неплохо, но это требует серьезной поддержки — 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

Этот флаг устанавливается в значение true, если 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 необходимо отобразить сообщение (предупреждения, ошибки и т. д.).

ОШИБКИ

Интерфейс, определенный этим модулем, отсутствует некоторые последние дополнения к функциональности отладки Perl. Поэтому этот интерфейс следует считать экспериментальным и подвержен изменениям.

АВТОР

Gurusamy Sarathy gsar@activestate.com

Этот код сильно адаптирован из ранней версии perl5db.pl, приписываемой Лэрри Уолу и Perl Портерам.