B

СОДЕРЖАНИЕ

ИМЯ
СИНТАКСИС
ОПИСАНИЕ
ОБЗОР
Функции-утилиты
ОБЗОР КЛАССОВ
АВТОР

ИМЯ

B — Модуль Perl-компилятора

СИНТАКСИС

use B;

ОПИСАНИЕ

Модуль B предоставляет классы, которые позволяют Perl-программе заглянуть в свои внутренности. Это модуль, используемый для реализации «бекендов» Perl-компилятора. Использование компилятора не требует знания этого модуля: обратитесь к модулю O для пользовательской части. Модуль B полезен тем, кто хочет написать новые бекенды компилятора. Данная документация предполагает, что читатель хорошо знаком с внутренностями Perl, включая такие понятия, как SV, OP и внутреннюю таблицу символов и синтаксическое дерево программы.

ОБЗОР

Модуль B содержит набор вспомогательных функций для запроса текущего состояния Perl-интерпретатора; как правило, эти функции возвращают объекты из классов B::SV и B::OP, или их производных классов. Эти классы в свою очередь определяют методы для запроса у полученных объектов их внутреннего состояния.

Функции-утилиты

Модуль B экспортирует различные функции: некоторые являются простыми вспомогательными функциями, другие предоставляют Perl-программе способ получить начальную «ручку» к внутреннему объекту.

Функции, возвращающие `B::SV`, `B::AV`, `B::HV`, и `B::CV` объекты

Для описания иерархии классов этих объектов и методов, которые могут быть вызваны на них, см. ниже, "ОБЗОР КЛАССОВ" и "КЛАССЫ, СВЯЗАННЫЕ С SV".

sv_undef

Возвращает объект SV, соответствующий C-переменной sv_undef.

sv_yes

Возвращает объект SV, соответствующий C-переменной sv_yes.

sv_no

Возвращает объект SV, соответствующий C-переменной sv_no.

svref_2object(SVREF)

Принимает ссылку на любое Perl-значение и преобразует значение, на которое ссылается, в объект соответствующего класса, производного от B::OP или B::SV. Помимо функций, таких как main_root, это основной способ получить начальную «ручку» к внутренней структуре данных perl, к которой затем можно обратиться с помощью других методов доступа.

Возвращаемый объект будет действителен только до тех пор, пока существующие OP и SV не будут освобождены. Не пытайтесь использовать объект после того, как лежащие в основе структуры будут освобождены.

amagic_generation

Возвращает объект SV, соответствующий C-переменной amagic_generation. С версии Perl 5.18, это просто псевдоним для PL_na, поэтому его значение не имеет смысла.

init_av

Возвращает объект AV (т.е. класса B::AV), представляющий блоки INIT.

check_av

Возвращает объект AV (т.е. класса B::AV), представляющий блоки CHECK.

unitcheck_av

Возвращает объект AV (т.е. класса B::AV), представляющий блоки UNITCHECK.

begin_av

Возвращает объект AV (т.е. класса B::AV), представляющий блоки BEGIN.

end_av

Возвращает объект AV (т.е. класса B::AV), представляющий блоки END.

comppadlist

Возвращает объект PADLIST (т.е. класса B::PADLIST) глобального comppadlist. В Perl 5.16 и более ранних версиях возвращается объект AV (класса B::AV).

regex_padav

Только когда perl был скомпилирован с ithreads.

main_cv

Возвращает (имитируемый) CV, соответствующий основной части Perl-программы.

Функции для проверки таблицы символов

walksymtable(SYMREF, METHOD, RECURSE, PREFIX)

Обходит таблицу символов, начиная с SYMREF, и вызывает METHOD для каждого посещенного символа (объект B::GV). При достижении символов пакета (например, "Foo::") вызывает RECURSE, передавая имя символа, и рекурсивно заходит в пакет только если подпрограмма вернет true.

PREFIX — имя SYMREF, который вы обходите.

Например:

# Walk CGI's symbol table calling print_subs on each symbol.
# Recurse only into CGI::Util::
walksymtable(\%CGI::, 'print_subs',
             sub { $_[0] eq 'CGI::Util::' }, 'CGI::');

print_subs() — метод B::GV, который вы объявили. Также см. "Методы B::GV" ниже.

Функции, возвращающие `B::OP` объекты или для обхода деревьев OP

Для описания иерархии классов этих объектов и методов, которые могут быть вызваны на них, см. ниже, "ОБЗОР КЛАССОВ" и "КЛАССЫ, СВЯЗАННЫЕ С OP".

