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".

main_root: Возвращает корневой оператор (т. е. объект в соответствующем производном от B::OP классе) основной части Perl-программы.
main_start: Возвращает стартовый оператор основной части Perl-программы.
walkoptree(OP, METHOD): Выполняет обход дерева синтаксического анализа, начиная с OP, и вызывает METHOD для каждого посещённого оператора. Каждый узел посещается до своих потомков. Если walkoptree_debug (см. ниже) вызван для включения отладки, то метод walkoptree_debug вызывается для каждого оператора перед вызовом 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::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

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

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

Если вы работаете с globs во время выполнения и вам нужно различить *^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, определена, но имеет значение 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.

label
stash
stashpv
stashoff (только для многопоточных)
file
cop_seq
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: Список падов. Первый — 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
FLAGS: Для обратной совместимости, если установлен флаг PADNAMEt_OUTER, метод FLAGS также добавляет флаг SVf_FAKE.
TYPE: Объект B::HV, представляющий хранилище для типизированных лексических переменных.
SvSTASH: Псевдоним для TYPE для обратной совместимости.
OURSTASH: Объект B::HV, представляющий хранилище для переменных '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.32.0/B

B