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 и обозначаются числом из специальsv_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

IsBOOL

Возвращает true, если SV является булевым значением (истина или ложь). Затем вы можете использовать TRUE для проверки, является ли значение истиной или ложью.

my $something = ( 1 == 1 ) # boolean true
             || ( 1 == 0 ) # boolean false
             || 42         # IV true
             || 0;         # IV false
my $sv = B::svref_2object(\$something);

say q[Not a boolean value]
    if ! $sv->IsBOOL;

say q[This is a boolean with value: true]
    if   $sv->IsBOOL && $sv->TRUE_nomg;

say q[This is a boolean with value: false]
    if   $sv->IsBOOL && ! $sv->TRUE_nomg;

object_2svref

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

TRUE

Возвращает булевое значение, указывающее, будет ли Perl рассматривать SV как истинное или ложное.

Предупреждение Этот вызов выполняет магию "получения". Если вам нужно только проверить природу этого SV, используйте вспомогательную функцию TRUE_nomg.

Это псевдоним для SvTRUE($sv).

TRUE_nomg

Проверяет, является ли значение истинным (не выполняет магию "получения"). Возвращает булевое значение, указывающее, будет ли Perl рассматривать SV как истинное или ложное.

Это псевдоним для SvTRUE_nomg($sv).

Методы 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 смещение. Если ложь, список начинается с кодовой точки U+0000. Если истина, список начинается со следующих элементов.
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

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

-     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
Файл
Глубина
PADLIST: Возвращает объект B::PADLIST.
OUTSIDE
OUTSIDE_SEQ
XSUB
XSUBANY: Для константных подпрограмм возвращает константный SV, возвращённый подпрограммой.
CvFLAGS
const_sv
NAME_HEK: Возвращает имя лексической подпрограммы, в противном случае undef.

Методы B::HV

FILL
MAX
KEYS
RITER
Имя
ARRAY

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, определена, но ложна в Perl, поддерживающих метод, но скомпилированных без -DPERL_OP_PARENT, и истинна в противном случае.

name

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

ppaddr

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

desc

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

targ

тип

opt

флаги

private

резерв

Метод 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
строка
предупреждения
ввод/вывод
подсказки
hints_hash

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

first
meth_sv

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

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

Методы B::PADLIST

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

Методы B::PADNAMELIST

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

Методы B::PADNAME

PV
PVX
LEN
REFCNT
GEN
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.
PARENT_PAD_INDEX: Имеет смысл только если установлен PADNAMEt_OUTER.
PARENT_FAKELEX_FLAGS: Имеет смысл только если установлен PADNAMEt_OUTER.
IsUndef: Возвращает логическое значение для проверки, является ли padname PL_padname_undef.

$B::overlay

Хотя optree является только для чтения, есть функция наложения, которая позволяет переопределять возвращаемые значения различных методов B::*OP для определённой операции. $B::overlay должен содержать ссылку на хэш с двумя уровнями вложенности: индексированный по адресу OP, а затем имени метода. Всякий раз, когда вызывается метод операции, возвращается значение из хэша, если оно существует. Эта функция используется 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–2023 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.38.0/B

B