main_root: Возвращает корневой OP (т.е. объект соответствующего производного от B::OP класса) основной части Perl-программы.
main_start: Возвращает начальный OP основной части Perl-программы.
walkoptree(OP, METHOD): Выполняет обход дерева синтаксического дерева, начиная с OP, и вызывает METHOD для каждого посещенного OP. Каждый узел посещается перед своими дочерними узлами. Если walkoptree_debug (см. ниже) был вызван для включения отладки, то метод walkoptree_debug вызывается для каждого OP перед вызовом METHOD.
walkoptree_debug(DEBUG): Возвращает текущий флаг отладки для walkoptree. Если необязательный аргумент DEBUG отличен от нуля, он устанавливает флаг отладки в это значение. См. описание walkoptree выше для информации о том, что делает флаг отладки.

Разнообразные вспомогательные функции

ppname(OPNUM): Возвращает имя функции PP (например, "pp_add") для операции с номером OPNUM.
hash(STR): Возвращает строку в формате "0x..." представляющую значение внутренней хеш-функции, используемой Perl для строки STR.
cast_I32(I): Преобразует I к внутреннему типу I32, используемому Perl.
minus_c: Выполняет эквивалент опции командной строки -c. Очевидно, это полезно только в блоке BEGIN, иначе флаг устанавливается слишком поздно.
cstring(STR): Возвращает экранированную версию STR, заключенную в двойные кавычки, которая может быть использована как строка в коде на C.
perlstring(STR): Возвращает экранированную версию STR, заключенную в двойные кавычки, которая может быть использована как строка в коде на Perl.
safename(STR): Эта функция возвращает строку с изменённым первым символом, если это управляющий символ. Сначала она преобразует его в формат ^X, так что "\cG" становится "^G". Это используется внутренне в B::GV::SAFENAME, но вы можете вызвать её напрямую.
class(OBJ): Возвращает класс объекта без части имени класса, предшествующей первому "::". Это используется, например, для преобразования "B::UNOP" в "UNOP".
threadsv_names: Это использовалось для поддержки старого модуля потоков 5.005. Сейчас оно ничего не делает.

Экспортированные переменные-утилиты

@optype

my $op_type = $optype[$op_type_num];

Простое отображение номера типа операции на его тип (например, 'COP' или 'BINOP').

@specialsv_name

my $sv_name = $specialsv_name[$sv_index];

Некоторые типы SV считаются "специальными". Они представлены B::SPECIAL и обозначаются числом из specialsv_list. Этот массив отображает это число обратно на имя SV (например, 'Nullsv' или '&PL_sv_undef').

ОБЗОР КЛАССОВ

C-структуры, используемые в Perl для хранения информации SV и OP (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...), моделируются иерархией классов, и модуль B предоставляет к ним доступ через истинную иерархию объектов. Поля структур, которые указывают на другие объекты (будь то типы SV или типы OP), представлены модулем B в виде Perl-объектов соответствующего класса.

Основная часть модуля B — это методы для доступа к полям этих структур.

Обратите внимание, что все доступ к данным — только для чтения. Вы не можете изменить внутреннее состояние, используя этот модуль. Также обратите внимание, что объекты B::OP и B::SV, созданные этим модулем, являются валидными только до тех пор, пока существуют лежащие в основе объекты; их создание не увеличивает счётчики ссылок на подлежащие объекты. Попытка доступа к полям освобождённого объекта даст непонятные результаты или что-то худшее.

B::IV, B::NV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. Эти классы очевидным образом соответствуют лежащим в основе C-структурам с аналогичными именами. Иерархия наследования имитирует подлежащую C-иерархию:

                   B::SV
                     |
        +------------+------------+
        |            |            |
      B::PV        B::IV        B::NV
       /  \         /           /
      /    \       /           /
B::INVLIST  B::PVIV           /
                 \           /
                  \         /
                   \       /
                    B::PVNV
                       |
                       |
                    B::PVMG
                       |
   +-------+-------+---+---+-------+-------+
   |       |       |       |       |       |
 B::AV   B::GV   B::HV   B::CV   B::IO B::REGEXP
           |               |
           |               |
        B::PVLV          B::FM

Методы доступа соответствуют подлежащим C-макросам для доступа к полям, обычно с удаленным префиксом "указание класса" (Sv, Av, Hv, ...). Префикс оставляет только в случаях, когда его удаление приведёт к конфликту имён методов. Например, GvREFCNT остаётся без изменений, так как его сокращение повлекло бы конфликт с методом "суперкласса" REFCNT (соответствующим C-функции SvREFCNT).

