B

СОДЕРЖАНИЕ

ИМЯ
СИНТЕКС
ОПИСАНИЕ
ОБЗОР
Вспомогательные функции
ОБЗОР КЛАССОВ
АВТОР

ИМЯ

B — бэкенд Perl-компилятора

СИНТЕКС

use B;

ОПИСАНИЕ

Модуль B предоставляет классы, которые позволяют Perl-программе заглянуть в свои внутренности. Это модуль, используемый для реализации «бэкендов» Perl-компилятора. Использование компилятора не требует знания этого модуля: см. модуль O для части, видимой пользователю. Модуль B полезен тем, кто хочет написать новые бэкенды компилятора. В этом документе предполагается, что читатель хорошо знаком с внутренностями Perl, включая такие понятия, как SVs, 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::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::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') true, если 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
KEYS
RITER
NAME
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

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-операциями.

label
stash
stashpv
stashoff (только для многопоточных)
file
cop_seq
arybase
line
warnings
io
hints
hints_hash

Методы 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
ARRAY: Список PAD. Первый — B::PADNAMELIST, содержащий имена. Остальные в настоящее время являются объектами B::AV, но это может измениться в будущих версиях.
ARRAYelt: Аналогично ARRAY, но принимает индекс в качестве аргумента, чтобы получить только один элемент, а не список всех элементов.
NAMES: Этот метод, представленный в версии 5.22, возвращает B::PADNAMELIST. Он эквивалентен ARRAYelt с аргументом 0.
REFCNT
id: Этот метод, добавленный в версии 5.22, возвращает ID, общий для клонов одного и того же списка pad.
outid: Этот метод, также добавленный в версии 5.22, возвращает ID внешнего списка pad.

Методы B::PADNAMELIST

MAX
ARRAY
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.
PARENT_PAD_INDEX: Имеет смысл только если установлен PADNAMEt_OUTER.
PARENT_FAKELEX_FLAGS: Имеет смысл только если установлен PADNAMEt_OUTER.

$B::overlay

Хотя дерево опций является только для чтения, есть функция наложения, которая позволяет переопределять значения, которые возвращают различные методы 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–2020 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.28.3/B

B