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. В связи с этим этот интерфейс следует считать экспериментальным и подлежащим изменению.

АВТОР

Gurusamy Sarathy gsar@activestate.com

Этот код сильно адаптирован из ранней версии perl5db.pl, приписываемой Larry Wall и Perl Porters.