Методы B::SV

REFCNT
FLAGS
object_2svref: Возвращает ссылку на обычный скаляр, соответствующий этому объекту B::SV. Другими словами, этот метод — обратная операция подпрограмме svref_2object(). Этот скаляр и другие данные, на которые он указывает, должны рассматриваться как неизменяемые: их изменение небезопасно и не гарантирует разумного эффекта.

Методы B::IV

IV: Возвращает значение IV, интерпретируемое как целое со знаком. Это будет вводящим в заблуждение, если FLAGS & SVf_IVisUV. Возможно, вы хотите метод int_value?
IVX
UVX
int_value: Этот метод возвращает значение IV как целое число. Он отличается от IV тем, что возвращает правильное значение независимо от того, хранится ли оно со знаком или без знака.
needs64bits
packiv

Методы B::NV

NV
NVX
COP_SEQ_RANGE_LOW
COP_SEQ_RANGE_HIGH: Эти последние два допустимы только для SV имён блока. Они существовали только в классе B::NV до Perl 5.22. В 5.22 они были перемещены в класс B::PADNAME.

Методы B::RV

RV

Методы B::PV

PV

Этот метод обычно и нужен. Он строит строку, используя информацию о длине и смещении в структуре: для обычных скаляров он вернёт строку, которую вы бы увидели из Perl, даже если она содержит нулевые символы.

RV

То же, что и B::RV::RV, но он завершится с ошибкой (die()), если PV не является ссылкой.

PVX

Этот метод реже бывает полезен. Он предполагает, что строка, хранящаяся в структуре, завершается нулём, и игнорирует информацию о длине.

Это подходящий метод, если вам нужно получить имя лексической переменной из массива padname. Имена лексических переменных всегда хранятся с завершающим нулём, а поле длины (CUR) перегружено для других целей и здесь не может быть использовано.

CUR

Этот метод возвращает внутреннее поле длины, которое состоит из количества внутренних байтов, а не обязательно количества логических символов.

LEN

Этот метод возвращает количество байтов, выделенных (через malloc) для хранения строки. Это 0, если скаляр не "владеет" строкой.

Методы B::PVMG

MAGIC
SvSTASH

Методы B::MAGIC

MOREMAGIC
precomp: Доступно только для r-магии, возвращает строку, сгенерировавшую регулярное выражение.
PRIVATE
TYPE
FLAGS
OBJ: Вызовет ошибку (die()) при вызове на r-магии.
PTR
REGEX: Доступно только для r-магии, возвращает целочисленное значение REGEX, хранящееся в MAGIC.

Методы B::INVLIST

prev_index: Возвращает кешированный результат предыдущего invlist_search() (внутреннее использование)
is_offset: Возвращает булево значение (0 или 1), чтобы узнать, использует ли invlist смещение. Когда false, список начинается с кодовой точки U+0000. Когда true, список начинается со следующих элементов.
array_len: Возвращает целое число с размером массива, используемого для определения invlist.
get_invlist_array: Этот метод возвращает список целых чисел, представляющих массив, используемый invlist. Примечание: это нельзя использовать во время итерации по invlist, и вызовет ошибку (croaks).

Методы B::PVLV

TARGOFF
TARGLEN
TYPE
TARG

Методы B::BM

USEFUL
PREVIOUS
RARE
TABLE

Методы B::REGEXP

REGEX
precomp
qr_anoncv
compflags: Два последних были добавлены в Perl 5.22.

Методы B::GV

is_empty

Этот метод возвращает TRUE, если поле GP GV равно NULL.

NAME

SAFENAME

Этот метод возвращает имя глобуса, но если первый символ имени — управляющий символ, он сначала преобразует его в ^X, так что *^G вернёт "^G", а не "\cG".

Это полезно, если вы хотите напечатать имя переменной. Если вы ограничитесь глобусами, которые существуют во время компиляции, результат должен быть однозначным, потому что код вроде ${"^G"} = 1 компилируется как две операции — константная строка и разыменование (rv2gv) — так что глобус создаётся во время выполнения.

Если вы работаете с глобусами во время выполнения и вам нужно различить *^G от *{"^G"}, используйте метод NAME без преобразований.

STASH

SV

IO

FORM

AV

HV

EGV

CV

CVGEN

