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, но он завершится ошибкой (), если PV не является ссылкой.

PVX

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

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

CUR

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

LEN

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

Методы B::PVMG

MAGIC
SvSTASH

Методы B::MAGIC

MOREMAGIC
precomp: Действительно только для r-магии, возвращает строку, сгенерировавшую регулярное выражение.
PRIVATE
TYPE
FLAGS
OBJ: Вызовет ошибку (), если вызван для 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

Символ, обозначающий тип дескриптора 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-"наследование":

                         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

Методы доступа соответствуют именам полей базовой С-структуры, с удалённым префиксом "указания класса" ("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
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 должен содержать ссылку на хэш с двумя уровнями: индексированный по адресу 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–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.34.0/B

B