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

Этот флаг устанавливается в значение «истина», если 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 в контексте выполняемого кода.

CLIENT->cleanup()

Вызывается непосредственно перед выходом.

CLIENT->output(LIST)

Вызывается, когда API должен отобразить сообщение (предупреждения, ошибки и т. д.).

ОШИБКИ

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

АВТОР

Гурсамый Сарати gsar@activestate.com

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