LINE

FILE

FILEGV

GvREFCNT

FLAGS

GPFLAGS

Последний присутствует только в perl 5.22.0 и выше.

Методы B::IO

Объекты B::IO наследуются от объектов IO, и вы получите больше информации от самого объекта IO.

Например:

$gvio = B::svref_2object(\*main::stdin)->IO;
$IO = $gvio->object_2svref();
$fd = $IO->fileno();

LINES

PAGE

PAGE_LEN

LINES_LEFT

TOP_NAME

TOP_GV

FMT_NAME

FMT_GV

BOTTOM_NAME

BOTTOM_GV

SUBPROCESS

IoTYPE

Символ, обозначающий тип дескриптора ввода-вывода.

-     STDIN/OUT
I     STDIN/OUT/ERR
<     read-only
>     write-only
a     append
+     read and write
s     socket
|     pipe
I     IMPLICIT
#     NUMERIC
space closed handle
\0    closed internal handle

IoFLAGS

IsSTD

Принимает один аргумент ( 'stdin' | 'stdout' | 'stderr' ) и возвращает true, если IoIFP объекта равен дескриптору, имя которого передано в качестве аргумента; т.е., $io->IsSTD('stderr') истинно, если IoIFP($io) == PerlIO_stderr().

Методы B::AV

FILL
MAX
ARRAY
ARRAYelt: Как ARRAY, но принимает индекс в качестве аргумента, чтобы получить только один элемент, а не весь список.

Методы B::CV

STASH
START
ROOT
GV
FILE
DEPTH
PADLIST: Возвращает объект B::PADLIST.
OUTSIDE
OUTSIDE_SEQ
XSUB
XSUBANY: Для константных подпрограмм возвращает константный SV, возвращённый подпрограммой.
CvFLAGS
const_sv
NAME_HEK: Возвращает имя лексической подпрограммы, иначе undef.

Методы B::HV

FILL
MAX
КЛЮЧИ
RITER
ИМЯ
МАССИВ

B::OP, B::UNOP, B::UNOP_AUX, B::BINOP, B::LOGOP, B::LISTOP, B::PMOP, B::SVOP, B::PADOP, B::PVOP, B::LOOP, B::COP, B::METHOP.

Эти классы соответствуют по очевидному способу базовым C-структурам с аналогичными именами. Иерархия наследования имитирует базовое C-наследование:

                         B::OP
                           |
           +----------+---------+--------+-------+---------+
           |          |         |        |       |         |
        B::UNOP    B::SVOP  B::PADOP  B::COP  B::PVOP  B::METHOP
           |
       +---+---+---------+
       |       |         |
   B::BINOP  B::LOGOP  B::UNOP_AUX
       |
       |
   B::LISTOP
       |
   +---+---+
   |       |
B::LOOP   B::PMOP

Методы доступа соответствуют именам полей базовой C-структуры, из которых удалён префикс, указывающий на класс ("op_").

Методы B::OP

Эти методы извлекают значения полей с аналогичными именами в структуре данных OP. Дополнительная информация приведена в начале op.h.

next

sibling

parent

Возвращает родителя OP. Если родителя нет, или ваш Perl не был скомпилирован с -DPERL_OP_PARENT, возвращает NULL.

Обратите внимание, что глобальная переменная $B::OP::does_parent не определена в старых версиях Perl, которые не поддерживают метод parent, определена, но равна false в Perl, который поддерживает метод, но был скомпилирован без -DPERL_OP_PARENT, и равна true в остальных случаях.

name

Возвращает имя операции в виде строки (например, "add", "rv2av").

ppaddr

Возвращает имя функции в виде строки (например, "PL_ppaddr[OP_ADD]", "PL_ppaddr[OP_RV2AV]").

desc

Возвращает описание операции из глобального массива C PL_op_desc (например, "сложение", "обращение к массиву").

targ

type

opt

flags

private

spare

Метод B::UNOP

first

Методы B::UNOP_AUX (с версии 5.22)

aux_list(cv): Возвращает список элементов структуры данных aux операции или пустой список, если aux отсутствует. Возвращаемое значение зависит от типа объекта, но обычно это набор объектов B::IV, B::GV, и т. д. cv — объект B::CV , представляющий подпрограмму, в которой содержится операция.
string(cv): Возвращает текстовое представление объекта (вероятно, полезно для разбора и отладки) или пустую строку, если тип операции не поддерживает это. cv — объект B::CV , представляющий подпрограмму, в которой содержится операция.

Метод B::BINOP

last

Метод B::LOGOP

other

Метод B::LISTOP

children

Методы B::PMOP

pmreplroot
pmreplstart
pmflags
precomp
pmoffset: Только при компиляции perl с ithreads.
code_list: С версии perl 5.17.1
pmregexp: Добавлен в Perl 5.22, этот метод возвращает B::REGEXP, связанный с операцией. Хотя PMOP фактически не имеют полей pmregexp при многопоточных компиляциях, этот метод возвращает регулярное выражение и в многопоточных средах для удобства.

Методы B::SVOP

sv
gv

Метод B::PADOP

padix

Метод B::PVOP

pv

Методы B::LOOP

redoop
nextop
lastop

Методы B::COP

Класс B::COP используется для операций "nextstate" и "dbstate". С версии Perl 5.22 он также используется для операций "null", которые изначально были COP.

метка
stash
stashpv
stashoff (только для многопоточного режима)
файл
cop_seq
строка
предупреждения
ввод/вывод
подсказки
хэш-таблица подсказок

Методы B::METHOP (с версии Perl 5.22)

first
meth_sv

Perl 5.18 представил новый класс B::PADLIST, возвращаемый методом PADLIST класса B::CV.

Perl 5.22 представил классы B::PADNAMELIST и B::PADNAME.

Методы B::PADLIST

MAX
МАССИВ: Список PAD. Первый — B::PADNAMELIST, содержащий имена. Остальные — в настоящее время объекты B::AV, но это может измениться в будущих версиях.
ARRAYelt: Аналогично ARRAY, но принимает индекс в качестве аргумента, чтобы получить только один элемент, а не список всех элементов.
ИМЕНА: Этот метод, представленный в версии 5.22, возвращает B::PADNAMELIST. Он эквивалентен ARRAYelt с аргументом 0.
REFCNT
id: Этот метод, представленный в версии 5.22, возвращает ID, общий для клонов одного и того же списка PAD.
outid: Этот метод, также добавленный в версии 5.22, возвращает ID внешнего списка PAD.

Методы B::PADNAMELIST

MAX
МАССИВ
ARRAYelt: Эти два метода возвращают имена PAD, используя объекты B::SPECIAL для нулевых указателей и объекты B::PADNAME в противном случае.
REFCNT

Методы B::PADNAME

PV
PVX
LEN
REFCNT
FLAGS: Для обеспечения обратной совместимости, если установлен флаг PADNAMEt_OUTER, метод FLAGS дополнительно устанавливает флаг SVf_FAKE.
TYPE: Объект B::HV, представляющий хранилище (stash) для типизированного лексического.
SvSTASH: Псевдоним TYPE для обеспечения обратной совместимости.
OURSTASH: Объект B::HV, представляющий хранилище (stash) для переменных 'our'.
PROTOCV: Прототип CV для подпрограммы 'my'.
COP_SEQ_RANGE_LOW
COP_SEQ_RANGE_HIGH: Номера последовательности, представляющие область видимости лексической переменной. Не имеют смысла, если установлен PADNAMEt_OUTER.
ИНДЕКС_РОДИТЕЛЬСКОГО_PAD: Имеет смысл только если установлен PADNAMEt_OUTER.
ФЛАГИ_РОДИТЕЛЬСКОГО_ЛОЖНОГО_ЛЕКСИЧЕСКОГО: Имеет смысл только если установлен PADNAMEt_OUTER.

$B::overlay

Хотя дерево синтаксического анализа (optree) является неизменяемым, существует возможность переопределения значений, которые возвращают различные методы B::*OP для конкретной операции. $B::overlay должен ссылаться на двухуровневый хэш: индексированный по адресу операции, затем по имени метода. При вызове метода операции, если соответствующий элемент существует в хэше, возвращается его значение. Эта возможность используется B::Deparse для "отмены" некоторых оптимизаций. Например:

local $B::overlay = {};
...
if ($op->name eq "foo") {
    $B::overlay->{$$op} = {
            name => 'bar',
            next => $op->next->next,
    };
}
...
$op->name # returns "bar"
$op->next # returns the next op but one

АВТОР

Malcolm Beattie, mbeattie@sable.ox.ac.uk

© 1993–2021 Larry Wall and others
Licensed under the GNU General Public License version 1 or later, or the Artistic License.
The Perl logo is a trademark of the Perl Foundation.
https://perldoc.perl.org/5.36.0/B

B