perlapi

СОДЕРЖАНИЕ

НАЗВАНИЕ
ОПИСАНИЕ
Функции обработки массивов
Функции обратного вызова
Изменение регистра символов
Классификация символов
Клонирование интерпретатора
Временные крючки области видимости
Хеши подсказок COP
Чтение подсказок COP
Пользовательские операторы
Функции манипулирования CV
Переменные xsubpp и внутренние функции
Утилиты отладки
Функции отображения и вывода
Функции встраивания
Макросы обработки исключений (простые)
Функции в файле vutil.c
"Gimme" Значения
Глобальные переменные
Функции GV
Полезные значения
Функции манипулирования хешами
Управление крючками
Интерфейс лексического анализатора
Функции и макросы, связанные с локалью
Магические функции
Управление памятью
Разнообразные функции
Функции MRO
Функции Multicall
Числовые функции
Устаревшие функции обратной совместимости
Построение Optree
Функции манипулирования Optree
Упаковывание и распаковывание
Структуры данных Pad
Переменные на интерпретатор
Функции REGEXP
Макросы манипулирования стеком
Флаги SV
Функции манипулирования SV
Поддержка Unicode
Переменные, созданные xsubpp и внутренними функциями xsubpp
Предупреждения и завершение работы
Недокументированные функции
АВТОРЫ
СМОТРИТЕ ТАКЖЕ

НАЗВАНИЕ

perlapi - автоматически сгенерированная документация для публичного API Perl

ОПИСАНИЕ

Этот файл содержит большую часть документации публичного API Perl, сгенерированной embed.pl. В частности, это список функций, макросов, флагов и переменных, которые могут использоваться авторами расширений. Некоторые специализированные элементы документированы в config.h, perlapio, perlcall, perlclib, perlfilter, perlguts, perlmroapi, perlxs, perlxstut и warnings.

В конце приведен список функций, которые еще не были задокументированы. Ваши исправления приветствуются! Интерфейсы этих функций могут быть изменены без предварительного уведомления.

Все, что не указано здесь, не является частью публичного API и вообще не должно использоваться авторами расширений. По этим причинам следует избегать слепого использования функций, перечисленных в proto.h, при написании расширений.

В Perl, в отличие от C, строка символов может обычно содержать встроенные символы NUL. Иногда в документации строка Perl называется «буфером», чтобы отличить её от строки C, но иногда они оба называются просто строками.

Обратите внимание, что все глобальные переменные API Perl должны быть обработаны с префиксом PL_. Опять же, те, что не указаны здесь, не должны использоваться авторами расширений и могут быть изменены или удалены без предварительного уведомления; то же касается и макросов. Некоторые макросы предоставляются для совместимости со старыми, необработанными именами, но эта поддержка может быть отключена в будущих релизах.

Perl изначально был написан для обработки только US-ASCII (то есть символов, чьи порядковые номера находятся в диапазоне от 0 до 127). Документация и комментарии могут по-прежнему использовать термин ASCII, когда на самом деле подразумевается весь диапазон от 0 до 255.

Символы не-ASCII, находящиеся ниже 256, могут иметь различные значения, в зависимости от различных факторов. (См., в частности, perllocale). Но обычно весь диапазон можно рассматривать как ISO-8859-1. Часто термин «Latin-1» (или «Latin1») используется как эквивалент ISO-8859-1. Но некоторые люди считают, что «Latin1» относится только к символам в диапазоне от 128 до 255, или иногда от 160 до 255. В этой документации «Latin1» и «Latin-1» используются для обозначения всех 256 символов.

Обратите внимание, что Perl может быть скомпилирован и запущен как под ASCII, так и под EBCDIC (см. perlebcdic). Большая часть документации (и даже комментарии в коде) игнорирует возможность EBCDIC. Для почти всех целей различия прозрачны. Например, под EBCDIC вместо UTF-8 используется UTF-EBCDIC для кодирования строк Unicode, и поэтому, когда в этой документации упоминается utf8 (и варианты этого имени, включая в именах функций), это также (по существу прозрачно) означает UTF-EBCDIC. Но порядковые номера символов отличаются между ASCII, EBCDIC и UTF-кодировками, и строка, закодированная в UTF-EBCDIC, может занимать другое количество байтов, чем в UTF-8.

Список ниже отсортирован по алфавиту, регистронезависимо.

Функции обработки массивов

av_clear

Освобождает все элементы массива, оставляя его пустым. Эквивалент XS для @array = (). См. также "av_undef".

Обратите внимание, что действия деструктора, вызываемого напрямую или косвенно при освобождении элемента массива, могут привести к уменьшению счётчика ссылок самого массива (например, при удалении записи в таблице символов). Поэтому существует вероятность, что массив AV может быть освобождён (или даже перераспределён) по возвращении из вызова, если вы не удерживаете ссылку на него.

void    av_clear(AV *av)

av_create_and_push

ПРИМЕЧАНИЕ: эта функция экспериментальная и может быть изменена или удалена без предварительного уведомления.

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

ПРИМЕЧАНИЕ: эту функцию необходимо вызывать явно как Perl_av_create_and_push с параметром aTHX_.

void    Perl_av_create_and_push(pTHX_ AV **const avp,
                                SV *const val)

av_create_and_unshift_one

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

ПРИМЕЧАНИЕ: эту функцию необходимо вызывать явно как Perl_av_create_and_unshift_one с параметром aTHX_.

SV**    Perl_av_create_and_unshift_one(pTHX_ 
                                       AV **const avp,
                                       SV *const val)

av_delete

Удаляет элемент с индексом key из массива, делает элемент смертельным и возвращает его. Если flags равно G_DISCARD, элемент освобождается, и возвращается NULL. NULL также возвращается, если key находится вне диапазона.

Эквивалент Perl: splice(@myarray, $key, 1, undef) (в контексте void, если splice присутствует).

SV*     av_delete(AV *av, SSize_t key, I32 flags)

av_exists

Возвращает true, если элемент с индексом key был инициализирован.

Это основано на том, что неинициализированные элементы массива устанавливаются в NULL.

Эквивалент Perl: exists($myarray[$key]).

bool    av_exists(AV *av, SSize_t key)

av_extend

Предварительно расширяет массив, чтобы он мог хранить значения с индексами 0..key. Таким образом, av_extend(av,99) гарантирует, что массив может хранить 100 элементов, то есть, что av_store(av, 0, sv) до av_store(av, 99, sv) в простом массиве будут работать без дополнительного выделения памяти.

Если аргумент av — связанный массив, вызывается метод связанного массива EXTEND с аргументом (key+1).

void    av_extend(AV *av, SSize_t key)

av_fetch

Возвращает SV по указанному индексу в массиве. key — это индекс. Если lval истинно, вы гарантированно получите реальный SV (если он раньше не был реальным), который можно изменить. Проверьте, что возвращаемое значение не null, прежде чем разыменовывать его до SV*.

См. "Понимание магии связанных массивов и хэшей" в perlguts для получения дополнительной информации о использовании этой функции для связанных массивов.

Приблизительный эквивалент Perl: $myarray[$key].

SV**    av_fetch(AV *av, SSize_t key, I32 lval)

AvFILL

То же, что av_top_index() или av_tindex().

int     AvFILL(AV* av)

av_fill

Устанавливает наибольший индекс в массиве в заданное число, эквивалентно Perl's $#array = $fill;.

Количество элементов в массиве будет fill + 1 после av_fill() возвращается. Если массив был короче, то добавленные дополнительные элементы устанавливаются в NULL. Если массив был длиннее, то избыточные элементы освобождаются. av_fill(av, -1) — то же, что av_clear(av).

void    av_fill(AV *av, SSize_t fill)

av_len

То же, что "av_top_index". Обратите внимание, что, вопреки тому, что предполагает название, она возвращает наибольший индекс в массиве, поэтому для получения размера массива необходимо использовать av_len(av) + 1. Это отличается от "sv_len", которая возвращает ожидаемое значение.

SSize_t av_len(AV *av)

av_make

Создаёт новый AV и заполняет его списком SV. SV копируются в массив, поэтому они могут быть освобождены после вызова av_make. Новый AV будет иметь счётчик ссылок 1.

Эквивалент Perl: my @new_array = ($scalar1, $scalar2, $scalar3...);.

AV*     av_make(SSize_t size, SV **strp)

av_pop

Удаляет один SV из конца массива, уменьшая его размер на единицу и возвращая SV (передавая управление одним счётчиком ссылок) вызывающей стороне. Возвращает &PL_sv_undef если массив пуст.

Эквивалент Perl: pop(@myarray);.

SV*     av_pop(AV *av)

av_push

Добавляет SV (передавая управление одним счётчиком ссылок) в конец массива. Массив будет автоматически увеличиваться, чтобы вместить добавление.

Эквивалент Perl: push @myarray, $val;.

void    av_push(AV *av, SV *val)

av_shift

Удаляет один SV из начала массива, уменьшая его размер на единицу и возвращая SV (передавая управление одним счётчиком ссылок) вызывающей стороне. Возвращает &PL_sv_undef если массив пуст.

Эквивалент Perl: shift(@myarray);.

SV*     av_shift(AV *av)

av_store

Хранит SV в массиве. Индекс массива задаётся как key. Возвращаемое значение будет NULL если операция не удалась или значение не нужно было фактически хранить в массиве (как в случае связанных массивов). В противном случае можно разыменовать, чтобы получить SV* что было сохранено там (= val).

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

Приблизительный эквивалент Perl: splice(@myarray, $key, 1, $val).

SV**    av_store(AV *av, SSize_t key, SV *val)

av_tindex

То же, что av_top_index().

SSize_t av_tindex(AV *av)

av_top_index

Возвращает наибольший индекс в массиве. Количество элементов в массиве — av_top_index(av) + 1. Возвращает -1, если массив пуст.

Эквивалент Perl для этого — $#myarray.

(Несколько более короткая форма — av_tindex.)

SSize_t av_top_index(AV *av)

av_undef

Удаляет массив. Эквивалент XS для undef(@array).

Помимо освобождения всех элементов массива (как av_clear() ), это также освобождает память, используемую av для хранения списка скаляров.

См. "av_clear" для примечания о том, что массив может быть недействительным по возвращении.

void    av_undef(AV *av)

av_unshift

Вставляет заданное количество undef значений в начало массива. Массив будет автоматически увеличиваться, чтобы вместить добавление.

Эквивалент Perl: unshift @myarray, ((undef) x $num);

void    av_unshift(AV *av, SSize_t num)

get_av

Возвращает AV указанного Perl-глобального или пакетного массива с заданным именем (поэтому не работает с лексическими переменными). flags передаются в gv_fetchpv. Если GV_ADD установлено и Perl-переменной не существует, она будет создана. Если flags равно нулю и переменная не существует, возвращается NULL.

Эквивалент Perl: @{"$name"}.

ПРИМЕЧАНИЕ: perl_ -версия этой функции устарела.

AV*     get_av(const char *name, I32 flags)

newAV

Создаёт новый AV. Счётчик ссылок устанавливается в 1.

Эквивалент Perl: my @array;.

AV*     newAV()

sortsv

Сортирует массив указателей SV на месте с помощью заданной процедуры сравнения.

В настоящее время всегда используется слияние. См. "sortsv_flags" для более гибкой процедуры.

void    sortsv(SV** array, size_t num_elts,
               SVCOMPARE_t cmp)

Функции обратного вызова

call_argv

Выполняет обратный вызов указанной именованной и пакетной Perl-подпрограмме с argv (массивом строк, завершённым NULL ) в качестве аргументов. См. perlcall.

Приблизительный Perl-эквивалент: &{"$sub_name"}(@$argv).

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_argv(const char* sub_name, I32 flags,
                  char** argv)

call_method

Выполняет обратный вызов указанного Perl-метода. Благословенный объект должен находиться в стеке. См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_method(const char* methname, I32 flags)

call_pv

Выполняет обратный вызов указанной Perl-подпрограммы. См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_pv(const char* sub_name, I32 flags)

call_sv

Выполняет обратный вызов Perl-подпрограммы, указанной в SV.

Если ни флаг G_METHOD, ни флаг G_METHOD_NAMED не указаны, SV может быть любым из CV, GV, ссылкой на CV, ссылкой на GV или SvPV(sv) будет использовано в качестве имени вызываемой подпрограммы.

Если указан флаг G_METHOD, SV может быть ссылкой на CV или SvPV(sv) будет использовано в качестве имени вызываемого метода.

Если указан флаг G_METHOD_NAMED, SvPV(sv) будет использовано в качестве имени вызываемого метода.

Некоторые другие значения обрабатываются особым образом для внутреннего использования и не должны использоваться.

См. perlcall.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     call_sv(SV* sv, volatile I32 flags)

ENTER

Открывающая скобка в обратном вызове. См. "LEAVE" и perlcall.

ENTER;

ENTER_with_name

То же, что и "ENTER", но при включенном отладке он также связывает заданную строку-литерал с новым контекстом.

ENTER_with_name("name");

eval_pv

Указывает Perl на eval заданную строку в скалярном контексте и возвращает результат SV*.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

SV*     eval_pv(const char* p, I32 croak_on_error)

eval_sv

Указывает Perl на eval строку в SV. Он поддерживает те же флаги, что и call_sv, за исключением очевидного исключения G_EVAL. См. perlcall.

Флаг G_RETHROW может быть использован, если вам нужно, чтобы eval_sv() выполнял код, заданный строкой, но не ловил никакие ошибки.

ПРИМЕЧАНИЕ: форма функции perl_ устарела.

I32     eval_sv(SV* sv, I32 flags)

FREETMPS

Закрывающая скобка для временных переменных в обратном вызове. См. "SAVETMPS" и perlcall.

FREETMPS;

LEAVE

Закрывающая скобка в обратном вызове. См. "ENTER" и perlcall.

LEAVE;

LEAVE_with_name

То же, что и "LEAVE", но при включенной отладке она сначала проверяет, что контекст имеет заданное имя. name должна быть строкой-литералом.

LEAVE_with_name("name");

SAVETMPS

Открывающая скобка для временных переменных в обратном вызове. См. "FREETMPS" и perlcall.

SAVETMPS;

Изменение регистра символов

Perl использует "полные" преобразования регистра Юникода. Это означает, что преобразование одного символа в другой регистр может привести к последовательности более чем одного символа. Например, заглавная буква ß (маленькая буква с острым S в латинице) — это последовательность из двух символов SS. Это создаёт некоторые сложности. Нижний регистр всех символов в диапазоне 0..255 — это один символ, и поэтому "toLOWER_L1" предоставляется. Но toUPPER_L1 не может существовать, так как не могла бы возвращать правильный результат для всех законных входных данных. Вместо этого "toUPPER_uvchr" имеет API, который позволяет возвращать все возможные законные результаты.) Точно так же здесь не реализована никакая другая функция, которая была бы ограничена невозможностью предоставления правильных результатов для всего диапазона возможных входных данных.

toFOLD

Преобразует указанный символ в регистр с «складыванием». Если входной символ не является заглавной буквой ASCII, возвращается сам входной символ. Вариант toFOLD_A эквивалентен. (Нет эквивалента to_FOLD_L1 для всего диапазона Latin1, так как там нужна полная общность "toFOLD_uvchr".)

U8      toFOLD(U8 ch)

toFOLD_utf8

Преобразует первый символ, закодированный в UTF-8, в последовательности, начинающейся с p и не выходящей за пределы e - 1, в его форму с «складыванием» и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма с «складыванием» может быть длиннее исходного символа.

Возвращается первый код символа преобразованной формы (но обратите внимание, как объяснено в начале этого раздела на верхней части этого раздела, что может быть больше).

Он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это утверждается в -DDEBUGGING сборках). Если UTF-8 для входного символа каким-либо образом неверный, программа может «кричать» или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможным изменением в будущих выпусках.

UV      toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)

toFOLD_utf8_safe

То же, что и "toFOLD_utf8".

UV      toFOLD_utf8_safe(U8* p, U8* e, U8* s,
                         STRLEN* lenp)

toFOLD_uvchr

Преобразует код символа cp в его форму с «складыванием» и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как национальный, если он меньше 256; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма с «складыванием» может быть длиннее исходного символа.

UV      toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)

toLOWER

Преобразует указанный символ в нижний регистр. Если входной символ не является заглавной буквой ASCII, возвращается сам входной символ. Вариант toLOWER_A эквивалентен.

U8      toLOWER(U8 ch)

toLOWER_L1

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

U8      toLOWER_L1(U8 ch)

toLOWER_LC

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

U8      toLOWER_LC(U8 ch)

toLOWER_utf8

Преобразует первый символ, закодированный в UTF-8, в последовательности, начинающейся с p и не выходящей за пределы e - 1, в его форму нижнего регистра, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма нижнего регистра может быть длиннее исходного символа.

Возвращается первый код символа преобразованной формы (но обратите внимание, как объяснено в начале этого раздела на верхней части этого раздела, что может быть больше). Он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это утверждается в -DDEBUGGING сборках). Если UTF-8 для входного символа каким-либо образом неверный, программа может «кричать» или функция может вернуть ЗАМЕЩАЮЩИЙ СИМВОЛ по усмотрению реализации и с возможным изменением в будущих выпусках.

UV      toLOWER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)

toLOWER_utf8_safe

То же, что и "toLOWER_utf8".

UV      toLOWER_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toLOWER_uvchr

Преобразует код символа cp в его форму нижнего регистра, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как национальный, если он меньше 256; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма нижнего регистра может быть длиннее исходного символа.

UV      toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)

toTITLE

Преобразует указанный символ в заголовок. Если входной символ не является строчной буквой ASCII, возвращается сам входной символ. Вариант toTITLE_A эквивалентен. (Нет toTITLE_L1 для всего диапазона Latin1, так как нужна полная общность "toTITLE_uvchr". Регистр заголовка не является понятием, используемым в обработке языка, поэтому для этого нет функциональности.)

U8      toTITLE(U8 ch)

toTITLE_utf8

Преобразует первый символ, закодированный в UTF-8, в последовательности, начинающейся с p и не выходящей за пределы e - 1, в его форму заголовка, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма заголовка может быть длиннее исходного символа.

UV      toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)

toTITLE_utf8_safe

То же, что и "toTITLE_utf8".

UV      toTITLE_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toTITLE_uvchr

Преобразует код символа cp в его форму заголовка, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как национальный, если он меньше 256; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма заголовка может быть длиннее исходного символа.

UV      toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)

toUPPER

Преобразует указанный символ в верхний регистр. Если входной символ не является строчной буквой ASCII, возвращается сам входной символ. Вариант toUPPER_A эквивалентен.

U8      toUPPER(int ch)

toUPPER_utf8

Преобразует первый символ, закодированный в UTF-8, в последовательности, начинающейся с p и не выходящей за пределы e - 1, в его форму верхнего регистра, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма верхнего регистра может быть длиннее исходного символа.

UV      toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)

toUPPER_utf8_safe

То же, что и "toUPPER_utf8".

UV      toUPPER_utf8_safe(U8* p, U8* e, U8* s,
                          STRLEN* lenp)

toUPPER_uvchr

Преобразует код символа cp в его форму верхнего регистра, и сохраняет его в UTF-8 в s, а его длину в байтах в lenp. Код символа интерпретируется как национальный, если он меньше 256; в противном случае как Unicode. Обратите внимание, что буфер, на который указывает s, должен иметь размер не менее UTF8_MAXBYTES_CASE+1 байтов, так как форма верхнего регистра может быть длиннее исходного символа.

Возвращается первый код символа преобразованной формы (но обратите внимание, как объяснено в начале этого раздела на верхней части этого раздела, что может быть больше.)

UV      toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)

WIDEST_UTYPE

Возвращает тип целого беззнакового наибольшего размера на платформе, в настоящее время либо U32 или 64. Это можно использовать в объявлениях, таких как

WIDEST_UTYPE my_uv;

или приведения типов

my_uv = (WIDEST_UTYPE) val;

Классификация символов

Этот раздел посвящен функциям (на самом деле макросам), которые классифицируют символы по типам, например, знаки препинания против буквенных и т. д. Большинство из них аналогичны классам символов в регулярных выражениях. (См. "POSIX Character Classes" в perlrecharclass.) Существуют несколько вариантов для каждого класса. (Не все макросы имеют все варианты; каждый элемент ниже перечисляет те, которые для него действительны.) Никакие не затронуты use bytes, и только те, у которых в названии есть LC, затронуты текущим языком.

Основная функция, например, isALPHA(), принимает любое знаковое или беззнаковое значение, рассматривая его как код символа, и возвращает булево значение о том, является ли символ, представленный им (или на платформах, не использующих ASCII, соответствует ему) символом ASCII в указанном классе на основе платформы, Unicode и правил Perl. Если входное число не помещается в октет, возвращается FALSE.

Вариант isFOO_A (например, isALPHA_A()) идентичен базовой функции без суффикса "_A". Этот вариант используется для акцентирования в названии, что могут возвращать TRUE только символы из набора ASCII.

Вариант isFOO_L1 накладывает на платформу наборы символов Latin-1 (или эквивалент EBCDIC). То есть, кодовые точки ASCII не изменяются, так как ASCII является подмножеством Latin-1. Но не-ASCII кодовые точки обрабатываются как символы Latin-1. Например, isWORDCHAR_L1() вернёт true, когда вызывается с кодовой точкой 0xDF, которая является символом слова как в ASCII, так и в EBCDIC (хотя она представляет разные символы в каждом). Если входное значение — число, которое не помещается в октет, возвращается FALSE. (Документация Perl использует разговорное определение Latin-1, включающее все кодовые точки ниже 256.)

Вариант isFOO_uvchr точно такой же, как вариант isFOO_L1, для входных значений ниже 256, но если кодовая точка больше 255, используются правила Unicode для определения, находится ли она в классе символов. Например, isWORDCHAR_uvchr(0x100) возвращает TRUE, так как 0x100 — это заглавная буква A с макроном в Unicode и является символом слова.

Варианты isFOO_utf8 и isFOO_utf8_safe похожи на isFOO_uvchr, но используются для строк в кодировке UTF-8. Эти две формы — разные имена для одного и того же. Каждый вызов одного из них классифицирует первый символ строки, начиная с p. Второй параметр, e, указывает на любое место в строке за первым символом, до одного байта после конца всей строки. Хотя оба варианта идентичны, суффикс _safe в одном из имен подчёркивает, что он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это гарантируется в -DDEBUGGING сборках). Если UTF-8 для входного символа каким-то образом повреждён, программа может завершиться ошибкой или функция может вернуть FALSE по усмотрению реализации и может измениться в будущих версиях.

Вариант isFOO_LC похож на варианты isFOO_A и isFOO_L1, но результат основан на текущем языке, что и означает LC в имени. Если Perl может определить, что текущий язык — UTF-8, он использует опубликованные правила Unicode; в противном случае он использует функцию C-библиотеки, которая даёт указанную классификацию. Например, isDIGIT_LC() при отсутствии UTF-8 языка возвращает результат вызова isdigit(). FALSE всегда возвращается, если входное значение не помещается в октет. На некоторых платформах, где функция C-библиотеки известна как неисправная, Perl изменяет её результат, чтобы соответствовать правилам стандарта POSIX.

Вариант isFOO_LC_uvchr действует точно так же, как isFOO_LC для входных значений меньше 256, но для больших значений возвращает классификацию Unicode кодовой точки.

Варианты isFOO_LC_utf8 и isFOO_LC_utf8_safe похожи на isFOO_LC_uvchr, но используются для строк в кодировке UTF-8. Эти две формы — разные имена для одного и того же. Каждый вызов одного из них классифицирует первый символ строки, начиная с p. Второй параметр, e, указывает на любое место в строке за первым символом, до одного байта после конца всей строки. Хотя оба варианта идентичны, суффикс _safe в одном из имён подчёркивает, что он не будет пытаться читать за пределами e - 1, при условии, что ограничение s < e истинно (это гарантируется в -DDEBUGGING сборках). Если UTF-8 для входного символа каким-то образом повреждён, программа может завершиться ошибкой или функция может вернуть FALSE по усмотрению реализации и может измениться в будущих версиях.

isALPHA

Возвращает булево значение, указывающее, является ли указанный ввод одним из [A-Za-z], аналогично m/[[:alpha:]]/. См. начало этого раздела здесь для объяснения вариантов isALPHA_A, isALPHA_L1, isALPHA_uvchr, isALPHA_utf8, isALPHA_utf8_safe, isALPHA_LC, isALPHA_LC_uvchr, isALPHA_LC_utf8, и isALPHA_LC_utf8_safe.

bool    isALPHA(int ch)

isALPHANUMERIC

Возвращает булево значение, указывающее, является ли указанный символ одним из [A-Za-z0-9], аналогично m/[[:alnum:]]/. См. начало этого раздела здесь для объяснения вариантов isALPHANUMERIC_A, isALPHANUMERIC_L1, isALPHANUMERIC_uvchr, isALPHANUMERIC_utf8, isALPHANUMERIC_utf8_safe, isALPHANUMERIC_LC, isALPHANUMERIC_LC_uvchr, isALPHANUMERIC_LC_utf8, и isALPHANUMERIC_LC_utf8_safe.

Синоним (от использования которого рекомендуется воздержаться) — isALNUMC (приставка C означает, что это соответствует определению буквенно-цифровых символов языка C). Также существуют варианты isALNUMC_A, isALNUMC_L1 isALNUMC_LC, и isALNUMC_LC_uvchr.

bool    isALPHANUMERIC(int ch)

isASCII

Возвращает булево значение, указывающее, является ли указанный символ одним из 128 символов набора символов ASCII, аналогично m/[[:ascii:]]/. В платформах, не поддерживающих ASCII, возвращает ИСТИНА, если этот символ соответствует символу ASCII. Варианты isASCII_A() и isASCII_L1() идентичны isASCII(). См. начало этого раздела здесь для объяснения вариантов isASCII_uvchr, isASCII_utf8, isASCII_utf8_safe, isASCII_LC, isASCII_LC_uvchr, isASCII_LC_utf8, и isASCII_LC_utf8_safe. Однако обратите внимание, что некоторые платформы не имеют функцию C-библиотеки isascii(). В этих случаях варианты, имена которых содержат LC, эквивалентны соответствующим без этой приставки.

bool    isASCII(int ch)

isBLANK

Возвращает булево значение, указывающее, является ли указанный символ символом пробела, аналогично m/[[:blank:]]/. См. начало этого раздела здесь для объяснения вариантов isBLANK_A, isBLANK_L1, isBLANK_uvchr, isBLANK_utf8, isBLANK_utf8_safe, isBLANK_LC, isBLANK_LC_uvchr, isBLANK_LC_utf8, и isBLANK_LC_utf8_safe. Однако обратите внимание, что некоторые платформы не имеют функцию C-библиотеки isblank(). В этих случаях варианты, имена которых содержат LC, эквивалентны соответствующим без этой приставки.

bool    isBLANK(char ch)

isCNTRL

Возвращает булево значение, указывающее, является ли указанный символ управляющим символом, аналогично m/[[:cntrl:]]/. См. начало этого раздела здесь для объяснения вариантов isCNTRL_A, isCNTRL_L1, isCNTRL_uvchr, isCNTRL_utf8, isCNTRL_utf8_safe, isCNTRL_LC, isCNTRL_LC_uvchr, isCNTRL_LC_utf8 и isCNTRL_LC_utf8_safe. В платформах EBCDIC, вы почти всегда захотите использовать вариант isCNTRL_L1.

bool    isCNTRL(char ch)

isDIGIT

Возвращает булево значение, указывающее, является ли указанный символ цифрой, аналогично m/[[:digit:]]/. Варианты isDIGIT_A и isDIGIT_L1 идентичны isDIGIT. См. начало этого раздела здесь для объяснения вариантов isDIGIT_uvchr, isDIGIT_utf8, isDIGIT_utf8_safe, isDIGIT_LC, isDIGIT_LC_uvchr, isDIGIT_LC_utf8, и isDIGIT_LC_utf8_safe.

bool    isDIGIT(char ch)

isGRAPH

Возвращает булево значение, указывающее, является ли указанный символ графическим символом, аналогично m/[[:graph:]]/. См. начало этого раздела здесь для объяснения вариантов isGRAPH_A, isGRAPH_L1, isGRAPH_uvchr, isGRAPH_utf8, isGRAPH_utf8_safe, isGRAPH_LC, isGRAPH_LC_uvchr, isGRAPH_LC_utf8_safe, и isGRAPH_LC_utf8_safe.

bool    isGRAPH(char ch)

isIDCONT

Возвращает булево значение, указывающее, может ли указанный символ быть вторым или последующим символом идентификатора. Это очень близко, но не совсем то же самое, что и официальное свойство Unicode XID_Continue. Разница в том, что это возвращает true только в том случае, если входной символ также соответствует "isWORDCHAR". См. начало этого раздела здесь для объяснения вариантов isIDCONT_A, isIDCONT_L1, isIDCONT_uvchr, isIDCONT_utf8, isIDCONT_utf8_safe, isIDCONT_LC, isIDCONT_LC_uvchr, isIDCONT_LC_utf8, и isIDCONT_LC_utf8_safe.

bool    isIDCONT(char ch)

isIDFIRST

Возвращает булево значение, указывающее, может ли указанный символ быть первым символом идентификатора. Это очень близко, но не совсем то же самое, что и официальное свойство Unicode XID_Start. Разница в том, что это возвращает true только в том случае, если входной символ также соответствует "isWORDCHAR". См. начало этого раздела здесь для объяснения вариантов isIDFIRST_A, isIDFIRST_L1, isIDFIRST_uvchr, isIDFIRST_utf8, isIDFIRST_utf8_safe, isIDFIRST_LC, isIDFIRST_LC_uvchr, isIDFIRST_LC_utf8, и isIDFIRST_LC_utf8_safe.

bool    isIDFIRST(char ch)

isLOWER

Возвращает булево значение, указывающее, является ли указанный символ строчной буквой, аналогично m/[[:lower:]]/. См. начало этого раздела здесь для объяснения вариантов isLOWER_A, isLOWER_L1, isLOWER_uvchr, isLOWER_utf8, isLOWER_utf8_safe, isLOWER_LC, isLOWER_LC_uvchr, isLOWER_LC_utf8, и isLOWER_LC_utf8_safe.

bool    isLOWER(char ch)

isOCTAL

Возвращает булево значение, указывающее, является ли указанный символ восьмеричной цифрой [0-7]. Два единственных варианта — isOCTAL_A и isOCTAL_L1; каждый идентичен isOCTAL.

bool    isOCTAL(char ch)

isPRINT

Возвращает булево значение, указывающее, является ли указанный символ печатным символом, аналогично m/[[:print:]]/. См. начало этого раздела здесь для объяснения вариантов isPRINT_A, isPRINT_L1, isPRINT_uvchr, isPRINT_utf8, isPRINT_utf8_safe, isPRINT_LC, isPRINT_LC_uvchr, isPRINT_LC_utf8, и isPRINT_LC_utf8_safe.

bool    isPRINT(char ch)

isPSXSPC

(сокращенно Posix Space) Начиная с версии 5.18, этот вариант во всех своих формах идентичен соответствующим isSPACE() макросам. Локализованные формы этого макроса идентичны соответствующим isSPACE() формам во всех выпусках Perl. В выпусках до 5.18 нелокализованные формы отличаются от своих isSPACE() форм только тем, что isSPACE() формы не соответствуют вертикальной табуляции, а isPSXSPC() формы соответствуют. В остальном они идентичны. Таким образом, этот макрос аналогичен тому, что m/[[:space:]]/ соответствует в регулярном выражении. См. начало этого раздела здесь для объяснения вариантов isPSXSPC_A, isPSXSPC_L1, isPSXSPC_uvchr, isPSXSPC_utf8, isPSXSPC_utf8_safe, isPSXSPC_LC, isPSXSPC_LC_uvchr, isPSXSPC_LC_utf8, и isPSXSPC_LC_utf8_safe.

bool    isPSXSPC(char ch)

isPUNCT

Возвращает булево значение, указывающее, является ли указанный символ пунктуационным символом, аналогично m/[[:punct:]]/. Обратите внимание, что определение того, что является пунктуацией, не такое прямое, как хотелось бы. Подробности см. в разделе ""POSIX Character Classes" в perlrecharclass. См. начало этого раздела здесь для объяснения вариантов isPUNCT_A, isPUNCT_L1, isPUNCT_uvchr, isPUNCT_utf8, isPUNCT_utf8_safe, isPUNCT_LC, isPUNCT_LC_uvchr, isPUNCT_LC_utf8, и isPUNCT_LC_utf8_safe.

bool    isPUNCT(char ch)

isSPACE

Возвращает булево значение, указывающее, является ли указанный символ символом пробела. Это аналогично тому, что m/\s/ соответствует в регулярном выражении. Начиная с Perl 5.18, это также соответствует тому, что делает m/[[:space:]]/. До версии 5.18 только локализованные формы этого макроса (с LC в их именах) точно соответствовали тому, что делал m/[[:space:]]/. В этих выпусках единственное отличие в нелокализованных вариантах заключалось в том, что isSPACE() не соответствовал вертикальной табуляции. (См. "isPSXSPC" для макроса, который соответствует вертикальной табуляции во всех выпусках.) См. начало этого раздела здесь для объяснения вариантов isSPACE_A, isSPACE_L1, isSPACE_uvchr, isSPACE_utf8, isSPACE_utf8_safe, isSPACE_LC, isSPACE_LC_uvchr, isSPACE_LC_utf8, и isSPACE_LC_utf8_safe.

bool    isSPACE(char ch)

isUPPER

Возвращает булево значение, указывающее, является ли указанный символ заглавной буквой, аналогично m/[[:upper:]]/. См. начало этого раздела здесь для объяснения вариантов isUPPER_A, isUPPER_L1, isUPPER_uvchr, isUPPER_utf8, isUPPER_utf8_safe, isUPPER_LC, isUPPER_LC_uvchr, isUPPER_LC_utf8, и isUPPER_LC_utf8_safe.

bool    isUPPER(char ch)

isWORDCHAR

Возвращает логическое значение, указывающее, является ли указанный символ символом слова, аналогично тому, как m/\w/ и m/[[:word:]]/ соответствуют в регулярном выражении. Символ слова — это буквенный символ, десятичная цифра, символ пунктуации для соединения (например, нижнее подчёркивание) или символ «метки», который присоединяется к одному из них (например, какой-то диакритический знак). isALNUM() является синонимом, предоставленным для обратной совместимости, даже если символ слова включает больше, чем стандартное значение символа в языке C, относящееся к алфавитно-цифровым символам. См. начало этого раздела вверху этого раздела для объяснения вариантов isWORDCHAR_A, isWORDCHAR_L1, isWORDCHAR_uvchr, isWORDCHAR_utf8, и isWORDCHAR_utf8_safe. isWORDCHAR_LC, isWORDCHAR_LC_uvchr, isWORDCHAR_LC_utf8, и isWORDCHAR_LC_utf8_safe также описаны там, но дополнительно включают собственное нижнее подчёркивание платформы.

bool    isWORDCHAR(char ch)

isXDIGIT

Возвращает логическое значение, указывающее, является ли указанный символ шестнадцатеричной цифрой. В диапазоне ASCII это [0-9A-Fa-f]. Варианты isXDIGIT_A() и isXDIGIT_L1() идентичны isXDIGIT(). См. начало этого раздела вверху этого раздела для объяснения вариантов isXDIGIT_uvchr, isXDIGIT_utf8, isXDIGIT_utf8_safe, isXDIGIT_LC, isXDIGIT_LC_uvchr, isXDIGIT_LC_utf8, и isXDIGIT_LC_utf8_safe.

bool    isXDIGIT(char ch)

Клонирование интерпретатора

perl_clone

Создаёт и возвращает новый интерпретатор, клонируя текущий.

perl_clone принимает эти флаги в качестве параметров:

CLONEf_COPY_STACKS - используется для, ну, копирования стеков также, без него мы клонируем только данные и обнуляем стеки, с ним мы копируем стеки, и новый интерпретатор Perl готов к запуску в точной той же точке, что и предыдущий. Псевдо-код вилки использует COPY_STACKS, в то время как threads->create - нет.

CLONEf_KEEP_PTR_TABLE - perl_clone сохраняет таблицу указателей ptr_table со значением указателя старой переменной в качестве ключа и новой переменной в качестве значения, это позволяет ему проверять, клонировалась ли что-то, и не клонировать это снова, а вместо этого просто использовать значение и увеличить счётчик ссылок. Если KEEP_PTR_TABLE не установлен, то perl_clone удалит таблицу ptr_table, используя функцию ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;. Причина для её сохранения заключается в том, что вы хотите дублировать некоторые свои собственные переменные, которые находятся вне графа, который Perl сканирует.

CLONEf_CLONE_HOST - Это функция для win32, она игнорируется в Unix, она сообщает коду win32host Perl (который на C++) клонировать себя, это необходимо в win32, если вы хотите запустить две потоки одновременно, если вы просто хотите выполнить некоторые действия в отдельном интерпретаторе Perl, а затем выбросить его и вернуться к исходному, вам ничего не нужно делать.

PerlInterpreter* perl_clone(
                     PerlInterpreter *proto_perl,
                     UV flags
                 )

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

BhkDISABLE

ПРИМЕЧАНИЕ: эта функция является экспериментальной и может быть изменена или удалена без предварительного уведомления.

Временно отключить запись в этой структуре BHK, очистив соответствующий флаг. which — это препроцессорный токен, указывающий, какую запись отключить.

void    BhkDISABLE(BHK *hk, which)

BhkENABLE

Включить запись в этой структуре BHK, установив соответствующий флаг. which — это препроцессорный токен, указывающий, какую запись включить. Это вызовет утверждение (в режиме -DDEBUGGING), если запись не содержит допустимого указателя.

void    BhkENABLE(BHK *hk, which)

BhkENTRY_set

Установить запись в структуре BHK и установить флаги, чтобы указать, что она допустима. which — это препроцессорный токен, указывающий, какую запись установить. Тип ptr зависит от записи.

void    BhkENTRY_set(BHK *hk, which, void *ptr)

blockhook_register

Регистрирует набор хуков, которые будут вызываться при изменении лексической области видимости Perl во время компиляции. См. "Хуксы области видимости во время компиляции" в perlguts.

ПРИМЕЧАНИЕ: эта функция должна быть явно вызвана как Perl_blockhook_register с параметром aTHX_.

void    Perl_blockhook_register(pTHX_ BHK *hk)

Хеши подсказок COP

cophh_2hv

Генерирует и возвращает стандартный хеш Perl, представляющий полный набор пар ключ/значение в хеше подсказок cop cophh. flags в настоящее время не используется и должен быть нулём.

HV *    cophh_2hv(const COPHH *cophh, U32 flags)

cophh_copy

Создаёт и возвращает полную копию хеша подсказок cop cophh.

COPHH * cophh_copy(COPHH *cophh)

cophh_delete_pv

Как "cophh_delete_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

COPHH * cophh_delete_pv(const COPHH *cophh,
                        const char *key, U32 hash,
                        U32 flags)

cophh_delete_pvn

Удаляет ключ и связанное с ним значение из хеша подсказок cop cophh, и возвращает изменённый хеш. Возвращаемый указатель на хеш, как правило, не совпадает с указателем на хеш, который был передан на вход. Входной хеш потребляется функцией, и указатель на него не должен использоваться впоследствии. Используйте "cophh_copy", если вам нужны оба хеша.

Ключ задаётся с помощью keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, байты ключа интерпретируются как UTF-8, в противном случае они интерпретируются как Latin-1. hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен.

COPHH * cophh_delete_pvn(COPHH *cophh,
                         const char *keypv,
                         STRLEN keylen, U32 hash,
                         U32 flags)

cophh_delete_pvs

Как "cophh_delete_pvn", но принимает строку без модификатора длины вместо пары строка/длина, и без предварительно вычисленного хеша.

COPHH * cophh_delete_pvs(const COPHH *cophh, "key",
                         U32 flags)

cophh_delete_sv

Как "cophh_delete_pvn", но принимает скаляр Perl вместо пары строка/длина.

COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
                        U32 hash, U32 flags)

cophh_fetch_pv

Как "cophh_fetch_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

SV *    cophh_fetch_pv(const COPHH *cophh,
                       const char *key, U32 hash,
                       U32 flags)

cophh_fetch_pvn

Ищет запись в хеше подсказок cop cophh с ключом, заданным с помощью keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, байты ключа интерпретируются как UTF-8, в противном случае они интерпретируются как Latin-1. hash — это предварительно вычисленный хеш строки ключа или ноль, если он не был предварительно вычислен. Возвращает смертную копию скалярного значения, связанного с ключом, или &PL_sv_placeholder, если значение, связанное с ключом, отсутствует.

SV *    cophh_fetch_pvn(const COPHH *cophh,
                        const char *keypv,
                        STRLEN keylen, U32 hash,
                        U32 flags)

cophh_fetch_pvs

Как "cophh_fetch_pvn", но принимает строку без модификатора длины вместо пары строка/длина, и без предварительно вычисленного хеша.

SV *    cophh_fetch_pvs(const COPHH *cophh, "key",
                        U32 flags)

cophh_fetch_sv

Как "cophh_fetch_pvn", но принимает скаляр Perl вместо пары строка/длина.

SV *    cophh_fetch_sv(const COPHH *cophh, SV *key,
                       U32 hash, U32 flags)

cophh_free

Утилизирует хеш подсказок cop cophh, освобождая все ресурсы, связанные с ним.

void    cophh_free(COPHH *cophh)

cophh_new_empty

Генерирует и возвращает новый пустой хеш подсказок cop, не содержащий записей.

COPHH * cophh_new_empty()

cophh_store_pv

Как "cophh_store_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

COPHH * cophh_store_pv(const COPHH *cophh,
                       const char *key, U32 hash,
                       SV *value, U32 flags)

cophh_store_pvn

Сохраняет значение, связанное с ключом, в хеше подсказок cop cophh, и возвращает изменённый хеш. Возвращаемый указатель на хеш, как правило, не совпадает с указателем на хеш, который был передан на вход. Входной хеш потребляется функцией, и указатель на него не должен использоваться впоследствии. Используйте "cophh_copy", если вам нужны оба хеша.

value — это скалярное значение, которое нужно сохранить для этого ключа. value копируется этой функцией, которая, таким образом, не берёт на себя ответственность за ссылку на него, и последующие изменения скаляра не будут отражены в значении, видимом в хеше подсказок cop. Сложные типы скаляров не будут сохраняться с целостностью ссылок, но будут приведены к строкам.

COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
                        STRLEN keylen, U32 hash,
                        SV *value, U32 flags)

cophh_store_pvs

Как "cophh_store_pvn", но принимает строку без модификатора длины вместо пары строка/длина, и без предварительно вычисленного хеша.

COPHH * cophh_store_pvs(const COPHH *cophh, "key",
                        SV *value, U32 flags)

cophh_store_sv

Как "cophh_store_pvn", но принимает скаляр Perl вместо пары строка/длина.

COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
                       U32 hash, SV *value, U32 flags)

Чтение подсказок COP

cop_hints_2hv

Генерирует и возвращает стандартный Perl-хэш, представляющий полный набор записей подсказок в cop cop. flags в настоящее время не используется и должен быть равен нулю.

HV *    cop_hints_2hv(const COP *cop, U32 flags)

cop_hints_fetch_pv

Аналогично "cop_hints_fetch_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

SV *    cop_hints_fetch_pv(const COP *cop,
                           const char *key, U32 hash,
                           U32 flags)

cop_hints_fetch_pvn

Ищет запись подсказки в cop cop с ключом, заданным keypv и keylen. Если flags имеет установленный бит COPHH_KEY_UTF8, октеты ключа интерпретируются как UTF-8, в противном случае — как Latin-1. hash — предварительно вычисленный хэш строки ключа или ноль, если он не был предварительно вычислен. Возвращает смертную скалярную копию значения, связанного с ключом, или &PL_sv_placeholder, если значение, связанное с ключом, отсутствует.

SV *    cop_hints_fetch_pvn(const COP *cop,
                            const char *keypv,
                            STRLEN keylen, U32 hash,
                            U32 flags)

cop_hints_fetch_pvs

Аналогично "cop_hints_fetch_pvn", но принимает строку-литерал вместо пары строка/длина и не использует предварительно вычисленный хэш.

SV *    cop_hints_fetch_pvs(const COP *cop, "key",
                            U32 flags)

cop_hints_fetch_sv

Аналогично "cop_hints_fetch_pvn", но принимает Perl-скаляр вместо пары строка/длина.

SV *    cop_hints_fetch_sv(const COP *cop, SV *key,
                           U32 hash, U32 flags)

CopLABEL

Возвращает метку, прикреплённую к cop.

const char * CopLABEL(COP *const cop)

CopLABEL_len

Возвращает метку, прикрепленную к cop, и сохраняет ее длину в байтах в *len.

const char * CopLABEL_len(COP *const cop, STRLEN *len)

CopLABEL_len_flags

Возвращает метку, прикреплённую к cop, и сохраняет её длину в байтах в *len. По возвращении *flags будет установлено в SVf_UTF8 или 0.

const char * CopLABEL_len_flags(COP *const cop,
                                STRLEN *len, U32 *flags)

Операторы-пользователя

custom_op_register

Регистрация пользовательского оператора. См. "Операторы-пользователя" в perlguts.

ПРИМЕЧАНИЕ: эта функция должна быть явно вызвана как Perl_custom_op_register с параметром aTHX_.

void    Perl_custom_op_register(pTHX_ 
                                Perl_ppaddr_t ppaddr,
                                const XOP *xop)

Perl_custom_op_xop

Возвращает структуру XOP для заданного пользовательского оператора. Этот макрос следует считать внутренним для OP_NAME и других макросов доступа: используйте их вместо него. Этот макрос вызывает функцию. До версии 5.19.6, это была функция.

const XOP * Perl_custom_op_xop(pTHX_ const OP *o)

XopDISABLE

Временное отключение члена XOP путём сброса соответствующего флага.

void    XopDISABLE(XOP *xop, which)

XopENABLE

Восстановление активности члена XOP, который был отключён.

void    XopENABLE(XOP *xop, which)

XopENTRY

Возвращает члена структуры XOP. which — cpp-токен, указывающий, какой элемент вернуть. Если элемент не установлен, возвращается значение по умолчанию. Тип возвращаемого значения зависит от which. Этот макрос оценивает свои аргументы более одного раза. Если вы используете Perl_custom_op_xop для получения XOP * из OP *, используйте более эффективный "XopENTRYCUSTOM".

XopENTRY(XOP *xop, which)

XopENTRYCUSTOM

Точно так же, как и XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which), но более эффективно. Параметр which идентичен "XopENTRY".

XopENTRYCUSTOM(const OP *o, which)

XopENTRY_set

Устанавливает член структуры XOP. which — cpp-токен, указывающий, какой элемент установить. См. "Операторы-пользователя" в perlguts для получения подробной информации о доступных членах и их использовании. Этот макрос оценивает свои аргументы более одного раза.

void    XopENTRY_set(XOP *xop, which, value)

XopFLAGS

Возвращает флаги XOP.

U32     XopFLAGS(XOP *xop)

Функции манипулирования CV

В этом разделе описываются функции для манипулирования CV, которые представляют собой значения кода или подпрограммы. Дополнительную информацию см. в perlguts.

caller_cx

Аналог caller() для XSUB-авторов. Возвращаемая структура PERL_CONTEXT позволяет получить всю информацию, возвращаемую Perl вызовом caller. Обратите внимание, что XSUB не имеют фрейма стека, поэтому caller_cx(0, NULL) возвращает информацию для непосредственно окружающего Perl-кода.

Эта функция пропускает автоматические вызовы &DB::sub, осуществляемые от имени отладчика. Если запрошенный фрейм стека был подпрограммой, вызванной DB::sub, возвращаемое значение будет фреймом для вызова DB::sub, так как это имеет правильный номер строки/и т. д. для места вызова. Если dbcxp не NULL, он будет установлен в указатель на фрейм для самого вызова подпрограммы.

const PERL_CONTEXT * caller_cx(
                         I32 level,
                         const PERL_CONTEXT **dbcxp
                     )

CvSTASH

Возвращает хранилище (stash) CV. Хранилище — это хеш таблицы символов, содержащий переменные пакета, относящиеся к пакету, в котором была определена подпрограмма. Дополнительную информацию см. в perlguts.

Это также имеет специальное применение с XS AUTOLOAD подпрограммами. См. "Автозагрузка с XSUB" в perlguts.

HV*     CvSTASH(CV* cv)

find_runcv

Находит CV, соответствующий текущей выполняемой подпрограмме или eval. Если db_seqp не NULL, пропускаются CV из пакета DB и *db_seqp заполняется номером последовательности cop в момент входа кода DB::. (Это позволяет отладчикам выполнять eval в области точки останова, а не в области самого отладчика.)

CV*     find_runcv(U32 *db_seqp)

get_cv

Использует strlen для получения длины name, а затем вызывает get_cvn_flags.

ПРИМЕЧАНИЕ: perl_ форма этой функции устарела.

CV*     get_cv(const char* name, I32 flags)

get_cvn_flags

Возвращает CV указанной Perl-подпрограммы. flags передаются в gv_fetchpvn_flags. Если GV_ADD установлено, и Perl-подпрограмма не существует, она будет объявлена (что имеет тот же эффект, что и sub name;). Если GV_ADD не установлено, и подпрограмма не существует, возвращается NULL.

CV*     get_cvn_flags(const char* name, STRLEN len,
                      I32 flags)

`xsubpp` переменные и внутренние функции

ax

Переменная, устанавливаемая xsubpp для обозначения смещения начала стека, используемая макросами ST, XSprePUSH и XSRETURN. Макрос dMARK должен быть вызван перед установкой переменной MARK.

I32     ax

CLASS

Переменная, устанавливаемая xsubpp для обозначения имени класса для конструктора C++ XS. Это всегда char*. См. "THIS".

char*   CLASS

dAX

Устанавливает переменную ax. Обычно обрабатывается автоматически xsubpp путём вызова dXSARGS.

dAX;

dAXMARK

Устанавливает переменную ax и переменную метки стека mark. Обычно обрабатывается автоматически xsubpp путём вызова dXSARGS.

dAXMARK;

dITEMS

Устанавливает переменную items. Обычно обрабатывается автоматически xsubpp путём вызова dXSARGS.

dITEMS;

dUNDERBAR

Устанавливает любые переменные, необходимые макросу UNDERBAR. Раньше использовался для определения padoff_du, но сейчас он бесполезен. Тем не менее, настоятельно рекомендуется его использовать для обеспечения совместимости в прошлом и будущем.

dUNDERBAR;

dXSARGS

Устанавливает указатели на стек и метку для XSUB, вызывая dSP и dMARK. Устанавливает переменные ax и items путём вызова dAX и dITEMS. Обычно обрабатывается автоматически xsubpp.

dXSARGS;

dXSI32

Устанавливает переменную ix для XSUB, имеющего псевдонимы. Обычно обрабатывается автоматически xsubpp.

dXSI32;

items

Переменная, устанавливаемая xsubpp для обозначения количества элементов в стеке. См. "Список параметров переменной длины" в perlxs.

I32     items

ix

Переменная, устанавливаемая xsubpp для обозначения того, какой из псевдонимов XSUB был использован для его вызова. См. "Ключевое слово ALIAS" в perlxs.

I32     ix

RETVAL

Переменная, устанавливаемая xsubpp для хранения возвращаемого значения XSUB. Это всегда правильный тип для XSUB. См. "Переменная RETVAL" в perlxs.

(whatever)      RETVAL

ST

Используется для доступа к элементам стека XSUB.

SV*     ST(int ix)

THIS

Переменная, устанавливаемая xsubpp для обозначения объекта в C++ XSUB. Это всегда правильный тип для C++ объекта. См. "CLASS" и "Использование XS с C++" в perlxs.

(whatever)      THIS

UNDERBAR

SV*, соответствующий переменной $_. Работает даже если в области видимости есть лексическая переменная $_.

XS

Макрос для объявления XSUB и его списка C-параметров. Обрабатывается xsubpp. Это то же самое, что использование более явного макроса XS_EXTERNAL.

XS_EXTERNAL

Макрос для явного объявления XSUB и его списка C-параметров с экспортом символов.

XS_INTERNAL

Макрос для объявления XSUB и его списка C-параметров без экспорта символов. Это обрабатывается xsubpp и, как правило, предпочтительнее ненужного экспорта символов XSUB.

Утилиты отладки

dump_all

Выводит весь optree текущей программы, начиная с PL_main_root и заканчивая STDERR. Также выводит optree для всех видимых подпрограмм в PL_defstash.

void    dump_all()

dump_packsubs

Выводит optree для всех видимых подпрограмм в stash.

void    dump_packsubs(const HV* stash)

op_class

Учитывая операцию, определить тип структуры, в которой она была выделена. Возвращает одно из перечислений OPclass, таких как OPclass_LISTOP.

OPclass op_class(const OP *o)

op_dump

Выводит optree, начиная с OP o и заканчивая STDERR.

void    op_dump(const OP *o)

sv_dump

Выводит содержимое SV в файловый дескриптор STDERR.

Пример вывода см. в Devel::Peek.

void    sv_dump(SV* sv)

Функции отображения и вывода

pv_display

Аналогично

pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);

за исключением того, что к строке будет добавлен дополнительный "\0", когда len > cur и pv[cur] равно "\0".

Обратите внимание, что конечная строка может быть на 7 символов длиннее, чем pvlim.

char*   pv_display(SV *dsv, const char *pv, STRLEN cur,
                   STRLEN len, STRLEN pvlim)

pv_escape

Экранирует не более первых count символов pv и помещает результаты в dsv таким образом, чтобы размер экранированной строки не превышал max символов и не содержал никаких неполных последовательностей экранирования. Количество экранированных байтов будет возвращено в параметре STRLEN *escaped , если он не равен null. Когда параметр dsv равен null, фактического экранирования не происходит, но будет вычислено количество байтов, которые были бы экранированы, если бы он не был равен null.

Если flags содержит PERL_PV_ESCAPE_QUOTE , то все двойные кавычки в строке также будут экранированы.

Обычно SV очищается перед подготовкой экранированной строки, но когда PERL_PV_ESCAPE_NOCLEAR установлено, этого не произойдет.

Если PERL_PV_ESCAPE_UNI установлено, входная строка обрабатывается как UTF-8, если PERL_PV_ESCAPE_UNI_DETECT установлено, входная строка сканируется с помощью is_utf8_string() для определения того, является ли она UTF-8.

Если PERL_PV_ESCAPE_ALL установлено, все символы ввода выводятся с использованием экранирования в стиле \x01F1, иначе, если PERL_PV_ESCAPE_NONASCII установлено, только символы, не являющиеся ASCII, будут экранированы в этом стиле; в противном случае только символы с кодами выше 255 будут экранированы таким образом; другие непечатаемые символы будут использовать восьмеричный или стандартный вид экранирования, например \n. В противном случае, если PERL_PV_ESCAPE_NOBACKSLASH , все символы ниже 255 будут рассматриваться как печатаемые и выводятся как литералы.

Если PERL_PV_ESCAPE_FIRSTCHAR установлено, экранируется только первый символ строки, независимо от max. Если вывод должен быть в шестнадцатеричном формате, он будет возвращен как обычная шестнадцатеричная последовательность. Таким образом, выход будет либо одним символом, восьмеричной последовательностью экранирования, специальным экранированием, таким как \n , или шестнадцатеричным значением.

Если PERL_PV_ESCAPE_RE установлено, используемый символ экранирования будет "%", а не "\\". Это связано с тем, что выражения регулярных выражений часто содержат последовательности с обратным слэшем, тогда как "%" не является особенно распространённым символом в шаблонах.

Возвращает указатель на экранированный текст, хранящийся в dsv.

char*   pv_escape(SV *dsv, char const * const str,
                  const STRLEN count, const STRLEN max,
                  STRLEN * const escaped,
                  const U32 flags)

pv_pretty

Преобразует строку в удобочитаемый вид, обрабатывая экранирование через pv_escape() и поддерживая цитирование и многоточие.

Если установлен флаг PERL_PV_PRETTY_QUOTE, результат будет заключен в двойные кавычки, а любые двойные кавычки в строке будут экранированы. В противном случае, если установлен флаг PERL_PV_PRETTY_LTGT, результат будет заключён в угловые скобки.

Если установлен флаг PERL_PV_PRETTY_ELLIPSES и не все символы в строке были выведены, то к строке будет добавлен многоточие .... Обратите внимание, что это происходит ПОСЛЕ цитирования.

Если start_color не равно null, то оно будет вставлено после открывающей кавычки (если она есть), но перед экранированным текстом. Если end_color не равно null, то оно будет вставлено после экранированного текста, но перед кавычками или многоточием.

Возвращает указатель на отформатированный текст, хранящийся в dsv.

char*   pv_pretty(SV *dsv, char const * const str,
                  const STRLEN count, const STRLEN max,
                  char const * const start_color,
                  char const * const end_color,
                  const U32 flags)

Встраиваемые функции

cv_clone

Клонировать CV, создавая лексическое замыкание. proto предоставляет прототип функции: её код, структуру заполнения и другие атрибуты. Прототип комбинируется с захватом внешних лексических переменных, на которые ссылается код, взятых из текущего экземпляра непосредственно окружающего кода.

CV*     cv_clone(CV* proto)

cv_name

Возвращает SV, содержащий имя CV, в основном для использования в сообщениях об ошибках. CV может на самом деле быть GV, в этом случае возвращаемый SV содержит имя GV. Всё, что не является GV или CV, обрабатывается как строка, уже содержащая имя подпрограммы, но это может измениться в будущем.

В качестве второго аргумента может быть передан SV. В этом случае имя будет назначено ему и оно будет возвращено. В противном случае возвращаемый SV будет новым смертным.

Если flags имеет установленный бит CV_NAME_NOTQUAL, то имя пакета не будет включено. Если первый аргумент не является ни CV, ни GV, этот флаг игнорируется (может быть изменено).

SV *    cv_name(CV *cv, SV *sv, U32 flags)

cv_undef

Очистить все активные компоненты CV. Это может произойти либо явным undef &foo, либо при уменьшении счётчика ссылок до нуля. В первом случае мы сохраняем указатель CvOUTSIDE, чтобы все анонимные дочерние элементы могли следовать всей цепочке лексического охвата.

void    cv_undef(CV* cv)

find_rundefsv

Возвращает глобальную переменную $_.

SV*     find_rundefsv()

find_rundefsvoffset

УСТАРЕЛО! Планируется удалить эту функцию из будущей версии Perl. Не используйте её в новом коде; удалите из существующего кода.

До удаления лексической функции $_, эта функция находила позицию лексической переменной $_ в заполнителе текущей выполняющейся функции и возвращала смещение в текущем заполнителе, или NOT_IN_PAD.

Теперь она всегда возвращает NOT_IN_PAD.

PADOFFSET find_rundefsvoffset()

intro_my

«Ввести» my переменные в видимое состояние. Это вызывается во время парсинга в конце каждого оператора, чтобы сделать лексические переменные видимыми для последующих операторов.

U32     intro_my()

load_module

Загружает модуль, имя которого указано в строковой части name. Обратите внимание, что должно быть указано фактическое имя модуля, а не его имя файла. Например, «Foo::Bar», а не «Foo/Bar.pm». ver, если задан и не равен NULL, обеспечивает семантику версий, аналогичную use Foo::Bar VERSION. Дополнительные аргументы могут использоваться для указания аргументов метода import() модуля, аналогично use Foo::Bar VERSION LIST; их точное обработка зависит от флагов. Аргумент flags — это битовое ИЛИ из любого из PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, или PERL_LOADMOD_IMPORT_OPS (или 0 для отсутствия флагов).

Если PERL_LOADMOD_NOIMPORT установлено, модуль загружается так, как будто со списком импорта пустым, как в use Foo::Bar (); это единственный случай, когда можно опустить дополнительные аргументы. В противном случае, если PERL_LOADMOD_IMPORT_OPS установлено, дополнительные аргументы должны состоять ровно из одного OP*, содержащего дерево операций, которое производит соответствующие аргументы импорта. В противном случае дополнительные аргументы должны быть значениями SV*, которые будут использоваться в качестве аргументов импорта; и список должен заканчиваться (SV*) NULL. Если ни PERL_LOADMOD_NOIMPORT, ни PERL_LOADMOD_IMPORT_OPS не установлено, указатель NULL требуется даже если аргументы импорта не нужны. Счётчик ссылок для каждого указанного аргумента SV* уменьшается. Кроме того, аргумент name изменяется.

Если PERL_LOADMOD_DENY установлено, модуль загружается так, как будто с no вместо use.

void    load_module(U32 flags, SV* name, SV* ver, ...)

my_exit

Обёртка для функции C-библиотеки exit(3), учитывая то, что говорится в "PL_exit_flags" в perlapi.

void    my_exit(U32 status)

newPADNAMELIST

Создаёт новый список имён заполнителей. max — это максимальный индекс, для которого выделяется память.

PADNAMELIST * newPADNAMELIST(size_t max)

newPADNAMEouter

Создаёт и возвращает новое имя заполнителя. Используйте эту функцию только для имён, которые ссылаются на внешние лексические переменные. (См. также "newPADNAMEpvn".) outer — это внешнее имя заполнителя, которое это имя дублирует. Возвращаемое имя заполнителя уже имеет установленный флаг PADNAMEt_OUTER.

PADNAME * newPADNAMEouter(PADNAME *outer)

newPADNAMEpvn

Создаёт и возвращает новое имя заполнителя. s должна быть строкой UTF-8. Не используйте эту функцию для имён заполнителей, которые указывают на внешние лексические переменные. См. "newPADNAMEouter".

PADNAME * newPADNAMEpvn(const char *s, STRLEN len)

nothreadhook

Заглушка, которая предоставляет обработчик потоков для perl_destruct, когда потоков нет.

int     nothreadhook()

pad_add_anon

Выделяет место в текущем заполнителе, компилируемом с помощью "pad_alloc", для анонимной функции, лексически заключённой внутри текущей компилируемой функции. Функция func связана в заполнителе, и её связь CvOUTSIDE с внешним охватом ослабляется, чтобы избежать цикла ссылок.

Один счётчик ссылок воруется, поэтому вам может потребоваться сделать SvREFCNT_inc(func).

optype должен быть кодом операции, указывающим тип операции, которую должен поддерживать элемент заполнителя. Это не влияет на операционные семантику, но используется для отладки.

PADOFFSET pad_add_anon(CV* func, I32 optype)

pad_add_name_pv

Точно так же, как "pad_add_name_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

PADOFFSET pad_add_name_pv(const char *name,
                          const U32 flags,
                          HV *typestash, HV *ourstash)

pad_add_name_pvn

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

namepv/namelen задают имя переменной, включая ведущий знак. Если typestash не равно null, имя относится к типизированной лексической переменной, и это идентифицирует тип. Если ourstash не равно null, это лексическая ссылка на переменную пакета, и это идентифицирует пакет. Следующие флаги могут быть объединены с помощью OR:

padadd_OUR          redundantly specifies if it's a package var
padadd_STATE        variable will retain value persistently
padadd_NO_DUP_CHECK skip check for lexical shadowing

       PADOFFSET pad_add_name_pvn(const char *namepv,
                                  STRLEN namelen, U32 flags,
                                  HV *typestash, HV *ourstash)

pad_add_name_sv

Точно так же, как "pad_add_name_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET pad_add_name_sv(SV *name, U32 flags,
                          HV *typestash, HV *ourstash)

pad_alloc

Выделяет место в текущем компилируемом заполнителе, возвращая смещение выделенного слота заполнителя. Имя изначально не прикреплено к слоту заполнителя. tmptype — это набор флагов, указывающих на тип требуемого элемента заполнителя, который будет установлен в SV значения для выделенного элемента заполнителя:

SVs_PADMY    named lexical variable ("my", "our", "state")
SVs_PADTMP   unnamed temporary store
SVf_READONLY constant shared between recursion levels

SVf_READONLY поддерживается здесь только начиная с perl 5.20. Чтобы работать и с более ранними версиями, используйте SVf_READONLY|SVs_PADTMP. SVf_READONLY не делает SV в слоте заполнителя только для чтения, но просто сообщает pad_alloc, что будет сделано только для чтения (вызывающим приложением), или, по крайней мере, должно рассматриваться как таковое.

PADOFFSET pad_alloc(I32 optype, U32 tmptype)

pad_findmy_pv

Точно так же, как "pad_findmy_pvn", но принимает строку с нулевым завершением вместо пары строка/длина.

PADOFFSET pad_findmy_pv(const char* name, U32 flags)

pad_findmy_pvn

Учитывая имя лексической переменной, найти её положение в текущем компилируемом заполнителе. namepv/namelen задают имя переменной, включая ведущий знак. flags зарезервировано и должно быть равно нулю. Если её нет в текущем заполнителе, но она появляется в заполнителе любого лексически окружающего охвата, то для неё добавляется псевдоэлемент в текущем заполнителе. Возвращает смещение в текущем заполнителе или NOT_IN_PAD если такая лексическая переменная не в области видимости.

PADOFFSET pad_findmy_pvn(const char* namepv,
                         STRLEN namelen, U32 flags)

pad_findmy_sv

Точно так же, как "pad_findmy_pvn", но принимает строку имени в виде SV вместо пары строка/длина.

PADOFFSET pad_findmy_sv(SV* name, U32 flags)

padnamelist_fetch

Извлекает имя заполнителя по заданному индексу.

PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
                            SSize_t key)

padnamelist_store

Сохраняет имя заполнителя (которое может быть пустым) по заданному индексу, освобождая любое существующее имя заполнителя в этом слоте.

PADNAME ** padnamelist_store(PADNAMELIST *pnl,
                             SSize_t key, PADNAME *val)

pad_setsv

Установить значение по смещению po в текущем (компилируемом или выполняемом) заполнителе. Используйте макрос PAD_SETSV() вместо прямого вызова этой функции.

void    pad_setsv(PADOFFSET po, SV* sv)

pad_sv

Получить значение по смещению po в текущем (компилируемом или выполняемом) заполнителе. Используйте макрос PAD_SV вместо прямого вызова этой функции.

SV*     pad_sv(PADOFFSET po)

pad_tidy

Приведение в порядок заполнителя в конце компиляции кода, к которому он принадлежит. Задачи, выполняемые здесь: удалить большую часть содержимого из заполнителей анонимных подпрограмм; присвоить ему @_; отметить временные объекты как таковые. type указывает тип подпрограммы:

padtidy_SUB        ordinary subroutine
padtidy_SUBCLONE   prototype for lexical closure
padtidy_FORMAT     format

    void    pad_tidy(padtidy_type type)

perl_alloc

Выделяет новый интерпретатор Perl. См. perlembed.

PerlInterpreter* perl_alloc()

perl_construct

Инициализирует новый интерпретатор Perl. См. perlembed.

void    perl_construct(PerlInterpreter *my_perl)

perl_destruct

Завершает работу интерпретатора Perl. См. perlembed для обучающего материала.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". Он может быть инициализирован с помощью "perl_parse" и использован с помощью "perl_run" и другими средствами. Эта функция должна вызываться для любого интерпретатора Perl, созданного с помощью "perl_construct", даже если последующие операции с ним завершились ошибкой, например, если "perl_parse" вернула ненулевое значение.

Если слово PL_exit_flags интерпретатора имеет установленный флаг PERL_EXIT_DESTRUCT_END, то эта функция выполнит код в блоках END перед выполнением остальной части процесса уничтожения. Если необходимо использовать интерпретатор между "perl_parse" и "perl_destruct" помимо вызова "perl_run", то этот флаг следует установить на ранней стадии. Это важно, если "perl_run" не будет вызван или если будут выполнены какие-либо другие действия помимо вызова "perl_run".

Возвращает значение, подходящее для передачи в функцию C-библиотеки exit (или для возврата из main), которое служит кодом завершения, указывающим на характер завершения работы интерпретатора. Это учитывает любые ошибки в "perl_parse" и любое преждевременное завершение из "perl_run". Код завершения имеет тип, необходимый для операционной системы хоста, поэтому из-за различий в соглашениях о кодах завершения он не является переносимым для интерпретации определенных числовых значений как имеющих определенный смысл.

int     perl_destruct(PerlInterpreter *my_perl)

perl_free

Освобождает интерпретатор Perl. См. perlembed.

void    perl_free(PerlInterpreter *my_perl)

perl_parse

Указывает интерпретатору Perl на разбор скрипта Perl. Это выполняет большую часть начальной инициализации интерпретатора Perl. См. perlembed для обучающего материала.

my_perl указывает на интерпретатор Perl, который должен разобрать скрипт. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct". xsinit указывает на функцию обратного вызова, которая будет вызвана для настройки возможности загрузки расширений XS для этого интерпретатора Perl, или может быть равна null для того, чтобы не выполнять такую настройку.

argc и argv[argc] передают набор аргументов командной строки интерпретатору Perl, как это обычно передается функции main программы на C. argv[argc] должно быть равно null. Эти аргументы указывают на скрипт для разбора, либо путем указания имени файла скрипта, либо путем предоставления скрипта в -e параметре. Если $0 будет записано в интерпретатор Perl, то строки аргументов должны находиться в памяти, доступной для записи, а не являться просто строковыми константами.

env указывает набор переменных среды, которые будут использоваться этим интерпретатором Perl. Если не равно null, он должен указывать на нуль-терминированный массив строк среды. Если равно null, интерпретатор Perl будет использовать среду, предоставленную глобальной переменной environ.

Эта функция инициализирует интерпретатор, парсит и компилирует скрипт, указанный аргументами командной строки. Это включает выполнение кода в блоках BEGIN, UNITCHECK, и CHECK. Оно не выполняет блоки INIT или основную программу.

Возвращает целое число с несколько сложной интерпретацией. Правильное использование возвращаемого значения — как булевое значение, указывающее на наличие ошибки при инициализации. Если возвращено нулевое значение, это указывает на успешную инициализацию, и безопасно приступить к вызову "perl_run" и использовать его. Если возвращено ненулевое значение, это указывает на какую-то проблему, означающую, что интерпретатор хочет завершить работу. Интерпретатор не должен быть просто оставлен при такой ошибке; вызывающая сторона должна корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), служащим кодом завершения, указывающим на характер завершения инициализации. Однако это не переносимо из-за различных соглашений о кодах завершения. Сохраняется историческая ошибка: если встроенная функция Perl exit вызывается во время выполнения этой функции с типом выхода, подразумевающим нулевой код выхода в соответствии с соглашениями операционной системы хоста, то эта функция возвращает ноль, а не ненулевое значение. Эта ошибка [perl #2754] приводит к вызову perl_run (и, следовательно, к выполнению блоков INIT и основной программы) несмотря на вызов exit. Она сохранена, потому что популярный модуль установки модулей полагается на нее, и ей требуется время, чтобы ее исправить. Эта проблема [perl #132577], а исходная ошибка должна быть исправлена в Perl 5.30.

int     perl_parse(PerlInterpreter *my_perl,
                   XSINIT_t xsinit, int argc,
                   char** argv, char** env)

perl_run

Указывает интерпретатору Perl на выполнение его основной программы. См. perlembed для обучающего материала.

my_perl указывает на интерпретатор Perl. Он должен быть предварительно создан с помощью "perl_alloc" и "perl_construct" и инициализирован с помощью "perl_parse". Эта функция не должна вызываться, если "perl_parse" вернула ненулевое значение, указывая на ошибку инициализации или компиляции.

Эта функция выполняет код в блоках INIT, а затем выполняет главную программу. Выполняемый код определяется предыдущим вызовом "perl_parse". Если у слова PL_exit_flags интерпретатора не установлен флаг PERL_EXIT_DESTRUCT_END, то эта функция также выполнит код в блоках END. Если требуется дальнейшее использование интерпретатора после вызова этой функции, то блоки END следует отложить до времени "perl_destruct", установив этот флаг.

Возвращает целое число с несколько сложной интерпретацией. Правильное использование возвращаемого значения — как булевое значение, указывающее, завершилась ли программа нелокально. Если возвращено нулевое значение, это означает, что программа выполнилась до конца, и можно безопасно использовать интерпретатор (при условии, что флаг PERL_EXIT_DESTRUCT_END был установлен, как описано выше). Если возвращено ненулевое значение, это означает, что интерпретатор хочет прервать работу. Интерпретатор не должен быть просто оставлен из-за этого желания прервать работу; вызывающая сторона должна корректно завершить работу интерпретатора с помощью "perl_destruct" и освободить его с помощью "perl_free".

По историческим причинам ненулевое возвращаемое значение также пытается быть подходящим значением для передачи в функцию C-библиотеки exit (или для возврата из main), служащим кодом завершения, указывающим на характер завершения программы. Однако это не переносимо из-за различных соглашений о кодах завершения. Делается попытка вернуть код завершения, требуемого операционной системой хоста, но поскольку он ограничен ненулевым значением, не всегда возможно указать каждый тип завершения. Он надежен только на Unix, где нулевой код выхода может быть дополнен установленным битом, который будет проигнорирован. В любом случае, эта функция не является правильным местом для получения кода выхода: его следует получить из "perl_destruct".

int     perl_run(PerlInterpreter *my_perl)

require_pv

Указывает Perl на require файл, имя которого указано в строковом аргументе. Аналогично коду Perl eval "require '$file'". Он даже реализован таким образом; используйте вместо этого load_module.

ПРИМЕЧАНИЕ: perl-версия этой функции устарела.

void    require_pv(const char* pv)

Обработка исключений (простые) макросы

dXCPT

Настраивает необходимые локальные переменные для обработки исключений. См. "Обработка исключений" в perlguts.

dXCPT;

XCPT_CATCH

Вводит блок catch. См. "Обработка исключений" в perlguts.

XCPT_RETHROW

Перебрасывает ранее пойманное исключение. См. "Обработка исключений" в perlguts.

XCPT_RETHROW;

XCPT_TRY_END

Завершает блок try. См. "Обработка исключений" в perlguts.

XCPT_TRY_START

Начинает блок try. См. "Обработка исключений" в perlguts.

Функции в файле vutil.c

new_version

Возвращает новый объект версии, основанный на переданном SV:

SV *sv = new_version(SV *ver);

Не изменяет переданный SV. Смотрите "upg_version", если хотите обновить SV.

SV*     new_version(SV *ver)

prescan_version

Проверяет, может ли заданная строка быть обработана как объект версии, но не выполняет фактического разбора. Может использовать правила проверки строгого или свободного формата. Можно дополнительно задать несколько переменных подсказок, чтобы сэкономить время коду разбора при токенизации.

const char* prescan_version(const char *s, bool strict,
                            const char** errstr,
                            bool *sqv,
                            int *ssaw_decimal,
                            int *swidth, bool *salpha)

scan_version

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

Функция должна вызываться с уже существующим SV, например:

sv = newSV(0);
s = scan_version(s, SV *sv, bool qv);

Выполняет некоторую предобработку строки, чтобы убедиться, что она имеет правильные характеристики версии. Помечает объект, если он содержит символ подчеркивания (который обозначает альфа-версию). Логическое значение qv указывает, что версия должна интерпретироваться как имеющая несколько десятичных знаков, даже если это не так.

const char* scan_version(const char *s, SV *rv, bool qv)

upg_version

Прямое обновление предоставленного SV до объекта версии.

SV *sv = upg_version(SV *sv, bool qv);

Возвращает указатель на обновленный SV. Установите логическое значение qv, если вы хотите заставить этот SV интерпретироваться как «расширенную» версию.

SV*     upg_version(SV *ver, bool qv)

vcmp

Функция сравнения, учитывающая объекты версий. Оба операнда должны быть уже преобразованы в объекты версий.

int     vcmp(SV *lhv, SV *rhv)

vnormal

Принимает объект версии и возвращает нормализованное строковое представление. Вызов, например:

sv = vnormal(rv);

ПРИМЕЧАНИЕ: вы можете передать объект напрямую или SV, содержащийся в RV.

Возвращаемый SV имеет счетчик ссылок 1.

SV*     vnormal(SV *vs)

vnumify

Принимает объект версии и возвращает нормализованное представление с плавающей точкой. Вызов, например:

sv = vnumify(rv);

ПРИМЕЧАНИЕ: вы можете передать объект напрямую или SV, содержащийся в RV.

Возвращаемый SV имеет счетчик ссылок 1.

SV*     vnumify(SV *vs)

vstringify

Для сохранения максимальной совместимости с более ранними версиями Perl, эта функция вернёт представление с плавающей точкой или с несколькими точками, в зависимости от того, содержала ли оригинальная версия 1 или более точек, соответственно.

Возвращаемый SV имеет счетчик ссылок 1.

SV*     vstringify(SV *vs)

vverify

Проверяет, содержит ли SV допустимую внутреннюю структуру для объекта версии. Можно передать либо объект версии (RV), либо сам хеш (HV). Если структура допустима, возвращает HV. Если структура некорректна, возвращает NULL.

SV *hv = vverify(sv);

Обратите внимание, что она подтверждает только минимальную структуру (чтобы не путаться с производными классами, которые могут содержать дополнительные записи в хеш):

SV — это HV или ссылка на HV
Хеш содержит ключ "version"
Ключ "version" имеет ссылку на AV в качестве значения

SV*     vverify(SV *vs)

Значения "Gimme"

G_ARRAY

Используется для указания контекста списка. Смотрите "GIMME_V", "GIMME" и perlcall.

G_DISCARD

Указывает, что аргументы, возвращаемые из обратного вызова, должны быть отброшены. Смотрите perlcall.

G_EVAL

Используется для принудительного добавления Perl eval оболочки вокруг обратного вызова. Смотрите perlcall.

GIMME

Обратно совместимая версия GIMME_V, которая может возвращать только G_SCALAR или G_ARRAY; в пустом контексте возвращает G_SCALAR. Устаревшая. Используйте GIMME_V вместо неё.

U32     GIMME

GIMME_V

Аналог Perl wantarray для XSUB-писателей. Возвращает G_VOID, G_SCALAR или G_ARRAY для пустого, скалярного или списочного контекста соответственно. Смотрите perlcall для примера использования.

U32     GIMME_V

G_NOARGS

Указывает, что обратный вызов не получает никаких аргументов. Смотрите perlcall.

G_SCALAR

Используется для указания скалярного контекста. Смотрите "GIMME_V", "GIMME", и perlcall.

G_VOID

Используется для указания пустого контекста. Смотрите "GIMME_V" и perlcall.

Глобальные переменные

Эти переменные глобальны для всего процесса. Они общие для всех интерпретаторов и всех потоков в процессе. Любые не задокументированные здесь переменные могут быть изменены или удалены без предварительного уведомления, поэтому не используйте их! Если вам действительно нужно использовать незадокументированную переменную, отправьте письмо на perl5-porters@perl.org. Возможно, там подскажут способ достижения нужного результата без использования внутренней переменной. В противном случае вы должны получить разрешение на документирование и использование переменной.

PL_check

Массив, индексированный по операционному коду, функций, которые будут вызываться на стадии «проверки» при построении дерева optree во время компиляции Perl-кода. Для большинства (но не всех) типов операторов, после того, как оператор был первоначально построен и заполнен дочерними операторами, он будет отфильтрован через функцию проверки, ссылающуюся на соответствующий элемент этого массива. Новый оператор передаётся в качестве единственного аргумента функции проверки, и функция проверки возвращает завершённый оператор. Функция проверки может (как следует из названия) проверить оператор на правильность и сообщить об ошибках. Она также может инициализировать или изменить части операторов, или выполнить более радикальную операцию, например, добавить или удалить дочерние операторы, или даже выбросить оператор и вернуть другой оператор взамен.

Этот массив указателей на функции является удобным местом для подключения к процессу компиляции. Модуль XS может поместить свою собственную пользовательскую функцию проверки вместо любой из стандартных, чтобы повлиять на компиляцию определённого типа оператора. Однако пользовательская функция проверки никогда не должна полностью заменять стандартную функцию проверки (или даже пользовательскую функцию проверки из другого модуля). Модуль, изменяющий проверку, должен вместо этого обернуть существующую функцию проверки. Пользовательская функция проверки должна быть избирательной в отношении того, когда применять своё пользовательское поведение. В обычном случае, когда она решает ничего не делать со специальным оператором, она должна передавать существующую функцию оператора. Функции проверки, таким образом, связаны в цепочке, с базовой функцией проверки ядра в конце.

Для обеспечения потокобезопасности модули не должны записывать непосредственно в этот массив. Вместо этого используйте функцию "wrap_op_checker".

PL_keyword_plugin

Указатель на функцию, используемую для обработки расширенных ключевых слов. Функция должна быть объявлена как

int keyword_plugin_function(pTHX_
        char *keyword_ptr, STRLEN keyword_len,
        OP **op_ptr)

Функция вызывается из токенизатора всякий раз, когда встречается потенциальное ключевое слово. keyword_ptr указывает на слово в буфере ввода парсера, а keyword_len — его длину; он не завершается нулём. Функция должна проверить слово и, возможно, другое состояние, например, %^H, чтобы определить, хочет ли она обработать его как расширенное ключевое слово. Если нет, функция должна вернуть KEYWORD_PLUGIN_DECLINE, и нормальный процесс парсера продолжится.

Если функция хочет обработать ключевое слово, она должна сначала проанализировать всё, что следует за ключевым словом и является частью синтаксиса, введённого ключевым словом. Подробности см. в "Интерфейс лексического анализатора".

Когда ключевое слово обрабатывается, функция плагина должна построить дерево OP структур, представляющих код, который был проанализирован. Корень дерева должен быть сохранён в *op_ptr. Затем функция возвращает константу, указывающую синтаксическую роль конструкта, который она проанализировала: KEYWORD_PLUGIN_STMT если это полное утверждение или KEYWORD_PLUGIN_EXPR если это выражение. Обратите внимание, что конструкция утверждения не может использоваться внутри выражения (кроме do BLOCK и подобных), а выражение не является полным утверждением (оно требует хотя бы завершающей точки с запятой).

При обработке ключевого слова функция плагина также может иметь (времени компиляции) побочные эффекты. Она может модифицировать %^H, определять функции и т. д. Как правило, если побочные эффекты являются основной целью обработчика, он не хочет генерировать какие-либо операторы для включения в обычную компиляцию. В этом случае ему всё равно необходимо предоставить дерево операторов, но достаточно сгенерировать один пустой оператор.

Таким образом, функция *PL_keyword_plugin должна вести себя в целом. Однако обычно не нужно полностью заменять существующую функцию обработчика. Вместо этого скопируйте PL_keyword_plugin перед назначением собственной функции указателю. Ваша функция обработчика должна искать ключевые слова, которые её интересуют, и обрабатывать их. Если её не интересует ключевое слово, она должна вызвать сохранённую функцию плагина, передав полученные аргументы. Таким образом, PL_keyword_plugin фактически указывает на цепочку функций обработчиков, которые могут обрабатывать ключевые слова, и только последняя функция в цепочке (встроенная в ядро Perl) обычно вернёт KEYWORD_PLUGIN_DECLINE.

Для обеспечения потокобезопасности модули не должны устанавливать эту переменную напрямую. Вместо этого используйте функцию "wrap_keyword_plugin".

PL_phase

Значение, указывающее текущую фазу интерпретатора Perl. Возможные значения включают PERL_PHASE_CONSTRUCT, PERL_PHASE_START, PERL_PHASE_CHECK, PERL_PHASE_INIT, PERL_PHASE_RUN, PERL_PHASE_END, и PERL_PHASE_DESTRUCT.

Например, следующее определяет, находится ли интерпретатор в глобальной фазе уничтожения:

if (PL_phase == PERL_PHASE_DESTRUCT) {
    // we are in global destruction
}

PL_phase была введена в Perl 5.14; в более ранних версиях Perl можно использовать PL_dirty (булево значение) для определения, находится ли интерпретатор в глобальной фазе уничтожения. (Использование PL_dirty не рекомендуется с 5.14.)

enum perl_phase PL_phase

Функции GV

GV — это структура, которая соответствует Perl-типоглобу, т. е. *foo. Это структура, которая хранит указатель на скаляр, массив, хеш и т. д., соответствующие $foo, @foo, %foo.

GV обычно встречаются в качестве значений в стогах (хеши таблицы символов), где Perl хранит свои глобальные переменные.

GvAV

Возвращает AV из GV.

AV*     GvAV(GV* gv)

gv_const_sv

Если gv является typeglob, чья подпрограмма является константной подпрограммой, подходящей для встраивания, или gv является замещающей ссылкой, которая была бы преобразована в такой typeglob, то возвращает значение, возвращаемое подпрограммой. В противном случае возвращает NULL.

SV*     gv_const_sv(GV* gv)

GvCV

Возвращает CV из GV.

CV*     GvCV(GV* gv)

gv_fetchmeth

Подобно gv_fetchmeth_pvn, но без параметра flags.

GV*     gv_fetchmeth(HV* stash, const char* name,
                     STRLEN len, I32 level)

gv_fetchmethod_autoload

Возвращает glob, содержащий подпрограмму, которую нужно вызвать для вызова метода на stash. Фактически, при наличии автозагрузки это может быть glob для "AUTOLOAD". В этом случае соответствующая переменная $AUTOLOAD уже настроена.

Третий параметр gv_fetchmethod_autoload определяет, выполняется ли поиск AUTOLOAD, если заданный метод отсутствует: ненулевое значение означает да, искать AUTOLOAD; нулевое значение означает нет, не искать AUTOLOAD. Вызов gv_fetchmethod эквивалентен вызову gv_fetchmethod_autoload с ненулевым параметром autoload.

Эти функции предоставляют "SUPER" в качестве префикса имени метода. Обратите внимание, что если вы хотите сохранить возвращаемый glob надолго, вам нужно проверить, является ли он "AUTOLOAD", так как в более позднее время вызов может загрузить другую подпрограмму из-за изменения значения $AUTOLOAD. Используйте созданный glob как побочный эффект для этого.

Эти функции имеют такие же побочные эффекты, что и gv_fetchmeth с level==0. Предупреждение о передаче GV, возвращаемого gv_fetchmeth в call_sv, также относится к этим функциям.

GV*     gv_fetchmethod_autoload(HV* stash,
                                const char* name,
                                I32 autoload)

gv_fetchmeth_autoload

Это старая форма gv_fetchmeth_pvn_autoload, у которой нет параметра flags.

GV*     gv_fetchmeth_autoload(HV* stash,
                              const char* name,
                              STRLEN len, I32 level)

gv_fetchmeth_pv

Точно так же, как gv_fetchmeth_pvn, но принимает строку с нулевым завершением вместо пары строка/длина.

GV*     gv_fetchmeth_pv(HV* stash, const char* name,
                        I32 level, U32 flags)

gv_fetchmeth_pvn

Возвращает glob с заданным name и определенной подпрограммой или NULL. Glob находится в заданном stash, или в хранилищах, доступных через @ISA и UNIVERSAL::.

Аргумент level должен быть либо 0, либо -1. Если level==0, в качестве побочного эффекта создает glob с заданным name в заданном stash, который в случае успеха содержит псевдоним для подпрограммы, и настраивает информацию кеширования для этого glob.

Единственные значимые значения для flags — это GV_SUPER и SVf_UTF8.

GV_SUPER указывает, что мы хотим найти метод в суперклассах stash.

Возвращаемый GV из gv_fetchmeth может быть элементом кеша метода, который не виден коду Perl. Поэтому при вызове call_sv вы не должны использовать GV напрямую; вместо этого вы должны использовать CV метода, который можно получить из GV с помощью макроса GvCV.

GV*     gv_fetchmeth_pvn(HV* stash, const char* name,
                         STRLEN len, I32 level,
                         U32 flags)

gv_fetchmeth_pvn_autoload

То же, что и gv_fetchmeth_pvn(), но также ищет подпрограммы с автозагрузкой. Возвращает glob для подпрограммы.

Для подпрограммы с автозагрузкой без GV будет создан GV, даже если level < 0. Для подпрограммы с автозагрузкой без заглушки, GvCV() результата может быть равно нулю.

В настоящее время единственное значимое значение для flags — это SVf_UTF8.

GV*     gv_fetchmeth_pvn_autoload(HV* stash,
                                  const char* name,
                                  STRLEN len, I32 level,
                                  U32 flags)

gv_fetchmeth_pv_autoload

Точно так же, как gv_fetchmeth_pvn_autoload, но принимает строку с нулевым завершением вместо пары строка/длина.

GV*     gv_fetchmeth_pv_autoload(HV* stash,
                                 const char* name,
                                 I32 level, U32 flags)

gv_fetchmeth_sv

Точно так же, как gv_fetchmeth_pvn, но принимает строку имени в виде SV вместо пары строка/длина.

GV*     gv_fetchmeth_sv(HV* stash, SV* namesv,
                        I32 level, U32 flags)

gv_fetchmeth_sv_autoload

Точно так же, как gv_fetchmeth_pvn_autoload, но принимает строку имени в виде SV вместо пары строка/длина.

GV*     gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
                                 I32 level, U32 flags)

GvHV

Возвращает HV из GV.

HV*     GvHV(GV* gv)

gv_init

Старая форма gv_init_pvn(). Она не работает со строками UTF-8, так как не имеет параметра flags. Если параметр multi установлен, параметр GV_ADDMULTI будет передан в gv_init_pvn().

void    gv_init(GV* gv, HV* stash, const char* name,
                STRLEN len, int multi)

gv_init_pv

То же, что и gv_init_pvn(), но принимает строку с нулевым завершением для имени вместо отдельных параметров char * и length.

void    gv_init_pv(GV* gv, HV* stash, const char* name,
                   U32 flags)

gv_init_pvn

Преобразует скаляр в typeglob. Это непереводимый typeglob; присваивание ссылки приведет к присваиванию одному из его слотов, а не к перезаписи, как это происходит с typeglob, созданными SvSetSV. Преобразование любого скаляра, который является SvOK() может привести к непредсказуемым результатам и зарезервировано для внутреннего использования perl.

gv — это преобразуемый скаляр.

stash — это родительский хранилище/пакет, если таковой имеется.

name и len задают имя. Имя должно быть неквалифицированным; то есть оно не должно включать имя пакета. Если gv — элемент хранилища, ответственность за соответствие имени, переданного этой функции, имени элемента, лежит на вызывающей стороне. Если они не совпадают, внутренняя регистрация perl будет нарушена.

flags может быть установлено в SVf_UTF8 если name — строка UTF-8 или возвращаемое значение SvUTF8(sv). Оно также может принимать флаг GV_ADDMULTI, что означает, что необходимо предположить, что GV был виден ранее (т.е., подавить предупреждения "Used once").

void    gv_init_pvn(GV* gv, HV* stash, const char* name,
                    STRLEN len, U32 flags)

gv_init_sv

То же, что и gv_init_pvn(), но принимает SV * для имени вместо отдельных параметров char * и length. flags в настоящее время не используется.

void    gv_init_sv(GV* gv, HV* stash, SV* namesv,
                   U32 flags)

gv_stashpv

Возвращает указатель на хранилище для указанного пакета. Использует strlen для определения длины name, а затем вызывает gv_stashpvn().

HV*     gv_stashpv(const char* name, I32 flags)

gv_stashpvn

Возвращает указатель на хранилище для указанного пакета. Параметр namelen указывает длину name, в байтах. flags передается в gv_fetchpvn_flags(), поэтому, если установлено GV_ADD, пакет будет создан, если он еще не существует. Если пакет не существует и flags равно 0 (или любое другое значение, не создающее пакеты), то возвращается NULL.

Флаги могут быть следующими:

GV_ADD
SVf_UTF8
GV_NOADD_NOINIT
GV_NOINIT
GV_NOEXPAND
GV_ADDMG

Наиболее важные из них, вероятно, GV_ADD и SVf_UTF8.

Обратите внимание, использование gv_stashsv вместо gv_stashpvn по возможности настоятельно рекомендуется по соображениям производительности.

HV*     gv_stashpvn(const char* name, U32 namelen,
                    I32 flags)

gv_stashpvs

Подобно gv_stashpvn, но принимает литеральную строку вместо пары строка/длина.

HV*     gv_stashpvs("name", I32 create)

gv_stashsv

Возвращает указатель на хранилище для указанного пакета. См. "gv_stashpvn".

Обратите внимание, что этот интерфейс сильно предпочтительнее gv_stashpvn по соображениям производительности.

HV*     gv_stashsv(SV* sv, I32 flags)

GvSV

Возвращает SV из GV.

SV*     GvSV(GV* gv)

save_gp

Сохраняет текущий GP gv в стеке сохранения для восстановления при выходе из области видимости.

Если empty истинно, замените GP новым GP.

Если empty ложно, пометьте gv как GVf_INTRO, чтобы следующая назначенная ссылка была локализована, что является тем, как работает local *foo = $someref; .

void    save_gp(GV* gv, I32 empty)

setdefout

Устанавливает PL_defoutgv, стандартный файловый дескриптор для вывода, на переданный typeglob. Так как PL_defoutgv "владеет" ссылкой на свой typeglob, счетчик ссылок переданного typeglob увеличивается на единицу, а счетчик ссылок typeglob, на который указывает PL_defoutgv, уменьшается на единицу.

void    setdefout(GV* gv)

Полезные значения

C_ARRAY_END

Возвращает указатель на элемент, следующий за последним элементом входного массива C.

void *  C_ARRAY_END(void *a)

C_ARRAY_LENGTH

Возвращает количество элементов в входном массиве C (нужно, чтобы индексы с нуля были меньше, но не равны).

STRLEN  C_ARRAY_LENGTH(void *a)

cBOOL

Преобразование в bool. Простое (bool) expr преобразование может быть неверным: если bool определено как char, например, то преобразование из int является определённым реализацией.

(bool)!!(cbool) в условном операторе вызывает ошибку в xlc на AIX

bool    cBOOL(bool expr)

Nullav

УСТАРЕЛО! Планируется удалить эту функцию из будущей версии Perl. Не используйте её в новом коде; удалите её из существующего кода.

Указатель на нулевой массив AV.

(устарело - используйте (AV *)NULL вместо этого)

Nullch

Указатель на нулевой символ. (Больше недоступно, когда PERL_CORE определено.)

Nullcv

Указатель на нулевой CV.

(устарело - используйте (CV *)NULL вместо этого)

Nullhv

Указатель на нулевой HV.

(устарело - используйте (HV *)NULL вместо этого)

Nullsv

Указатель на нулевой SV. (Больше недоступно, когда PERL_CORE определено.)

STR_WITH_LEN

Возвращает два разделенных запятыми токена входной строковой литералы и её длину. Это удобный макрос, который помогает в некоторых вызовах API. Обратите внимание, что его нельзя использовать в качестве аргумента для макросов или функций, которые в некоторых конфигурациях могут быть макросами, что означает, что для любых вызовов API, где он используется, требуется полная форма Perl_xxx(aTHX_ ...).

pair    STR_WITH_LEN("literal string")

__ASSERT_

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

void    __ASSERT_(bool expr)

Функции управления хешами

Структура HV представляет собой перловский хеш. Она состоит в основном из массива указателей, каждый из которых указывает на связанный список структур HE. Массив индексируется по результату функции хеширования ключа, поэтому каждый связанный список представляет все записи хеша с одинаковым значением хеша. Каждая HE содержит указатель на фактическое значение плюс указатель на структуру HEK, которая содержит ключ и значение хеша.

cop_fetch_label

Возвращает метку, прикреплённую к cop, и сохраняет её длину в байтах в *len. По возвращении *flags будет установлено в значение SVf_UTF8 или 0.

В качестве альтернативы, используйте макрос "CopLABEL_len_flags"; или если вам не нужно знать, является ли метка UTF-8, макрос "CopLABEL_len"; или если вам также не нужна длина, "CopLABEL".

const char * cop_fetch_label(COP *const cop,
                             STRLEN *len, U32 *flags)

cop_store_label

Сохранить метку в cop_hints_hash. Для метки UTF-8 необходимо установить флаги в SVf_UTF8. Любые другие флаги игнорируются.

void    cop_store_label(COP *const cop,
                        const char *label, STRLEN len,
                        U32 flags)

get_hv

Возвращает HV указанного Perl-хэша. flags передаются в gv_fetchpv. Если GV_ADD установлено, а Perl-переменная не существует, она будет создана. Если flags равно нулю, а переменная не существует, возвращается NULL.

ПРИМЕЧАНИЕ: perl-форма этой функции устарела.

HV*     get_hv(const char *name, I32 flags)

HEf_SVKEY

Этот флаг, используемый в слоте длины элементов хэша и магических структур, указывает, что структура содержит указатель SV*, где ожидается указатель char*. (Для справки — не использовать).

HeHASH

Возвращает вычисленный хэш, хранящийся в элементе хэша.

U32     HeHASH(HE* he)

HeKEY

Возвращает фактический указатель, хранящийся в слоте ключа элемента хэша. Указатель может быть либо char*, либо SV*, в зависимости от значения HeKLEN(). Может быть присвоено. Макросы HePV() или HeSVKEY() обычно предпочтительнее для поиска значения ключа.

void*   HeKEY(HE* he)

HeKLEN

Если это отрицательное значение, и оно соответствует HEf_SVKEY, это указывает, что запись содержит ключ SV*. В противном случае содержит фактическую длину ключа. Может быть присвоено. Макрос HePV() обычно предпочтительнее для поиска длин ключей.

STRLEN  HeKLEN(HE* he)

HePV

Возвращает слот ключа элемента хэша как значение char*, выполняя необходимые дереференции, возможно, SV* ключей. Длина строки помещается в len (это макрос, поэтому не используйте &len). Если вас не интересует длина ключа, вы можете использовать глобальную переменную PL_na, хотя это несколько менее эффективно, чем использование локальной переменной. Тем не менее, помните, что ключи хэша в Perl могут содержать вложенные нули, поэтому использование strlen() или аналогичных методов не является хорошим способом определения длины ключей хэша. Это очень похоже на макрос SvPV(), описанный в другом месте этого документа. См. также "HeUTF8".

Если вы используете HePV для получения значений для передачи в newSVpvn() для создания нового SV, следует рассмотреть использование newSVhek(HeKEY_hek(he)), так как оно более эффективно.

char*   HePV(HE* he, STRLEN len)

HeSVKEY

Возвращает ключ как SV*, или NULL, если элемент хэша не содержит ключа SV*.

SV*     HeSVKEY(HE* he)

HeSVKEY_force

Возвращает ключ как SV*. Создаст и вернёт временный смертный SV*, если элемент хэша содержит только ключ char*.

SV*     HeSVKEY_force(HE* he)

HeSVKEY_set

Устанавливает ключ на заданное SV*, позаботившись об установке соответствующих флагов для указания наличия ключа SV*, и возвращает тот же SV*.

SV*     HeSVKEY_set(HE* he, SV* sv)

HeUTF8

Возвращает, закодировано ли значение char *, возвращаемое HePV, в UTF-8, выполняя необходимые дереференции, возможно, SV* ключей. Возвращаемое значение будет 0 или отличным от 0, а не обязательно 1 (или даже значение с установленными младшими битами), поэтому не следует бездумно присваивать это переменной bool, так как bool может быть типом для char.

U32     HeUTF8(HE* he)

HeVAL

Возвращает слот значения (тип SV*) хранящийся в элементе хэша. Может быть присвоено.

SV *foo= HeVAL(hv);
HeVAL(hv)= sv;


      SV*     HeVAL(HE* he)

hv_assert

Проверяет, находится ли хэш во внутренне согласованном состоянии.

ПРИМЕЧАНИЕ: эта функция должна быть явно вызвана как Perl_hv_assert с параметром aTHX_.

void    Perl_hv_assert(pTHX_ HV *hv)

hv_bucket_ratio

Если хэш привязан, происходит пересылка к методу SCALAR привязки, в противном случае, если хэш не содержит ключей, возвращается 0, в противном случае возвращается смертный sv, содержащий строку, указывающую количество используемых ведер, за которой следует косой чертой, количество доступных ведер.

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

SV*     hv_bucket_ratio(HV *hv)

hv_clear

Освобождает все элементы хэша, оставляя его пустым. Эквивалент XS %hash = (). См. также "hv_undef".

См. "av_clear" для примечания о том, что хэш может быть недействительным по возвращении.

void    hv_clear(HV *hv)

hv_clear_placeholders

Очищает все заглушки из хэша. Если у ограниченного хэша есть ключи, помеченные как только для чтения, и ключ впоследствии удалён, ключ фактически не удаляется, а помечается присвоением ему значения &PL_sv_placeholder. Это помечает его так, что он будет игнорироваться будущими операциями, такими как итерация по хэшу, но всё ещё позволит присвоить хэшу значение для ключа в будущем. Эта функция очищает все такие заполнительные ключи из хэша. См. Hash::Util::lock_keys() для примера использования.

void    hv_clear_placeholders(HV *hv)

hv_copy_hints_hv

Специализированная версия "newHVhv" для копирования %^H. ohv должен быть указателем на хэш (который может иметь магию %^H, но в целом должен быть не магическим) или NULL (интерпретируется как пустой хэш). Содержимое ohv копируется в новый хэш, к которому добавляется магия, специфичная для %^H. Возвращается указатель на новый хэш.

HV *    hv_copy_hints_hv(HV *const ohv)

hv_delete

Удаляет пару ключ/значение в хэше. SV значения удаляется из хэша, делается смертельным и возвращается вызывающему коду. Абсолютное значение klen — это длина ключа. Если klen отрицательное, ключ предполагается закодированным в UTF-8. Значение flags обычно равно нулю; если установлено в G_DISCARD, возвращается NULL. NULL также возвращается, если ключ не найден.

SV*     hv_delete(HV *hv, const char *key, I32 klen,
                  I32 flags)

hv_delete_ent

Удаляет пару ключ/значение в хэше. SV значения удаляется из хэша, делается смертельным и возвращается вызывающему коду. Значение flags обычно равно нулю; если установлено в G_DISCARD, возвращается NULL. NULL также возвращается, если ключ не найден. hash может быть действительным предварительно вычисленным значением хэша или 0, чтобы запросить его вычисление.

SV*     hv_delete_ent(HV *hv, SV *keysv, I32 flags,
                      U32 hash)

HvENAME

Возвращает эффективное имя хранилища или NULL, если его нет. Эффективное имя представляет собой местоположение в таблице символов, где находится это хранилище. Оно обновляется автоматически при алиасировании или удалении пакетов. У хранилища, которое больше не находится в таблице символов, нет эффективного имени. Это имя предпочтительнее HvNAME для использования в линейных MRO и кэшах isa.

char*   HvENAME(HV* stash)

HvENAMELEN

Возвращает длину эффективного имени хранилища.

STRLEN  HvENAMELEN(HV *stash)

HvENAMEUTF8

Возвращает true, если эффективное имя закодировано в UTF-8.

unsigned char HvENAMEUTF8(HV *stash)

hv_exists

Возвращает булево значение, указывающее, существует ли указанный ключ хэша. Абсолютное значение klen — это длина ключа. Если klen отрицательно, ключ предполагается закодированным в UTF-8.

bool    hv_exists(HV *hv, const char *key, I32 klen)

hv_exists_ent

Возвращает булево значение, указывающее, существует ли указанный ключ хэша. hash может быть действительным предварительно вычисленным значением хэша или 0, чтобы запросить его вычисление.

bool    hv_exists_ent(HV *hv, SV *keysv, U32 hash)

hv_fetch

Возвращает SV, соответствующий указанному ключу в хэше. Абсолютное значение klen — это длина ключа. Если klen отрицательное, ключ предполагается закодированным в UTF-8. Если lval установлено, извлечение будет частью сохранения. Это означает, что если в хэше нет значения, связанного с данным ключом, создаётся одно, и возвращается указатель на него. К SV* которому он указывает, можно присвоить значение. Но всегда проверяйте, что возвращаемое значение не равно null, прежде чем дереференцировать его в SV*.

См. «

SV**    hv_fetch(HV *hv, const char *key, I32 klen,
                 I32 lval)

\" в perlguts для получения дополнительной информации о том, как использовать эту функцию для привязанных хэшей.

SV**    hv_fetch(HV *hv, const char *key, I32 klen,
                 I32 lval)

hv_fetchs

Подобно hv_fetch, но принимает литеральную строку вместо пары строка/длина.

SV**    hv_fetchs(HV* tb, "key", I32 lval)

hv_fetch_ent

Возвращает запись хеша, соответствующую указанному ключу в хеше. hash должен быть действительным предварительно вычисленным числом хеша для данного key, или 0, если вы хотите, чтобы функция его вычислила. ЕСЛИ lval установлено, то запрос будет частью записи. Убедитесь, что возвращаемое значение не равно null перед доступом к нему. Возвращаемое значение, когда hv это привязанный хеш, - указатель на статическое местоположение, поэтому обязательно сделайте копию структуры, если вам нужно ее сохранить где-либо.

См. "Понимание магии связанных хешей и массивов" в perlguts для получения дополнительной информации о том, как использовать эту функцию для привязанных хешей.

HE*     hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
                     U32 hash)

HvFILL

См. "hv_fill".

STRLEN  HvFILL(HV *const hv)

hv_fill

Возвращает количество используемых корзин хеша.

Эта функция обернута макросом HvFILL.

Начиная с perl 5.25, эта функция используется только для отладки, и количество используемых корзин хеша никак не кэшируется, поэтому эта функция может быть дорогостоящей в выполнении, так как ей необходимо перебрать все корзины в хеше.

ПРИМЕЧАНИЕ: эту функцию необходимо явно вызвать как Perl_hv_fill с параметром aTHX_.

STRLEN  Perl_hv_fill(pTHX_ HV *const hv)

hv_iterinit

Подготавливает начальную точку для обхода таблицы хеша. Возвращает количество ключей в хеше, включая заглушки (т. е. такие же, как HvTOTALKEYS(hv)). Возвращаемое значение в настоящее время имеет смысл только для хешей без магической привязки.

ПРИМЕЧАНИЕ: До версии 5.004_65 hv_iterinit возвращала количество используемых корзин хеша. Если вам все еще нужно это экзотическое значение, вы можете получить его через макрос HvFILL(hv).

I32     hv_iterinit(HV *hv)

hv_iterkey

Возвращает ключ из текущей позиции итератора хеша. См. "hv_iterinit".

char*   hv_iterkey(HE* entry, I32* retlen)

hv_iterkeysv

Возвращает ключ как SV* из текущей позиции итератора хеша. Возвращаемое значение всегда является смертной копией ключа. Также см. "hv_iterinit".

SV*     hv_iterkeysv(HE* entry)

hv_iternext

Возвращает записи из итератора хеша. См. "hv_iterinit".

Вы можете вызвать hv_delete или hv_delete_ent для записи хеша, на которую в настоящее время указывает итератор, не потеряв свое место или не сделав свой итератор недействительным. Обратите внимание, что в этом случае текущая запись удаляется из хеша, и ваш итератор хранит последнюю ссылку на нее. Ваш итератор помечен для освобождения записи при следующем вызове hv_iternext, поэтому вы не должны сразу отбрасывать свой итератор, иначе запись будет утечкой - вызовите hv_iternext для запуска освобождения ресурсов.

HE*     hv_iternext(HV *hv)

hv_iternextsv

Выполняет hv_iternext, hv_iterkey, и hv_iterval в одной операции.

SV*     hv_iternextsv(HV *hv, char **key, I32 *retlen)

hv_iternext_flags

Возвращает записи из итератора хеша. См. "hv_iterinit" и "hv_iternext". Значение flags обычно равно нулю; если HV_ITERNEXT_WANTPLACEHOLDERS установлено, то ключи-заглушки (для ограниченных хешей) будут возвращаться дополнительно к обычным ключам. По умолчанию заглушки автоматически пропускаются. В настоящее время заглушка реализована со значением &PL_sv_placeholder. Обратите внимание, что реализация заглушек и ограниченных хешей может измениться, а текущая реализация недостаточно абстрагирована для любых изменений, чтобы быть аккуратной.

HE*     hv_iternext_flags(HV *hv, I32 flags)

hv_iterval

Возвращает значение из текущей позиции итератора хеша. См. "hv_iterkey".

SV*     hv_iterval(HV *hv, HE *entry)

hv_magic

Добавляет магию к хешу. См. "sv_magic".

void    hv_magic(HV *hv, GV *gv, int how)

HvNAME

Возвращает имя пакета стека или NULL если stash не является стеком. См. "SvSTASH", "CvSTASH".

char*   HvNAME(HV* stash)

HvNAMELEN

Возвращает длину имени стека.

STRLEN  HvNAMELEN(HV *stash)

HvNAMEUTF8

Возвращает true, если имя закодировано в UTF-8.

unsigned char HvNAMEUTF8(HV *stash)

hv_scalar

Вычисляет хеш в скалярном контексте и возвращает результат.

Если хеш привязан, вызывает метод SCALAR, в противном случае возвращает смертный SV, содержащий количество ключей в хеше.

Обратите внимание, что до 5.25 эта функция возвращала то, что сейчас возвращает функция hv_bucket_ratio().

SV*     hv_scalar(HV *hv)

hv_store

Сохраняет SV в хеше. Ключ хеша указан как key и абсолютное значение klen - это длина ключа. Если klen отрицательно, то ключ предполагается закодированным в UTF-8 Unicode. Параметр hash - предварительно вычисленное значение хеша; если оно равно нулю, Perl его вычислит.

Возвращаемое значение будет NULL если операция завершилась неудачно или если значение не нужно было фактически хранить в хеше (как в случае с привязанными хешами). В противном случае можно получить доступ к исходному SV*. Обратите внимание, что вызывающая сторона отвечает за соответствующее увеличение счетчика ссылок на val перед вызовом и уменьшение его, если функция вернула NULL. Фактически успешный hv_store принимает во владение одну ссылку на val. Это обычно то, что вам нужно; у только что созданного SV счетчик ссылок равен одному, поэтому если весь ваш код состоит из создания SV и их сохранения в хеше, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду больше не нужно ничего делать для приведения в порядок. hv_store не реализован как вызов hv_store_ent, и не создает временный SV для ключа, поэтому если ваши данные ключа еще не в формате SV, используйте hv_store вместо hv_store_ent.

SV**    hv_store(HV *hv, const char *key, I32 klen,
                 SV *val, U32 hash)

hv_stores

Как hv_store, но принимает литеральную строку вместо пары строка/длина и опускает параметр хеша.

SV**    hv_stores(HV* tb, "key", SV* val)

hv_store_ent

Сохраняет val в хеш. Ключ хеша задается как key. Параметр hash - предварительно вычисленное значение хеша; если оно равно нулю, Perl его вычислит. Возвращаемое значение - новая запись хеша, созданная таким образом. Это будет NULL если операция завершилась неудачно или если значение не нужно было фактически хранить в хеше (как в случае с привязанными хешами). В противном случае содержимое возвращаемого значения можно получить, используя макросы He? описанные здесь. Обратите внимание, что вызывающая сторона отвечает за соответствующее увеличение счетчика ссылок на val перед вызовом и уменьшение его, если функция вернула NULL. Фактически успешный hv_store_ent принимает во владение одну ссылку на val. Это обычно то, что вам нужно; у только что созданного SV счетчик ссылок равен одному, поэтому если весь ваш код состоит из создания SV и их сохранения в хеше, hv_store будет владеть единственной ссылкой на новый SV, и вашему коду больше не нужно ничего делать для приведения в порядок. Обратите внимание, что hv_store_ent считывает только key; в отличие от val он не принимает владение, поэтому сохранение правильного счетчика ссылок на key полностью лежит на ответственности вызывающей стороны. Причина, по которой он не берет на себя владение, заключается в том, что key не используется после возврата этой функции, и поэтому может быть освобожден немедленно. hv_store не реализован как вызов hv_store_ent, и не создает временный SV для ключа, поэтому если ваши данные ключа еще не в формате SV, используйте hv_store вместо hv_store_ent.

HE*     hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)

hv_undef

Освобождает хеш. Эквивалент XS для undef(%hash).

Помимо освобождения всех элементов хеша (как и hv_clear() ), это также освобождает любые вспомогательные данные и хранилище, связанные с хешем.

См. "av_clear" для примечания о возможном нарушении хеша при возврате.

void    hv_undef(HV *hv)

newHV

Создает новый HV. Счетчик ссылок устанавливается в 1.

HV*     newHV()

Работа с крючками

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

wrap_op_checker

Помещает C-функцию в цепочку функций проверки для указанного типа операции. Это предпочтительный способ манипулирования массивом "PL_check". opcode указывает, какой тип операции должен быть затронут. new_checker — указатель на C-функцию, которая должна быть добавлена в цепочку проверки этого кода операции, а old_checker_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_checker записывается в массив "PL_check", а ранее сохраненное значение записывается в *old_checker_p.

"PL_check" является глобальным для всего процесса, и модуль, желающий подключить проверку операций, может быть вызван более одного раза на процесс, обычно в разных потоках. Для обработки этой ситуации функция является идемпотентной. Место *old_checker_p должно первоначально (один раз на процесс) содержать нулевой указатель. C-переменная со статическим сроком действия (объявленная на уровне файла, как правило, также помеченная static для предоставления внутренней связи) будет неявно инициализирована соответствующим образом, если она не имеет явного инициализатора. Эта функция фактически будет изменять цепочку проверки только в том случае, если она обнаружит, что *old_checker_p равно нулю. Эта функция также безопасна для потоков в малом масштабе. Она использует соответствующую блокировку, чтобы избежать гонок при доступе к "PL_check".

Когда эта функция вызывается, функция, на которую ссылается new_checker , должна быть готова к вызову, за исключением того, что *old_checker_p не заполнен. В ситуации с потоками new_checker может быть вызвана немедленно, даже до возвращения этой функции. *old_checker_p всегда будет должным образом установлено до вызова new_checker. Если new_checker решает не делать ничего особенного с операцией, которая ему предоставляется (что является обычным случаем для большинства случаев подключения проверки операций), он должен передать функцию проверки, на которую ссылается *old_checker_p.

В целом, XS-код для подключения проверки операций обычно выглядит примерно так:

static Perl_check_t nxck_frob;
static OP *myck_frob(pTHX_ OP *op) {
    ...
    op = nxck_frob(aTHX_ op);
    ...
    return op;
}
BOOT:
    wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);

Если вы хотите повлиять на компиляцию вызовов определённой подпрограммы, используйте "cv_set_call_checker_flags" вместо подключения проверки всех entersub операций.

void    wrap_op_checker(Optype opcode,
                        Perl_check_t new_checker,
                        Perl_check_t *old_checker_p)

Интерфейс лексического анализатора

Это нижний уровень парсера Perl, управляющий символами и токенами.

lex_bufutf8

Указывает, следует ли интерпретировать байты в буфере лексера ("PL_parser->linestr") как кодировку UTF-8 для символов Юникода. В противном случае они должны интерпретироваться как символы Latin-1. Это аналогично флагу SvUTF8 для скаляров.

В режиме UTF-8 не гарантируется, что буфер лексера фактически содержит допустимый UTF-8. Код лексирования должен быть устойчивым к некорректной кодировке.

Флаг SvUTF8 скаляра "PL_parser->linestr" важен, но не является единственным фактором, определяющим кодировку входных символов. Обычно при чтении файла скаляр содержит байты, и его флаг SvUTF8 выключен, но байты должны интерпретироваться как UTF-8, если действует прагма use utf8. Однако во время выполнения строки кода скаляр может иметь флаг SvUTF8 включённым, и в этом случае его байты должны интерпретироваться как UTF-8, если не действует прагма use bytes. Эта логика может быть изменена в будущем; используйте эту функцию вместо того, чтобы реализовывать логику самостоятельно.

bool    lex_bufutf8()

lex_discard_to

Отбрасывает первую часть буфера "PL_parser->linestr" до ptr. Остальное содержимое буфера будет перемещено, и все указатели в буфер будут обновлены соответствующим образом. ptr не должен находиться в буфере позже, чем позиция "PL_parser->bufptr": запрещено отбрасывать текст, который ещё не был проанализирован.

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

void    lex_discard_to(char* ptr)

lex_grow_linestr

Перевыделяет буфер лексера ("PL_parser->linestr") для размещения как минимум len байтов (включая завершающий NUL). Возвращает указатель на перевыделенный буфер. Это необходимо перед любым прямым изменением буфера, которое увеличит его длину. "lex_stuff_pvn" предоставляет более удобный способ вставки текста в буфер.

Не используйте SvGROW или sv_grow напрямую на PL_parser->linestr; эта функция обновляет все переменные лексера, которые указывают непосредственно в буфер.

char*   lex_grow_linestr(STRLEN len)

lex_next_chunk

Читает следующий фрагмент текста для анализа, добавляя его к "PL_parser->linestr". Это нужно вызывать, когда код лексирования дошел до конца текущего фрагмента и хочет получить больше информации. Обычно, но не обязательно, лексирование потребляет весь текущий фрагмент в этот момент.

Если "PL_parser->bufptr" указывает на самый конец текущего фрагмента (т. е. текущий фрагмент был полностью потреблен), обычно текущий фрагмент будет отброшен одновременно с чтением нового фрагмента. Если flags имеет бит LEX_KEEP_PREVIOUS установленным, текущий фрагмент не будет отброшен. Если текущий фрагмент не был полностью потреблен, то он не будет отброшен независимо от флага.

Возвращает true, если в буфер был добавлен новый текст, или false, если буфер достиг конца входного текста.

bool    lex_next_chunk(U32 flags)

lex_peek_unichar

Предварительно просматривает один (символ Юникода) в тексте, который в данный момент анализируется. Возвращает код символа (целое без знака) следующего символа или -1, если лексирование достигло конца входного текста. Чтобы прочитать просмотренный символ, используйте "lex_read_unichar".

Если следующий символ находится (или простирается в) следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет отброшен одновременно, но если flags имеет установленный бит LEX_KEEP_PREVIOUS, текущий фрагмент не будет отброшен.

Если вход интерпретируется как UTF-8 и встречается ошибка кодирования UTF-8, генерируется исключение.

I32     lex_peek_unichar(U32 flags)

lex_read_space

Читает необязательные пробелы в стиле Perl в тексте, который в данный момент анализируется. Пробелы могут включать обычные пробельные символы и комментарии в стиле Perl. Директивы #line обрабатываются при встрече. "PL_parser->bufptr" перемещается за пробелы, так что он указывает на символ, не являющийся пробелом (или конец входного текста).

Если пробелы простираются в следующий фрагмент входного текста, следующий фрагмент будет прочитан. Обычно текущий фрагмент будет отброшен одновременно, но если flags имеет установленный бит LEX_KEEP_PREVIOUS, текущий фрагмент не будет отброшен.

void    lex_read_space(U32 flags)

lex_read_to

Обрабатывает текст в буфере лексера от "PL_parser->bufptr" до ptr. Это перемещает "PL_parser->bufptr" для соответствия ptr, выполняя корректную обработку при прохождении символа новой строки. Это обычный способ обработки проанализированного текста.

Интерпретацию байтов буфера можно абстрагировать, используя немного более высокие функции "lex_peek_unichar" и "lex_read_unichar".

void    lex_read_to(char* ptr)

lex_read_unichar

Читает следующий (символ Юникода) в тексте, который в данный момент анализируется. Возвращает код символа (целое без знака) прочитанного символа и перемещает "PL_parser->bufptr" за символ или возвращает -1, если лексирование достигло конца входного текста. Для неразрушающего просмотра следующего символа используйте "lex_peek_unichar".

Если вход интерпретируется как UTF-8 и встречается ошибка кодирования UTF-8, генерируется исключение.

I32     lex_read_unichar(U32 flags)

lex_start

Создаёт и инициализирует новый объект состояния лексера/парсера, предоставляя контекст для лексирования и анализа из нового источника кода Perl. Указатель на новый объект состояния помещается в "PL_parser". В стеке сохранения делается запись, чтобы при разворачивании новый объект состояния был уничтожен, а прежнее значение "PL_parser" было восстановлено. Для очистки контекста анализа ничего больше делать не нужно.

Анализируемый код поступает из line и rsfp. line, если не равно нулю, предоставляет строку (в форме SV) содержащую код для анализа. Создаётся копия строки, поэтому последующее изменение line не повлияет на анализ. rsfp, если не равно нулю, предоставляет входной поток, из которого будет считываться код для анализа. Если оба не равны нулю, код в line идёт первым и должен состоять из полных строк ввода, и rsfp предоставляет остальную часть исходного текста.

Параметр flags зарезервирован для будущего использования. В настоящее время он используется только Perl внутри, поэтому расширения всегда должны передавать ноль.

void    lex_start(SV* line, PerlIO *rsfp, U32 flags)

lex_stuff_pv

Вставляет символы в буфер лексера ("PL_parser->linestr") сразу после текущей точки лексирования ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексирования, который выполняется позже, будет видеть символы так, как будто они появились во входных данных. Не рекомендуется делать это как часть обычного анализа, и большинство применений этого механизма рискуют быть интерпретированными вставляемыми символами нежелательным образом.

Вставляемая строка представлена байтами, начинающимися с pv и продолжающимися до первого нуля. Эти байты интерпретируются как UTF-8 или Latin-1, в зависимости от того, установлен ли флаг LEX_STUFF_UTF8 в flags. Символы перекодируются для буфера лексера в соответствии с тем, как в данный момент интерпретируется буфер ("lex_bufutf8"). Если неудобно завершать строку, которую нужно вставить, нулём, функция "lex_stuff_pvn" более подходит.

void    lex_stuff_pv(const char* pv, U32 flags)

lex_stuff_pvn

Вставляемая строка представлена len байтами, начинающимися с pv. Эти байты интерпретируются как UTF-8 или Latin-1, в зависимости от того, установлен ли флаг LEX_STUFF_UTF8 в flags. Символы перекодируются для буфера лексера в соответствии с тем, как в данный момент интерпретируется буфер ("lex_bufutf8"). Если вставляемая строка доступна как Perl скаляр, функция "lex_stuff_sv" удобнее.

void    lex_stuff_pvn(const char* pv, STRLEN len,
                      U32 flags)

lex_stuff_pvs

Как "lex_stuff_pvn", но принимает строку-литерал вместо пары строка/длина.

void    lex_stuff_pvs("pv", U32 flags)

lex_stuff_sv

Вставляет символы в буфер лексического анализатора ("PL_parser->linestr") сразу после текущей точки лексического анализа ("PL_parser->bufptr"), перевыделяя буфер при необходимости. Это означает, что код лексического анализа, который выполняется позже, увидит символы так, как будто они появились во входных данных. Не рекомендуется делать это в рамках обычного синтаксического анализа, и большинство случаев использования этого механизма сопряжено с риском интерпретации вставленных символов нежелательным образом.

Строка, которая должна быть вставлена, — это строковое значение sv. Символы закодированы для буфера лексического анализатора в соответствии с текущей интерпретацией буфера ("lex_bufutf8"). Если вставляемая строка не является Perl-скаляром, функция "lex_stuff_pvn" позволяет избежать необходимости в построении скаляра.

void    lex_stuff_sv(SV* sv, U32 flags)

lex_unstuff

Отбрасывает текст, который должен быть проанализирован лексически, от "PL_parser->bufptr" до ptr. Текст, следующий за ptr, будет перемещен, а буфер укорочен. Это скрывает отбрасываемый текст от любого последующего кода лексического анализа, как будто этот текст никогда не появлялся.

Это не обычный способ потребления проанализированного текста. Для этого используйте "lex_read_to".

void    lex_unstuff(char* ptr)

parse_arithexpr

Разбирает арифметическое выражение Perl. Оно может содержать операторы приоритетов до операторов сдвига битов. Выражение должно следовать (и, таким образом, завершаться) сравнением или оператором с более низким приоритетом, или чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно является обязательным. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для выражения.

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

В случае возникновения ошибки при разборе или компиляции в большинстве случаев возвращается корректное дерево операторов. Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне разбора, который покрывает все ошибки компиляции, которые произошли. Однако некоторые ошибки компиляции вызовут исключение немедленно.

OP*     parse_arithexpr(U32 flags)

parse_barestmt

Разбирает одно простое Perl-утверждение. Это может быть обычное императивное утверждение или объявление, имеющее влияние на время компиляции. Оно не включает никаких меток или других присоединённых элементов. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операторов, представляющее утверждение. Это может быть нулевой указатель, если утверждение равно нулю, например, если это было фактически определение подпрограммы (имеющее побочные эффекты на время компиляции). Если не нулевой, это будут операторы, напрямую реализующие утверждение, подходящие для передачи в "newSTATEOP". Обычно он не будет включать в себя оператор nextstate или аналогичный (за исключением тех, которые встроены в область, полностью содержащуюся в операторе).

Параметр flags зарезервирован для использования в будущем и всегда должен быть нулевым.

OP*     parse_barestmt(U32 flags)

parse_block

Разбирает один полный блок кода Perl. Он состоит из открывающей фигурной скобки, последовательности утверждений и закрывающей фигурной скобки. Блок представляет собой лексическую область, поэтому my переменные и различные эффекты на время компиляции могут быть содержатся в нем. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операторов, представляющее блок кода. Это всегда настоящий оператор, никогда не нулевой указатель. Обычно это список lineseq, включая nextstate или аналогичные операторы. Операторы для построения любого вида области выполнения не включены в силу того, что это блок.

В случае возникновения ошибки при разборе или компиляции в большинстве случаев возвращается корректное дерево операторов (вероятно, пустое). Об ошибке сообщается в состоянии парсера, что обычно приводит к одному исключению на верхнем уровне разбора, который покрывает все ошибки компиляции, которые произошли. Однако некоторые ошибки компиляции вызовут исключение немедленно.

Параметр flags зарезервирован для использования в будущем и всегда должен быть нулевым.

OP*     parse_block(U32 flags)

parse_fullexpr

Разбирает одно полное Perl-выражение. Это позволяет использовать всю грамматику выражений, включая операторы с самым низким приоритетом, такие как or. Выражение должно следовать (и, следовательно, завершаться) маркером, которым обычно завершается выражение: конец файла, закрывающие скобки, точка с запятой или одно из ключевых слов, указывающих на модификатор оператора выражения постфикса. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно является обязательным. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для выражения.

OP*     parse_fullexpr(U32 flags)

parse_fullstmt

Разбирает одно полное Perl-утверждение. Это может быть обычное императивное утверждение или объявление, которое оказывает влияние на время компиляции, и может включать необязательные метки. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для оператора.

Возвращается дерево операторов, представляющее оператор. Это может быть нулевой указатель, если утверждение равно нулю, например, если это было фактически определение подпрограммы (имеющее побочные эффекты на время компиляции). Если не нулевой, это результат вызова "newSTATEOP", обычно включающий в себя оператор nextstate или аналогичный.

Параметр flags зарезервирован для использования в будущем и всегда должен быть нулевым.

OP*     parse_fullstmt(U32 flags)

parse_label

Разбирает одну метку, возможно необязательную, типа, которая может предшествовать Perl-оператору. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода. Если flags имеет установленный бит PARSE_OPTIONAL, то метка является необязательной, в противном случае она является обязательной.

Имя метки возвращается в виде свежего скаляра. Если необязательная метка отсутствует, возвращается нулевой указатель.

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

SV*     parse_label(U32 flags)

parse_listexpr

Разбирает Perl-выражение списка. Оно может содержать операторы с приоритетами до оператора запятой. Выражение должно следовать (и, следовательно, завершаться) оператором с низким приоритетом, таким как or, или чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно является обязательным. Вызывающая сторона должна убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно настроено, чтобы отражать источник анализируемого кода и лексический контекст для выражения.

OP*     parse_listexpr(U32 flags)

parse_stmtseq

Разбор последовательности нуля или более операторов Perl. Это могут быть обычные операторы-инструкции, включая необязательные метки, или объявления, которые имеют влияние на время компиляции, или любая их смесь. Последовательность операторов заканчивается, когда встречается закрывающая фигурная скобка или конец файла в месте, где новый оператор мог бы быть допустимо начат. От пользователя требуется убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно установлено, чтобы отразить источник разбираемого кода и лексический контекст операторов.

Дерево op, представляющее последовательность операторов, возвращается. Это может быть указатель на нуль, если все операторы были нулевыми, например, если операторов не было или были только определения подпрограмм (которые имеют побочные эффекты во время компиляции). Если не нулевой, это будет lineseq список, обычно включающий nextstate или эквивалентные операторы.

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

Параметр flags зарезервирован для будущего использования и должен всегда быть равен нулю.

OP*     parse_stmtseq(U32 flags)

parse_subsignature

Разбор объявления подписи подпрограммы. Это содержимое скобок, следующих за объявлением подпрограммы с именем или анонимной, когда включена функция signatures. Обратите внимание, что эта функция не ожидает и не потребляет открывающие и закрывающие скобки вокруг подписи; обработка этих скобок ложится на вызывающую функцию.

Эта функция должна вызываться только во время разбора подпрограммы; после того, как была вызвана "start_subparse". Она может выделять лексические переменные в стеке для текущей подпрограммы.

Возвращается дерево op для распаковки аргументов из стека во время выполнения. Это дерево op должно появляться в начале скомпилированной функции. Вызывающая функция может захотеть использовать "op_append_list" для построения тела функции после него или объединить его с телом перед вызовом "newATTRSUB".

Параметр flags зарезервирован для будущего использования и должен всегда быть равен нулю.

OP*     parse_subsignature(U32 flags)

parse_termexpr

Разбор выражения Perl. Оно может содержать операторы с приоритетом до операторов присваивания. Выражение должно быть после (и таким образом завершено) запятой или оператором с меньшим приоритетом или чем-то, что обычно завершает выражение, например, точкой с запятой. Если flags имеет установленный бит PARSE_OPTIONAL, то выражение является необязательным, в противном случае оно является обязательным. От пользователя требуется убедиться, что динамическое состояние парсера ("PL_parser" и т. д.) правильно установлено, чтобы отразить источник разбираемого кода и лексический контекст выражения.

Возвращается дерево op, представляющее выражение. Если необязательное выражение отсутствует, возвращается указатель на null, в противном случае указатель не будет null.

OP*     parse_termexpr(U32 flags)

PL_parser

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

PL_parser->bufend

Прямой указатель на конец блока текста, который в настоящее время анализируется, конец буфера лексического анализатора. Он равен SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr). Символ NUL (нулевой байт) всегда находится в конце буфера и не считается частью содержимого буфера.

PL_parser->bufptr

Указывает на текущую позицию лексического анализа в буфере лексического анализатора. Символы вокруг этой точки могут быть свободно исследованы в пределах диапазона, ограниченного SvPVX("PL_parser->linestr") и "PL_parser->bufend". Байты буфера могут быть предназначены для интерпретации как UTF-8, так и Latin-1, как указано в "lex_bufutf8".

Код лексического анализа (будь то в ядре Perl или нет) перемещает этот указатель мимо потребляемых символов. Также ожидается, что он будет выполнять некоторую учётную запись всякий раз, когда потребляется символ новой строки. Это перемещение может быть более удобно выполнено функцией "lex_read_to", которая обрабатывает новые строки должным образом.

Интерпретацию байтов буфера можно абстрагировать, используя несколько более высокоуровневые функции "lex_peek_unichar" и "lex_read_unichar".

PL_parser->linestart

Указывает на начало текущей строки внутри буфера лексического анализатора. Это полезно для указания того, в какой колонке произошла ошибка, и не для чего больше. Это должно обновляться любым кодом лексического анализа, который потребляет символ новой строки; функция "lex_read_to" обрабатывает эту деталь.

PL_parser->linestr

Скалярный буфер, содержащий блок текста, который в настоящее время рассматривается для текста, который в настоящее время лексически анализируется. Это всегда скалярная строка (для которой SvPOK истинно). Не предполагается использовать его как скаляр стандартными способами; вместо этого обратитесь к буферу напрямую через указатель, описанные ниже.

Лексический анализатор поддерживает различные char* указатели на вещи в буфере PL_parser->linestr. Если PL_parser->linestr когда-либо перевыделяется, все эти указатели должны быть обновлены. Не пытайтесь делать это вручную, а используйте "lex_grow_linestr", если вам нужно перевыделить буфер.

Содержимое блока текста в буфере обычно представляет собой ровно одну полную строку ввода, включая и завершающий символ новой строки, но есть ситуации, когда это иначе. Байты буфера могут быть предназначены для интерпретации как UTF-8, так и Latin-1. Функция "lex_bufutf8" говорит вам, какой.

Не используйте флаг SvUTF8 для этого скаляра, который может с ним не совпадать.

Для прямого просмотра буфера переменная "PL_parser->bufend" указывает на конец буфера. Текущая позиция лексического анализа указывается "PL_parser->bufptr". Прямое использование этих указателей обычно предпочтительнее просмотра скаляра обычными способами.

wrap_keyword_plugin

Добавляет функцию C в цепочку плагинов ключевых слов. Это предпочтительный способ манипулирования переменной "PL_keyword_plugin". new_plugin - указатель на функцию C, которая должна быть добавлена в цепочку плагинов ключевых слов, и old_plugin_p указывает на место хранения указателя на следующую функцию в цепочке. Значение new_plugin записывается в переменную "PL_keyword_plugin", а ранее сохранённое там значение записывается в *old_plugin_p.

"PL_keyword_plugin" является глобальной для всего процесса, и модуль, желающий подключить разбор ключевых слов, может оказаться вызванным более одного раза на процесс, обычно в разных потоках. Для обработки этой ситуации эта функция является идемпотентной. Место *old_plugin_p вначале (один раз на процесс) должно содержать указатель на null. Переменная C со статическим сроком действия (объявленная на уровне файла, обычно также помеченная static для предоставления ей внутренней связи) будет неявно инициализирована должным образом, если у неё нет явного инициализатора. Эта функция будет фактически изменять цепочку плагинов только если найдёт *old_plugin_p равным null. Эта функция также потокобезопасна в малом масштабе. Она использует соответствующие блокировки, чтобы избежать гонок при доступе к "PL_keyword_plugin".

Когда эта функция вызывается, функция, на которую ссылается new_plugin, должна быть готова к вызову, за исключением того, что *old_plugin_p не заполнено. В ситуации с потоками new_plugin может быть вызвана немедленно, даже до того, как эта функция вернётся. *old_plugin_p всегда будет должным образом установлена перед вызовом new_plugin. Если new_plugin решит ничего не делать со своим идентификатором (что является обычным случаем для большинства вызовов плагина ключевого слова), оно должно подключить функцию плагина, на которую ссылается *old_plugin_p.

В целом, код XS для установки плагина ключевых слов обычно выглядит примерно так:

static Perl_keyword_plugin_t next_keyword_plugin;
static OP *my_keyword_plugin(pTHX_
    char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
{
    if (memEQs(keyword_ptr, keyword_len,
               "my_new_keyword")) {
        ...
    } else {
        return next_keyword_plugin(aTHX_
            keyword_ptr, keyword_len, op_ptr);
    }
}
BOOT:
    wrap_keyword_plugin(my_keyword_plugin,
                        &next_keyword_plugin);

Прямого доступа к "PL_keyword_plugin" следует избегать.

void    wrap_keyword_plugin(
            Perl_keyword_plugin_t new_plugin,
            Perl_keyword_plugin_t *old_plugin_p
        )

DECLARATION_FOR_LC_NUMERIC_MANIPULATION

Данная макрокоманда должна использоваться в качестве оператора. Она объявляет приватную переменную (название которой начинается с нижнего подчёркивания), необходимую для других макросов в данном разделе. Отсутствие правильного объявления приведёт к синтаксической ошибке. Для совместимости с компиляторами C89 C, она должна быть размещена в блоке перед любыми исполняемыми операторами.

void    DECLARATION_FOR_LC_NUMERIC_MANIPULATION

IN_LOCALE

Принимает значение TRUE, если в действии находится обычный pragma locale без параметра (use locale).

bool    IN_LOCALE

IN_LOCALE_COMPILETIME

Принимает значение TRUE, если при компиляции программы Perl (включая eval) активен обычный pragma locale без параметра (use locale).

bool    IN_LOCALE_COMPILETIME

IN_LOCALE_RUNTIME

Принимает значение TRUE, если при выполнении программы Perl (включая eval) активен обычный pragma locale без параметра (use locale).

bool    IN_LOCALE_RUNTIME

Perl_langinfo

Это (почти) полная замена системной функции nl_langinfo(3), принимающей те же item параметры и возвращающей ту же информацию. Но она более потокобезопасна, чем обычная nl_langinfo(), скрывает особенности обработки locale в Perl от вашего кода и может использоваться на системах, в которых отсутствует родная nl_langinfo.

Подробности:

Причина, по которой это не полная замена, на самом деле является преимуществом. Единственное отличие заключается в том, что она возвращает const char *, в то время как обычная nl_langinfo() возвращает char *, но вам (только по документации) запрещено записывать в буфер. Объявив эту const, компилятор накладывает это ограничение, так что при его нарушении вы узнаете об этом во время компиляции, а не получите ошибку segfaults во время выполнения.
Она обеспечивает правильные результаты для элементов RADIXCHAR и THOUSEP, без необходимости написания дополнительного кода. Причина дополнительного кода заключается в том, что они из категории locale LC_NUMERIC, которая обычно устанавливается Perl так, что радикс (десятичная точка) – это точка, а разделитель – пустая строка, независимо от того, каким должен быть базовый locale, и поэтому для получения ожидаемых результатов необходимо временно переключиться на базовый locale и затем вернуться обратно. (Вы можете использовать обычные nl_langinfo и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING", но тогда вы не получите других преимуществ Perl_langinfo(); не поддержание LC_NUMERIC в C (или эквивалентном) locale сломает много модулей CPAN, которые ожидают, что символ радикса (десятичной точки) будет точкой.)
Системная функция, которую она заменяет, может испортить свой статический буфер возврата не только последующим вызовом этой функции, но и freelocale, setlocale или другими изменениями locale. Возвращаемый буфер этой функции не изменяется до следующего вызова, поэтому буфер никогда не находится в испорченном состоянии.
Её буфер возврата предназначен для каждого потока, поэтому он также никогда не перезаписывается вызовом этой функции из другого потока, в отличие от функции, которую она заменяет.
Но самое главное, она работает на системах, на которых отсутствует nl_langinfo, таких как Windows, что делает ваш код более переносимым. Из примерно пятидесяти возможных элементов, указанных в стандарте POSIX 2008, http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html, только один полностью не реализован, хотя на платформах, не являющихся Windows, другой существенный элемент также не реализован. Она использует различные методы для извлечения других элементов, включая вызовы localeconv(3) и strftime(3), оба из которых указаны в C89, и поэтому всегда должны быть доступны. Более поздние версии strftime() имеют дополнительные возможности; "" возвращается для тех, что недоступны на вашей системе.

Важно отметить, что при вызове с элементом, который извлекается с помощью localeconv, буфер из любого предыдущего явного вызова localeconv будет перезаписан. Это означает, что вам необходимо сохранить содержимое этого буфера, если вам нужно получить доступ к нему после вызова этой функции. (Но имейте в виду, что вы, возможно, не захотите использовать localeconv() напрямую из-за проблем, перечисленных во втором пункте этого списка (выше) для RADIXCHAR и THOUSEP. Вы можете использовать методы, описанные в perlcall, чтобы вызвать "localeconv" в POSIX и избежать всех проблем, но тогда у вас будет хэш для распаковки.)

Подробности для тех элементов, которые могут отличаться от того, что возвращает эта эмуляция, и от того, что вернула бы родная nl_langinfo(), указаны в I18N::Langinfo.

При использовании Perl_langinfo на системах, на которых нет родной nl_langinfo(), вы должны

#include "perl_langinfo.h"

перед perl.h #include. Вы можете заменить свою langinfo.h #include на эту (делая это сохраняет символы, которые обычная langinfo.h пыталась бы импортировать в пространство имен для кода, которому это не нужно.)

Первоначальный импульс для Perl_langinfo() заключался в том, чтобы код, которому нужно определить текущий символ валюты, символ десятичной точки для чисел с плавающей запятой или разделитель групп цифр, мог использовать более простой и более потокобезопасный API nl_langinfo вместо localeconv(3), что сложно сделать потокобезопасным. Для других полей, возвращаемых localeconv, лучше использовать методы, описанные в perlcall, для вызова POSIX::localeconv(), который является потокобезопасным.

const char* Perl_langinfo(const nl_item item)

Perl_setlocale

Это (почти) полная замена системной функции setlocale(3), принимающей те же параметры и возвращающей ту же информацию, за исключением того, что она возвращает правильный базовый LC_NUMERIC locale. Обычная setlocale вместо этого вернёт C если базовый locale имеет неточку десятичную точку или непустой разделитель тысяч для отображения чисел с плавающей запятой. Это потому, что Perl сохраняет эту категорию locale так, что она имеет точку и пустой разделитель, временно изменяя locale во время операций, где требуется базовый. Perl_setlocale знает об этом и компенсирует; обычная setlocale нет.

Ещё одна причина, по которой это не полная замена, заключается в том, что она объявлена возвращать const char *, в то время как системная setlocale опускает const (вероятно, потому, что её API был определён давно и не может быть обновлён; изменение информации, которую setlocale возвращает, запрещено; это приводит к segfaults.)

Наконец, Perl_setlocale работает во всех ситуациях, в то время как обычная setlocale может быть полностью неэффективной на некоторых платформах в некоторых конфигурациях.

Perl_setlocale не следует использовать для изменения locale, за исключением систем, где предопределённая переменная ${^SAFE_LOCALES} равна 1. На некоторых таких системах системная setlocale() неэффективна, возвращает неправильную информацию и не меняет locale фактически. Perl_setlocale, однако, работает должным образом во всех ситуациях.

Возвращаемый указатель указывает на статический буфер для каждого потока, который перезаписывается при следующем вызове Perl_setlocale в том же потоке.

const char* Perl_setlocale(const int category,
                           const char* locale)

RESTORE_LC_NUMERIC

Используется в сочетании с одной из макрокоманд "STORE_LC_NUMERIC_SET_TO_NEEDED" и "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" для правильного восстановления состояния LC_NUMERIC.

Вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" должен был быть выполнен для объявления при компиляции приватной переменной, используемой этой макрокомандой и двумя STORE макрокомандами. Данная макрокоманда должна вызываться как одиночное утверждение, а не выражение, но с пустым списком аргументов, как показано ниже:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   RESTORE_LC_NUMERIC();
    ...
}

       void    RESTORE_LC_NUMERIC()

STORE_LC_NUMERIC_FORCE_TO_UNDERLYING

Используется кодом XS, который LC_NUMERIC учитывает locale, для принудительного установки locale для категории LC_NUMERIC на то, что Perl считает текущим базовым locale. (Интерпретатор Perl может ошибаться относительно фактического базового locale, если некоторый C или XS-код вызвал функцию C setlocale(3) за спиной; вызов "sync_locale" перед вызовом этой макрокоманды обновит записи Perl.)

Вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" должен был быть выполнен для объявления приватной переменной, используемой этой макрокомандой. Эта макрокоманда должна вызываться как отдельное утверждение, а не выражение, но с пустым списком аргументов, как показано ниже:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

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

В многопоточных Perl-интерпретаторах, работающих без потокобезопасности, эта макрокоманда использует мьютекс для принудительного создания критической секции. Таким образом, соответствующий RESTORE должен быть рядом и гарантированно вызван.

void    STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()

STORE_LC_NUMERIC_SET_TO_NEEDED

Это используется для помощи в оболочке кода XS или C, который LC_NUMERIC учитывает локаль. Эта категория локалей обычно устанавливается в локаль, где десятичный разделитель — точка, а разделитель между группами цифр — пустая строка. Это потому, что большинство кодов XS, которые читают числа с плавающей точкой, ожидают, что они будут иметь этот синтаксис.

Эта макрокоманда гарантирует, что текущее состояние LC_NUMERIC установлено должным образом, чтобы учитывать локаль, если вызов кода XS или C из программы Perl происходит в области действия use locale; или игнорировать локаль, если вызов вместо этого происходит вне такой области действия.

Эта макрокоманда является началом оболочки кода C или XS; завершение оболочки выполняется вызовом макрокоманды "RESTORE_LC_NUMERIC" после операции. В противном случае состояние может быть изменено, что негативно повлияет на другой код XS.

Вызов "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" должен быть выполнен для объявления в момент компиляции частной переменной, используемой этой макрокомандой. Эта макрокоманда должна вызываться как отдельное утверждение, а не выражение, но с пустым списком аргументов, например так:

{
   DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    ...
   STORE_LC_NUMERIC_SET_TO_NEEDED();
    ...
   RESTORE_LC_NUMERIC();
    ...
}

В многопоточных Perl-интерпретаторах, которые не работают с многопоточной безопасностью, эта макрокоманда использует мьютекс для принудительного создания критической секции. Поэтому соответствующий RESTORE должен быть расположен рядом и гарантированно вызван; см. "WITH_LC_NUMERIC_SET_TO_NEEDED" для более ограниченного способа обеспечения этого.

void    STORE_LC_NUMERIC_SET_TO_NEEDED()

STORE_LC_NUMERIC_SET_TO_NEEDED_IN

То же, что и "STORE_LC_NUMERIC_SET_TO_NEEDED", с in_lc_numeric, предоставленным как предварительно вычисленное значение IN_LC(LC_NUMERIC). Ответственность вызывающей стороны — убедиться, что статус PL_compiling и PL_hints не изменился с момента предварительного вычисления.

void    STORE_LC_NUMERIC_SET_TO_NEEDED_IN(
            bool in_lc_numeric
        )

switch_to_global_locale

В системах без поддержки локали или в типичных однопоточных сборках, или на платформах, не поддерживающих локаль на уровне потока, эта функция ничего не делает. На таких системах, которые поддерживают локаль, доступна только глобальная локаль для всего приложения.

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

Однако на системах Windows это не совсем так до Visual Studio 15, после чего Microsoft исправила ошибку. В случае использования следующих операций на более ранних платформах Windows может возникнуть гонка:

POSIX::localeconv
I18N::Langinfo, элементы CRNCYSTR и THOUSEP
"Perl_langinfo" в perlapi, элементы CRNCYSTR и THOUSEP

Первый элемент не поддаётся исправлению (кроме как обновлением до более поздней версии Visual Studio), но было бы возможно обойти последние два элемента, используя функции API Windows GetNumberFormat и GetCurrencyFormat; предлагаем исправления.

Без этого вызова функции потоки, использующие системную функцию setlocale(3), не будут работать должным образом, так как все функции, чувствительные к локали, будут обращаться к локали на уровне потока, и setlocale не будет иметь никакого эффекта для этого потока.

Код Perl должен быть переведен для вызова Perl_setlocale (который является прямым заменой системной функции setlocale) или использовать методы, указанные в perlcall, для вызова POSIX::setlocale. Любой из них прозрачно и правильно обработает все случаи однопоточных и многопоточных систем, поддерживающих POSIX 2008 или нет.

Библиотеки, не являющиеся библиотеками Perl, такие как gtk, которые вызывают системную функцию setlocale, могут продолжать работать, если эта функция вызывается перед передачей управления библиотеке.

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

void    switch_to_global_locale()

sync_locale

Perl_setlocale может быть использован в любое время для запроса или изменения локали (хотя изменение локали — нежелательная и опасная практика в многопоточных системах, не поддерживающих многопоточно безопасные операции с локальностью. (См. "Многопоточная операция" в perllocale). Следует избегать использования системной функции setlocale(3). Тем не менее, некоторые библиотеки, не являющиеся библиотеками Perl, которые вызываются из кода XS, такие как Gtk используют её, и это нельзя изменить. Когда локаль изменяется кодом XS, который не использовал Perl_setlocale, Perl необходимо сообщить об изменении локали. Используйте эту функцию для этого перед возвратом в Perl.

Значение возврата — логическое значение: TRUE, если глобальная локаль в момент вызова была активна; и FALSE, если была активна локаль на уровне потока. Это может использоваться вызывающей стороной, которая нуждается в восстановлении состояния таким, как было, для принятия решения о вызове Perl_switch_to_global_locale.

bool    sync_locale()

WITH_LC_NUMERIC_SET_TO_NEEDED

Эта макрокоманда вызывает предоставленное утверждение или блок в контексте пары "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC", если это необходимо, например:

WITH_LC_NUMERIC_SET_TO_NEEDED(
  SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
);

эквивалентно:

  {
#ifdef USE_LOCALE_NUMERIC
    DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
    STORE_LC_NUMERIC_SET_TO_NEEDED();
#endif
    SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
#ifdef USE_LOCALE_NUMERIC
    RESTORE_LC_NUMERIC();
#endif
  }

        void    WITH_LC_NUMERIC_SET_TO_NEEDED(block)

WITH_LC_NUMERIC_SET_TO_NEEDED_IN

То же, что и "WITH_LC_NUMERIC_SET_TO_NEEDED", с in_lc_numeric, предоставленным как предварительно вычисленное значение IN_LC(LC_NUMERIC). Ответственность вызывающей стороны — убедиться, что статус PL_compiling и PL_hints не изменился с момента предварительного вычисления.

void    WITH_LC_NUMERIC_SET_TO_NEEDED_IN(
            bool in_lc_numeric, block
        )

Магические функции

mg_clear

Очистить что-то магическое, что представляет SV. См. "sv_magic".

int     mg_clear(SV* sv)

mg_copy

Копирует магию из одного SV в другой. См. "sv_magic".

int     mg_copy(SV *sv, SV *nsv, const char *key,
                I32 klen)

mg_find

Находит указатель магии для type, соответствующий SV. См. "sv_magic".

MAGIC*  mg_find(const SV* sv, int type)

mg_findext

Находит указатель магии type с заданным vtbl для SV. См. "sv_magicext".

MAGIC*  mg_findext(const SV* sv, int type,
                   const MGVTBL *vtbl)

mg_free

Освободить любой магический ресурс, используемый SV. См. "sv_magic".

int     mg_free(SV* sv)

mg_freeext

Удалить любую магию типа how, используя виртуальную таблицу vtbl из SV sv. См. "sv_magic".

mg_freeext(sv, how, NULL) эквивалентно mg_free_type(sv, how).

void    mg_freeext(SV* sv, int how, const MGVTBL *vtbl)

mg_free_type

Удалить любую магию типа how из SV sv. См. "sv_magic".

void    mg_free_type(SV* sv, int how)

mg_get

Выполнить магию перед извлечением значения из SV. Тип SV должен быть >= SVt_PVMG. См. "sv_magic".

int     mg_get(SV* sv)

mg_length

УСТАРЕВШАЯ функция! Планируется удалить эту функцию в будущих версиях Perl. Не используйте её в новом коде; удалите её из существующего кода.

Сообщает длину SV в байтах, вызывая магическую функцию length, если она доступна, но не устанавливает флаг UTF8 на sv. Будет переходить к магической функции «get», если нет магии «length», но без указания, вызывалась ли магия «get». Предполагается, что sv — PVMG или выше. Используйте sv_len() вместо этого.

U32     mg_length(SV* sv)

mg_magical

Включает магическое состояние SV. См. "sv_magic".

void    mg_magical(SV* sv)

mg_set

Выполнить магию после присвоения значения SV. См. "sv_magic".

int     mg_set(SV* sv)

SvGETMAGIC

Вызывает mg_get на SV, если у него есть магия «get». Например, это вызовет FETCH для привязанной переменной. Эта макрокоманда вычисляет свой аргумент более одного раза.

void    SvGETMAGIC(SV* sv)

SvLOCK

Организует получение блокировки взаимного исключения на sv, если соответствующий модуль загружен.

void    SvLOCK(SV* sv)

SvSETMAGIC

Вызывает mg_set на SV, если у него есть магия «set». Это необходимо после изменения скаляра, если это магическая переменная, например, $|, или привязанная переменная (вызывает STORE). Эта макрокоманда вычисляет свой аргумент более одного раза.

void    SvSETMAGIC(SV* sv)

SvSetMagicSV

Как SvSetSV, но выполняет все необходимые действия магии «set» после этого.

void    SvSetMagicSV(SV* dsv, SV* ssv)

SvSetMagicSV_nosteal

Как SvSetSV_nosteal, но выполняет все необходимые действия магии «set» после этого.

void    SvSetMagicSV_nosteal(SV* dsv, SV* ssv)

SvSetSV

Вызывает sv_setsv, если dsv не совпадает с ssv. Может вычислять аргументы более одного раза. Не обрабатывает магию «set» для целевого SV.

void    SvSetSV(SV* dsv, SV* ssv)

SvSetSV_nosteal

Вызывает неразрушающую версию sv_setsv, если dsv не совпадает с ssv . Может вычислять аргументы более одного раза.

void    SvSetSV_nosteal(SV* dsv, SV* ssv)

SvSHARE

Организует совместное использование sv между потоками, если соответствующий модуль загружен.

void    SvSHARE(SV* sv)

sv_string_from_errnum

Генерирует строку сообщения, описывающую ошибку ОС, и возвращает её как SV. errnum должно быть значением, которое errno может принять, идентифицируя тип ошибки.

Если tgtsv не является пустым указателем, то строка будет записана в этот SV (заменяя существующее содержимое), и он будет возвращён. Если tgtsv является пустым указателем, то строка будет записана в новый временный SV, который будет возвращён.

Сообщение будет взято из локали, которая используется $!, и закодировано в SV так, как это сделает $!. Подробности этого процесса могут измениться в будущем. В настоящее время сообщение берётся по умолчанию из C локали (обычно генерируя английское сообщение), и из выбранной локали, когда действует pragma use locale. Делается попытка декодировать сообщение из кодировки символов локали, но оно будет декодировано только как UTF-8 или ISO-8859-1. Оно всегда корректно декодируется в локали UTF-8, обычно в локали ISO-8859-1 и никогда в других локалях.

SV всегда возвращается, содержащий фактическую строку и без других установленных битов. В отличие от $!, сообщение генерируется даже для errnum ноль (означающее успех), и если нет полезного сообщения, возвращается бесполезная строка (в настоящее время пустая).

SV*     sv_string_from_errnum(int errnum, SV* tgtsv)

SvUNLOCK

Освобождает блокировку взаимного исключения на sv , если соответствующий модуль загружен.

void    SvUNLOCK(SV* sv)

Управление памятью

Копирование

Интерфейс XSUB-писателя для C-функции memcpy. src — это источник, dest — это место назначения, nitems — количество элементов, а type — тип. Может завершиться ошибкой при перекрывающихся копиях. См. также "Move".

void    Copy(void* src, void* dest, int nitems, type)

Копирование D

Подобно Copy, но возвращает dest. Полезно для побуждения компиляторов к оптимизации хвостовой рекурсии.

void *  CopyD(void* src, void* dest, int nitems, type)

Перемещение

Интерфейс XSUB-писателя для C-функции memmove. src — это источник, dest — это место назначения, nitems — количество элементов, а type — тип. Поддерживает перекрывающиеся перемещения. См. также "Copy".

void    Move(void* src, void* dest, int nitems, type)

Перемещение D

Подобно Move, но возвращает dest. Полезно для побуждения компиляторов к оптимизации хвостовой рекурсии.

void *  MoveD(void* src, void* dest, int nitems, type)

Newx

Интерфейс XSUB-писателя для C-функции malloc.

Память, полученная с помощью этой функции, только должна быть освобождена с помощью «Safefree».

В версии 5.9.3 функции Newx() и аналогичные заменяют более старую API New(), удаляя первый параметр, x, который являлся вспомогательным средством отладки, позволяющим вызывающим функциям идентифицировать себя. Данное средство было заменено новой опцией компиляции PERL_MEM_LOG (см. «PERL_MEM_LOG» в perlhacktips). Более старая API всё ещё доступна для использования в XS-модулях, поддерживающих более ранние версии Perl.

void    Newx(void* ptr, int nitems, type)

Newxc

Интерфейс XSUB-писателя для C-функции malloc с приведением типов. См. также "Newx".

Память, полученная с помощью этой функции, только должна быть освобождена с помощью «Safefree».

void    Newxc(void* ptr, int nitems, type, cast)

Newxz

Интерфейс XSUB-писателя для C-функции malloc. Выделенная память обнуляется с помощью memzero. См. также "Newx".

Память, полученная с помощью этой функции, только должна быть освобождена с помощью «Safefree».

void    Newxz(void* ptr, int nitems, type)

Отравление

PoisonWith(0xEF) для отслеживания доступа к освобождённой памяти.

void    Poison(void* dest, int nitems, type)

Отравление освобождения

PoisonWith(0xEF) для отслеживания доступа к освобождённой памяти.

void    PoisonFree(void* dest, int nitems, type)

Отравление нового

PoisonWith(0xAB) для отслеживания доступа к выделенной, но не инициализированной памяти.

void    PoisonNew(void* dest, int nitems, type)

Отравление значением

Заполнение памяти шаблоном байтов (байт повторяется многократно), который, надеемся, поймает попытки доступа к неинициализированной памяти.

void    PoisonWith(void* dest, int nitems, type,
                   U8 byte)

Перевыделение

Интерфейс XSUB-писателя для C-функции realloc.

Память, полученная с помощью этой функции, только должна быть освобождена с помощью «Safefree».

void    Renew(void* ptr, int nitems, type)

Перевыделение с приведением типов

Интерфейс XSUB-писателя для C-функции realloc с приведением типов.

Память, полученная с помощью этой функции, только должна быть освобождена с помощью «Safefree».

void    Renewc(void* ptr, int nitems, type, cast)

Безопасное освобождение

Интерфейс XSUB-писателя для C-функции free.

Это следует исключительно использовать для памяти, полученной с помощью «Newx» и аналогичных функций.

void    Safefree(void* ptr)

savepv

Perl-версия strdup(). Возвращает указатель на новую выделенную строку, которая является дубликатом pv. Размер строки определяется strlen(), что означает, что она может не содержать вложенных NUL символов и должна иметь завершающий NUL символ. Для предотвращения утечек памяти, выделенная для новой строки память должна быть освобождена, когда она больше не нужна. Это можно сделать с помощью функции «Safefree» или «SAVEFREEPV».

На некоторых платформах, например, Windows, вся выделенная память, принадлежащая потоку, освобождается при завершении этого потока. Поэтому, если вам нужно, чтобы этого не происходило, необходимо использовать функции совместного использования памяти, такие как "savesharedpv".

char*   savepv(const char* pv)

savepvn

Perl-версия того, чем strndup() была бы, если бы существовала. Возвращает указатель на новую выделенную строку, которая является дубликатом первых len байтов из pv, плюс завершающий NUL байт. Выделенная для новой строки память может быть освобождена с помощью функции Safefree().

char*   savepvn(const char* pv, Size_t len)

savepvs

Подобно savepvn, но принимает литеральную строку вместо пары строка/длина.

char*   savepvs("literal string")

savesharedpv

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

char*   savesharedpv(const char* pv)

savesharedpvn

Версия savepvn(), которая выделяет дублирующую строку в памяти, которая совместно используется между потоками. (С конкретным отличием, что указатель на NULL не приемлем).

char*   savesharedpvn(const char *const pv,
                      const STRLEN len)

savesharedpvs

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

char*   savesharedpvs("literal string")

savesharedsvpv

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

char*   savesharedsvpv(SV *sv)

savesvpv

Версия savepv()/savepvn(), которая получает строку для дублирования из переданного SV, используя SvPV()

char*   savesvpv(SV* sv)

Копирование структуры

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

void    StructCopy(type *src, type *dest, type)

Ноль

Интерфейс XSUB-писателя для C-функции memzero. dest — это место назначения, nitems — количество элементов, а type — тип.

void    Zero(void* dest, int nitems, type)

Ноль D

Подобно Zero, но возвращает dest. Полезно для побуждения компиляторов к оптимизации хвостовой рекурсии.

void *  ZeroD(void* dest, int nitems, type)

Функции прочие

dump_c_backtrace

Выводит трассировку стека вызовов C в заданный fp.

Возвращает true, если трассировка стека была получена, и false — в противном случае.

bool    dump_c_backtrace(PerlIO* fp, int max_depth,
                         int skip)

fbm_compile

Анализирует строку для быстрых поисков в ней с использованием алгоритма Бойера-Мура — fbm_instr().

void    fbm_compile(SV* sv, U32 flags)

fbm_instr

Возвращает позицию SV в строке, ограниченной big и bigend (bigend) — символ, следующий за последним символом). Возвращает NULL, если строка не найдена. sv не обязательно должен быть fbm_compiled, но тогда поиск будет не таким быстрым.

char*   fbm_instr(unsigned char* big,
                  unsigned char* bigend, SV* littlestr,
                  U32 flags)

foldEQ

Возвращает true, если ведущие len байта строк s1 и s2 одинаковы без учета регистра; в противном случае — false. Заглавные и строчные буквы ASCII диапазона соответствуют самим себе и своим противоположным регистрам. Символы без регистра и вне ASCII диапазона соответствуют только самим себе.

I32     foldEQ(const char* a, const char* b, I32 len)

foldEQ_locale

Возвращает true, если ведущие len байта строк s1 и s2 одинаковы без учета регистра в текущем локали; в противном случае — false.

I32     foldEQ_locale(const char* a, const char* b,
                      I32 len)

form

Принимает шаблон форматирования в стиле sprintf и стандартные (не SV) аргументы и возвращает отформатированную строку.

(char *) Perl_form(pTHX_ const char* pat, ...)

может использоваться в любом месте, где требуется строка (char *):

char * s = Perl_form("%d.%d",major,minor);

Использует один частный буфер, поэтому если нужно отформатировать несколько строк, необходимо явно скопировать предыдущие строки (и освободить копии, когда закончите).

char*   form(const char* pat, ...)

getcwd_sv

Заполняет sv текущим рабочим каталогом

int     getcwd_sv(SV* sv)

get_c_backtrace_dump

Возвращает SV, содержащий дамп depth кадров стека вызовов, пропуская skip самых вложенных. Обычно достаточно 20.

Выводимый результат выглядит так:

... 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl ...

Поля разделены табуляцией. Первый столбец — глубина (ноль — самый вложенный не пропущенный кадр). В шестнадцатеричном:смещении шестнадцатеричное значение — местонахождение счётчика команд в S_parse_body, а :смещение (возможно, отсутствует) — смещение внутри S_parse_body счётчика команд.

util.c:1716 — файл исходного кода и номер строки.

/usr/bin/perl — очевидно (надеюсь).

Неизвестные — "-". К сожалению, неизвестные могут возникать довольно легко: если платформа не поддерживает извлечение информации; если в двоичном файле отсутствуют отладочные данные; если оптимизатор преобразовывал код, например, через встраивание.

SV*     get_c_backtrace_dump(int max_depth, int skip)

ibcmp

Это синоним для (! foldEQ())

I32     ibcmp(const char* a, const char* b, I32 len)

ibcmp_locale

Это синоним для (! foldEQ_locale())

I32     ibcmp_locale(const char* a, const char* b,
                     I32 len)

instr

То же самое, что strstr(3), которое находит и возвращает указатель на первое вхождение завершающейся нулём подстроки little в завершающейся нулём строке big, возвращая NULL, если не найдено. Завершающие нулевые байты не сравниваются.

char*   instr(const char* big, const char* little)

IS_SAFE_SYSCALL

То же самое, что "is_safe_syscall".

bool    IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
                        NN const char *what,
                        NN const char *op_name)

is_safe_syscall

Проверяет, что заданный pv (с длиной len) не содержит внутренних NUL символов. Если содержит, устанавливает errno в ENOENT, при желании предупреждает с использованием категории syscalls, и возвращает FALSE.

Возвращает TRUE, если имя безопасно.

what и op_name используются в любом предупреждении.

Используется макросом IS_SAFE_SYSCALL().

bool    is_safe_syscall(const char *pv, STRLEN len,
                        const char *what,
                        const char *op_name)

LIKELY

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

memCHRs

Возвращает позицию первого вхождения байта c в литеральной строке "list", или NULL, если c не встречается в "list". Все байты обрабатываются как unsigned char. Таким образом, этот макрос может использоваться для определения, присутствует ли c в наборе определённых символов. В отличие от strchr(3), он работает даже если c является NUL (и набор не включает NUL).

bool    memCHRs("list", char c)

memEQ

Проверяет два буфера (которые могут содержать встраиваемые NUL символы), чтобы определить, равны ли они. Параметр len указывает количество байтов для сравнения. Возвращает ноль, если равны, или ненулевое значение, если не равны.

bool    memEQ(char* s1, char* s2, STRLEN len)

memEQs

Подобно "memEQ", но вторая строка — литерал в двойных кавычках, l1 указывает количество байтов в s1. Возвращает ноль, если равны, или ненулевое значение, если не равны.

bool    memEQs(char* s1, STRLEN l1, "s2")

memNE

Проверяет два буфера (которые могут содержать встраиваемые NUL символы), чтобы определить, не равны ли они. Параметр len указывает количество байтов для сравнения. Возвращает ноль, если не равны, или ненулевое значение, если равны.

bool    memNE(char* s1, char* s2, STRLEN len)

memNEs

Подобно "memNE", но вторая строка — литерал в двойных кавычках, l1 указывает количество байтов в s1. Возвращает ноль, если не равны, или ненулевое значение, если равны.

bool    memNEs(char* s1, STRLEN l1, "s2")

mess

Принимает шаблон форматирования в стиле sprintf и список аргументов. Используется для генерации сообщения. Если сообщение не заканчивается символом новой строки, то оно будет дополнено некоторым указанием текущего расположения в коде, как описано для "mess_sv".

Обычно результирующее сообщение возвращается в новом смертном SV. Во время глобального уничтожения один SV может быть общим для нескольких вызовов этой функции.

SV*     mess(const char* pat, ...)

mess_sv

Расширяет сообщение, предназначенное для пользователя, добавив в него указание текущего положения в коде, если сообщение не выглядит завершённым.

basemsg — начальное сообщение или объект. Если это ссылка, она будет использована как есть и будет результатом этой функции. В противном случае она используется как строка, и если она уже заканчивается символом новой строки, она считается завершённой, и результат этой функции будет той же строкой. Если сообщение не заканчивается символом новой строки, то будет добавлен фрагмент типа at foo.pl line 37, а возможно и другие фрагменты, указывающие текущее состояние выполнения. Результирующее сообщение будет заканчиваться точкой и символом новой строки.

Обычно результирующее сообщение возвращается в новом смертном SV. Во время глобального уничтожения один SV может быть общим для нескольких вызовов этой функции. Если consume истинно, функция может (но не обязана) изменить и вернуть basemsg вместо выделения нового SV.

SV*     mess_sv(SV* basemsg, bool consume)

my_snprintf

Функциональность C-библиотеки snprintf, если она доступна и соответствует стандартам (используется vsnprintf). Однако, если vsnprintf недоступна, к сожалению, будет использована небезопасная vsprintf, которая может привести к переполнению буфера (есть проверка на переполнение, но она может быть слишком поздней). Рассмотрите использование sv_vcatpvf вместо этого или получение vsnprintf.

int     my_snprintf(char *buffer, const Size_t len,
                    const char *format, ...)

my_sprintf

УСТАРЕВШИЙ! Планируется удалить эту функцию из будущих версий Perl. Не используйте её в новом коде; удалите из существующего.

НЕ используйте её из-за возможности переполнения buffer. Используйте my_snprintf() вместо неё.

int     my_sprintf(NN char *buffer, NN const char *pat,
                   ...)

my_strlcat

Функция C-библиотеки strlcat, если она доступна, или Perl-реализация. Работает со строками C, завершёнными нулём.

my_strlcat() добавляет строку src в конец dst. Она добавит не более size - strlen(dst) - 1 символов. Затем она добавит завершающий нуль, если size не равно 0, или если исходная строка dst была длиннее size. (на практике это не должно происходить, так как это означает, что либо size некорректно, либо dst не является корректной строкой, завершённой нулём).

Обратите внимание, что size — это полный размер буфера назначения, и результат гарантированно завершен нулём, если есть место. Обратите внимание, что место для NUL должно быть включено в size.

Возвращаемое значение — общая длина, которую dst имела бы, если size достаточно велика. Таким образом, это начальная длина dst плюс длина src. Если size меньше возвращаемого значения, избыток не был добавлен.

Size_t  my_strlcat(char *dst, const char *src,
                   Size_t size)

my_strlcpy

Функция C-библиотеки strlcpy, если она доступна, или Perl-реализация. Работает со строками C, завершёнными нулём.

my_strlcpy() копирует до size - 1 символов из строки src в dst, завершая результат нулём, если size не равно 0.

Возвращаемое значение — общая длина, которую src имела бы, если бы копирование полностью удалось. Если оно больше size, избыток не был скопирован.

Size_t  my_strlcpy(char *dst, const char *src,
                   Size_t size)

my_strnlen

Библиотека C strnlen (если доступна) или её реализация на Perl.

my_strnlen() вычисляет длину строки до maxlen символов. Она никогда не попытается обратиться к больше чем maxlen символам, что делает её подходящей для использования со строками, которые не гарантированно завершаются нулём.

Size_t  my_strnlen(const char *str, Size_t maxlen)

my_vsnprintf

Библиотека C vsnprintf (если доступна и соответствует стандарту). Однако, если vsnprintf недоступна, она, к сожалению, будет использовать небезопасную функцию vsprintf, которая может переполнить буфер (есть проверка переполнения, но она может оказаться слишком поздней). Рассмотрите использование sv_vcatpvf или получение vsnprintf.

int     my_vsnprintf(char *buffer, const Size_t len,
                     const char *format, va_list ap)

ninstr

Находит первое (самое левое) вхождение последовательности байтов в другой последовательности. Это версия Perl функции strstr(), расширенная для обработки произвольных последовательностей, потенциально содержащих встроенные NUL символы (NUL - это то, что обозначает начальный n в имени функции; некоторые системы имеют эквивалент, memmem(), но с несколько отличающимся API).

Другой способ понять эту функцию - найти иглу в стоге сена. big указывает на первый байт в стоге сена. big_end указывает на байт, следующий за последним байтом в стоге сена. little указывает на первый байт в игле. little_end указывает на байт, следующий за последним байтом в игле. Все параметры должны быть не-NULL.

Функция возвращает NULL если нет вхождения little в big. Если little является пустой строкой, возвращается big.

Поскольку эта функция работает на уровне байтов, и из-за присущих характеристик UTF-8 (или UTF-EBCDIC), она будет работать правильно, если и игла, и стог сена - это строки с одинаковым UTF-8 представлением, но не если их UTF-8 представления отличаются.

char*   ninstr(const char* big, const char* bigend,
               const char* little, const char* lend)

PERL_SYS_INIT

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

void    PERL_SYS_INIT(int *argc, char*** argv)

PERL_SYS_INIT3

void    PERL_SYS_INIT3(int *argc, char*** argv,
                       char*** env)

PERL_SYS_TERM

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

void    PERL_SYS_TERM()

READ_XDIGIT

Возвращает значение шестнадцатеричной цифры ASCII и продвигает указатель строки. Поведение определено только в случае, когда isXDIGIT(*str) истинно.

U8      READ_XDIGIT(char str*)

rninstr

Как "ninstr", но вместо этого находит последнее (самое правое) вхождение последовательности байтов в другой последовательности, возвращая NULL если такого вхождения нет.

char*   rninstr(const char* big, const char* bigend,
                const char* little, const char* lend)

STMT_START

STMT_START { statements; } STMT_END;

может использоваться как отдельное оператор, как в

if (x) STMT_START { ... } STMT_END; else ...

Они часто используются в определениях макросов. Обратите внимание, что из них нельзя вернуть значение.

strEQ

Проверяет, равны ли две строки, завершённые NUL, возвращает true или false.

bool    strEQ(char* s1, char* s2)

strGE

Проверяет, больше или равно ли первая строка, s1, второй строке, s2, завершённые NUL, возвращает true или false.

bool    strGE(char* s1, char* s2)

strGT

Проверяет, больше ли первая строка, s1, второй строке, s2, завершённые NUL, возвращает true или false.

bool    strGT(char* s1, char* s2)

strLE

Проверяет, меньше или равно ли первая строка, s1, второй строке, s2, завершённые NUL, возвращает true или false.

bool    strLE(char* s1, char* s2)

strLT

Проверяет, меньше ли первая строка, s1, второй строке, s2, завершённые NUL, возвращает true или false.

bool    strLT(char* s1, char* s2)

strNE

Проверяет, отличаются ли две строки, завершённые NUL, возвращает true или false.

bool    strNE(char* s1, char* s2)

strnEQ

Проверяет, равны ли две строки, завершённые NUL, возвращает true или false. Параметр len указывает количество сравниваемых байтов. (Обёртка для strncmp).

bool    strnEQ(char* s1, char* s2, STRLEN len)

strnNE

Проверяет, отличаются ли две строки, завершённые NUL, возвращает true или false. Параметр len указывает количество сравниваемых байтов. (Обёртка для strncmp).

bool    strnNE(char* s1, char* s2, STRLEN len)

sv_destroyable

Функция-заглушка, сообщающая, что объект может быть уничтожен, когда модуль совместного использования отсутствует. Она игнорирует свой единственный аргумент SV и возвращает 'true'. Существует, чтобы избежать проверки указателя на функцию NULL и потому что она может выдать предупреждение при определённом уровне строгости.

bool    sv_destroyable(SV *sv)

sv_nosharing

Функция-заглушка, которая "делит" SV, когда модуль совместного использования отсутствует. Или "блокирует" его. Или "разблокирует" его. Другими словами, игнорирует свой единственный аргумент SV. Существует, чтобы избежать проверки указателя на функцию NULL и потому что она может выдать предупреждение при определённом уровне строгости.

void    sv_nosharing(SV *sv)

UNLIKELY

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

vmess

pat и args - это шаблон формата в стиле sprintf и список аргументов соответственно. Они используются для генерации сообщения в виде строки. Если сообщение не заканчивается новой строкой, оно будет дополнено каким-либо указанием на текущее место в коде, как описано для "mess_sv".

Обычно результирующее сообщение возвращается в новом временном SV. Во время глобальной очистки может быть один SV, используемый совместно между вызовами этой функции.

SV*     vmess(const char* pat, va_list* args)

Функции MRO

Эти функции относятся к порядку разрешения методов (MRO) классов Perl. Также см. perlmroapi.

mro_get_linear_isa

Возвращает линейную структуризацию MRO для данного хранилища (stash). По умолчанию это будет то, что возвращает mro_get_linear_isa_dfs, если для хранилища не используется другой порядок MRO. Значение возврата — AV* только для чтения.

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

AV*     mro_get_linear_isa(HV* stash)

mro_method_changed_in

Очищает кэширование методов для всех дочерних классов данного хранилища, чтобы они могли заметить изменения в нём.

В идеале, все экземпляры PL_sub_generation++ в исходном коде Perl вне mro.c должны быть заменены вызовами этой функции.

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

1) Прямое изменение записей хранилища HV из кода XS.

2) Присваивание ссылки на константу скаляра только для чтения в запись хранилища для создания константной подпрограммы (как делает constant.pm).

Эта же функция доступна из чистого Perl через mro::method_changed_in(classname).

void    mro_method_changed_in(HV* stash)

mro_register

Регистрирует плагин пользовательского MRO. Подробную информацию об этой и других функциях MRO см. в perlmroapi.

ПРИМЕЧАНИЕ: эту функцию необходимо явно вызывать как Perl_mro_register с параметром aTHX_.

void    Perl_mro_register(pTHX_ 
                          const struct mro_alg *mro)

Функции Multicall

dMULTICALL

Объявляет локальные переменные для multicall. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

dMULTICALL;

MULTICALL

Создаёт лёгкий обратный вызов. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

MULTICALL;

POP_MULTICALL

Закрывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

POP_MULTICALL;

PUSH_MULTICALL

Открывающая скобка для лёгкого обратного вызова. См. "LIGHTWEIGHT CALLBACKS" в perlcall.

PUSH_MULTICALL(CV* the_cv);

Числовые функции

grok_bin

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

На входе start и *len_p задают строку для сканирования, *flags задаёт флаги преобразования, а result должно быть NULL или указателем на NV. Сканирование останавливается в конце строки или перед первой неверной символом. Если PERL_SCAN_SILENT_ILLDIGIT установлено в *flags, встреча с неверным символом (кроме NUL) также вызовет предупреждение. По возвращении *len_p устанавливается в длину прочитанной строки, а *flags задаёт флаги вывода.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_bin возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает приближённое значение в *result (которое является NV; или приближение отбрасывается, если result равно NULL).

Двоичное число может необязательно иметь префикс "0b" или "b", если PERL_SCAN_DISALLOW_PREFIX не установлено в *flags при входе.

Если PERL_SCAN_ALLOW_UNDERSCORES установлено в *flags, то любые или все пары цифр могут быть разделены одиночной подчёркиванием; также допускается одиночное подчёркивание в начале.

UV      grok_bin(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

grok_hex

преобразует строку, представляющую шестнадцатеричное число, в числовой вид.

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_hex возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает приближённое значение в *result (которое является NV; или приближение отбрасывается, если result равно NULL).

Шестнадцатеричное число может необязательно иметь префикс "0x" или "x", если PERL_SCAN_DISALLOW_PREFIX не установлено в *flags при входе.

UV      grok_hex(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

grok_infnan

Вспомогательная функция для grok_number(), принимает различные способы написания «бесконечность» или «не число» и возвращает одну из следующих комбинаций флагов:

IS_NUMBER_INFINITY
IS_NUMBER_NAN
IS_NUMBER_INFINITY | IS_NUMBER_NEG
IS_NUMBER_NAN | IS_NUMBER_NEG
0

возможно, |-ed с IS_NUMBER_TRAILING.

Если распознаётся бесконечность или не число, *sp будет указывать на один байт за концом распознанной строки. Если распознавание не удалось, возвращается ноль, и *sp не смещается.

int     grok_infnan(const char** sp, const char *send)

grok_number

Идентично grok_number_flags() с flags установленным в ноль.

int     grok_number(const char *pv, STRLEN len,
                    UV *valuep)

grok_number_flags

Распознаёт (или нет) число. Возвращает тип числа (0, если не распознано), иначе это побитовое ИЛИ комбинация IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (определены в perl.h).

Если значение числа может поместиться в UV, оно возвращается в *valuep. IS_NUMBER_IN_UV будет установлено, чтобы указать, что *valuep корректно, IS_NUMBER_IN_UV никогда не устанавливается, если *valuep не корректно, но *valuep может быть присвоено во время обработки, даже если IS_NUMBER_IN_UV не установлено по возвращении. Если valuep равно NULL, IS_NUMBER_IN_UV будет установлено в тех же случаях, что и когда valuep не-NULL, но никакого фактического присваивания (или SEGV) не произойдёт.

IS_NUMBER_NOT_INT будет установлено с IS_NUMBER_IN_UV, если были встречены конечные десятичные разряды (в этом случае *valuep даёт истинное значение, усечённое до целого), и IS_NUMBER_NEG, если число отрицательное (в этом случае *valuep содержит абсолютное значение). IS_NUMBER_IN_UV не устанавливается, если использовалась запись с обозначением порядка или число больше, чем UV.

flags разрешает только PERL_SCAN_TRAILING, что позволяет конечный нечисловой текст в случае успешного grok, устанавливая IS_NUMBER_TRAILING в результате.

int     grok_number_flags(const char *pv, STRLEN len,
                          UV *valuep, U32 flags)

GROK_NUMERIC_RADIX

Синоним для "grok_numeric_radix"

bool    GROK_NUMERIC_RADIX(NN const char **sp,
                           NN const char *send)

grok_numeric_radix

Сканировать и пропустить десятичную запятую (радикс).

bool    grok_numeric_radix(const char **sp,
                           const char *send)

grok_oct

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

Если значение меньше или равно UV_MAX, оно возвращается как UV, флаги вывода сбрасываются, и ничего не записывается в *result. Если значение больше UV_MAX, grok_oct возвращает UV_MAX, устанавливает PERL_SCAN_GREATER_THAN_UV_MAX во флагах вывода и записывает приближённое значение в *result (которое является NV; или приближение отбрасывается, если result равно NULL).

Флаг PERL_SCAN_DISALLOW_PREFIX всегда обрабатывается как установленный для этой функции.

UV      grok_oct(const char* start, STRLEN* len_p,
                 I32* flags, NV *result)

isinfnan

Функция Perl_isinfnan() — вспомогательная функция, которая возвращает true, если аргумент NV является бесконечностью или NaN, и false в противном случае. Для более подробных проверок используйте Perl_isinf() и Perl_isnan().

Это также логическое отрицание Perl_isfinite().

bool    isinfnan(NV nv)

IS_NUMBER_GREATER_THAN_UV_MAX bool IS_NUMBER_GREATER_THAN_UV_MAX

IS_NUMBER_INFINITY bool IS_NUMBER_INFINITY

IS_NUMBER_IN_UV bool IS_NUMBER_IN_UV

IS_NUMBER_NAN bool IS_NUMBER_NAN

IS_NUMBER_NEG bool IS_NUMBER_NEG

IS_NUMBER_NOT_INT

bool    IS_NUMBER_NOT_INT

my_strtod

Эта функция эквивалентна функции libc strtod(), и доступна даже на платформах, где обычная strtod() отсутствует. Её возвращаемое значение — наилучшая доступная точность в зависимости от возможностей платформы и опций Configure.

Она корректно обрабатывает символ разделителя десятичной части в зависимости от локали, то есть ожидает точку, за исключением случаев вызова из области действия use locale, в котором случае символом разделителя десятичной части должна быть запятая, указанная текущей локалью.

Вместо неё можно использовать синоним Strtod().

NV      my_strtod(const char * const s, char ** e)

PERL_ABS

Бестиповая abs или fabs, и так далее. (Использование ниже указывает, что это для целых чисел, но это работает для любого типа.) Используйте вместо них, так как функции C-библиотеки принуждают свой аргумент к тому, что они ожидают, что может привести к катастрофе. Но также будьте осторожны, что это вычисляет свой аргумент дважды, поэтому нет x++.

int     PERL_ABS(int)

PERL_INT_MAX

Эта и PERL_INT_MIN, PERL_LONG_MAX, PERL_LONG_MIN, PERL_QUAD_MAX, PERL_SHORT_MAX, PERL_SHORT_MIN, PERL_UCHAR_MAX, PERL_UCHAR_MIN, PERL_UINT_MAX, PERL_ULONG_MAX, PERL_ULONG_MIN, PERL_UQUAD_MAX, PERL_UQUAD_MIN, PERL_USHORT_MAX, PERL_USHORT_MIN, PERL_QUAD_MIN задают наибольшее и наименьшее число, представимое в текущей платформе, в переменных соответствующих типов.

Для знакомых типов наименьшее представимое число — это самое отрицательное число, которое максимально удалено от нуля.

Для компиляторов C99 и более поздних версий они соответствуют таким вещам, как INT_MAX, которые доступны коду C. Но эти константы, предоставленные Perl, позволяют коду, скомпилированному на более ранних компиляторах, получить доступ к тем же константам.

Perl_signbit

Возвращает ненулевое целое число, если бит знака в NV установлен, и 0, если нет.

Если Configure обнаруживает, что в этой системе есть signbit(), который будет работать с нашими NV, то мы просто используем его через #define в perl.h. В противном случае используется это реализация. Основное применение этой функции — отлов -0.0.

Configure примечания: Эта функция называется 'Perl_signbit' вместо просто 'signbit', потому что легко представить себе систему с функцией или макросом signbit(), которая не работает с нашим выбором NV. Мы не должны просто пере#define signbit как Perl_signbit и ожидать, что стандартные заголовки системы будут довольны. Кроме того, это функция без контекста (без pTHX_ ), так как Perl_signbit() обычно пере#defined в perl.h как простой вызов макроса к системной signbit(). Пользователи должны всегда вызывать Perl_signbit().

int     Perl_signbit(NV f)

scan_bin

Для обратной совместимости. Используйте grok_bin вместо этого.

NV      scan_bin(const char* start, STRLEN len,
                 STRLEN* retlen)

scan_hex

Для обратной совместимости. Используйте grok_hex вместо этого.

NV      scan_hex(const char* start, STRLEN len,
                 STRLEN* retlen)

scan_oct

Для обратной совместимости. Используйте grok_oct вместо этого.

NV      scan_oct(const char* start, STRLEN len,
                 STRLEN* retlen)

Strtod

Это синоним для "my_strtod".

NV      Strtod(NN const char * const s,
               NULLOK char ** e)

Strtol

Платформенно- и конфигурационно-независимая strtol. Это расширяется до соответствующей функции типа strotol в зависимости от платформы и опций Configure. Например, это может расшириться до strtoll или strtoq вместо strtol.

NV      Strtol(NN const char * const s,
               NULLOK char ** e, int base)

Strtoul

Платформенно- и конфигурационно-независимая strtoul. Это расширяется до соответствующей функции типа strotoul в зависимости от платформы и опций Configure. Например, это может расшириться до strtoull или strtouq вместо strtoul.

NV      Strtoul(NN const char * const s,
                NULLOK char ** e, int base)

Функции устаревшей обратной совместимости

Некоторые из них также устарели. Вы можете исключить их из компилируемого Perl, добавив эту опцию в Configure: -Accflags='-DNO_MATHOMS'

custom_op_desc

УСТАРЕЛО! Планируется удалить эту функцию в будущей версии Perl. Не используйте её в новом коде; удалите её из существующего кода.

Возвращает описание заданного пользовательского оператора. Раньше это использовалось макросом OP_DESC, но больше не используется: оно сохранено только для совместимости и не должно использоваться.

const char * custom_op_desc(const OP *o)

custom_op_name

Возвращает имя заданного пользовательского оператора. Раньше это использовалось макросом OP_NAME, но больше не используется: оно сохранено только для совместимости и не должно использоваться.

const char * custom_op_name(const OP *o)

gv_fetchmethod

См. "gv_fetchmethod_autoload".

GV*     gv_fetchmethod(HV* stash, const char* name)

is_utf8_char

Проверяет, начинается ли заданное количество байтов с валидного символа UTF-8. Обратите внимание, что неизменный (т.е. ASCII на не-EBCDIC машинах) символ является валидным символом UTF-8. Фактическое количество байтов в символе UTF-8 будет возвращено, если он валиден, иначе 0.

Эта функция устарела из-за возможности того, что некорректный ввод может привести к чтению за пределами буфера ввода. Используйте "isUTF8_CHAR" вместо неё.

STRLEN  is_utf8_char(const U8 *s)

is_utf8_char_buf

Это идентично макросу "isUTF8_CHAR" в perlapi.

STRLEN  is_utf8_char_buf(const U8 *buf,
                         const U8 *buf_end)

pack_cat

Двигатель, реализующий функцию pack() Perl. Примечание: параметры next_in_list и flags не используются. Не следует использовать этот вызов; используйте packlist вместо него.

void    pack_cat(SV *cat, const char *pat,
                 const char *patend, SV **beglist,
                 SV **endlist, SV ***next_in_list,
                 U32 flags)

pad_compname_type

Определяет тип лексической переменной в позиции po в текущем наборе компиляции. Если переменная типизирована, возвращается stash класса, к которому она типизирована. В противном случае возвращается NULL.

HV*     pad_compname_type(const PADOFFSET po)

sv_2pvbyte_nolen

Возвращает указатель на байтовое представление SV. Может привести к понижению SV до UTF-8 как побочному эффекту.

Обычно используется через макрос SvPVbyte_nolen.

char*   sv_2pvbyte_nolen(SV* sv)

sv_2pvutf8_nolen

Возвращает указатель на UTF-8 представление SV. Может привести к повышению SV до UTF-8 как побочному эффекту.

Обычно используется через макрос SvPVutf8_nolen.

char*   sv_2pvutf8_nolen(SV* sv)

sv_2pv_nolen

Аналогично sv_2pv(), но не возвращает длину. Вам следует обычно использовать обертывающий макрос SvPV_nolen(sv).

char*   sv_2pv_nolen(SV* sv)

sv_catpvn_mg

Аналогично sv_catpvn, но также обрабатывает магию 'set'.

void    sv_catpvn_mg(SV *sv, const char *ptr,
                     STRLEN len)

sv_catsv_mg

Аналогично sv_catsv, но также обрабатывает магию 'set'.

void    sv_catsv_mg(SV *dsv, SV *ssv)

sv_force_normal

Отменяет различные виды подделок над SV: если PV является общей строкой, создает частную копию; если это ссылка, прекращает ссылку; если это глобальная переменная, понижает до xpvmg. См. также "sv_force_normal_flags".

void    sv_force_normal(SV *sv)

sv_iv

Внутренняя реализация макроса SvIVx для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

IV      sv_iv(SV* sv)

sv_nolocking

Заглушка, которая «блокирует» SV, когда модуль блокировки отсутствует. Существует для предотвращения проверки на указатель функции NULL и потому что может предупреждать в определенных уровнях строгости.

«Заменено» на sv_nosharing().

void    sv_nolocking(SV *sv)

sv_nounlocking

Заглушка, которая «разблокирует» SV, когда модуль блокировки отсутствует. Существует для предотвращения проверки на указатель функции NULL и потому что может предупреждать в определенных уровнях строгости.

«Заменено» на sv_nosharing().

void    sv_nounlocking(SV *sv)

sv_nv

Внутренняя реализация макроса SvNVx для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

NV      sv_nv(SV* sv)

sv_pv

Используйте макрос SvPV_nolen вместо этого.

char*   sv_pv(SV *sv)

sv_pvbyte

Используйте SvPVbyte_nolen вместо этого.

char*   sv_pvbyte(SV *sv)

sv_pvbyten

Внутренняя реализация макроса SvPVbyte для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

char*   sv_pvbyten(SV *sv, STRLEN *lp)

sv_pvn

Внутренняя реализация макроса SvPV для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

char*   sv_pvn(SV *sv, STRLEN *lp)

sv_pvutf8

Используйте макрос SvPVutf8_nolen вместо этого.

char*   sv_pvutf8(SV *sv)

sv_pvutf8n

Внутренняя реализация макроса SvPVutf8 для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

char*   sv_pvutf8n(SV *sv, STRLEN *lp)

sv_taint

Пометить SV как зараженный. Используйте SvTAINTED_on вместо этого.

void    sv_taint(SV* sv)

sv_unref

Снимает статус RV у SV и уменьшает счетчик ссылок того, на что указывает RV. Это практически обратный процесс newSVrv. Это sv_unref_flags со значением flag равным нулю. См. "SvROK_off".

void    sv_unref(SV* sv)

sv_usepvn

Указывает SV использовать ptr для поиска своего строкового значения. Реализовано путем вызова sv_usepvn_flags со значением flags 0, поэтому не обрабатывает магию 'set'. См. "sv_usepvn_flags".

void    sv_usepvn(SV* sv, char* ptr, STRLEN len)

sv_usepvn_mg

Аналогично sv_usepvn, но также обрабатывает магию 'set'.

void    sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)

sv_uv

Внутренняя реализация макроса SvUVx для компиляторов, которые не могут обрабатывать сложные выражения макроса. Всегда используйте макрос вместо этого.

UV      sv_uv(SV* sv)

unpack_str

Двигатель, реализующий функцию unpack() Perl. Примечание: параметры strbeg, new_s и ocnt не используются. Не следует использовать этот вызов; используйте unpackstring вместо него.

SSize_t unpack_str(const char *pat, const char *patend,
                   const char *s, const char *strbeg,
                   const char *strend, char **new_s,
                   I32 ocnt, U32 flags)

utf8_to_uvchr

Возвращает кодовую точку символа в строке s, которая предположительно закодирована в UTF-8; retlen будет установлено на длину этого символа в байтах.

Обнаружена часть, но не все некорректные UTF-8 строки, и, фактически, некоторые некорректные входные данные могут привести к чтению за пределами буфера ввода, поэтому эта функция устарела. Используйте "utf8_to_uvchr_buf" вместо неё.

Если s указывает на одну из обнаруженных некорректных строк, и предупреждения UTF8 включены, возвращается ноль, и *retlen устанавливается (если retlen не NULL ) в -1. Если эти предупреждения отключены, вычисленное значение (или заменяющий символ Unicode, если нет) будет молча возвращено, и *retlen устанавливается (если retlen не NULL), так что (s + *retlen) является следующей возможной позицией в s, которая могла бы начать не-некорректный символ. См. "utf8n_to_uvchr" для получения подробностей о том, когда возвращается заменяющий символ.

UV      utf8_to_uvchr(const U8 *s, STRLEN *retlen)

Построение Optree

newASSIGNOP

Создаёт, проверяет и возвращает оператор присваивания. left и right предоставляют параметры присваивания; они используются этой функцией и становятся частью создаваемого дерева операций.

Если optype равно OP_ANDASSIGN, OP_ORASSIGN, или OP_DORASSIGN, то создаётся соответствующее условное дерево операций. Если optype — код бинарного оператора, такого как OP_BIT_OR, то создаётся оператор, выполняющий бинарную операцию и присваивающий результат левому аргументу. В любом случае, если optype не равно нулю, то flags не оказывает никакого влияния.

Если optype равно нулю, то создаётся обычное присваивание скаляра или списка. Тип присваивания определяется автоматически. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 или 2 устанавливается автоматически, как требуется.

OP*     newASSIGNOP(I32 flags, OP* left, I32 optype,
                    OP* right)

newBINOP

Создаёт, проверяет и возвращает оператор любого бинарного типа. type — код оператора. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 или 2 устанавливается автоматически, как требуется. first и last предоставляют до двух операций, которые станут непосредственными дочерними элементами бинарного оператора; они потребляются этой функцией и становятся частью создаваемого дерева операций.

OP*     newBINOP(I32 type, I32 flags, OP* first,
                 OP* last)

newCONDOP

Создаёт, проверяет и возвращает оператор условного выражения (cond_expr) op. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 устанавливается автоматически. first предоставляет выражение, выбирающее между двумя ветвями, а trueop и falseop предоставляют ветви; они потребляются этой функцией и становятся частью создаваемого дерева операций.

OP*     newCONDOP(I32 flags, OP* first, OP* trueop,
                  OP* falseop)

newDEFSVOP

Создаёт и возвращает оператор доступа к $_.

OP*     newDEFSVOP()

newFOROP

Создаёт, проверяет и возвращает дерево операций, представляющее цикл foreach (итерация по списку значений). Это цикл с высокой степенью детализации, с структурой, позволяющей выйти из цикла с помощью last и аналогичных инструкций.

sv (необязательно) предоставляет переменную, которая будет связана с каждым элементом поочерёдно; если null, по умолчанию используется $_. expr предоставляет список значений для итерации. block предоставляет основную часть цикла, а cont (необязательно) предоставляет блок continue, который работает как вторая половина тела. Все эти входные данные дерева операций потребляются этой функцией и становятся частью создаваемого дерева операций.

flags предоставляет восемь бит op_flags для оператора leaveloop и, сдвинутые влево на восемь бит, восемь бит op_private для оператора leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически.

OP*     newFOROP(I32 flags, OP* sv, OP* expr, OP* block,
                 OP* cont)

newGIVENOP

Создаёт, проверяет и возвращает дерево операций, выражающее блок given. cond предоставляет выражение, значение которого будет локально присвоено $_, а block предоставляет тело конструкции given; они потребляются этой функцией и становятся частью создаваемого дерева операций. defsv_off должно быть равно нулю (оно использовалось для идентификации слота заполнения лексической $_).

OP*     newGIVENOP(OP* cond, OP* block,
                   PADOFFSET defsv_off)

newGVOP

Создаёт, проверяет и возвращает оператор любого типа, который включает встроенную ссылку на GV. type — код оператора. flags предоставляет восемь бит op_flags. gv идентифицирует GV, на который должен ссылаться оператор; вызов этой функции не передаёт владения какой-либо ссылкой на него.

OP*     newGVOP(I32 type, I32 flags, GV* gv)

newLISTOP

Создаёт, проверяет и возвращает оператор любого типа списка. type — код оператора. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, если требуется. first и last предоставляют до двух операций, которые станут непосредственными дочерними элементами оператора списка; они потребляются этой функцией и становятся частью создаваемого дерева операций.

Для большинства операторов списка функция проверки ожидает, что все дочерние операции уже присутствуют, поэтому вызов newLISTOP(OP_JOIN, ...) (например) не подходит. В этом случае нужно создать оператор типа OP_LIST, добавить к нему больше дочерних элементов и затем вызвать "op_convert_list". Дополнительную информацию см. в "op_convert_list".

OP*     newLISTOP(I32 type, I32 flags, OP* first,
                  OP* last)

newLOGOP

Создаёт, проверяет и возвращает логический (управляющий потоком) оператор. type — код оператора. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 устанавливается автоматически. first предоставляет выражение, управляющее потоком, а other предоставляет побочную (альтернативную) цепочку операций; они потребляются этой функцией и становятся частью создаваемого дерева операций.

OP*     newLOGOP(I32 optype, I32 flags, OP *first,
                 OP *other)

newLOOPEX

Создаёт, проверяет и возвращает оператор выхода из цикла (например, goto или last). type — код оператора. label предоставляет параметр, определяющий целевой оператор; он потребляется этой функцией и становится частью создаваемого дерева операций.

OP*     newLOOPEX(I32 type, OP* label)

newLOOPOP

Создаёт, проверяет и возвращает дерево операций, представляющее цикл. Это только цикл в управлении потоком через дерево операций; он не имеет структуры цикла с высокой степенью детализации, которая позволяет выходить из цикла с помощью last и аналогичных инструкций. flags предоставляет восемь бит op_flags для оператора верхнего уровня, за исключением того, что некоторые биты будут установлены автоматически, как требуется. expr предоставляет выражение, управляющее итерацией цикла, а block предоставляет тело цикла; они потребляются этой функцией и становятся частью создаваемого дерева операций. debuggable в настоящее время не используется и всегда должно быть равно 1.

OP*     newLOOPOP(I32 flags, I32 debuggable, OP* expr,
                  OP* block)

newMETHOP

Создаёт, проверяет и возвращает оператор типа метода с именем метода, вычисляемым во время выполнения. type — код оператора. flags предоставляет восемь бит op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутое влево на восемь бит, восемь бит op_private, за исключением того, что бит со значением 1 устанавливается автоматически. dynamic_meth предоставляет оператор, который вычисляет имя метода; он потребляется этой функцией и становится частью создаваемого дерева операций. Поддерживаемые типы операций: OP_METHOD.

OP*     newMETHOP(I32 type, I32 flags, OP* dynamic_meth)

newMETHOP_named

Создаёт, проверяет и возвращает оператор типа метода с постоянным именем метода. type — код оператора. flags предоставляет восемь бит op_flags, и, сдвинутое влево на восемь бит, восемь бит op_private. const_meth предоставляет постоянное имя метода; оно должно быть общим строковым значением COW. Поддерживаемые типы операций: OP_METHOD_NAMED.

OP*     newMETHOP_named(I32 type, I32 flags,
                        SV* const_meth)

newNULLLIST

Создаёт, проверяет и возвращает новый оператор stub, который представляет собой пустое выражение списка.

OP*     newNULLLIST()

newOP

Создаёт, проверяет и возвращает оператор любого базового типа (любой тип без дополнительных полей). type — код оператора. flags предоставляет восемь бит op_flags, и, сдвинутое влево на восемь бит, восемь бит op_private.

OP*     newOP(I32 optype, I32 flags)

newPADOP

Создаёт, проверяет и возвращает оператор любого типа, который включает ссылку на элемент заполнения. type — код оператора. flags предоставляет восемь бит op_flags. Слоты заполнения автоматически выделяются и заполняются sv; эта функция принимает владение одной ссылкой на него.

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

OP*     newPADOP(I32 type, I32 flags, SV* sv)

newPMOP

Создаёт, проверяет и возвращает оператор любого типа сопоставления с образцом. type — код оператора. flags предоставляет восемь бит op_flags и, сдвинутые влево на восемь бит, восемь бит op_private.

OP*     newPMOP(I32 type, I32 flags)

newPVOP

Создаёт, проверяет и возвращает оператор любого типа, который включает встроенный C-уровневый указатель (PV). type — код оператора. flags предоставляет восемь бит op_flags. pv предоставляет C-уровневый указатель. В зависимости от типа оператора, память, на которую ссылается pv, может быть освобождена при уничтожении оператора. Если оператор относится к типу освобождения, pv должен был быть выделен с использованием PerlMemShared_malloc.

OP*     newPVOP(I32 type, I32 flags, char* pv)

newRANGE

Создаёт и возвращает оператор range с подчиненными операторами flip и flop. flags предоставляет восемь бит op_flags для оператора flip и, сдвинутые влево на восемь бит, восемь бит op_private для обоих операторов flip и range, за исключением того, что бит со значением 1 устанавливается автоматически. left и right предоставляют выражения, управляющие конечными точками диапазона; они потребляются этой функцией и становятся частью создаваемого дерева операций.

OP*     newRANGE(I32 flags, OP* left, OP* right)

newSLICEOP

Создаёт, проверяет и возвращает операцию lslice (срез списка). flags предоставляет восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически, и, сдвинутые влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 или 2 будет автоматически установлен по необходимости. listval и subscript предоставляют параметры среза; они потребляются этой функцией и становятся частью построенного дерева операций.

OP*     newSLICEOP(I32 flags, OP* subscript, OP* listop)

newSTATEOP

Создаёт операцию состояния (COP). Операция состояния обычно является операцией nextstate, но будет операцией dbstate если отладка включена для текущего компилируемого кода. Операция состояния заполняется из PL_curcop (или PL_compiling). Если label не равно null, оно предоставляет имя метки для прикрепления к операции состояния; эта функция принимает на себя владение памятью, на которую указывает label, и освободит её. flags предоставляет восемь битов op_flags для операции состояния.

Если o равно null, операция состояния возвращается. В противном случае операция состояния объединяется с o в операцию списка lineseq, которая возвращается. o потребляется этой функцией и становится частью возвращённого дерева операций.

OP*     newSTATEOP(I32 flags, char* label, OP* o)

newSVOP

Создаёт, проверяет и возвращает операцию любого типа, которая включает в себя встроенный SV. type — это код операции. flags предоставляет восемь битов op_flags. sv предоставляет SV для встраивания в операцию; эта функция принимает на себя владение одной ссылкой на него.

OP*     newSVOP(I32 type, I32 flags, SV* sv)

newUNOP

Создаёт, проверяет и возвращает операцию любого унарного типа. type — это код операции. flags предоставляет восемь битов op_flags, за исключением того, что OPf_KIDS будет установлено автоматически при необходимости, и, сдвинутые влево на восемь битов, восемь битов op_private, за исключением того, что бит со значением 1 будет автоматически установлен. first предоставляет необязательную операцию, которая будет непосредственным потомком унарной операции; она потребляется этой функцией и становится частью построенного дерева операций.

OP*     newUNOP(I32 type, I32 flags, OP* first)

newUNOP_AUX

Аналогично newUNOP, но создаёт структуру UNOP_AUX, с op_aux инициализированной как aux

OP*     newUNOP_AUX(I32 type, I32 flags, OP* first,
                    UNOP_AUX_item *aux)

newWHENOP

Создаёт, проверяет и возвращает дерево операций, выражающее блок when. cond предоставляет выражение проверки, а block предоставляет блок, который будет выполнен, если проверка вернёт true; они потребляются этой функцией и становятся частью построенного дерева операций. cond будет интерпретировано DWIM-но, часто как сравнение со $_, и может быть null для генерации блока default.

OP*     newWHENOP(OP* cond, OP* block)

newWHILEOP

Создаёт, проверяет и возвращает дерево операций, выражающее цикл while. Это тяжёлый цикл с структурой, которая позволяет выйти из цикла с помощью last и тому подобного.

loop — это необязательная предварительно построенная операция enterloop для использования в цикле; если она равна null, то будет построена подходящая операция. expr предоставляет выражение управления циклом. block предоставляет основное тело цикла, и cont необязательно предоставляет блок continue, который функционирует как вторая половина тела. Все эти входные данные optree потребляются этой функцией и становятся частью построенного дерева операций.

flags предоставляет восемь битов op_flags для операции leaveloop и, сдвинутые влево на восемь битов, восемь битов op_private для операции leaveloop, за исключением того, что (в обоих случаях) некоторые биты будут установлены автоматически. debuggable в настоящее время не используется и должно всегда быть равно 1. has_my может быть предоставлено как true, чтобы принудительно поместить тело цикла в собственный область видимости.

OP*     newWHILEOP(I32 flags, I32 debuggable,
                   LOOP* loop, OP* expr, OP* block,
                   OP* cont, I32 has_my)

Функции манипулирования Optree

alloccopstash

Доступна только в потоковых сборках, эта функция выделяет запись в PL_stashpad для стека, переданного ей.

PADOFFSET alloccopstash(HV *hv)

block_end

Обрабатывает выход из области видимости во время компиляции. floor — это индекс стека сохранения, возвращаемый функцией block_start, а seq — это тело блока. Возвращает блок, возможно, измененный.

OP*     block_end(I32 floor, OP* seq)

block_start

Обрабатывает вход в область видимости во время компиляции. Обеспечивает восстановление подсказок при выходе из блока, а также обрабатывает номера последовательностей заполнения для правильного ограничения области видимости лексических переменных. Возвращает индекс стека сохранения для использования с block_end.

int     block_start(int full)

ck_entersub_args_list

Выполняет стандартную обработку аргументов части дерева операций entersub. Она заключается в применении контекста списка к каждой из операций аргументов. Это стандартная обработка, используемая для вызова, помеченного как &, или для вызова метода, или для вызова через ссылку на подпрограмму, или для любого другого вызова, где вызываемый объект не может быть идентифицирован во время компиляции, или для вызова, где вызываемый объект не имеет прототипа.

OP*     ck_entersub_args_list(OP *entersubop)

ck_entersub_args_proto

Выполняет обработку аргументов части дерева операций entersub на основе прототипа подпрограммы. Это выполняет различные модификации операций аргументов, от применения контекста до вставки операций refgen, и проверки количества и синтаксических типов аргументов в соответствии с прототипом. Это стандартная обработка, используемая для вызова подпрограммы, не помеченной как &, где вызываемый объект может быть идентифицирован во время компиляции и имеет прототип.

protosv предоставляет прототип подпрограммы для применения к вызову. Он может быть обычным скалярным значением, в этом случае будет использовано строковое значение. В качестве альтернативы для удобства, это может быть объект подпрограммы (CV*, преобразованный в SV*), у которого есть прототип. Предоставленный прототип, в любом виде, не обязан соответствовать фактическому вызываемому объекту, указанному в дереве операций.

Если операции аргументов не соответствуют прототипу, например, из-за неприемлемого количества аргументов, то возвращается корректное дерево операций. Ошибка отражается в состоянии парсера, что обычно приводит к единственному исключению на верхнем уровне разбора, которое охватывает все произошедшие ошибки компиляции. В сообщении об ошибке вызываемый объект обозначается именем, определенным параметром namegv.

OP*     ck_entersub_args_proto(OP *entersubop,
                               GV *namegv, SV *protosv)

ck_entersub_args_proto_or_list

Выполняет обработку аргументов части дерева операций entersub либо на основе прототипа подпрограммы, либо с использованием обработки по умолчанию для контекста списка. Это стандартная обработка, используемая для вызова подпрограммы, не помеченной как &, где вызываемый объект может быть идентифицирован во время компиляции.

protosv предоставляет прототип подпрограммы для применения к вызову или указывает, что прототип отсутствует. Это может быть обычная скалярная переменная, если она определена, то её строковое значение будет использоваться как прототип, а если она не определена, то прототип отсутствует. В качестве альтернативы для удобства, это может быть объект подпрограммы (CV*, преобразованный в SV*), прототип которого будет использован, если он есть. Предоставленный прототип (или его отсутствие), в любом виде, не обязан соответствовать фактическому вызываемому объекту, указанному в дереве операций.

OP*     ck_entersub_args_proto_or_list(OP *entersubop,
                                       GV *namegv,
                                       SV *protosv)

cv_const_sv

Если cv является константной подпрограммой, пригодной для инлайнинга, возвращает константное значение, возвращаемое подпрограммой. В противном случае возвращает NULL.

Константные подпрограммы могут быть созданы с помощью newCONSTSUB или, как описано в "Константные функции" в perlsub.

SV*     cv_const_sv(const CV *const cv)

cv_get_call_checker

Исходная форма "cv_get_call_checker_flags", которая не возвращает флаги проверки. При использовании функции проверки, возвращаемой этой функцией, безопасно вызывать её только с истинным GV в качестве аргумента namegv.

void    cv_get_call_checker(CV *cv,
                            Perl_call_checker *ckfun_p,
                            SV **ckobj_p)

cv_get_call_checker_flags

Извлекает функцию, которая будет использована для обработки вызова подпрограммы cv. Конкретно, функция применяется к дереву операций entersub для вызова подпрограммы, не помеченной как &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию на уровне C возвращается в *ckfun_p, аргумент SV для неё возвращается в *ckobj_p, а управляющие флаги возвращаются в *ckflags_p. Функция предназначена для вызова следующим образом:

entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));

В этом вызове entersubop — указатель на операцию entersub, которая может быть заменена функцией проверки, а namegv — имя, которое должна использовать функция проверки для ссылки на вызываемый объект операции entersub при необходимости вывода диагностических сообщений. Разрешается применять функцию проверки в нестандартных ситуациях, таких как вызов другой подпрограммы или вызов метода.

namegv может на самом деле не быть GV. Если бит CALL_CHECKER_REQUIRE_GV в *ckflags_p сброшен, разрешается передать CV или другой SV вместо него, всё, что может быть использовано в качестве первого аргумента "cv_name". Если бит CALL_CHECKER_REQUIRE_GV установлен в *ckflags_p, функция проверки требует, чтобы namegv был истинным GV.

По умолчанию функцией проверки является Perl_ck_entersub_args_proto_or_list, параметр SV — это cv сам по себе, а флаг CALL_CHECKER_REQUIRE_GV сброшен. Это реализует стандартную обработку прототипов. Она может быть изменена для конкретной подпрограммы с помощью "cv_set_call_checker_flags".

Если бит CALL_CHECKER_REQUIRE_GV установлен в gflags, это означает, что вызывающий объект знает только о версии namegv в виде истинного GV, и соответственно соответствующий бит всегда будет установлен в *ckflags_p, независимо от требований функции проверки. Если бит CALL_CHECKER_REQUIRE_GV сброшен в gflags, это означает, что вызывающий объект знает о возможности передачи чего-то кроме GV в качестве namegv, и соответственно соответствующий бит может быть либо установлен, либо сброшен в *ckflags_p, указывая требования функции проверки.

gflags — набор битов, передаваемый в cv_get_call_checker_flags, в котором в настоящее время определён только бит CALL_CHECKER_REQUIRE_GV (см. выше). Все остальные биты должны быть сброшены.

void    cv_get_call_checker_flags(
            CV *cv, U32 gflags,
            Perl_call_checker *ckfun_p, SV **ckobj_p,
            U32 *ckflags_p
        )

cv_set_call_checker

Исходная форма "cv_set_call_checker_flags", которая передаёт флаг CALL_CHECKER_REQUIRE_GV для обратной совместимости. Влияние этого флага заключается в том, что функция проверки гарантированно получит настоящий GV в качестве аргумента namegv.

void    cv_set_call_checker(CV *cv,
                            Perl_call_checker ckfun,
                            SV *ckobj)

cv_set_call_checker_flags

Устанавливает функцию, которая будет использоваться для обработки вызова cv. В частности, функция применяется к дереву операций entersub для вызова подпрограммы, не помеченной как &, где вызываемый объект может быть идентифицирован во время компиляции как cv.

Указатель на функцию на уровне C передаётся в ckfun, аргумент SV для неё передаётся в ckobj, а управляющие флаги передаются в ckflags. Функция должна быть определена следующим образом:

STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)

Она предназначена для вызова следующим образом:

entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);

namegv может фактически не быть GV. Для повышения эффективности Perl может передать CV или другой SV вместо него. Переданное значение может быть использовано в качестве первого аргумента "cv_name". Можно заставить Perl передавать GV, включив CALL_CHECKER_REQUIRE_GV в ckflags.

ckflags — набор битов, в котором в настоящее время определён только бит CALL_CHECKER_REQUIRE_GV (см. выше). Все остальные биты должны быть сброшены.

Текущее значение для конкретного CV можно получить с помощью "cv_get_call_checker_flags".

void    cv_set_call_checker_flags(
            CV *cv, Perl_call_checker ckfun, SV *ckobj,
            U32 ckflags
        )

LINKLIST

Учитывая корень дерева операций, свяжите дерево в порядке выполнения с помощью указателей op_next и верните первую операцию, которая будет выполнена. Если это уже сделано, то это не будет переделано, и вернётся o->op_next. Если o->op_next ещё не установлен, o должен быть, как минимум, UNOP.

OP*     LINKLIST(OP *o)

newCONSTSUB

Ведёт себя как "newCONSTSUB_flags", за исключением того, что name имеет нуль-терминацию, а не счёт длины, и флаги не установлены. (Это означает, что name всегда интерпретируется как Latin-1.)

CV*     newCONSTSUB(HV* stash, const char* name, SV* sv)

newCONSTSUB_flags

Создайте подпрограмму-константу, выполняя также некоторые связанные задачи. Скалярная подпрограмма с постоянным значением подходит для встраивания во время компиляции, и в коде Perl может быть создана с помощью sub FOO () { 123 }. Другие типы подпрограмм-констант обрабатываются по-другому.

У подпрограммы будет пустой прототип, и она будет игнорировать любые аргументы при вызове. Ее поведение как константы определяется sv. Если sv равно null, подпрограмма вернёт пустой список. Если sv указывает на скаляр, подпрограмма всегда вернёт этот скаляр. Если sv указывает на массив, подпрограмма всегда вернёт список элементов этого массива в контексте списка или количество элементов в массиве в скалярном контексте. Эта функция принимает во владение одну счётную ссылку на скаляр или массив и организует существование объекта до тех пор, пока существует подпрограмма. Если sv указывает на скаляр, то при встраивании предполагается, что значение скаляра никогда не изменится, поэтому вызывающая сторона должна убедиться, что скаляр впоследствии не изменяется. Если sv указывает на массив, такое предположение не делается, поэтому изменение массива или его элементов, по-видимому, безопасно, но поддерживается ли это на самом деле, не определено.

У подпрограммы будет CvFILE установлено в соответствии с PL_curcop. Другие аспекты подпрограммы останутся в своём исходном состоянии. Вызывающая сторона свободна изменять подпрограмму после возвращения этой функции.

Если name равно null, подпрограмма будет анонимной, а её CvGV будет ссылаться на __ANON__ глобальную переменную. Если name не равно null, подпрограмма будет именованной, на которую будет ссылаться соответствующая глобальная переменная. name — это строка длиной len байт, представляющая имя символа без сигила, в UTF-8, если у flags установлен бит SVf_UTF8, и в Latin-1 в противном случае. Имя может быть квалифицированным или неквалифицированным. Если имя неквалифицированное, оно по умолчанию находится в стеке, указанном stash, если оно не равно null, или в PL_curstash, если stash равно null. Символ всегда добавляется в стек при необходимости, с использованием семантики GV_ADDMULTI.

flags не должно иметь установленных битов, кроме SVf_UTF8.

Если подпрограмма с указанным именем уже существует, новая подпрограмма заменит существующую в глобальной переменной. Может быть выведено предупреждение о переопределении.

Если подпрограмма имеет одно из нескольких специальных имён, таких как BEGIN или END, то она будет затребована соответствующим очереди для автоматического выполнения подпрограмм, связанных с фазой. В этом случае соответствующая глобальная переменная останется пустой, даже если она содержала подпрограмму ранее. Выполнение подпрограммы, вероятно, будет пустым действием, если sv был связанным массивом или вызывающая сторона каким-либо образом изменила подпрограмму перед ее выполнением. В случае BEGIN, обработка является ошибочной: подпрограмма будет выполнена только наполовину, и может быть удалена преждевременно, что, возможно, приведёт к сбою.

Функция возвращает указатель на созданную подпрограмму. Если подпрограмма анонимная, владение одной счётной ссылкой на подпрограмму передаётся вызывающей стороне. Если подпрограмма именованная, вызывающая сторона не получает владения ссылкой. Во многих таких случаях, когда у подпрограммы есть имя, не связанное с фазой, подпрограмма будет существовать в момент возвращения, будучи содержащейся в глобальной переменной, которая ее называет. Подпрограмма, имеющая имя, связанное с фазой, обычно будет существовать благодаря ссылке, принадлежащей автоматической очереди запуска фазы. Подпрограмма BEGIN может быть уже уничтожена к моменту возвращения этой функции, но в настоящее время ошибки возникают в этом случае до получения контроля вызывающей стороной. Вызывающая сторона несет ответственность за обеспечение понимания, какой из этих ситуаций соответствует.

CV*     newCONSTSUB_flags(HV* stash, const char* name,
                          STRLEN len, U32 flags, SV* sv)

newXS

Используется xsubpp для подключения XSUB как подпрограмм Perl. filename должна быть статической областью памяти, так как она используется непосредственно как CvFILE(), без создания копии.

op_append_elem

Добавить элемент в список операций, содержащихся непосредственно в операции типа список, возвращая удлинённый список. first — это операция типа список, а last — это операция, которую нужно добавить в список. optype указывает на предполагаемый код операции для списка. Если first ещё не является списком нужного типа, он будет преобразован в него. Если либо first, либо last равно null, другая возвращается без изменений.

OP*     op_append_elem(I32 optype, OP* first, OP* last)

op_append_list

Конкатенация списков операций, содержащихся непосредственно в двух операциях типа список, возвращая объединённый список. first и last — это операции типа список для конкатенации. optype указывает на предполагаемый код операции для списка. Если либо first, либо last не является списком нужного типа, оно будет преобразовано в него. Если либо first, либо last равно null, другая возвращается без изменений.

OP*     op_append_list(I32 optype, OP* first, OP* last)

OP_CLASS

Возвращает класс предоставленной операции: то есть, который из *OP структур используется. Для основных операций в настоящее время информация извлекается из PL_opargs, что не всегда точно отражает используемый тип; начиная с версии 5.26, см. также функцию "op_class", которая может лучше определить используемый тип.

Для пользовательских операций тип возвращается из регистрации, и от регистратора зависит обеспечение точности. Возвращаемое значение будет одним из OA_* констант из op.h.

U32     OP_CLASS(OP *o)

op_contextualize

Применяет синтаксический контекст к дереву операций, представляющему выражение. o — это дерево операций, а context должно быть G_SCALAR, G_ARRAY, или G_VOID, чтобы указать контекст для применения. Изменённое дерево операций возвращается.

OP*     op_contextualize(OP* o, I32 context)

op_convert_list

Преобразует o в операцию списка, если это не операция списка, а затем преобразует её в указанную type, вызывая её проверочную функцию, выделяя целевой объект, если это необходимо, и сворачивая константы.

Операция типа список обычно создается по одному потомку за раз с помощью newLISTOP, op_prepend_elem и op_append_elem. Затем она передается op_convert_list, чтобы придать ей нужный тип.

OP*     op_convert_list(I32 optype, I32 flags, OP* o)

OP_DESC

Возвращает краткое описание предоставленной операции.

const char * OP_DESC(OP *o)

op_free

Освободить операцию и ее потомков. Используйте это только тогда, когда операция больше не связана с каким-либо деревом операций.

void    op_free(OP* arg)

OpHAS_SIBLING

Возвращает true, если у o есть брат/сестра

bool    OpHAS_SIBLING(OP *o)

OpLASTSIB_set

Помечает o как не имеющий дальнейших братьев/сестер и помечает o как имеющий указанного родителя. См. также "OpMORESIB_set" и OpMAYBESIB_set. Для интерфейса более высокого уровня см. "op_sibling_splice".

void    OpLASTSIB_set(OP *o, OP *parent)

op_linklist

Эта функция является реализацией макроса "LINKLIST". Не следует вызывать ее напрямую.

OP*     op_linklist(OP *o)

op_lvalue

Распространяет контекст "lvalue" ("модифицируемый") на операцию и ее потомков. type представляет тип контекста, примерно основанный на типе операции, которая будет выполнять модификацию, хотя local() представлен OP_NULL, потому что у него нет собственного типа операции (он сигнализируется флагом в операции lvalue).

Эта функция обнаруживает элементы, которые не могут быть изменены, такие как $x+1, и генерирует ошибки для них. Например, $x+1 = 2 приведет к ее вызову с операцией типа OP_ADD и аргументом type типа OP_SASSIGN.

Она также отмечает элементы, которые должны вести себя особенно в контексте lvalue, такие как $$x = 5, которые могут потребовать оживления ссылки в $x.

OP*     op_lvalue(OP* o, I32 type)

OpMAYBESIB_set

Условно выполняет OpMORESIB_set или OpLASTSIB_set в зависимости от того, является ли sib не равным null. Для интерфейса более высокого уровня см. "op_sibling_splice".

void    OpMAYBESIB_set(OP *o, OP *sib, OP *parent)

OpMORESIB_set

Устанавливает брата/сестру o в ненулевое значение sib. См. также "OpLASTSIB_set" и "OpMAYBESIB_set". Для интерфейса более высокого уровня см. "op_sibling_splice".

void    OpMORESIB_set(OP *o, OP *sib)

OP_NAME

Возвращает имя предоставленной операции. Для основных операций это ищет имя из op_type; для пользовательских операций из op_ppaddr.

const char * OP_NAME(OP *o)

op_null

Деактивирует операцию, когда она больше не нужна, но все еще связана с другими операциями.

void    op_null(OP* o)

op_parent

Возвращает родительскую операцию o, если у нее есть родитель. В противном случае возвращает NULL.

OP*     op_parent(OP *o)

op_prepend_elem

Добавить элемент в начало списка операций, содержащихся непосредственно в операции типа список, возвращая удлинённый список. first — это операция, которую нужно добавить в начало списка, а last — это операция типа список. optype указывает на предполагаемый код операции для списка. Если last еще не является списком нужного типа, он будет преобразован в него. Если либо first, либо last равно null, другая возвращается без изменений.

OP*     op_prepend_elem(I32 optype, OP* first, OP* last)

op_scope

Оборачивает дерево операций дополнительными операциями, чтобы во время выполнения был создан динамический контекст. Исходные операции выполняются в новом динамическом контексте, а затем, при нормальном завершении, контекст будет размотан. Дополнительные операции, используемые для создания и размотки динамического контекста, обычно будут парой enter/leave, но операция scope может быть использована вместо этого, если операции достаточно простые, чтобы не потребовалась полная структура динамического контекста.

OP*     op_scope(OP* o)

OpSIBLING

Возвращает следующего брата элемента o, или NULL, если такого брата нет

OP*     OpSIBLING(OP *o)

op_sibling_splice

Общая функция для редактирования структуры существующей цепочки узлов op_sibling. Аналогично функции splice() на уровне Perl, позволяет удалить ноль или более последовательных узлов, заменив их нулём или более различными узлами. Выполняет необходимые операции op_first/op_last для родительского узла и манипуляции op_sibling для дочерних узлов. Последний удалённый узел помечается как последний, обновляя поле op_sibling/op_sibparent или op_moresib соответственно.

Обратите внимание, что op_next не изменяется, и узлы не освобождаются; это ответственность вызывающей стороны. Также она не создаст новый список op для пустого списка и т. п.; для этого используйте функции более высокого уровня, такие как op_append_elem().

parent является родительским узлом цепочки братьев. Он может быть передан как NULL, если вставка не затрагивает первый или последний op в цепочке.

start — узел, предшествующий первому узлу, который будет изменён. Узел(ы), следующий за ним, будут удалены, а ops будут вставлены после него. Если он NULL, то удаляются все узлы с первого и вставляются узлы в начало.

del_count — количество узлов для удаления. Если ноль, то узлы не удаляются. Если -1 или больше или равно количеству оставшихся детей, удаляются все оставшиеся дети.

insert — первый из цепочки узлов, которые будут вставлены вместо удалённых узлов. Если NULL, узлы не вставляются.

Возвращается начало цепочки удалённых ops, или NULL, если ops не были удалены.

Например:

action                    before      after         returns
------                    -----       -----         -------

                          P           P
splice(P, A, 2, X-Y-Z)    |           |             B-C
                          A-B-C-D     A-X-Y-Z-D

                          P           P
splice(P, NULL, 1, X-Y)   |           |             A
                          A-B-C-D     X-Y-B-C-D

                          P           P
splice(P, NULL, 3, NULL)  |           |             A-B-C
                          A-B-C-D     D

                          P           P
splice(P, B, 0, X-Y)      |           |             NULL
                          A-B-C-D     A-B-X-Y-C-D

Для более низкоуровневого прямого управления op_sibparent и op_moresib, см. "OpMORESIB_set", "OpLASTSIB_set", "OpMAYBESIB_set".

OP*     op_sibling_splice(OP *parent, OP *start,
                          int del_count, OP* insert)

OP_TYPE_IS

Возвращает true, если данный OP не является указателем NULL и если он является указанного типа.

Также доступны отрицание этого макроса, OP_TYPE_ISNT, а также OP_TYPE_IS_NN и OP_TYPE_ISNT_NN, которые исключают проверку на указатель NULL.

bool    OP_TYPE_IS(OP *o, Optype type)

OP_TYPE_IS_OR_WAS

Возвращает true, если данный OP не является указателем NULL и если он является указанного типа или им был до замены на OP типа OP_NULL.

Также доступны отрицание этого макроса, OP_TYPE_ISNT_AND_WASNT, а также OP_TYPE_IS_OR_WAS_NN и OP_TYPE_ISNT_AND_WASNT_NN, которые исключают проверку на указатель NULL.

bool    OP_TYPE_IS_OR_WAS(OP *o, Optype type)

rv2cv_op_cv

Рассматривает op, который, как ожидается, идентифицирует подпрограмму во время выполнения, и пытается определить во время компиляции, какую подпрограмму он идентифицирует. Это обычно используется во время компиляции Perl для определения того, можно ли применить шаблон к вызову функции. cvop — рассматриваемый op, обычно op rv2cv. Указатель на идентифицированную подпрограмму возвращается, если она могла быть определена статически, и возвращается нулевой указатель, если это было невозможно определить статически.

В настоящее время подпрограмма может быть определена статически, если RV, над которым должен действовать rv2cv, предоставляется подходящим op gv или const. Op gv подходит, если слот CV GV заполнен. Op const подходит, если константа должна быть RV, указывающим на CV. Подробности этого процесса могут измениться в будущих версиях Perl. Если у op rv2cv установлен флаг OPpENTERSUB_AMPER, то попытка статического определения подпрограммы не предпринимается: этот флаг используется для подавления магических операций во время компиляции при вызове подпрограммы, заставляя использовать поведение по умолчанию во время выполнения.

Если у flags установлен бит RV2CVOPCV_MARK_EARLY, то обработка ссылки GV изменяется. Если GV был проанализирован и его слот CV оказался пустым, то у op gv установлен флаг OPpEARLY_CV. Если op не оптимизирован, а слот CV позже заполняется подпрограммой с шаблоном, этот флаг в конечном итоге вызывает предупреждение "вызов слишком рано для проверки шаблона".

Если у flags установлен бит RV2CVOPCV_RETURN_NAME_GV, то вместо возвращения указателя на подпрограмму возвращается указатель на GV, предоставляющий наиболее подходящее имя для подпрограммы в данном контексте. Обычно это просто CvGV подпрограммы, но для анонимной (CvANON) подпрограммы, на которую ссылаются через GV, это будет ссылающийся GV. Полученный GV* приводится к типу CV* для возврата. Нулевой указатель возвращается как обычно, если нет статически определяемой подпрограммы.

CV*     rv2cv_op_cv(OP *cvop, U32 flags)

Упаковщики и распаковщики

packlist

Двигатель, реализующий функцию Perl pack().

void    packlist(SV *cat, const char *pat,
                 const char *patend, SV **beglist,
                 SV **endlist)

unpackstring

Двигатель, реализующий функцию Perl unpack().

Используя шаблон pat..patend, эта функция распаковывает строку s..strend в несколько смертных SVs, которые она помещает на стек аргументов Perl (@_) (поэтому вам необходимо выполнить PUTBACK перед и SPAGAIN после вызова этой функции). Она возвращает количество помещённых элементов.

Указатели strend и patend должны указывать на байт, следующий за последним символом каждой строки.

Хотя эта функция возвращает свои значения на стеке аргументов Perl, она не принимает параметры со стека (и, следовательно, в частности, нет необходимости выполнять PUSHMARK перед её вызовом, в отличие от "call_pv", например).

SSize_t unpackstring(const char *pat,
                     const char *patend, const char *s,
                     const char *strend, U32 flags)

Структуры данных с заполнителями

CvPADLIST

CV может иметь CvPADLIST(cv), установленным на указатель на PADLIST. Это рабочая область CV, в которой хранятся лексические переменные, временные значения кода и значения на основе потока.

В этих целях «форматы» являются своего рода CV; eval"" тоже (за исключением того, что они не вызываются по желанию и всегда удаляются после выполнения eval""). Требуемые файлы — это просто eval без внешней лексической области.

XSUB не имеют CvPADLIST. dXSTARG извлекает значения из PL_curpad, но это фактически рабочая область вызывающей стороны (слот, выделенный каждым entersub). Не получайте и не устанавливайте CvPADLIST для CV, являющегося XSUB (как определяется CvISXSUB()), слот CvPADLIST повторно используется для другой внутренней цели в XSUB.

PADLIST имеет массив C, где хранятся pads.

Нулевой элемент PADLIST — PADNAMELIST, который представляет «имена», или скорее «статическую информацию о типе» для лексических переменных. Отдельные элементы PADNAMELIST — это PADNAME. Будущие рефакторинги могут прекратить хранение PADNAMELIST в массиве PADLIST, поэтому не полагайтесь на это. См. "PadlistNAMES".

Элемент с индексом CvDEPTH в PADLIST — PAD (AV), который представляет собой кадр стека на данной глубине рекурсии в CV. Нулевой слот AV кадра — AV, который @_. Другие элементы — хранилище для переменных и целей операторов.

Итерация по PADNAMELIST итерирует по всем возможным элементам pad. Слот pad для целей (SVs_PADTMP) и GVs получают имена &PL_padname_undef, а для констант — &PL_padname_const имена (см. "pad_alloc"). То, что &PL_padname_undef и &PL_padname_const используются, является деталью реализации, которая может измениться. Для проверки используйте !PadnamePV(name) и PadnamePV(name) && !PadnameLEN(name) соответственно.

Только my/our переменные имеют действительные имена. Остальные — цели операторов/GVs/константы, которые статически выделены или разрешены во время компиляции. У них нет имен, по которым их можно найти в коде Perl во время выполнения с помощью eval"", так как my/our переменные могут быть найдены. Так как их нельзя найти по «имени», а только по индексу, выделенному во время компиляции (который обычно в PL_op->op_targ), тратить SV для имени не имеет смысла.

Имена pad в PADNAMELIST имеют PV, содержащий имя переменной. Поля COP_SEQ_RANGE_LOW и _HIGH образуют диапазон (low+1..high включительно) номеров cop_seq, для которых имя является допустимым. Во время компиляции эти поля могут содержать специальное значение PERL_PADSEQ_INTRO, чтобы указать различные стадии:

COP_SEQ_RANGE_LOW        _HIGH
-----------------        -----
PERL_PADSEQ_INTRO            0   variable not yet introduced:
                                 { my ($x
valid-seq#   PERL_PADSEQ_INTRO   variable in scope:
                                 { my ($x);
valid-seq#          valid-seq#   compilation of scope complete:
                                 { my ($x); .... }

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

my ($x, $x); # '"my" variable $x masks earlier declaration'
my $x = $x;  # equal to my $x = $::x;

Для типизированных лексических переменных PadnameTYPE указывает на stash типа. Для our лексических переменных PadnameOURSTASH указывает на stash связанной глобальной переменной (чтобы можно было обнаружить дублированные our объявления в одном пакете). PadnameGEN иногда используется для хранения номера генерации во время компиляции.

Если PadnameOUTER установлено для имени pad, то соответствующий элемент в AV кадра является объектом REFCNT, ссылающимся на лексическую переменную «извне». Такие элементы иногда называют «псевдо». В этом случае имя не использует «low» и «high» для хранения диапазона cop_seq, так как оно находится в области действия на протяжении всего времени. Вместо этого «high» хранит некоторые флаги, содержащие информацию о реальной лексической переменной (объявлена ли она в анонимной области и может ли она быть экземпляризована несколько раз?), а для подпрограмм ANON «low» содержит индекс в pad родительской структуры, где хранится значение лексической переменной, чтобы ускорить клонирование.

Если «имя» равно &, соответствующий элемент в PAD — CV, представляющий потенциальное замыкание.

Обратите внимание, что форматы обрабатываются как анонимные подпрограммы и клонируются каждый раз при вызове write (при необходимости).

Флаг SVs_PADSTALE сбрасывается для лексических переменных каждый раз при выполнении my(), и устанавливается при выходе из области действия. Это позволяет генерировать предупреждение "Variable $x is not available" в eval, например

{ my $x = 1; sub f { eval '$x'} } f();

Для переменных состояния SVs_PADSTALE перегружено, чтобы означать «еще не инициализировано», но это внутреннее состояние хранится в отдельном элементе pad.

PADLIST * CvPADLIST(CV *cv)

pad_add_name_pvs

Точно так же, как "pad_add_name_pvn", но принимает строку-литерал вместо пары «строка/длина».

PADOFFSET pad_add_name_pvs("name", U32 flags,
                           HV *typestash, HV *ourstash)

PadARRAY

Массив C элементов pad.

SV **   PadARRAY(PAD * pad)

pad_findmy_pvs

Точно так же, как "pad_findmy_pvn", но принимает строку-литерал вместо пары «строка/длина».

PADOFFSET pad_findmy_pvs("name", U32 flags)

PadlistARRAY

Массив C элементов padlist, содержащий pads. Подставляйте только числа ≥ 1, так как нулевой элемент не гарантированно будет доступен.

PAD **  PadlistARRAY(PADLIST * padlist)

PadlistMAX

Индекс последнего выделенного места в padlist. Обратите внимание, что последний pad может находиться в более раннем слоте. Любые элементы после него будут NULL в этом случае.

SSize_t PadlistMAX(PADLIST * padlist)

PadlistNAMES

Имена, связанные с элементами pad.

PADNAMELIST * PadlistNAMES(PADLIST * padlist)

PadlistNAMESARRAY

Массив C имён pad.

PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)

PadlistNAMESMAX

Индекс последнего имени pad.

SSize_t PadlistNAMESMAX(PADLIST * padlist)

PadlistREFCNT

Счётчик ссылок padlist. В настоящее время всегда равен 1.

U32     PadlistREFCNT(PADLIST * padlist)

PadMAX

Индекс последнего элемента pad.

SSize_t PadMAX(PAD * pad)

PadnameLEN

Длина имени.

STRLEN  PadnameLEN(PADNAME * pn)

PadnamelistARRAY

Массив C имён pad.

PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)

PadnamelistMAX

Индекс последнего имени pad.

SSize_t PadnamelistMAX(PADNAMELIST * pnl)

PadnamelistREFCNT

Счётчик ссылок списка имён pad.

SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)

PadnamelistREFCNT_dec

Уменьшает счётчик ссылок списка имён pad.

void    PadnamelistREFCNT_dec(PADNAMELIST * pnl)

PadnamePV

Имя, хранящееся в структуре имени pad. Возвращает NULL для слота цели.

char *  PadnamePV(PADNAME * pn)

PadnameREFCNT

Счётчик ссылок имени pad.

SSize_t PadnameREFCNT(PADNAME * pn)

PadnameREFCNT_dec

Уменьшает счётчик ссылок имени pad.

void    PadnameREFCNT_dec(PADNAME * pn)

PadnameSV

Возвращает имя pad как смертный SV.

SV *    PadnameSV(PADNAME * pn)

PadnameUTF8

Является ли PadnamePV в UTF-8. В настоящее время всегда истинно.

bool    PadnameUTF8(PADNAME * pn)

pad_new

Создаёт новый padlist, обновляя глобальные переменные для текущего компилируемого padlist, чтобы они указывали на новый padlist. Следующие флаги можно объединить с помощью OR:

padnew_CLONE        this pad is for a cloned CV
padnew_SAVE         save old globals on the save stack
padnew_SAVESUB      also save extra stuff for start of sub

    PADLIST* pad_new(int flags)

PL_comppad

Во время компиляции указывает на массив, содержащий значения части pad для текущего компилируемого кода. (Во время выполнения CV может иметь много таких массивов значений; во время компиляции строится только один.) Во время выполнения указывает на массив, содержащий текущие значения для pad для текущего выполняемого кода.

PL_comppad_name

Во время компиляции указывает на массив, содержащий имена части pad для текущего компилируемого кода.

PL_curpad

Указывает напрямую на тело массива "PL_comppad". (То есть, это PadARRAY(PL_comppad))

Переменные на интерпретатор

PL_curcop

Текущий активный COP (control op), примерно соответствующий текущему оператору в исходном коде.

COP*    PL_curcop

PL_curstash

Стек для кода пакета, в который будет компилироваться.

HV*     PL_curstash

PL_defgv

GV, представляющий *_. Полезен для доступа к $_.

GV *    PL_defgv

PL_exit_flags

Содержит флаги, управляющие поведением Perl при вызове exit():

PERL_EXIT_DESTRUCT_END

Если установлен, блоки END будут выполнены при уничтожении интерпретатора. Обычно устанавливается Perl после создания интерпретатора.
PERL_EXIT_ABORT

Вызвать abort() при выходе. Используется Perl для аварийного завершения, если exit вызывается во время обработки exit.
PERL_EXIT_WARN

Вывести предупреждение при выходе.
PERL_EXIT_EXPECTED

Устанавливается оператором "exit" in perlfunc.

U8      PL_exit_flags

PL_modglobal

PL_modglobal — универсальный интерпретаторский глобальный HV, используемый расширениями, которым необходимо хранить информацию на основе интерпретатора. В случае необходимости, он также может использоваться как таблица символов для обмена данными между расширениями. Рекомендуется использовать ключи, префикс которых содержит имя пакета расширения, владеющего данными.

HV*     PL_modglobal

PL_na

Вспомогательная переменная, обычно используемая с SvPV в тех случаях, когда не нужно заботиться о длине строки. Обычно более эффективно либо объявить локальную переменную, либо использовать макрос SvPV_nolen.

STRLEN  PL_na

PL_opfreehook

Если не NULL, функция, на которую указывает эта переменная, будет вызываться каждый раз, когда оператор OP освобождается с соответствующим оператором OP в качестве аргумента. Это позволяет расширениям освобождать любые дополнительные атрибуты, локально прикрепленные к оператору OP. Гарантируется, что сначала будет вызвано действие для родительского оператора OP, а затем для его потомков.

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

Perl_ophook_t   PL_opfreehook

PL_peepp

Указатель на оптимизатор peephole на уровне подпрограммы. Эта функция вызывается в конце компиляции Perl-подпрограммы (или эквивалентной независимой части Perl-кода) для выполнения корректировок некоторых операторов и небольших оптимизаций. Функция вызывается один раз для каждой компилируемой подпрограммы и получает в качестве единственного параметра указатель на оператор, являющийся точкой входа в подпрограмму. Она изменяет дерево операторов на месте.

Оптимизатор peephole никогда не следует полностью заменять. Вместо этого, добавьте код, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" in perlguts. Если новый код хочет работать с операторами по всей структуре подпрограммы, а не только на верхнем уровне, вероятно, удобнее будет обернуть обработчик "PL_rpeepp".

peep_t  PL_peepp

PL_perl_destruct_level

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

Возможные значения:

0 — нет
1 — полная
2 или больше — полная с проверками.

Если $ENV{PERL_DESTRUCT_LEVEL} установлено на целое число, большее, чем значение PL_perl_destruct_level, используется его значение.

signed char     PL_perl_destruct_level

PL_rpeepp

Указатель на рекурсивный оптимизатор peephole. Эта функция вызывается в конце компиляции Perl-подпрограммы (или эквивалентной независимой части Perl-кода) для выполнения корректировок некоторых операторов и небольших оптимизаций. Функция вызывается один раз для каждой цепочки операторов, связанных через поля op_next; она рекурсивно вызывается для обработки каждой боковой цепочки. Ей передаётся в качестве единственного параметра указатель на оператор, который находится в голове цепочки. Она изменяет дерево операторов на месте.

Оптимизатор peephole никогда не следует полностью заменять. Вместо этого, добавьте код, обернув существующий оптимизатор. Основной способ сделать это показан в "Compile pass 3: peephole optimization" in perlguts. Если новый код хочет работать только с операторами на верхнем уровне подпрограммы, а не по всей структуре, вероятно, удобнее будет обернуть обработчик "PL_peepp".

peep_t  PL_rpeepp

PL_runops

См. "Pluggable runops" in perlguts.

runops_proc_t   PL_runops

PL_sv_no

Это false SV. См. "PL_sv_yes". Всегда ссылайтесь на него как на &PL_sv_no.

SV      PL_sv_no

PL_sv_undef

Это undef SV. Всегда ссылайтесь на него как на &PL_sv_undef.

SV      PL_sv_undef

PL_sv_yes

Это true SV. См. "PL_sv_no". Всегда ссылайтесь на него как на &PL_sv_yes.

SV      PL_sv_yes

PL_sv_zero

Этот только для чтения SV имеет нулевое числовое значение и строковое значение "0". Аналогичен "PL_sv_no", за исключением его строкового значения. Может использоваться в качестве более быстрого варианта mXPUSHi(0), например. Всегда ссылайтесь на него как на &PL_sv_zero. Введён в 5.28.

SV      PL_sv_zero

Функции REGEXP

SvRX

Удобный макрос для получения REGEXP из SV. Примерно эквивалентен следующему фрагменту кода:

if (SvMAGICAL(sv))
    mg_get(sv);
if (SvROK(sv))
    sv = MUTABLE_SV(SvRV(sv));
if (SvTYPE(sv) == SVt_REGEXP)
    return (REGEXP*) sv;

Если REGEXP* не найден, возвращается NULL.

REGEXP * SvRX(SV *sv)

SvRXOK

Возвращает булево значение, указывающее, является ли SV (или на который он ссылается) REGEXP.

Если вы хотите выполнить действия с REGEXP* позже, используйте SvRX и проверьте на NULL.

bool    SvRXOK(SV* sv)

Макросы управления стеком

dMARK

Объявить переменную маркера стека, mark, для XSUB. См. "MARK" и "dORIGMARK".

dMARK;

dORIGMARK

Сохраняет исходную метку стека для XSUB. См. "ORIGMARK".

dORIGMARK;

dSP

Объявляет локальную копию указателя стека Perl для XSUB, доступную через макрос SP. См. "SP".

dSP;

EXTEND

Используется для расширения стека аргументов для значений возврата XSUB. После использования гарантируется, что в стеке есть место для помещения по крайней мере nitems элементов.

void    EXTEND(SP, SSize_t nitems)

MARK

Переменная маркера стека для XSUB. См. "dMARK".

mPUSHi

Поместить целое число в стек. В стеке должно быть место для этого элемента. Не использует TARG. См. также "PUSHi", "mXPUSHi" и "XPUSHi".

void    mPUSHi(IV iv)

mPUSHn

Поместить двойное число в стек. В стеке должно быть место для этого элемента. Не использует TARG. См. также "PUSHn", "mXPUSHn" и "XPUSHn".

void    mPUSHn(NV nv)

mPUSHp

Поместить строку в стек. В стеке должно быть место для этого элемента. len указывает длину строки. Не использует TARG. См. также "PUSHp", "mXPUSHp" и "XPUSHp".

void    mPUSHp(char* str, STRLEN len)

mPUSHs

Поместить SV в стек и сделать SV смертельным. В стеке должно быть место для этого элемента. Не использует TARG. См. также "PUSHs" и "mXPUSHs".

void    mPUSHs(SV* sv)

mPUSHu

Поместить беззнаковое целое число в стек. В стеке должно быть место для этого элемента. Не использует TARG. См. также "PUSHu", "mXPUSHu" и "XPUSHu".

void    mPUSHu(UV uv)

mXPUSHi

Поместить целое число в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHi", "mPUSHi" и "PUSHi".

void    mXPUSHi(IV iv)

mXPUSHn

Поместить двойное число в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHn", "mPUSHn" и "PUSHn".

void    mXPUSHn(NV nv)

mXPUSHp

Поместить строку в стек, расширяя стек при необходимости. len указывает длину строки. Не использует TARG. См. также "XPUSHp", mPUSHp и PUSHp.

void    mXPUSHp(char* str, STRLEN len)

mXPUSHs

Поместить SV в стек, расширяя стек при необходимости и делая SV смертельным. Не использует TARG. См. также "XPUSHs" и "mPUSHs".

void    mXPUSHs(SV* sv)

mXPUSHu

Поместить беззнаковое целое число в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHu", "mPUSHu" и "PUSHu".

void    mXPUSHu(UV uv)

ORIGMARK

Исходная метка стека для XSUB. См. "dORIGMARK".

POPi

Извлекает целое число из стека.

IV      POPi

POPl

Извлекает целое число типа long из стека.

long    POPl

POPn

Извлекает двойное число из стека.

NV      POPn

POPp

Извлекает строку из стека.

char*   POPp

POPpbytex

Извлекает строку из стека, которая должна состоять из байтов, т. е. символов < 256.

char*   POPpbytex

POPpx

Извлекает строку из стека. Идентично POPp. Есть два имени по историческим причинам.

char*   POPpx

POPs

Извлекает SV из стека.

SV*     POPs

POPu

Извлекает беззнаковое целое число из стека.

UV      POPu

POPul

Извлекает беззнаковое целое число типа long из стека.

long    POPul

PUSHi

Поместить целое число в стек. В стеке должно быть место для этого элемента. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mPUSHi" вместо этого. См. также "XPUSHi" и "mXPUSHi".

void    PUSHi(IV iv)

PUSHMARK

Открывающая скобка для аргументов в обратном вызове. См. "PUTBACK" и perlcall.

void    PUSHMARK(SP)

PUSHmortal

Поместить новый смертельный SV в стек. В стеке должно быть место для этого элемента. Не использует TARG. См. также "PUSHs", "XPUSHmortal" и "XPUSHs".

void    PUSHmortal

PUSHn

Поместить двойное число в стек. В стеке должно быть место для этого элемента. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mPUSHn" вместо этого. См. также "XPUSHn" и "mXPUSHn".

void    PUSHn(NV nv)

PUSHp

Поместить строку в стек. В стеке должно быть место для этого элемента. len указывает длину строки. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mPUSHp" вместо этого. См. также "XPUSHp" и "mXPUSHp".

void    PUSHp(char* str, STRLEN len)

PUSHs

Поместить SV в стек. В стеке должно быть место для этого элемента. Не обрабатывает магию 'set'. Не использует TARG. См. также "PUSHmortal", "XPUSHs", и "XPUSHmortal".

void    PUSHs(SV* sv)

PUSHu

Поместить беззнаковое целое число в стек. В стеке должно быть место для этого элемента. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mPUSHu" вместо этого. См. также "XPUSHu" и "mXPUSHu".

void    PUSHu(UV uv)

PUTBACK

Закрывающая скобка для аргументов XSUB. Обычно это обрабатывается xsubpp. См. "PUSHMARK" и perlcall для других применений.

PUTBACK;

SP

Указатель стека. Обычно это обрабатывается xsubpp. См. "dSP" и SPAGAIN.

SPAGAIN

Перезагрузка указателя стека. Используется после обратного вызова. См. perlcall.

SPAGAIN;

XPUSHi

Поместить целое число в стек, расширяя стек при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mXPUSHi" вместо этого. См. также "PUSHi" и "mPUSHi".

void    XPUSHi(IV iv)

XPUSHmortal

Поместить новый смертельный SV в стек, расширяя стек при необходимости. Не использует TARG. См. также "XPUSHs", "PUSHmortal" и "PUSHs".

void    XPUSHmortal

XPUSHn

Поместить двойное число в стек, расширяя стек при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mXPUSHn" вместо этого. См. также "PUSHn" и "mPUSHn".

void    XPUSHn(NV nv)

XPUSHp

Поместить строку в стек, расширяя стек при необходимости. len указывает длину строки. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mXPUSHp" вместо этого. См. также "PUSHp" и "mPUSHp".

void    XPUSHp(char* str, STRLEN len)

XPUSHs

Поместить SV в стек, расширяя стек при необходимости. Не обрабатывает магию 'set'. Не использует TARG. См. также "XPUSHmortal", PUSHs и PUSHmortal.

void    XPUSHs(SV* sv)

XPUSHu

Поместить беззнаковое целое число в стек, расширяя стек при необходимости. Обрабатывает магию 'set'. Использует TARG, поэтому dTARGET или dXSTARG должны быть вызваны для объявления. Не вызывайте несколько макросов, ориентированных на TARG, для возврата списков из XSUB - используйте "mXPUSHu" вместо этого. См. также "PUSHu" и "mPUSHu".

void    XPUSHu(UV uv)

XSRETURN

Возврат из XSUB, указывающий количество элементов в стеке. Обычно это обрабатывается xsubpp.

void    XSRETURN(int nitems)

XSRETURN_EMPTY

Немедленно вернуть пустой список из XSUB.

XSRETURN_EMPTY;

XSRETURN_IV

Немедленно вернуть целое число из XSUB. Использует XST_mIV.

void    XSRETURN_IV(IV iv)

XSRETURN_NO

Немедленно вернуть &PL_sv_no из XSUB. Использует XST_mNO.

XSRETURN_NO;

XSRETURN_NV

Возвращает двойное значение из XSUB немедленно. Использует XST_mNV.

void    XSRETURN_NV(NV nv)

XSRETURN_PV

Возвращает копию строки из XSUB немедленно. Использует XST_mPV.

void    XSRETURN_PV(char* str)

XSRETURN_UNDEF

Возвращает &PL_sv_undef из XSUB немедленно. Использует XST_mUNDEF.

XSRETURN_UNDEF;

XSRETURN_UV

Возвращает целое число из XSUB немедленно. Использует XST_mUV.

void    XSRETURN_UV(IV uv)

XSRETURN_YES

Возвращает &PL_sv_yes из XSUB немедленно. Использует XST_mYES.

XSRETURN_YES;

XST_mIV

Размещает целое число в указанную позицию pos на стеке. Значение хранится в новой смертной переменной (mortal SV).

void    XST_mIV(int pos, IV iv)

XST_mNO

Размещает &PL_sv_no в указанную позицию pos на стеке.

void    XST_mNO(int pos)

XST_mNV

Размещает двойное значение в указанную позицию pos на стеке. Значение хранится в новой смертной переменной (mortal SV).

void    XST_mNV(int pos, NV nv)

XST_mPV

Размещает копию строки в указанную позицию pos на стеке. Значение хранится в новой смертной переменной (mortal SV).

void    XST_mPV(int pos, char* str)

XST_mUNDEF

Размещает &PL_sv_undef в указанную позицию pos на стеке.

void    XST_mUNDEF(int pos)

XST_mUV

Размещает беззнаковое целое число в указанную позицию pos на стеке. Значение хранится в новой смертной переменной (mortal SV).

void    XST_mUV(int pos, UV uv)

XST_mYES

Размещает &PL_sv_yes в указанную позицию pos на стеке.

void    XST_mYES(int pos)

Флаги SV

SVt_IV

Флаг типа для скаляров. См. "svtype".

SVt_NULL

Флаг типа для скаляров. См. "svtype".

SVt_NV

Флаг типа для скаляров. См. "svtype".

SVt_PV

Флаг типа для скаляров. См. "svtype".

SVt_PVAV

Флаг типа для массивов. См. "svtype".

SVt_PVCV

Флаг типа для подпрограмм. См. "svtype".

SVt_PVFM

Флаг типа для форматов. См. "svtype".

SVt_PVGV

Флаг типа для типглобов. См. "svtype".

SVt_PVHV

Флаг типа для хэшей. См. "svtype".

SVt_PVIO

Флаг типа для объектов ввода/вывода. См. "svtype".

SVt_PVIV

Флаг типа для скаляров. См. "svtype".

SVt_PVLV

Флаг типа для скаляров. См. "svtype".

SVt_PVMG

Флаг типа для скаляров. См. "svtype".

SVt_PVNV

Флаг типа для скаляров. См. "svtype".

SVt_REGEXP

Флаг типа для регулярных выражений. См. "svtype".

svtype

Перечисление флагов для типов Perl. Эти флаги находятся в файле sv.h в перечислении svtype. Проверяйте эти флаги с помощью макроса SvTYPE.

Типы:

SVt_NULL
SVt_IV
SVt_NV
SVt_RV
SVt_PV
SVt_PVIV
SVt_PVNV
SVt_PVMG
SVt_INVLIST
SVt_REGEXP
SVt_PVGV
SVt_PVLV
SVt_PVAV
SVt_PVHV
SVt_PVCV
SVt_PVFM
SVt_PVIO

Их проще всего объяснить снизу вверх.

SVt_PVIO предназначен для объектов ввода/вывода, SVt_PVFM для форматов, SVt_PVCV для подпрограмм, SVt_PVHV для хэшей и SVt_PVAV для массивов.

Все остальные являются скалярными типами, то есть вещами, которые могут быть связаны с переменной $. Для них внутренние типы в основном ортогональны типам в языке Perl.

Поэтому проверка SvTYPE(sv) < SVt_PVAV - лучший способ определить, является ли что-то скалярным.

SVt_PVGV представляет типглоб. Если !SvFAKE(sv), то это реальный, не преобразуемый типглоб. Если SvFAKE(sv), то это скаляр, которому был назначен типглоб. Повторное назначение сделает его не типглобом. SVt_PVLV представляет скаляр, который делегирует работу другому скаляру за кулисами. Используется, например, для возвращаемого значения substr и для связанных хэшей и элементов массива. Он может хранить любое скалярное значение, включая типглоб. SVt_REGEXP предназначен для регулярных выражений. SVt_INVLIST предназначен только для внутреннего использования ядра Perl.

SVt_PVMG представляет «обычный» скаляр (не типглоб, регулярное выражение или делегат). Поскольку большинству скаляров не нужны все внутренние поля PVMG, мы экономим память, выделяя более компактные структуры, когда это возможно. Все остальные типы — это просто более простые формы SVt_PVMG, с меньшим количеством внутренних полей. SVt_NULL может хранить только undef. SVt_IV может хранить undef, целое число или ссылку. (SVt_RV является псевдонимом для SVt_IV, который существует для обратной совместимости.) SVt_NV может хранить любое из них или двойное значение. SVt_PV может хранить только undef или строку. SVt_PVIV является супермножеством SVt_PV и SVt_IV. SVt_PVNV подобен ему. SVt_PVMG может хранить все, что может хранить SVt_PVNV, но может, но необязательно, быть благословлённым или магическим.

Функции обработки SV

boolSV

Возвращает SV со значением true, если b имеет истинное значение, или SV со значением false, если b равно 0.

См. также "PL_sv_yes" и "PL_sv_no".

SV *    boolSV(bool b)

croak_xs_usage

Специализированная версия croak() для вывода сообщения об использовании для xsubs

croak_xs_usage(cv, "eee_yow");

определяет имя пакета и имя подпрограммы из cv, а затем вызывает croak(). Таким образом, если cv равно &ouch::awk, то вызов croak будет выглядеть так:

Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
                                                    "eee_yow");

       void    croak_xs_usage(const CV *const cv,
                              const char *const params)

get_sv

Возвращает SV указанного перловского скаляра. flags передаются в gv_fetchpv. Если GV_ADD установлено и перловская переменная не существует, то она будет создана. Если flags равно нулю и переменная не существует, то возвращается NULL.

ПРИМЕЧАНИЕ: перловская форма этой функции устарела.

SV*     get_sv(const char *name, I32 flags)

looks_like_number

Проверяет, выглядит ли содержимое SV как число (или является числом). Inf и Infinity обрабатываются как числа (поэтому предупреждение о нечисловом значении не будет выдаваться), даже если ваш atof() их не распознаёт. Функция get-magic игнорируется.

I32     looks_like_number(SV *const sv)

newRV_inc

Создаёт обёртку RV для SV. Счётчик ссылок для исходного SV увеличивается.

SV*     newRV_inc(SV* sv)

newRV_noinc

Создаёт обёртку RV для SV. Счётчик ссылок для исходного SV не увеличивается.

SV*     newRV_noinc(SV *const tmpRef)

newSV

Создаёт новый SV. Не нулевое значение параметра len указывает на количество байтов предварительно выделенного места для строки в SV. Также резервируется дополнительный байт для заключительного NUL. (SvPOK не устанавливается для SV, даже если выделено место для строки.) Счётчик ссылок для нового SV устанавливается в 1.

В версии 5.9.3, newSV() заменяет устаревший API NEWSV(), и удаляет первый параметр, x, инструмент отладки, который позволял вызывающим сторонам идентифицировать себя. Этот инструмент был заменён новым параметром сборки PERL_MEM_LOG (см. "PERL_MEM_LOG" в perlhacktips). Устаревший API всё ещё доступен для использования в модулях XS, поддерживающих более старые версии Perl.

SV*     newSV(const STRLEN len)

newSVhek

Создаёт новый SV из структуры ключа хэша. По возможности создаёт скаляры, указывающие на общую таблицу строк. Возвращает новый (неопределённый) SV, если hek равен NULL.

SV*     newSVhek(const HEK *const hek)

newSViv

Создаёт новый SV и копирует в него целое число. Счётчик ссылок для SV устанавливается в 1.

SV*     newSViv(const IV i)

newSVnv

Создаёт новый SV и копирует в него значение с плавающей точкой. Счётчик ссылок для SV устанавливается в 1.

SV*     newSVnv(const NV n)

newSVpadname

Создаёт новый SV, содержащий имя блока.

SV*     newSVpadname(PADNAME *pn)

newSVpv

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символы). Счётчик ссылок для SV устанавливается в 1. Если len равно нулю, Perl вычислит длину, используя strlen(), (что означает, что если вы используете этот параметр, то s не может содержать вложенные NUL символы и должен иметь завершающий NUL байт).

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

Использование "newSVpvn" является более безопасной альтернативой для строк, не завершённых NUL. Для строковых литералов используйте "newSVpvs" вместо этого. Эта функция будет нормально работать со строками, завершёнными NUL, но если вы хотите избежать проверки, нужно ли вызывать strlen, используйте newSVpvn вместо этого (вызывая strlen самостоятельно).

SV*     newSVpv(const char *const s, const STRLEN len)

newSVpvf

Создаёт новый SV и инициализирует его строкой, отформатированной как sv_catpvf.

SV*     newSVpvf(const char *const pat, ...)

newSVpvn

Создаёт новый SV и копирует в него строку, которая может содержать NUL символы (\0) и другие двоичные данные. Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку длиной 0 (Perl). Вы несёте ответственность за обеспечение того, что исходный буфер имеет длину как минимум len байт. Если аргумент buffer равен NULL, новый SV будет неопределённым.

SV*     newSVpvn(const char *const buffer,
                 const STRLEN len)

newSVpvn_flags

Создаёт новый SV и копирует в него строку (которая может содержать NUL (\0) символов). Счётчик ссылок для SV устанавливается в 1. Обратите внимание, что если len равно нулю, Perl создаст строку длиной 0. Вы несёте ответственность за обеспечение того, что исходная строка имеет длину как минимум len байт. Если аргумент s равен NULL, новый SV будет неопределённым. В настоящее время принимаются только флаги SVf_UTF8 и SVs_TEMP. Если SVs_TEMP установлен, то sv_2mortal() вызывается для результата перед возвращением. Если SVf_UTF8 установлен, s считается UTF-8 и флаг SVf_UTF8 будет установлен для нового SV. newSVpvn_utf8() — это удобная обёртка для этой функции, определённая как

#define newSVpvn_utf8(s, len, u)                    \
    newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)

    SV*     newSVpvn_flags(const char *const s,
                           const STRLEN len,
                           const U32 flags)

newSVpvn_share

Создаёт новый SV, в котором SvPVX_const указывает на общую строку в таблице строк. Если строка ещё не существует в таблице, она создаётся сначала. Включает флаг SvIsCOW (или READONLY и FAKE в версиях 5.16 и ранее). Если параметр hash не равен нулю, используется это значение; в противном случае вычисляется хэш. Хэш строки можно получить из SV с помощью макроса SvSHARED_HASH(). Идея состоит в том, что так как таблица строк используется для общих ключей хэшей, эти строки будут иметь SvPVX_const == HeKEY и поиск по хэшу избежит сравнения строк.

SV*     newSVpvn_share(const char* s, I32 len, U32 hash)

newSVpvn_utf8

Создаёт новый SV и копирует в него строку, которая может содержать NUL (\0) символов. Если utf8 истинно, вызывает SvUTF8_on для нового SV. Реализовано как обёртка вокруг newSVpvn_flags.

SV*     newSVpvn_utf8(const char* s, STRLEN len,
                      U32 utf8)

newSVpvs

Как newSVpvn, но принимает строковый литерал вместо пары строка/длина.

SV*     newSVpvs("literal string")

newSVpvs_flags

Как newSVpvn_flags, но принимает строковый литерал вместо пары строка/длина.

SV*     newSVpvs_flags("literal string", U32 flags)

newSVpv_share

Как newSVpvn_share, но принимает строку, завершенную NUL, вместо пары строка/длина.

SV*     newSVpv_share(const char* s, U32 hash)

newSVpvs_share

Как newSVpvn_share, но принимает строковый литерал вместо пары строка/длина и опускает параметр хэша.

SV*     newSVpvs_share("literal string")

newSVrv

Создаёт новый SV, чтобы существующий RV, rv, указывал на него. Если rv не является RV, то он будет преобразован в него. Если classname не равно NULL, то новый SV будет освящён в указанном пакете. Новый SV возвращается, и его счётчик ссылок равен 1. Счётчик ссылок 1 принадлежит rv. См. также newRV_inc() и newRV_noinc() для правильного создания нового RV.

SV*     newSVrv(SV *const rv,
                const char *const classname)

newSVsv

Создаёт новый SV, являющийся точной копией исходного SV. (Использует sv_setsv.)

SV*     newSVsv(SV *const old)

newSVsv_nomg

Как newSVsv но не обрабатывает get-магию.

SV*     newSVsv_nomg(SV *const old)

newSV_type

Создаёт новый SV заданного типа. Счётчик ссылок нового SV устанавливается в 1.

SV*     newSV_type(const svtype type)

newSVuv

Создаёт новый SV и копирует в него беззнаковое целое число. Счётчик ссылок для SV устанавливается в 1.

SV*     newSVuv(const UV u)

sortsv_flags

Сортирует массив указателей на SV на месте с заданной функцией сравнения и различными флагами SORTf_*.

void    sortsv_flags(SV** array, size_t num_elts,
                     SVCOMPARE_t cmp, U32 flags)

sv_2bool

Этот макрос используется только sv_true() или его макро-эквивалентом, и только если аргумент последнего не равен SvPOK, SvIOK или SvNOK. Он вызывает sv_2bool_flags с флагом SV_GMAGIC.

bool    sv_2bool(SV *const sv)

sv_2bool_flags

Эта функция используется только sv_true() и аналогичными функциями, и только если аргумент последнего не равен SvPOK, SvIOK или SvNOK. Если флаги содержат SV_GMAGIC, то сначала выполняется mg_get().

bool    sv_2bool_flags(SV *sv, I32 flags)

sv_2cv

Используя различные методы, пытается получить CV из SV; кроме того, по возможности устанавливает *st и *gvp в хранилище и GV, связанные с ним. Флаги в lref передаются в gv_fetchsv.

CV*     sv_2cv(SV* sv, HV **const st, GV **const gvp,
               const I32 lref)

sv_2io

Используя различные методы, пытается получить IO из SV: слот IO, если это GV; или рекурсивный результат, если это RV; или слот IO символа, названного по PV, если это строка.

Магия 'Get' игнорируется для sv, переданного на вход, но будет вызвана для SvRV(sv) если sv является RV.

IO*     sv_2io(SV *const sv)

sv_2iv_flags

Возвращает целое значение SV, выполнив необходимые преобразования строк. Если flags имеет установленный бит SV_GMAGIC, то сначала выполняется mg_get(). Обычно используется через макросы SvIV(sv) и SvIVx(sv).

IV      sv_2iv_flags(SV *const sv, const I32 flags)

sv_2mortal

Помечает существующий SV как смертельный. SV будет уничтожен «скоро», либо явным вызовом FREETMPS, либо неявным вызовом в местах, таких как границы операторов. SvTEMP() включено, что означает, что буфер строк SV может быть «украден», если этот SV копируется. См. также "sv_newmortal" и "sv_mortalcopy".

SV*     sv_2mortal(SV *const sv)

sv_2nv_flags

Возвращает числовое значение SV, выполняя необходимые преобразования строк или целых чисел. Если flags имеет установленный бит SV_GMAGIC, выполняется mg_get() сначала. Обычно используется через макросы SvNV(sv) и SvNVx(sv).

NV      sv_2nv_flags(SV *const sv, const I32 flags)

sv_2pvbyte

Возвращает указатель на байтовое представление SV и устанавливает *lp в его длину. Если SV помечен как закодированный в UTF-8, он будет понижен до байтовой строки как побочный эффект, если это возможно. Если SV нельзя понизить, произойдёт ошибка.

Обычно используется через макрос SvPVbyte.

char*   sv_2pvbyte(SV *sv, STRLEN *const lp)

sv_2pvutf8

Возвращает указатель на UTF-8 представление SV и устанавливает *lp в его длину. Может привести к повышению кодировки SV до UTF-8 в качестве побочного эффекта.

Обычно используется через макрос SvPVutf8.

char*   sv_2pvutf8(SV *sv, STRLEN *const lp)

sv_2pv_flags

Возвращает указатель на строковое значение SV и устанавливает *lp в его длину. Если флаги имеют установленный бит SV_GMAGIC, выполняется mg_get() сначала. Преобразует sv в строку при необходимости. Обычно вызывается через макрос SvPV_flags. sv_2pv() и sv_2pv_nomg обычно заканчиваются здесь тоже.

char*   sv_2pv_flags(SV *const sv, STRLEN *const lp,
                     const I32 flags)

sv_2uv_flags

Возвращает целое беззнаковое значение SV, выполняя необходимые преобразования строк. Если flags имеет установленный бит SV_GMAGIC, выполняется mg_get() сначала. Обычно используется через макросы SvUV(sv) и SvUVx(sv).

UV      sv_2uv_flags(SV *const sv, const I32 flags)

sv_backoff

Удалить любой смещение строки. Вы обычно должны использовать макрос-обёртку SvOOK_off вместо этого.

void    sv_backoff(SV *const sv)

sv_bless

Освящает SV в указанный пакет. SV должен быть RV. Пакет должен быть обозначен его хранилищем (см. "gv_stashpv"). Счётчик ссылок SV не изменяется.

SV*     sv_bless(SV *const sv, HV *const stash)

sv_catpv

Конкатенирует строку, завершающуюся NUL, к концу строки в SV. Если SV имеет установленный статус UTF-8, то добавленные байты должны быть валидным UTF-8. Обрабатывает магию 'get', но не магию 'set'. См. "sv_catpv_mg".

void    sv_catpv(SV *const sv, const char* ptr)

sv_catpvf

Обрабатывает свои аргументы как sprintf, и добавляет отформатированный вывод к SV. Как и в случае с sv_vcatpvfn с ненулевым списком аргументов C-стиля, переупорядочивание аргументов не поддерживается. Если добавленные данные содержат «широкие» символы (включая, но не ограничиваясь, SVs с PV UTF-8, отформатированными с %s, и символами >255, отформатированными с %c), исходный SV может быть повышен до UTF-8. Обрабатывает магию 'get', но не магию 'set'. См. "sv_catpvf_mg". Если исходный SV был UTF-8, шаблон должен быть валидным UTF-8; если исходный SV был байтами, шаблон тоже.

void    sv_catpvf(SV *const sv, const char *const pat,
                  ...)

sv_catpvf_mg

Как sv_catpvf, но также обрабатывает магию 'set'.

void    sv_catpvf_mg(SV *const sv,
                     const char *const pat, ...)

sv_catpvn

Конкатенирует строку к концу строки в SV. len указывает количество байтов для копирования. Если SV имеет установленный статус UTF-8, то добавленные байты должны быть валидным UTF-8. Обрабатывает магию 'get', но не магию 'set'. См. "sv_catpvn_mg".

void    sv_catpvn(SV *dsv, const char *sstr, STRLEN len)

sv_catpvn_flags

Конкатенирует строку к концу строки в SV. len указывает количество байтов для копирования.

По умолчанию предполагается, что добавляемая строка является валидным UTF-8, если у SV установлен статус UTF-8, и строка байтов в противном случае. Можно заставить интерпретировать добавленную строку как UTF-8, задав флаг SV_CATUTF8, и как байты, задав флаг SV_CATBYTES; SV или добавленная строка будут повышены до UTF-8 при необходимости.

Если flags имеет установленный бит SV_SMAGIC, будет вызвано mg_set для dsv впоследствии, если это необходимо. sv_catpvn и sv_catpvn_nomg реализованы через эту функцию.

void    sv_catpvn_flags(SV *const dstr,
                        const char *sstr,
                        const STRLEN len,
                        const I32 flags)

sv_catpvn_nomg

Как sv_catpvn, но не обрабатывает магию.

void    sv_catpvn_nomg(SV* sv, const char* ptr,
                       STRLEN len)

sv_catpvs

Как sv_catpvn, но принимает строку вместо пары строка/длина.

void    sv_catpvs(SV* sv, "literal string")

sv_catpvs_flags

Как sv_catpvn_flags, но принимает строку вместо пары строка/длина.

void    sv_catpvs_flags(SV* sv, "literal string",
                        I32 flags)

sv_catpvs_mg

Как sv_catpvn_mg, но принимает строку вместо пары строка/длина.

void    sv_catpvs_mg(SV* sv, "literal string")

sv_catpvs_nomg

Как sv_catpvn_nomg, но принимает строку вместо пары строка/длина.

void    sv_catpvs_nomg(SV* sv, "literal string")

sv_catpv_flags

Конкатенирует строку, завершающуюся NUL, к концу строки в SV. Если SV имеет установленный статус UTF-8, то добавленные байты должны быть валидным UTF-8. Если flags имеет установленный бит SV_SMAGIC, будет вызвано mg_set для модифицированного SV, если это необходимо.

void    sv_catpv_flags(SV *dstr, const char *sstr,
                       const I32 flags)

sv_catpv_mg

Как sv_catpv, но также обрабатывает магию 'set'.

void    sv_catpv_mg(SV *const sv, const char *const ptr)

sv_catpv_nomg

Как sv_catpv но не обрабатывает магию.

void    sv_catpv_nomg(SV* sv, const char* ptr)

sv_catsv

Конкатенирует строку из SV ssv к концу строки в SV dsv. Если ssv равно null, ничего не делает; в противном случае изменяет только dsv. Обрабатывает магию 'get' для обоих SV, но не магию 'set'. См. "sv_catsv_mg" и "sv_catsv_nomg".

void    sv_catsv(SV *dstr, SV *sstr)

sv_catsv_flags

Конкатенирует строку из SV ssv к концу строки в SV dsv. Если ssv равно null, ничего не делает; в противном случае изменяет только dsv. Если flags имеет установленный бит SV_GMAGIC, будет вызвано mg_get для обоих SV, если это необходимо. Если flags имеет установленный бит SV_SMAGIC, mg_set будет вызвано для изменённого SV впоследствии, если это необходимо. sv_catsv, sv_catsv_nomg, и sv_catsv_mg реализованы через эту функцию.

void    sv_catsv_flags(SV *const dsv, SV *const ssv,
                       const I32 flags)

sv_catsv_nomg

Как sv_catsv, но не обрабатывает магию.

void    sv_catsv_nomg(SV* dsv, SV* ssv)

sv_chop

Эффективное удаление символов с начала буфера строк. SvPOK(sv), или по крайней мере SvPOKp(sv), должны быть истинными и ptr должен быть указателем на место внутри буфера строк. ptr становится первым символом скорректированной строки. Использует хак OOK. По возвращении, только SvPOK(sv) и SvPOKp(sv) среди флагов OK будут истинными.

Предупреждение: после возврата этой функции ptr и SvPVX_const(sv) могут больше не ссылаться на один и тот же кусок данных.

Несчастное сходство имени этой функции с оператором Perl's chop является строго случайным. Эта функция работает слева направо; chop работает справа налево.

void    sv_chop(SV *const sv, const char *const ptr)

sv_clear

Очистить SV: вызвать все деструкторы, освободить всю память, используемую телом, и освободить само тело. Голова SV не освобождается, хотя её тип устанавливается в все 1, чтобы она не была случайным образом принята как живая во время глобального уничтожения и т. д. Эту функцию следует вызывать только когда REFCNT равно нулю. Большинство времени вы захотите вызвать sv_free() (или её макросную обёртку SvREFCNT_dec) вместо этого.

void    sv_clear(SV *const orig_sv)

sv_cmp

Сравнивает строки в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли строка в sv1, равна или больше строки в sv2. Поддерживает UTF-8 и 'use bytes', обрабатывает магию get и преобразует свои аргументы в строки при необходимости. См. также "sv_cmp_locale".

I32     sv_cmp(SV *const sv1, SV *const sv2)

sv_cmp_flags

Сравнивает строки в двух SV. Возвращает -1, 0 или 1, указывая, меньше ли строка в sv1, равна или больше строки в sv2. Поддерживает UTF-8 и 'use bytes' и преобразует свои аргументы в строки при необходимости. Если в флагах установлен бит SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_locale_flags".

I32     sv_cmp_flags(SV *const sv1, SV *const sv2,
                     const U32 flags)

sv_cmp_locale

Сравнивает строки в двух SV с учётом локали. Поддерживает UTF-8 и 'use bytes', обрабатывает магию get и преобразует свои аргументы в строки при необходимости. См. также "sv_cmp".

I32     sv_cmp_locale(SV *const sv1, SV *const sv2)

sv_cmp_locale_flags

Сравнивает строки в двух SV с учётом локали. Поддерживает UTF-8 и 'use bytes' и преобразует свои аргументы в строки при необходимости. Если флаги содержат SV_GMAGIC, обрабатывает магию get. См. также "sv_cmp_flags".

I32     sv_cmp_locale_flags(SV *const sv1,
                            SV *const sv2,
                            const U32 flags)

sv_collxfrm

Вызывает sv_collxfrm_flags с флагом SV_GMAGIC. См. "sv_collxfrm_flags".

char*   sv_collxfrm(SV *const sv, STRLEN *const nxp)

sv_collxfrm_flags

Добавить магию Collate Transform в SV, если её там нет. Если флаги содержат SV_GMAGIC, обрабатывает get-магию.

Любая скалярная переменная может содержать PERL_MAGIC_collxfrm магию, которая содержит данные скалярной переменной, но преобразованные в такой формат, что для сравнения данных в соответствии с настройками языка можно использовать обычное сравнение в памяти.

char*   sv_collxfrm_flags(SV *const sv,
                          STRLEN *const nxp,
                          I32 const flags)

sv_copypv

Копирует строковое представление исходного SV в целевой SV. Автоматически выполняет необходимые mg_get и приведение числовых значений к строкам. Гарантирует сохранение UTF8 флага даже из перегруженных объектов. Похож по природе на sv_2pv[_flags], но работает непосредственно со SV вместо только строки. В основном использует sv_2pv_flags для своей работы, за исключением случаев, когда это приведёт к потере UTF-8-ности PV.

void    sv_copypv(SV *const dsv, SV *const ssv)

sv_copypv_flags

Реализация sv_copypv и sv_copypv_nomg. Вызывает get magic, если в флагах установлен бит SV_GMAGIC.

void    sv_copypv_flags(SV *const dsv, SV *const ssv,
                        const I32 flags)

sv_copypv_nomg

Подобно sv_copypv, но не вызывает get magic сначала.

void    sv_copypv_nomg(SV *const dsv, SV *const ssv)

SvCUR

Возвращает длину строки, находящейся в SV. См. "SvLEN".

STRLEN  SvCUR(SV* sv)

SvCUR_set

Устанавливает текущую длину строки, которая находится в SV. См. "SvCUR" и SvIV_set>.

void    SvCUR_set(SV* sv, STRLEN len)

sv_dec

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает магию 'get' и перегрузку операторов.

void    sv_dec(SV *const sv)

sv_dec_nomg

Автоматическое уменьшение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает перегрузку операторов. Пропускает обработку 'get' магии.

void    sv_dec_nomg(SV *const sv)

sv_derived_from

Точно так же, как "sv_derived_from_pv", но не принимает параметр flags.

bool    sv_derived_from(SV* sv, const char *const name)

sv_derived_from_pv

Точно так же, как "sv_derived_from_pvn", но принимает нуль-терминированную строку вместо пары "строка/длина".

bool    sv_derived_from_pv(SV* sv,
                           const char *const name,
                           U32 flags)

sv_derived_from_pvn

Возвращает булево значение, указывающее, является ли SV производным от указанного класса на уровне C. Для проверки производности на уровне Perl вызовите isa() как обычный Perl-метод.

В настоящее время единственное значимое значение для flags — SVf_UTF8.

bool    sv_derived_from_pvn(SV* sv,
                            const char *const name,
                            const STRLEN len, U32 flags)

sv_derived_from_sv

Точно так же, как "sv_derived_from_pvn", но принимает строку в виде SV вместо пары "строка/длина". Этот вариант рекомендуется.

bool    sv_derived_from_sv(SV* sv, SV *namesv,
                           U32 flags)

sv_does

Подобно "sv_does_pv", но не принимает параметр flags.

bool    sv_does(SV* sv, const char *const name)

sv_does_pv

Подобно "sv_does_sv", но принимает нуль-терминированную строку вместо SV.

bool    sv_does_pv(SV* sv, const char *const name,
                   U32 flags)

sv_does_pvn

Подобно "sv_does_sv", но принимает пару "строка/длина" вместо SV.

bool    sv_does_pvn(SV* sv, const char *const name,
                    const STRLEN len, U32 flags)

sv_does_sv

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

bool    sv_does_sv(SV* sv, SV* namesv, U32 flags)

SvEND

Возвращает указатель на позицию сразу после последнего символа в строке, которая находится в SV, где обычно находится заключительный символ NUL (даже если скаляры Perl его строго не требуют). См. "SvCUR". Доступ к символу осуществляется как *(SvEND(sv)).

Предупреждение: Если SvCUR равно SvLEN, то SvEND указывает на невыделенную память.

char*   SvEND(SV* sv)

sv_eq

Возвращает булево значение, указывающее, идентичны ли строки в двух SV. Учитывает UTF-8 и 'use bytes', обрабатывает get magic и приведёт аргументы к строкам при необходимости.

I32     sv_eq(SV* sv1, SV* sv2)

sv_eq_flags

Возвращает булево значение, указывающее, идентичны ли строки в двух SV. Учитывает UTF-8 и 'use bytes', а также приведёт аргументы к строкам при необходимости. Если в флагах установлен бит SV_GMAGIC, то обрабатывается и get-магия.

I32     sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)

sv_force_normal_flags

Отменяет различные виды фальсификации в SV, где фальсификация означает "больше, чем" строка: если PV является общей строкой, создаёт частную копию; если это ссылка, прекращает её; если это шаблон, понижает до xpvmg; если это скаляр с копированием при записи, это время записи, когда мы делаем копию, и также используется локально; если это vстрока, удаляет магию vстроки. Если установлен SV_COW_DROP_PV, тогда скаляр с копированием при записи удаляет буфер PV (если он есть) и становится SvPOK_off, а не создаёт копию. (Используется, когда этот скаляр собирается быть установлен на какое-то другое значение). Кроме того, параметр flags передаётся в sv_unref_flags() при отмене ссылки. sv_force_normal вызывает эту функцию с флагами, установленными в 0.

Ожидается, что эта функция будет использоваться для сигнализации perl о том, что этот SV собирается быть записанным, и все дополнительные ведения должны быть выполнены. Поэтому она выдаёт ошибку для значений только для чтения.

void    sv_force_normal_flags(SV *const sv,
                              const U32 flags)

sv_free

Уменьшает счётчик ссылок SV, и если он падает до нуля, вызывает sv_clear для вызова деструкторов и освобождения любой памяти, используемой телом; в конце концов, освобождает сам заголовок SV. Обычно вызывается через макрос-обёртку SvREFCNT_dec.

void    sv_free(SV *const sv)

SvGAMAGIC

Возвращает true, если SV имеет get магию или перегрузку. Если хотя бы одно из них верно, то скаляр является активными данными и может возвращать новое значение каждый раз при обращении. Поэтому необходимо быть осторожным, чтобы читать его только один раз за логическую операцию пользователя и работать с этим возвращённым значением. Если ни то, ни другое не верно, значение скаляра не может измениться, пока ему не будет присвоено новое значение.

U32     SvGAMAGIC(SV* sv)

sv_gets

Получить строку из файлового дескриптора и сохранить её в SV, необязательно добавляя к текущей сохранённой строке. Если append не равно 0, строка добавляется к SV вместо перезаписи. append должно быть установлено на смещение байта, с которого должна начинаться добавленная строка в SV (как правило, SvCUR(sv) является подходящим выбором).

char*   sv_gets(SV *const sv, PerlIO *const fp,
                I32 append)

sv_get_backrefs

Если sv является целью слабого указателя, то возвращает структуру обратных ссылок, связанную с sv; в противном случае возвращает NULL.

При возвращении ненулевого результата тип возвращаемого значения имеет значение. Если это AV, то элементы AV являются слабыми ссылками RV, которые указывают на этот элемент. Если это любой другой тип, то сам элемент является слабой ссылкой.

См. также Perl_sv_add_backref(), Perl_sv_del_backref(), Perl_sv_kill_backrefs()

SV*     sv_get_backrefs(SV *const sv)

SvGROW

Расширяет буфер символов в SV, чтобы он мог вместить указанное количество байтов (не забудьте зарезервировать место для дополнительного заключительного символа NUL). Вызывает sv_grow для выполнения расширения при необходимости. Возвращает указатель на буфер символов. SV должен быть типа >= SVt_PV. Альтернативой является вызов sv_grow если тип SV неизвестен.

Возможно, вы ошибочно думаете, что len — это количество байтов, которые нужно добавить к текущему размеру, но на самом деле это — общий размер, которым должен быть sv.

char *  SvGROW(SV* sv, STRLEN len)

sv_grow

Расширяет буфер символов в SV. При необходимости использует sv_unref и повышает SV до SVt_PV. Возвращает указатель на буфер символов. Используйте обёртку SvGROW вместо этого.

char*   sv_grow(SV *const sv, STRLEN newlen)

sv_inc

Автоматическое увеличение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает магию 'get' и перегрузку операторов.

void    sv_inc(SV *const sv)

sv_inc_nomg

Автоматическое увеличение значения в SV, выполняя преобразование строки в число при необходимости. Обрабатывает перегрузку операторов. Пропускает обработку 'get' магии.

void    sv_inc_nomg(SV *const sv)

sv_insert

Вставляет и/или заменяет строку по указанному смещению/длине в SV. Похожа на Perl-функцию substr(), где littlelen байтов, начиная с little, заменяют len байтов строки в bigstr, начиная с offset. Обрабатывает get магию.

void    sv_insert(SV *const bigstr, const STRLEN offset,
                  const STRLEN len,
                  const char *const little,
                  const STRLEN littlelen)

sv_insert_flags

То же, что и sv_insert, но дополнительные flags передаются функции SvPV_force_flags, которая применяется к bigstr.

void    sv_insert_flags(SV *const bigstr,
                        const STRLEN offset,
                        const STRLEN len,
                        const char *little,
                        const STRLEN littlelen,
                        const U32 flags)

SvIOK

Возвращает значение U32, указывающее, содержит ли SV целое число.

U32     SvIOK(SV* sv)

SvIOK_notUV

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

bool    SvIOK_notUV(SV* sv)

SvIOK_off

Сбрасывает статус IV SV.

void    SvIOK_off(SV* sv)

SvIOK_on

Указывает SV, что это целое число.

void    SvIOK_on(SV* sv)

SvIOK_only

Указывает SV, что это целое число, и отключает все другие OK биты.

void    SvIOK_only(SV* sv)

SvIOK_only_UV

Указывает SV, что это беззнаковое целое число, и отключает все другие OK биты.

void    SvIOK_only_UV(SV* sv)

SvIOKp

Возвращает значение U32, указывающее, содержит ли SV целое число. Проверяет частное значение. Используйте SvIOK вместо этого.

U32     SvIOKp(SV* sv)

SvIOK_UV

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно интерпретироваться как беззнаковое. Беззнаковое целое число, чьё значение находится в пределах диапазона как IV, так и UV, может быть помечено либо SvUOK или SvIOK.

bool    SvIOK_UV(SV* sv)

END_OF_DOCUMENT_MARKER

sv_isa

Возвращает булево значение, указывающее, благословен ли SV в указанный класс.

Это не проверяет подтипы или перегрузку методов. Используйте sv_isa_sv для проверки отношения наследования так же, как оператор isa, учитывая любую перегрузку метода isa(); или sv_derived_from_sv для прямой проверки фактического типа объекта.

int     sv_isa(SV* sv, const char *const name)

sv_isa_sv

Возвращает булево значение, указывающее, является ли SV ссылкой на объект и происходит ли он от указанного класса, учитывая любую перегрузку метода isa().

Возвращает false, если sv не является ссылкой на объект или не происходит от указанного класса.

Эта функция используется для реализации поведения оператора isa.

Не вызывает магию над sv.

Не путать со старой функцией sv_isa, которая не использует перегруженный метод isa(), и не проверяет наследование от подклассов.

bool    sv_isa_sv(SV* sv, SV* namesv)

SvIsCOW

Возвращает значение U32, указывающее, является ли SV Copy-On-Write (либо общий ключ хэша скаляр, либо полный скаляр Copy On Write, если 5.9.0 настроен для COW).

U32     SvIsCOW(SV* sv)

SvIsCOW_shared_hash

Возвращает булево значение, указывающее, является ли SV Copy-On-Write общим скаляром-ключом хэша.

bool    SvIsCOW_shared_hash(SV* sv)

sv_isobject

Возвращает булево значение, указывающее, является ли SV RV, указывающим на благословенный объект. Если SV не является RV, или объект не благословен, то возвращается false.

int     sv_isobject(SV* sv)

SvIV

Приводит данный SV к типу IV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте IV sv, но не во всех. (Используйте "sv_setiv" для того, чтобы это гарантировать).

См. "SvIVx", для версии, которая гарантирует, что sv будет вычислено только один раз.

IV      SvIV(SV* sv)

SvIV_nomg

Как SvIV, но не обрабатывает магию.

IV      SvIV_nomg(SV* sv)

SvIV_set

Устанавливает значение указателя IV в sv в значение val. Можно выполнить ту же функцию, что и эта макрос, с присваиванием значения lvalue к SvIVX. Однако, в будущих версиях Perl будет более эффективным использовать SvIV_set вместо присваивания lvalue к SvIVX.

void    SvIV_set(SV* sv, IV val)

SvIVX

Возвращает исходное значение в слоте IV SV без проверок и преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvIV".

IV      SvIVX(SV* sv)

SvIVx

Эта форма гарантирует, что sv будет вычислено только один раз. Используйте только в том случае, если sv это выражение с побочными эффектами, в противном случае используйте более эффективную функцию SvIV.

IV      SvIVx(SV* sv)

SvLEN

Возвращает размер буфера строки в SV, не включая часть, приписываемую SvOOK. См. "SvCUR".

STRLEN  SvLEN(SV* sv)

sv_len

Возвращает длину строки в SV. Обрабатывает магию и приведение типов и устанавливает флаг UTF8 соответствующим образом. См. также "SvCUR", которая предоставляет прямой доступ к слоту xpv_cur.

STRLEN  sv_len(SV *const sv)

SvLEN_set

Устанавливает размер буфера строки для SV. См. "SvLEN".

void    SvLEN_set(SV* sv, STRLEN len)

sv_len_utf8

Возвращает количество символов в строке в SV, считая широкие байты UTF-8 как один символ. Обрабатывает магию и приведение типов.

STRLEN  sv_len_utf8(SV *const sv)

sv_magic

Добавляет магию к SV. Сначала повышает sv до типа SVt_PVMG при необходимости, затем добавляет новый элемент магии типа how в начало списка магии.

См. "sv_magicext" (которую теперь вызывает sv_magic) для описания обработки аргументов name и namlen.

Необходимо использовать sv_magicext для добавления магии к SvREADONLY SV и для добавления более одного экземпляра той же how.

void    sv_magic(SV *const sv, SV *const obj,
                 const int how, const char *const name,
                 const I32 namlen)

sv_magicext

Добавляет магию к SV, повышая его при необходимости. Применяет предоставленный vtable и возвращает указатель на добавленную магию.

Обратите внимание, что sv_magicext позволит вещи, которые sv_magic не позволит. В частности, вы можете добавить магию к SvREADONLY SV и добавить больше одного экземпляра той же how.

Если namlen больше нуля, то savepvn копия name хранится, если namlen равно нулю, то name хранится как есть, и - как другой особый случай - если (name && namlen == HEf_SVKEY), то name предполагается содержать SV* и хранится как есть с увеличенным REFCNT.

(Теперь используется как подпрограмма sv_magic.)

MAGIC * sv_magicext(SV *const sv, SV *const obj,
                    const int how,
                    const MGVTBL *const vtbl,
                    const char *const name,
                    const I32 namlen)

SvMAGIC_set

Установите значение указателя MAGIC в sv в значение val. См. "SvIV_set".

void    SvMAGIC_set(SV* sv, MAGIC* val)

sv_mortalcopy

Создает новый SV, который является копией исходного SV (используя sv_setsv). Новый SV помечен как смертный. Он будет уничтожен «скоро», либо явным вызовом FREETMPS, либо неявным вызовом в точках, таких как границы операторов. См. также "sv_newmortal" и "sv_2mortal".

SV*     sv_mortalcopy(SV *const oldsv)

sv_mortalcopy_flags

Как sv_mortalcopy, но дополнительные flags передаются в sv_setsv_flags.

SV*     sv_mortalcopy_flags(SV *const oldsv, U32 flags)

sv_newmortal

Создает новый нулевой SV, который является смертным. Счетчик ссылок SV установлен в 1. Он будет уничтожен «скоро», либо явным вызовом FREETMPS, либо неявным вызовом в местах, таких как границы операторов. См. также "sv_mortalcopy" и "sv_2mortal".

SV*     sv_newmortal()

sv_newref

Увеличивает счетчик ссылок SV. Используйте оберточную функцию SvREFCNT_inc() вместо нее.

SV*     sv_newref(SV *const sv)

SvNIOK

Возвращает значение U32, указывающее, содержит ли SV число, целое или двойное значение.

U32     SvNIOK(SV* sv)

SvNIOK_off

Сбрасывает состояние NV/IV SV.

void    SvNIOK_off(SV* sv)

SvNIOKp

Возвращает значение U32, указывающее, содержит ли SV число, целое или двойное значение. Проверяет частное значение. Используйте SvNIOK вместо него.

U32     SvNIOKp(SV* sv)

SvNOK

Возвращает значение U32, указывающее, содержит ли SV двойное значение.

U32     SvNOK(SV* sv)

SvNOK_off

Сбрасывает состояние NV SV.

void    SvNOK_off(SV* sv)

SvNOK_on

Указывает SV, что это двойное значение.

void    SvNOK_on(SV* sv)

SvNOK_only

Указывает SV, что это двойное значение, и отключает все остальные биты OK.

void    SvNOK_only(SV* sv)

SvNOKp

Возвращает значение U32, указывающее, содержит ли SV двойное значение. Проверяет частное значение. Используйте SvNOK вместо него.

U32     SvNOKp(SV* sv)

SvNV

Приводит данный SV к типу NV и возвращает его. Возвращаемое значение во многих случаях будет сохранено в слоте NV sv, но не во всех. (Используйте "sv_setnv" для того, чтобы это гарантировать).

См. "SvNVx", для версии, которая гарантирует, что sv будет вычислено только один раз.

NV      SvNV(SV* sv)

SvNV_nomg

Как SvNV, но не обрабатывает магию.

NV      SvNV_nomg(SV* sv)

SvNV_set

Установите значение указателя NV в sv в значение val. См. "SvIV_set".

void    SvNV_set(SV* sv, NV val)

SvNVX

Возвращает исходное значение в слоте NV SV без проверок и преобразований. Используйте только когда уверены, что SvNOK истинно. См. также "SvNV".

NV      SvNVX(SV* sv)

SvNVx

NV      SvNVx(SV* sv)

SvOK

Возвращает значение U32, указывающее, определено ли значение. Это имеет смысл только для скаляров.

U32     SvOK(SV* sv)

SvOOK

Возвращает U32, указывающее, смещен ли указатель на буфер строки. Этот хак используется внутри для ускорения удаления символов из начала SvPV. Когда SvOOK истинно, начало выделенного буфера строки фактически SvOOK_offset() байтов перед SvPVX.

Этот смещение раньше хранился в SvIVX, но теперь хранится внутри свободного места буфера.

U32     SvOOK(SV* sv)

SvOOK_offset

Считывает в len смещение от SvPVX до истинного начала выделенного буфера, которое будет не нулевым, если sv_chop использовался для эффективного удаления символов из начала буфера. Реализован как макрос, принимающий адрес len, который должен быть типа STRLEN. Вычисляет sv более одного раза. Устанавливает len в 0, если SvOOK(sv) ложно.

void    SvOOK_offset(SV*sv, STRLEN len)

SvPOK

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

U32     SvPOK(SV* sv)

SvPOK_off

Сбрасывает состояние PV SV.

void    SvPOK_off(SV* sv)

SvPOK_on

Сообщает SV, что это строка.

void    SvPOK_on(SV* sv)

SvPOK_only

Сообщает SV, что это строка и отключает все другие OK биты. Также отключит статус UTF-8.

void    SvPOK_only(SV* sv)

SvPOK_only_UTF8

Сообщает SV, что это строка и отключает все другие OK биты, а статус UTF-8 оставит прежним.

void    SvPOK_only_UTF8(SV* sv)

SvPOKp

Возвращает значение U32, указывающее, содержит ли SV строку. Проверяет SvPOK настройку. Используйте SvPOK вместо этого.

U32     SvPOKp(SV* sv)

sv_pos_b2u

Преобразует значение, на которое указывает offsetp, из количества байтов от начала строки в количество эквивалентных символов UTF-8. Обрабатывает магию и приведение типов.

Используйте sv_pos_b2u_flags, что правильно обрабатывает строки длиннее 2 Гб.

void    sv_pos_b2u(SV *const sv, I32 *const offsetp)

sv_pos_b2u_flags

Преобразует offset из количества байтов от начала строки в количество эквивалентных символов UTF-8. Обрабатывает приведение типов. flags передаётся в SvPV_flags, и обычно должно быть SV_GMAGIC|SV_CONST_RETURN, чтобы обработать магию.

STRLEN  sv_pos_b2u_flags(SV *const sv,
                         STRLEN const offset, U32 flags)

sv_pos_u2b

Преобразует значение, на которое указывает offsetp, из количества символов UTF-8 от начала строки в количество эквивалентных байтов; если lenp не равно нулю, выполняет то же самое для lenp, но на этот раз начиная со смещения, а не с начала строки. Обрабатывает магию и приведение типов.

Используйте sv_pos_u2b_flags вместо этого, что правильно обрабатывает строки длиннее 2 Гб.

void    sv_pos_u2b(SV *const sv, I32 *const offsetp,
                   I32 *const lenp)

sv_pos_u2b_flags

Преобразует смещение из количества символов UTF-8 от начала строки в количество эквивалентных байтов; если lenp не равно нулю, выполняет то же самое для lenp, но на этот раз начиная со смещения offset, а не с начала строки. Обрабатывает приведение типов. flags передаётся в SvPV_flags, и обычно должно быть SV_GMAGIC|SV_CONST_RETURN, чтобы обработать магию.

STRLEN  sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
                         STRLEN *const lenp, U32 flags)

SvPV

Возвращает указатель на строку в SV или строковое представление SV, если SV не содержит строку. SV может кэшировать строковое представление, становясь SvPOK. Обрабатывает магию «get». Переменная len будет установлена в длину строки (это макрос, поэтому не используйте &len). Также см. "SvPVx" для версии, гарантирующей, что sv будет вычислено только один раз.

Обратите внимание, что нет гарантии, что возвращаемое значение SvPV() равно SvPVX(sv), или что SvPVX(sv) содержит действительные данные, или что последовательные вызовы SvPV(sv) будут возвращать каждый раз одно и то же значение указателя. Это связано с тем, как обрабатываются такие вещи, как перегрузка и Copy-On-Write. В этих случаях возвращаемое значение может указывать на временный буфер или что-то подобное. Если вам абсолютно необходимо, чтобы поле SvPVX было действительным (например, если вы собираетесь в него записывать), см. "SvPV_force".

char*   SvPV(SV* sv, STRLEN len)

SvPVbyte

Как SvPV, но преобразует sv в байтовое представление, если это необходимо. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   SvPVbyte(SV* sv, STRLEN len)

SvPVbyte_force

Как SvPV_force, но преобразует sv в байтовое представление, если это необходимо. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   SvPVbyte_force(SV* sv, STRLEN len)

SvPVbyte_nolen

Как SvPV_nolen, но преобразует sv в байтовое представление, если это необходимо. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   SvPVbyte_nolen(SV* sv)

SvPVbyte_nomg

Как SvPVbyte, но не обрабатывает магию «get».

char*   SvPVbyte_nomg(SV* sv, STRLEN len)

sv_pvbyten_force

Бэкенд для макроса SvPVbytex_force. Всегда используйте макрос вместо него. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   sv_pvbyten_force(SV *const sv, STRLEN *const lp)

SvPVbyte_or_null

Как SvPVbyte, но когда sv не определено, возвращает NULL.

char*   SvPVbyte_or_null(SV* sv, STRLEN len)

SvPVbyte_or_null_nomg

Как SvPVbyte_or_null, но не обрабатывает магию «get».

char*   SvPVbyte_or_null_nomg(SV* sv, STRLEN len)

SvPVbytex

Как SvPV, но преобразует sv в байтовое представление, если это необходимо. Гарантирует, что sv будет вычислено только один раз; используйте более эффективный SvPVbyte в противном случае. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   SvPVbytex(SV* sv, STRLEN len)

SvPVbytex_force

Как SvPV_force, но преобразует sv в байтовое представление, если это необходимо. Гарантирует, что sv будет вычислено только один раз; используйте более эффективный SvPVbyte_force в противном случае. Если SV нельзя преобразовать из UTF-8, происходит ошибка.

char*   SvPVbytex_force(SV* sv, STRLEN len)

SvPVCLEAR

Обеспечивает, что sv является SVt_PV, что его SvCUR равен 0 и что он правильно завершен нулём. Эквивалентно sv_setpvs(""), но более эффективно.

char *  SvPVCLEAR(SV* sv)

SvPV_force

Как SvPV, но принудительно заставит SV содержать строку (SvPOK) и только строку (SvPOK_only) любым способом. Вам нужна принудительная установка, если вы собираетесь обновлять SvPVX напрямую. Обрабатывает магию «get».

Обратите внимание, что принудительное преобразование произвольного скаляра в обычный PV может привести к удалению полезных данных из него. Например, если SV был SvROK, то ссылка будет иметь свой счётчик ссылок уменьшен, а сам SV может быть преобразован в скаляр SvPOK со строковым буфером, содержащим значение, например, "ARRAY(0x1234)".

char*   SvPV_force(SV* sv, STRLEN len)

SvPV_force_nomg

Как SvPV_force, но не обрабатывает магию «get».

char*   SvPV_force_nomg(SV* sv, STRLEN len)

SvPV_nolen

Как SvPV, но не устанавливает переменную длины.

char*   SvPV_nolen(SV* sv)

SvPV_nomg

Как SvPV, но не обрабатывает магию.

char*   SvPV_nomg(SV* sv, STRLEN len)

SvPV_nomg_nolen

Как SvPV_nolen, но не обрабатывает магию.

char*   SvPV_nomg_nolen(SV* sv)

sv_pvn_force

Получить осмысленную строку из SV каким-либо способом. Частное реализация макроса SvPV_force для компиляторов, которые не могут справиться со сложными выражениями макроса. Всегда используйте макрос вместо него.

char*   sv_pvn_force(SV* sv, STRLEN* lp)

sv_pvn_force_flags

Получить осмысленную строку из SV каким-либо способом. Если у flags установлен бит SV_GMAGIC, выполнит mg_get для sv, если это уместно, иначе - нет. sv_pvn_force и sv_pvn_force_nomg реализованы в терминах этой функции. Обычно вы хотите использовать различные макросы-обёртки: см. "SvPV_force" и "SvPV_force_nomg".

char*   sv_pvn_force_flags(SV *const sv,
                           STRLEN *const lp,
                           const I32 flags)

SvPV_set

Вероятно, этого не нужно использовать, скорее всего, вам нужны "sv_usepvn_flags", "sv_setpvn" или "sv_setpvs".

Установите значение указателя PV в sv для NUL-завершённой строки val, выделенной Perl. Также см. "SvIV_set".

Не забудьте освободить предыдущий буфер PV. Есть много вещей, которые нужно проверить. Будьте осторожны, что существующий указатель может быть вовлечён в copy-on-write или другую неисправность, поэтому сделайте SvOOK_off(sv) и используйте sv_force_normal или SvPV_force (или проверьте флаг SvIsCOW) сначала, чтобы убедиться, что это изменение безопасно. Затем, наконец, если это не COW, вызовите SvPV_free для освобождения предыдущего буфера PV.

void    SvPV_set(SV* sv, char* val)

SvPVutf8

Как SvPV, но преобразует sv в UTF-8, если это необходимо.

char*   SvPVutf8(SV* sv, STRLEN len)

sv_pvutf8n_force

Бэкенд для макроса SvPVutf8x_force. Всегда используйте макрос вместо него.

char*   sv_pvutf8n_force(SV *const sv, STRLEN *const lp)

SvPVutf8x

Как SvPV, но преобразует sv в UTF-8, если это необходимо. Гарантирует, что sv будет вычислено только один раз; используйте более эффективный SvPVutf8 в противном случае.

char*   SvPVutf8x(SV* sv, STRLEN len)

SvPVutf8x_force

Как SvPV_force, но преобразует sv в UTF-8, если это необходимо. Гарантирует, что sv будет вычислено только один раз; используйте более эффективный SvPVutf8_force в противном случае.

char*   SvPVutf8x_force(SV* sv, STRLEN len)

SvPVutf8_force

Как SvPV_force, но преобразует sv в UTF-8, если это необходимо.

char*   SvPVutf8_force(SV* sv, STRLEN len)

SvPVutf8_nolen

Как SvPV_nolen, но преобразует sv в UTF-8, если это необходимо.

char*   SvPVutf8_nolen(SV* sv)

SvPVutf8_nomg

Как SvPVutf8, но не обрабатывает магию «get».

char*   SvPVutf8_nomg(SV* sv, STRLEN len)

SvPVutf8_or_null

Как SvPVutf8, но когда sv не определено, возвращает NULL.

char*   SvPVutf8_or_null(SV* sv, STRLEN len)

SvPVutf8_or_null_nomg

Как SvPVutf8_or_null, но не обрабатывает магию «get».

char*   SvPVutf8_or_null_nomg(SV* sv, STRLEN len)

SvPVX

Возвращает указатель на физическую строку в SV. SV должен содержать строку. До версии 5.9.3 использование этого макроса небезопасно, если тип SV >= SVt_PV.

Также используется для хранения имени загруженной по запросу подпрограммы в XS AUTOLOAD процедуре. См. "Автозагрузка с XSUB" в perlguts.

char*   SvPVX(SV* sv)

SvPVx

Версия SvPV, гарантирующая оценку sv только один раз. Используйте только в том случае, если sv — выражение со побочными эффектами, в противном случае используйте более эффективную SvPV.

char*   SvPVx(SV* sv, STRLEN len)

SvREADONLY

Возвращает true, если аргумент является только для чтения, иначе возвращает false. Доступно коду Perl через Internals::SvREADONLY().

U32     SvREADONLY(SV* sv)

SvREADONLY_off

Отметить объект как не-только для чтения. Точное значение зависит от типа объекта. Доступно коду Perl через Internals::SvREADONLY().

U32     SvREADONLY_off(SV* sv)

SvREADONLY_on

Отметить объект как только для чтения. Точное значение зависит от типа объекта. Доступно коду Perl через Internals::SvREADONLY().

U32     SvREADONLY_on(SV* sv)

sv_ref

Возвращает SV, описывающий, к чему относится переданный SV.

dst может быть SV, который будет установлен в описание, или NULL, в этом случае возвращается смертный SV.

Если ob равно true и SV освящён, описанием является имя класса, в противном случае — тип SV, "SCALAR", "ARRAY" и т.д.

SV*     sv_ref(SV *dst, const SV *const sv,
               const int ob)

SvREFCNT

Возвращает значение счётчика ссылок объекта. Доступно коду Perl через Internals::SvREFCNT().

U32     SvREFCNT(SV* sv)

SvREFCNT_dec

Уменьшает счётчик ссылок данного SV. sv может быть NULL.

void    SvREFCNT_dec(SV *sv)

SvREFCNT_dec_NN

То же, что и SvREFCNT_dec, но может использоваться только если известно, что sv не NULL. Поскольку проверка на NULL не требуется, она быстрее и меньше.

void    SvREFCNT_dec_NN(SV *sv)

SvREFCNT_inc

Увеличивает счётчик ссылок данного SV, возвращая SV.

Все следующие SvREFCNT_inc* являются оптимизированными версиями SvREFCNT_inc, и могут быть заменены на SvREFCNT_inc.

SV *    SvREFCNT_inc(SV *sv)

SvREFCNT_inc_NN

То же, что и SvREFCNT_inc, но может использоваться только если известно, что sv не NULL. Поскольку проверка на NULL не требуется, она быстрее и меньше.

SV *    SvREFCNT_inc_NN(SV *sv)

SvREFCNT_inc_simple

То же, что и SvREFCNT_inc, но может использоваться только с выражениями без побочных эффектов. Поскольку нам не нужно хранить временное значение, она быстрее.

SV*     SvREFCNT_inc_simple(SV* sv)

SvREFCNT_inc_simple_NN

То же, что и SvREFCNT_inc_simple, но может использоваться только если известно, что sv не NULL. Поскольку проверка на NULL не требуется, она быстрее и меньше.

SV*     SvREFCNT_inc_simple_NN(SV* sv)

SvREFCNT_inc_simple_void

То же, что и SvREFCNT_inc_simple, но может использоваться только если вам не нужно значение возврата. Макрос не должен возвращать осмысленное значение.

void    SvREFCNT_inc_simple_void(SV* sv)

SvREFCNT_inc_simple_void_NN

То же, что и SvREFCNT_inc, но может использоваться только если вам не нужно значение возврата, и вы знаете, что sv не NULL. Макрос не должен возвращать осмысленное значение или проверять на NULL, поэтому он меньше и быстрее.

void    SvREFCNT_inc_simple_void_NN(SV* sv)

SvREFCNT_inc_void

То же, что и SvREFCNT_inc, но может использоваться только если вам не нужно значение возврата. Макрос не должен возвращать осмысленное значение.

void    SvREFCNT_inc_void(SV *sv)

SvREFCNT_inc_void_NN

void    SvREFCNT_inc_void_NN(SV* sv)

sv_reftype

Возвращает строку, описывающую, к чему относится SV.

Если ob равно true и SV освящён, строкой является имя класса, в противном случае — тип SV, "SCALAR", "ARRAY" и т.д.

const char* sv_reftype(const SV *const sv, const int ob)

sv_replace

Создаёт копию второго аргумента для первого, затем удаляет оригинал. Целевой SV физически принимает на себя владение телом исходного SV и наследует его флаги; однако, целевой SV сохраняет все имеющиеся у него магии, и любые магии в исходном SV отбрасываются. Обратите внимание, что это довольно специализированная операция копирования SV; в большинстве случаев вы захотите использовать sv_setsv или один из его многочисленных макросов-фронтов.

void    sv_replace(SV *const sv, SV *const nsv)

sv_report_used

Выводит содержимое всех SV, которые ещё не освобождены (помощник отладки).

void    sv_report_used()

sv_reset

Реализация подпрограммы reset функции Perl. Обратите внимание, что функция на уровне Perl слабо устарела.

void    sv_reset(const char* s, HV *const stash)

SvROK

Проверяет, является ли SV RV.

U32     SvROK(SV* sv)

SvROK_off

Снимает статус RV у SV.

void    SvROK_off(SV* sv)

SvROK_on

Указывает SV, что он является RV.

void    SvROK_on(SV* sv)

SvRV

Разыменовывает RV, чтобы вернуть SV.

SV*     SvRV(SV* sv)

SvRV_set

Устанавливает значение указателя RV в sv на val. См. "SvIV_set".

void    SvRV_set(SV* sv, SV* val)

sv_rvunweaken

Убирает ослабление ссылки: Очищает флаг SvWEAKREF для этого RV; удаляет обратную ссылку на этот RV из массива обратных ссылок, связанных с целевым SV, увеличивает счётчик ссылок целевого объекта. Бездействует при undef и предупреждает об отсутствии слабых ссылок.

SV*     sv_rvunweaken(SV *const sv)

sv_rvweaken

Ослабление ссылки: устанавливает флаг SvWEAKREF для этого RV; присваивает целевому SV PERL_MAGIC_backref магию, если она ещё не установлена; и добавляет обратную ссылку на этот RV в массив обратных ссылок, связанных с этой магией. Если RV магический, вызов set magic произойдёт после очистки RV. Бездействует при undef и предупреждает об уже существующих слабых ссылках.

SV*     sv_rvweaken(SV *const sv)

sv_setiv

Копирует целое число в данный SV, сначала производя апгрейд, если необходимо. Не обрабатывает магию "set". См. также "sv_setiv_mg".

void    sv_setiv(SV *const sv, const IV num)

sv_setiv_mg

Как sv_setiv, но также обрабатывает магию "set".

void    sv_setiv_mg(SV *const sv, const IV i)

sv_setnv

Копирует двойное число в данный SV, сначала производя апгрейд, если необходимо. Не обрабатывает магию "set". См. также "sv_setnv_mg".

void    sv_setnv(SV *const sv, const NV num)

sv_setnv_mg

Как sv_setnv, но также обрабатывает магию "set".

void    sv_setnv_mg(SV *const sv, const NV num)

sv_setpv

Копирует строку в SV. Строка должна заканчиваться символом NUL, и не должна содержать встроенных NUL. Не обрабатывает магию "set". См. "sv_setpv_mg".

void    sv_setpv(SV *const sv, const char *const ptr)

sv_setpvf

Работает как sv_catpvf, но копирует текст в SV вместо добавления его. Не обрабатывает магию "set". См. "sv_setpvf_mg".

void    sv_setpvf(SV *const sv, const char *const pat,
                  ...)

sv_setpvf_mg

Как sv_setpvf, но также обрабатывает магию "set".

void    sv_setpvf_mg(SV *const sv,
                     const char *const pat, ...)

sv_setpviv

УСТАРЕВШАЯ! Планируется удалить эту функцию в будущих версиях Perl. Не используйте в новом коде; удалите из существующего кода.

Копирует целое число в данный SV, обновляя также его строковое значение. Не обрабатывает магию "set". См. "sv_setpviv_mg".

void    sv_setpviv(SV *const sv, const IV num)

sv_setpviv_mg

Как sv_setpviv, но также обрабатывает магию "set".

void    sv_setpviv_mg(SV *const sv, const IV iv)

sv_setpvn

Копирует строку (возможно, содержащую вложенные символы NUL ) в SV. Параметр len указывает количество байтов для копирования. Если аргумент ptr равен NULL, SV станет неопределённым. Не обрабатывает магию "set". См. "sv_setpvn_mg".

Флаг UTF-8 этой функцией не изменяется. Гарантируется завершающий нулевой байт.

void    sv_setpvn(SV *const sv, const char *const ptr,
                  const STRLEN len)

sv_setpvn_mg

Как sv_setpvn, но также обрабатывает магию "set".

void    sv_setpvn_mg(SV *const sv,
                     const char *const ptr,
                     const STRLEN len)

sv_setpvs

Как sv_setpvn, но принимает литеральную строку вместо пары строка/длина.

void    sv_setpvs(SV* sv, "literal string")

sv_setpvs_mg

Как sv_setpvn_mg, но принимает литеральную строку вместо пары строка/длина.

void    sv_setpvs_mg(SV* sv, "literal string")

sv_setpv_bufsize

Устанавливает SV как строку длиной cur байтов, с по крайней мере len байтами доступными. Обеспечивает наличие нулевого байта в SvEND. Возвращает указатель char * на буфер SvPV.

char  * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
                         const STRLEN len)

sv_setpv_mg

Как sv_setpv, но также обрабатывает магию "set".

void    sv_setpv_mg(SV *const sv, const char *const ptr)

sv_setref_iv

Копирует целое число в новый SV, необязательно освящая SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для освящения. Установите classname в NULL, чтобы избежать освящения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_iv(SV *const rv,
                     const char *const classname,
                     const IV iv)

sv_setref_nv

Копирует двойное число в новый SV, необязательно освящая SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для освящения. Установите classname в NULL, чтобы избежать освящения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_nv(SV *const rv,
                     const char *const classname,
                     const NV nv)

sv_setref_pv

Копирует указатель в новый SV, необязательно благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Если аргумент pv равен NULL, то PL_sv_undef будет помещено в SV. Аргумент classname указывает пакет для благословения. Установите classname в значение NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

Не используйте с другими типами Perl, такими как HV, AV, SV, CV, потому что эти объекты будут повреждены процессом копирования указателя.

Обратите внимание, что sv_setref_pvn копирует строку, в то время как это копирует указатель.

SV*     sv_setref_pv(SV *const rv,
                     const char *const classname,
                     void *const pv)

sv_setref_pvn

Копирует строку в новый SV, необязательно благословляя SV. Длина строки должна быть указана с помощью n. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в значение NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

Обратите внимание, что sv_setref_pv копирует указатель, в то время как это копирует строку.

SV*     sv_setref_pvn(SV *const rv,
                      const char *const classname,
                      const char *const pv,
                      const STRLEN n)

sv_setref_pvs

Аналогично sv_setref_pvn, но принимает литеральную строку вместо пары строка/длина.

SV *    sv_setref_pvs(SV *const rv,
                      const char *const classname,
                      "literal string")

sv_setref_uv

Копирует целое беззнаковое число в новый SV, необязательно благословляя SV. Аргумент rv будет преобразован в RV. Этот RV будет изменён для указания на новый SV. Аргумент classname указывает пакет для благословения. Установите classname в значение NULL, чтобы избежать благословения. Новый SV будет иметь счётчик ссылок 1, и RV будет возвращён.

SV*     sv_setref_uv(SV *const rv,
                     const char *const classname,
                     const UV uv)

sv_setsv

Копирует содержимое исходного SV ssv в целевой SV dsv. Исходный SV может быть уничтожен, если он смертный, поэтому не используйте эту функцию, если исходный SV нужно повторно использовать. Не обрабатывает магию "set" для целевого SV. Вызывает магию "get" для исходного SV. Грубо говоря, выполняет копирование по значению, уничтожая предыдущее содержимое назначения.

Вероятно, вам нужно использовать один из наборов обёртки, таких как SvSetSV, SvSetSV_nosteal, SvSetMagicSV и SvSetMagicSV_nosteal.

void    sv_setsv(SV *dstr, SV *sstr)

sv_setsv_flags

Копирует содержимое исходного SV ssv в целевой SV dsv. Исходный SV может быть уничтожен, если он смертный, поэтому не используйте эту функцию, если исходный SV нужно повторно использовать. Не обрабатывает магию "set". Грубо говоря, выполняет копирование по значению, уничтожая предыдущее содержимое назначения. Если параметр flags имеет установленный бит SV_GMAGIC, то будет mg_get для ssv, в противном случае нет. Если параметр flags имеет установленный бит SV_NOSTEAL, то буферы временных переменных не будут украдены. sv_setsv и sv_setsv_nomg реализованы с использованием этой функции.

Вероятно, вам нужно использовать один из наборов обёртки, таких как SvSetSV, SvSetSV_nosteal, SvSetMagicSV и SvSetMagicSV_nosteal.

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

void    sv_setsv_flags(SV *dstr, SV *sstr,
                       const I32 flags)

sv_setsv_mg

Аналогично sv_setsv, но также обрабатывает магию "set".

void    sv_setsv_mg(SV *const dstr, SV *const sstr)

sv_setsv_nomg

Аналогично sv_setsv, но не обрабатывает магию.

void    sv_setsv_nomg(SV* dsv, SV* ssv)

sv_setuv

Копирует целое беззнаковое число в данный SV, предварительно выполняя преобразование, если необходимо. Не обрабатывает магию "set". См. также "sv_setuv_mg".

void    sv_setuv(SV *const sv, const UV num)

sv_setuv_mg

Аналогично sv_setuv, но также обрабатывает магию "set".

void    sv_setuv_mg(SV *const sv, const UV u)

sv_set_undef

Эквивалентно sv_setsv(sv, &PL_sv_undef), но более эффективно. Не обрабатывает магию "set".

Аналог в Perl - $sv = undef;. Обратите внимание, что он не освобождает буфер строки, в отличие от undef $sv.

Введено в Perl 5.25.12.

void    sv_set_undef(SV *sv)

SvSTASH

Возвращает stash SV.

HV*     SvSTASH(SV* sv)

SvSTASH_set

Устанавливает значение указателя STASH в sv на val. См. "SvIV_set".

void    SvSTASH_set(SV* sv, HV* val)

SvTAINT

Помечает SV как повреждённый, если включено помечание и если какой-либо вход в текущее выражение помечен как повреждённый — обычно переменная, но также и явные входные данные, такие как настройки локалей. SvTAINT распространяет эту повреждённость на выходы выражения пессимистическим образом; т.е. без учёта того, какие выходы влияют на какие входные данные.

void    SvTAINT(SV* sv)

SvTAINTED

Проверяет, помечен ли SV как повреждённый. Возвращает TRUE, если помечен, FALSE — в противном случае.

bool    SvTAINTED(SV* sv)

sv_tainted

Проверяет SV на наличие повреждённости. Используйте SvTAINTED вместо этого.

bool    sv_tainted(SV *const sv)

SvTAINTED_off

Снимает пометку "повреждён" с SV. Будьте очень осторожны с этой процедурой, так как она обходит некоторые фундаментальные функции безопасности Perl. Авторы модулей XS не должны использовать эту функцию, если они не полностью понимают все последствия безусловного снятия метки "повреждён" со значения. Снятие метки "повреждён" должно выполняться стандартным способом Perl, с помощью тщательно составленного регулярного выражения, а не непосредственным снятием метки с переменных.

void    SvTAINTED_off(SV* sv)

SvTAINTED_on

Помечает SV как повреждённый, если включено помечание.

void    SvTAINTED_on(SV* sv)

SvTRUE

Возвращает булево значение, указывающее, рассматривает ли Perl SV как истинное или ложное. См. "SvOK" для проверки определённого/неопределённого значения. Обрабатывает магию "get", если скаляр не является SvPOK, SvIOK или SvNOK (общедоступные, а не приватные флаги).

См. "SvTRUEx" для версии, которая гарантирует, что sv будет вычислена только один раз.

bool    SvTRUE(SV* sv)

sv_true

Возвращает true, если SV имеет истинное значение по правилам Perl. Используйте макрос SvTRUE вместо этого, который может вызвать sv_true() или использовать встроенную версию.

I32     sv_true(SV *const sv)

SvTRUE_nomg

Возвращает булево значение, указывающее, рассматривает ли Perl SV как истинное или ложное. См. "SvOK" для проверки определённого/неопределённого значения. Не обрабатывает магию "get".

bool    SvTRUE_nomg(SV* sv)

SvTRUEx

Эта форма гарантирует, что sv будет вычислена только один раз. Используйте только в том случае, если sv — это выражение с побочными эффектами, в противном случае используйте более эффективную функцию SvTRUE.

bool    SvTRUEx(SV* sv)

SvTYPE

Возвращает тип SV. См. "svtype".

svtype  SvTYPE(SV* sv)

sv_unmagic

Удаляет всю магию типа type из SV.

int     sv_unmagic(SV *const sv, const int type)

sv_unmagicext

Удаляет всю магию типа type со специфицированным vtbl из SV.

int     sv_unmagicext(SV *const sv, const int type,
                      MGVTBL *vtbl)

sv_unref_flags

Сбрасывает статус RV SV и уменьшает счётчик ссылок того, на что указывает RV. Это почти как обратная функция newSVrv. Аргумент cflags может содержать SV_IMMEDIATE_UNREF, чтобы принудительно уменьшить счётчик ссылок (в противном случае уменьшение выполняется при условии, что счётчик ссылок отличается от единицы или ссылка является читаемым только SV). См. "SvROK_off".

void    sv_unref_flags(SV *const ref, const U32 flags)

sv_untaint

Снять пометку "повреждён" со SV. Используйте SvTAINTED_off вместо этого.

void    sv_untaint(SV *const sv)

SvUOK

Возвращает булево значение, указывающее, содержит ли SV целое число, которое должно интерпретироваться как беззнаковое. Целое неотрицательное число, значение которого находится в диапазоне IV и UV, может быть помечено как SvUOK или SvIOK.

bool    SvUOK(SV* sv)

SvUPGRADE

Используется для повышения SV до более сложной формы. Использует sv_upgrade для выполнения повышения, если необходимо. См. "svtype".

void    SvUPGRADE(SV* sv, svtype type)

sv_upgrade

Повышает SV до более сложной формы. Обычно добавляет новый тип тела к SV, затем копирует как можно больше информации со старого тела. Выдает ошибку, если SV уже имеет более сложную форму, чем запрошенная. Обычно вам нужно использовать обёртку макроса SvUPGRADE, которая проверяет тип перед вызовом sv_upgrade, и поэтому не выдаёт ошибку. См. также "svtype".

void    sv_upgrade(SV *const sv, svtype new_type)

sv_usepvn_flags

Сообщает SV использовать ptr для поиска значения строки. Обычно строка хранится внутри SV, но sv_usepvn позволяет SV использовать внешнюю строку. ptr должен указывать на память, выделенную функцией Newx. Это должно быть начало Newx-блока памяти, а не указатель на середину блока (осторожно с OOK и копированием при записи), и не из не-Newx менеджера памяти, такого как malloc. Длина строки, len, должна быть указана. По умолчанию эта функция Renew (т.е. realloc, перемещение) память, на которую указывает ptr, поэтому указатель не должен освобождаться или использоваться программистом после передачи его sv_usepvn, и не должны использоваться никакие указатели "за" этим указателем (например, ptr + 1).

Если flags & SV_SMAGIC истинно, вызовет SvSETMAGIC. Если flags & SV_HAS_TRAILING_NUL истинно, то ptr[len] должно быть NUL, и realloc будет пропущен (т.е. буфер фактически на 1 байт длиннее, чем len, и уже соответствует требованиям для хранения в SvPVX).

void    sv_usepvn_flags(SV *const sv, char* ptr,
                        const STRLEN len,
                        const U32 flags)

SvUTF8

Возвращает значение U32, указывающее на состояние UTF-8 SV. При правильной настройке это указывает, содержит ли SV данные, закодированные в UTF-8. Вы должны использовать эту функцию после вызова SvPV() или одного из его вариантов, на случай, если любой вызов перегрузки строк обновит внутренний флаг.

Если вы хотите учесть прагму bytes, используйте "DO_UTF8" вместо этого.

U32     SvUTF8(SV* sv)

sv_utf8_decode

Если PV SV является последовательностью байтов в расширенном UTF-8 Perl и содержит многобайтовый символ, то флаг SvUTF8 устанавливается, чтобы он выглядел как символ. Если PV содержит только однобайтовые символы, флаг SvUTF8 остается выключенным. Анализирует PV на корректность и возвращает FALSE, если PV является недопустимым UTF-8.

bool    sv_utf8_decode(SV *const sv)

sv_utf8_downgrade

Попытка преобразовать PV SV из символов в байты. Если PV содержит символ, который не может быть представлен байтом, это преобразование завершится неудачей; в этом случае либо возвращает false, либо, если fail_ok не true, вызывает croak.

Это не универсальный интерфейс кодирования Unicode в байты: используйте расширение Encode для этого.

Эта функция обрабатывает магию получения на sv.

bool    sv_utf8_downgrade(SV *const sv,
                          const bool fail_ok)

sv_utf8_downgrade_flags

Как sv_utf8_downgrade, но с дополнительными flags. Если flags имеет бит SV_GMAGIC, обрабатывает магию получения на sv.

bool    sv_utf8_downgrade_flags(SV *const sv,
                                const bool fail_ok,
                                const U32 flags)

sv_utf8_downgrade_nomg

Как sv_utf8_downgrade, но не обрабатывает магию получения на sv.

bool    sv_utf8_downgrade_nomg(SV *const sv,
                               const bool fail_ok)

sv_utf8_encode

Преобразует PV SV в UTF-8, но затем отключает флаг SvUTF8, чтобы он снова выглядел как байты.

void    sv_utf8_encode(SV *const sv)

sv_utf8_upgrade

Преобразует PV SV в его форму UTF-8. Приводит SV к строковому типу, если это не так. Будет mg_get по sv при необходимости. Всегда устанавливает флаг SvUTF8, чтобы избежать проверки валидности в будущем, даже если вся строка одинакова в UTF-8 и без него. Возвращает количество байтов в преобразованной строке

Это не универсальный интерфейс кодирования байтов в Unicode: используйте расширение Encode для этого.

STRLEN  sv_utf8_upgrade(SV *sv)

sv_utf8_upgrade_flags

Преобразует PV SV в его форму UTF-8. Приводит SV к строковому типу, если это не так. Всегда устанавливает флаг SvUTF8, чтобы избежать будущих проверок валидности, даже если все байты инвариантны в UTF-8. Если flags имеет бит SV_GMAGIC, выполнит mg_get по sv при необходимости, иначе нет.

Флаг SV_FORCE_UTF8_UPGRADE теперь игнорируется.

Возвращает количество байтов в преобразованной строке.

Это не универсальный интерфейс кодирования байтов в Unicode: используйте расширение Encode для этого.

STRLEN  sv_utf8_upgrade_flags(SV *const sv,
                              const I32 flags)

sv_utf8_upgrade_flags_grow

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

sv_utf8_upgrade, sv_utf8_upgrade_nomg, и sv_utf8_upgrade_flags реализованы через эту функцию.

Возвращает количество байтов в преобразованной строке (без учета резервных).

STRLEN  sv_utf8_upgrade_flags_grow(SV *const sv,
                                   const I32 flags,
                                   STRLEN extra)

sv_utf8_upgrade_nomg

Как sv_utf8_upgrade, но не выполняет магию на sv.

STRLEN  sv_utf8_upgrade_nomg(SV *sv)

SvUTF8_off

Сбрасывает состояние UTF-8 SV (данные не меняются, изменяется только флаг). Не используйте легкомысленно.

void    SvUTF8_off(SV *sv)

SvUTF8_on

Включить состояние UTF-8 SV (данные не меняются, изменяется только флаг). Не используйте легкомысленно.

void    SvUTF8_on(SV *sv)

SvUV

Приводит данный SV к типу UV и возвращает его. Возвращаемое значение во многих случаях будет храниться в слоте UV sv, но не во всех случаях. (Используйте "sv_setuv" для того, чтобы убедиться, что это так).

См. "SvUVx" для версии, которая гарантирует, что sv оценивается только один раз.

UV      SvUV(SV* sv)

SvUV_nomg

Как SvUV но не обрабатывает магию.

UV      SvUV_nomg(SV* sv)

SvUV_set

Устанавливает значение указателя UV в sv на значение val. См. "SvIV_set".

void    SvUV_set(SV* sv, UV val)

SvUVX

Возвращает исходное значение в слоте UV SV без проверок или преобразований. Используйте только когда уверены, что SvIOK истинно. См. также "SvUV".

UV      SvUVX(SV* sv)

SvUVx

Этот вариант гарантирует, что sv оценивается только один раз. Используйте этот вариант только если sv - выражение со побочными эффектами, в противном случае используйте более эффективную функцию SvUV.

UV      SvUVx(SV* sv)

SvUVXx

УСТЕРЕЛО! Планируется удалить эту функцию в будущих версиях Perl. Не используйте её в новом коде; удалите её из существующего кода.

Это излишний синоним для "SvUVX"

UV      SvUVXx(SV* sv)

sv_vcatpvf

Обрабатывает свои аргументы как sv_vcatpvfn с непустым списком аргументов C-стиля и добавляет отформатированный вывод к SV. Не обрабатывает магию 'set'. См. "sv_vcatpvf_mg".

Обычно используется через переднюю функцию sv_catpvf.

void    sv_vcatpvf(SV *const sv, const char *const pat,
                   va_list *const args)

sv_vcatpvfn

void    sv_vcatpvfn(SV *const sv, const char *const pat,
                    const STRLEN patlen,
                    va_list *const args,
                    SV **const svargs,
                    const Size_t sv_count,
                    bool *const maybe_tainted)

sv_vcatpvfn_flags

Обрабатывает свои аргументы как vsprintf и добавляет отформатированный вывод к SV. Использует массив SV, если список аргументов C-стиля отсутствует (NULL). Переупорядочивание аргументов (с использованием спецификаторов формата, таких как %2$d или %*2$d ) поддерживается только при использовании массива SV; использование списка аргументов C-стиля со строкой формата, использующей переупорядочивание аргументов, приведет к исключению.

При включенных проверках загрезнения, указывает с помощью maybe_tainted, если результаты недостоверны (часто из-за использования локали).

Если вызывается как sv_vcatpvfn или флаг имеет бит SV_GMAGIC, вызывается get magic.

Предполагает, что pat имеет ту же utf8-ость, что и sv. Ответственность вызывающей стороны - убедиться в этом.

Обычно используется через один из его фронтендов sv_vcatpvf и sv_vcatpvf_mg.

void    sv_vcatpvfn_flags(SV *const sv,
                          const char *const pat,
                          const STRLEN patlen,
                          va_list *const args,
                          SV **const svargs,
                          const Size_t sv_count,
                          bool *const maybe_tainted,
                          const U32 flags)

sv_vcatpvf_mg

Как sv_vcatpvf, но также обрабатывает магию 'set'.

Обычно используется через переднюю функцию sv_catpvf_mg.

void    sv_vcatpvf_mg(SV *const sv,
                      const char *const pat,
                      va_list *const args)

SvVOK

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

bool    SvVOK(SV* sv)

sv_vsetpvf

Работает как sv_vcatpvf но копирует текст в SV вместо добавления его. Не обрабатывает магию 'set'. См. "sv_vsetpvf_mg".

Обычно используется через переднюю функцию sv_setpvf.

void    sv_vsetpvf(SV *const sv, const char *const pat,
                   va_list *const args)

sv_vsetpvfn

Работает как sv_vcatpvfn но копирует текст в SV вместо добавления его.

Обычно используется через один из его фронтендов sv_vsetpvf и sv_vsetpvf_mg.

void    sv_vsetpvfn(SV *const sv, const char *const pat,
                    const STRLEN patlen,
                    va_list *const args,
                    SV **const svargs,
                    const Size_t sv_count,
                    bool *const maybe_tainted)

sv_vsetpvf_mg

Как sv_vsetpvf, но также обрабатывает магию 'set'.

Обычно используется через переднюю функцию sv_setpvf_mg.

void    sv_vsetpvf_mg(SV *const sv,
                      const char *const pat,
                      va_list *const args)

Поддержка Юникода

"Поддержка Юникода" в perlguts содержит введение в этот API.

См. также "Классификация символов" и "Изменение регистра символов". Различные функции вне этого раздела также работают особенно с Юникодом. Поищите строку "utf8" в этом документе.

BOM_UTF8

Это макрос, который вычисляет строковую константу байтов UTF-8, определяющих метку порядка байтов Unicode (U+FEFF) для платформы, на которой скомпилирован Perl. Это позволяет использовать мнемонику для этого символа, которая работает как на платформах ASCII, так и EBCDIC. sizeof(BOM_UTF8) - 1 можно использовать для получения его длины в байтах.

bytes_cmp_utf8

Сравнивает последовательность символов (хранящихся как октеты) в b, blen с последовательностью символов (хранящихся как UTF-8) в u, ulen. Возвращает 0, если они равны, -1 или -2, если первая строка меньше второй строки, +1 или +2, если первая строка больше второй строки.

-1 или +1 возвращается, если более короткая строка была идентична началу более длинной строки. -2 или +2 возвращается, если между символами строк было различие.

int     bytes_cmp_utf8(const U8 *b, STRLEN blen,
                       const U8 *u, STRLEN ulen)

bytes_from_utf8

Преобразует потенциально закодированную в UTF-8 строку s длиной *lenp в кодировку байтов по умолчанию. На входе булево значение *is_utf8p указывает, закодирована ли s в UTF-8.

В отличие от "utf8_to_bytes", но как и "bytes_to_utf8", эта функция не изменяет входную строку.

Не делает ничего, если *is_utf8p равно 0, или если в строке есть символы, не представимые в кодировке байтов по умолчанию. В этих случаях *is_utf8p и *lenp остаются без изменений, а возвращаемое значение — исходное s.

В противном случае *is_utf8p устанавливается в 0, и возвращаемое значение — указатель на новую строку, содержащую пониженную копию s, длина которой возвращается в *lenp, обновлённая. Новая строка завершается NUL. Вызывающая сторона отвечает за освобождение памяти, используемой этой строкой.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp перед вызовом и вычтя значение *lenp после вызова из него.

U8*     bytes_from_utf8(const U8 *s, STRLEN *lenp,
                        bool *is_utf8p)

bytes_to_utf8

Преобразует строку s длиной *lenp байтов из кодировки по умолчанию в UTF-8. Возвращает указатель на созданную строку и устанавливает *lenp для отражения новой длины в байтах. Вызывающая сторона отвечает за освобождение памяти, используемой этой строкой.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp перед вызовом и вычтя его из значения *lenp после вызова.

Символ NUL будет записан после конца строки.

Если вы хотите преобразовать в UTF-8 из кодировок, отличных от кодировки по умолчанию (Latin1 или EBCDIC), см. "sv_recode_to_utf8"().

U8*     bytes_to_utf8(const U8 *s, STRLEN *lenp)

DO_UTF8

Возвращает булево значение, указывающее, должна ли переменная PV в sv обрабатываться как закодированная в UTF-8.

Вы должны использовать это после вызова SvPV() или одного из его вариантов, на случай, если какой-либо вызов перегрузки строк обновит внутренний флаг кодирования в UTF-8.

bool    DO_UTF8(SV* sv)

foldEQ_utf8

Возвращает true, если ведущие части строк s1 и s2 (любая или обе из которых могут быть в UTF-8) совпадают без учёта регистра; в противном случае — false. Определяется, насколько глубоко в строки проводить сравнение, другими входными параметрами.

Если u1 имеет значение true, строка s1 предполагается закодированной в UTF-8; в противном случае она предполагается закодированной в кодировке байтов по умолчанию. Соответственно для u2 относительно s2.

Если длина в байтах l1 отлична от нуля, она указывает, насколько глубоко в s1 проверять равенство с учётом регистра. Другими словами, s1+l1 будет использоваться в качестве цели. Сканирование не будет считаться совпадением, если цель не будет достигнута, и сканирование не будет продолжаться за этой целью. Соответственно для l2 относительно s2.

Если pe1 отлично от NULL и указатель, на который она указывает, не NULL, этот указатель считается конечным указателем на позицию на 1 байт за максимальной точкой в s1, за которой сканирование не будет продолжаться ни при каких обстоятельствах. (Эта процедура предполагает, что UTF-8 закодированные входные строки не повреждены; повреждённый ввод может привести к чтению за pe1). Это означает, что если оба l1 и pe1 указаны, и pe1 меньше s1+l1, совпадение никогда не произойдёт, потому что оно никогда не достигнет своей цели (и, на самом деле, утверждается против неё). Соответственно для pe2 относительно s2.

По крайней мере, одна из s1 и s2 должна иметь цель (по крайней мере, один из l1 и l2 должен быть отличным от нуля), и если оба имеют, оба должны быть достигнуты для успешного совпадения. Кроме того, если преобразование символа с учётом регистра даёт несколько символов, все они должны совпадать (см. ссылку на tr21 ниже для "преобразования с учётом регистра").

После успешного совпадения, если pe1 не равно NULL, оно будет установлено в указатель на начало следующего символа s1 после того, что совпало. Соответственно для pe2 и s2.

Для неучета регистра используется «преобразование с учётом регистра» Unicode, а не преобразование символов в верхний/нижний регистр, см. https://www.unicode.org/unicode/reports/tr21/ (Преобразования с учётом регистра).

I32     foldEQ_utf8(const char *s1, char **pe1, UV l1,
                    bool u1, const char *s2, char **pe2,
                    UV l2, bool u2)

is_ascii_string

Это вводящее в заблуждение синоним для "is_utf8_invariant_string". На платформах, похожих на ASCII, название не вводит в заблуждение: символы диапазона ASCII — это именно инварианты UTF-8. Но на машинах EBCDIC инварианты шире, чем просто символы ASCII, поэтому is_utf8_invariant_string предпочтительнее.

bool    is_ascii_string(const U8* const s, STRLEN len)

is_c9strict_utf8_string

Возвращает TRUE, если первые len байта строки s образуют правильную UTF-8 закодированную строку, которая соответствует Поправке Unicode #9; в противном случае возвращает FALSE. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот параметр, у s не может быть вложенных NUL символов и должен быть завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую UTF-8 строку».

Эта функция возвращает FALSE для строк, содержащих любые кодовые точки выше максимального значения Unicode 0x10FFFF или суррогатных кодовых точек, но принимает несимвольные кодовые точки в соответствии с Поправкой #9.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_c9strict_utf8_string(const U8 *s, STRLEN len)

is_c9strict_utf8_string_loc

Как "is_c9strict_utf8_string" но сохраняет местоположение ошибки (в случае «некорректности UTF-8») или местоположение s+len (в случае «корректности UTF-8») в указателе ep.

См. также "is_c9strict_utf8_string_loclen".

bool    is_c9strict_utf8_string_loc(const U8 *s,
                                    STRLEN len,
                                    const U8 **ep)

is_c9strict_utf8_string_loclen

См. также "is_c9strict_utf8_string_loc".

bool    is_c9strict_utf8_string_loclen(const U8 *s,
                                       STRLEN len,
                                       const U8 **ep,
                                       STRLEN *el)

isC9_STRICT_UTF8_CHAR

Имеет ненулевое значение, если первые несколько байтов строки, начиная с s и не выходя за пределы e - 1, являются правильно сформированным UTF-8, представляющим некоторую кодовую точку Unicode, не являющуюся суррогатной; в противном случае имеет значение 0. Если не равно нулю, значение показывает количество байтов, начиная с s , которые составляют представление кодовой точки. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первой кодовой точки в s, не проверяются.

Наибольшая допустимая кодовая точка — максимальное значение Unicode 0x10FFFF. Это отличается от "isSTRICT_UTF8_CHAR" только тем, что оно принимает несимвольные кодовые точки. Это соответствует Поправке Unicode #9, которая гласит, что несимвольные кодовые точки просто не рекомендуются, а не запрещены для открытого обмена. См. "Несимвольные кодовые точки" в perlunicode.

Используйте "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen" для проверки целых строк.

Size_t  isC9_STRICT_UTF8_CHAR(const U8 * const s0,
                              const U8 * const e)

is_invariant_string

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

bool    is_invariant_string(const U8* const s,
                            STRLEN len)

isSTRICT_UTF8_CHAR

Оценивается как ненулевое значение, если первые несколько байтов строки, начиная с s и не дальше, чем e - 1, являются корректным UTF-8, представляющим какой-либо символ Юникода, полностью приемлемый для открытого обмена между всеми приложениями; в противном случае оценивается как 0. Если ненулевое, значение показывает, сколько байтов, начиная с s составляют представление символа. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первого символа в s, не проверяются.

Наибольший допустимый символ — это максимальное значение Юникода 0x10FFFF, и он не должен быть суррогатным или недопустимым символом. Таким образом, это исключает любые символы из расширенного UTF-8 Perl.

Это используется для эффективного определения, являются ли следующие несколько байтов в s допустимым Юникод-совместимым UTF-8 для одного символа.

Используйте "isC9_STRICT_UTF8_CHAR" для использования определения допустимых символов Юникода из Поправки Юникода #9; "isUTF8_CHAR" для проверки расширенного UTF-8 Perl; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_strict_utf8_string", "is_strict_utf8_string_loc", и "is_strict_utf8_string_loclen" для проверки целых строк.

Size_t  isSTRICT_UTF8_CHAR(const U8 * const s0,
                           const U8 * const e)

is_strict_utf8_string

Возвращает ИСТИНА, если первые len байтов строки s образуют допустимую строку UTF-8, полностью взаимозаменяемую любым приложением, использующим правила Юникода; в противном случае возвращает ЛОЖЬ. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот параметр, у s не может быть встроенных NUL символов и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую строку UTF-8».

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

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_strict_utf8_string(const U8 *s, STRLEN len)

is_strict_utf8_string_loc

Подобно "is_strict_utf8_string", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep.

См. также "is_strict_utf8_string_loclen".

bool    is_strict_utf8_string_loc(const U8 *s,
                                  STRLEN len,
                                  const U8 **ep)

is_strict_utf8_string_loclen

Подобно "is_strict_utf8_string", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep, а также количество закодированных UTF-8 символов в указателе el.

См. также "is_strict_utf8_string_loc".

bool    is_strict_utf8_string_loclen(const U8 *s,
                                     STRLEN len,
                                     const U8 **ep,
                                     STRLEN *el)

is_utf8_fixed_width_buf_flags

Возвращает ИСТИНА, если фиксированный буфер, начинающийся с s и имеющий длину len полностью соответствует UTF-8, с учетом ограничений, заданных flags; в противном случае возвращает ЛОЖЬ.

Если flags равно 0, любой корректный UTF-8, как расширенный Perl, принимается без ограничений. Если последние несколько байтов буфера не образуют полный символ, это возвращает ИСТИНА, при условии, что "is_utf8_valid_partial_char_flags" возвращает ИСТИНА для них.

Если flags ненулевое, оно может быть любой комбинацией флагов UTF8_DISALLOW_foo , принятых "utf8n_to_uvchr", и с теми же значениями.

Эта функция отличается от "is_utf8_string_flags" только тем, что последняя возвращает ЛОЖЬ, если последние несколько байтов строки не образуют полный символ.

bool    is_utf8_fixed_width_buf_flags(
            const U8 * const s, STRLEN len,
            const U32 flags
        )

is_utf8_fixed_width_buf_loclen_flags

Подобно "is_utf8_fixed_width_buf_loc_flags", но хранит количество полных, корректных символов в указателе el.

bool    is_utf8_fixed_width_buf_loclen_flags(
            const U8 * const s, STRLEN len,
            const U8 **ep, STRLEN *el, const U32 flags
        )

is_utf8_fixed_width_buf_loc_flags

Подобно "is_utf8_fixed_width_buf_flags", но сохраняет местоположение ошибки в указателе ep. Если функция возвращает ИСТИНА, *ep укажет на начало любого частичного символа в конце буфера; если частичного символа нет, *ep будет содержать s+len.

См. также "is_utf8_fixed_width_buf_loclen_flags".

bool    is_utf8_fixed_width_buf_loc_flags(
            const U8 * const s, STRLEN len,
            const U8 **ep, const U32 flags
        )

is_utf8_invariant_string

Возвращает ИСТИНА, если первые len байты строки s одинаковы независимо от кодировки UTF-8 строки (или кодировки UTF-EBCDIC на машинах EBCDIC); в противном случае возвращает ЛОЖЬ. То есть, возвращает ИСТИНА, если они инвариантны UTF-8. На машинах ASCII-подобного типа все символы ASCII и только символы ASCII соответствуют этому определению. На машинах EBCDIC символы ASCII-диапазона инвариантны, но также и C1-управляющие символы.

Если len равно 0, оно будет вычислено с помощью strlen(s), (что означает, что если вы используете этот параметр, у s не может быть встроенных NUL символов и должен иметь завершающий NUL байт).

См. также "is_utf8_string", "is_utf8_string_flags", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_utf8_invariant_string(const U8* const s,
                                 STRLEN len)

is_utf8_invariant_string_loc

Подобно "is_utf8_invariant_string", но при ошибке сохраняет местоположение первого символа, не инвариантного к UTF-8, в указателе ep; если все символы инвариантны UTF-8, эта функция не изменяет содержимое *ep.

bool    is_utf8_invariant_string_loc(const U8* const s,
                                     STRLEN len,
                                     const U8 ** ep)

is_utf8_string

Возвращает ИСТИНА, если первые len байтов строки s образуют корректную строку расширенного UTF-8 Perl; в противном случае возвращает ЛОЖЬ. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот параметр, у s не может быть встроенных NUL символов и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую строку UTF-8».

Эта функция рассматривает расширенный UTF-8 Perl как допустимый. Это означает, что символы с кодами выше Юникода, суррогатные символы и недопустимые символы считаются допустимыми этой функцией. Используйте "is_strict_utf8_string", "is_c9strict_utf8_string", или "is_utf8_string_flags" для ограничения допустимых символов.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string_loc", "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags",

bool    is_utf8_string(const U8 *s, STRLEN len)

is_utf8_string_flags

Возвращает ИСТИНА, если первые len байтов строки s образуют допустимую строку UTF-8, с учетом ограничений, наложенных flags; в противном случае возвращает ЛОЖЬ. Если len равно 0, оно будет вычислено с помощью strlen(s) (что означает, что если вы используете этот параметр, у s не может быть встроенных NUL символов и должен иметь завершающий NUL байт). Обратите внимание, что все символы ASCII составляют «допустимую строку UTF-8».

Если flags равно 0, это даёт те же результаты, что и "is_utf8_string"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "is_strict_utf8_string"; и если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "is_c9strict_utf8_string". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo , понятных "utf8n_to_uvchr", с теми же значениями.

См. также "is_utf8_invariant_string", "is_utf8_invariant_string_loc", "is_utf8_string", "is_utf8_string_loc", "is_utf8_string_loc_flags", "is_utf8_string_loclen", "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags", "is_utf8_fixed_width_buf_loc_flags", "is_utf8_fixed_width_buf_loclen_flags", "is_strict_utf8_string", "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen", "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", и "is_c9strict_utf8_string_loclen".

bool    is_utf8_string_flags(const U8 *s, STRLEN len,
                             const U32 flags)

is_utf8_string_loc

Подобно "is_utf8_string" , но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep.

См. также "is_utf8_string_loclen".

bool    is_utf8_string_loc(const U8 *s,
                           const STRLEN len,
                           const U8 **ep)

is_utf8_string_loclen

Подобно "is_utf8_string", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep, а также количество закодированных UTF-8 символов в указателе el.

См. также "is_utf8_string_loc".

bool    is_utf8_string_loclen(const U8 *s, STRLEN len,
                              const U8 **ep, STRLEN *el)

is_utf8_string_loclen_flags

Подобно "is_utf8_string_flags", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep, а также количество закодированных UTF-8 символов в указателе el.

См. также "is_utf8_string_loc_flags".

bool    is_utf8_string_loclen_flags(const U8 *s,
                                    STRLEN len,
                                    const U8 **ep,
                                    STRLEN *el,
                                    const U32 flags)

is_utf8_string_loc_flags

Подобно "is_utf8_string_flags", но сохраняет местоположение ошибки (в случае «ошибки utf8») или местоположение s+len (в случае «успеха utf8») в указателе ep.

См. также "is_utf8_string_loclen_flags".

bool    is_utf8_string_loc_flags(const U8 *s,
                                 STRLEN len,
                                 const U8 **ep,
                                 const U32 flags)

is_utf8_valid_partial_char

Возвращает 0, если последовательность байтов, начиная с s и не заходя дальше e - 1, соответствует кодировке UTF-8, расширенной Perl, для одного или нескольких кодовых точек. В противном случае возвращает 1, если существует по крайней мере одна непустая последовательность байтов, которая, при добавлении к последовательности s, начиная с позиции e, приводит всю последовательность к корректной UTF-8 для некоторой кодовой точки; в противном случае возвращает 0.

Другими словами, это возвращает ИСТИНА, если s указывает на частичную кодовую точку в UTF-8-кодировке.

Это полезно, когда проверяется буфер фиксированной длины на корректность UTF-8, но последние несколько байтов в нём не образуют целого символа; то есть, он разделён посередине конечной UTF-8-представления последней кодовой точки. (Предположительно, когда буфер будет обновлён следующей частью данных, новые первые байты завершат частичную кодовую точку.) Эта функция используется для проверки, являются ли последние байты в текущем буфере законным началом некоторой кодовой точки, так что если они таковыми не являются, можно сигнализировать об ошибке, не дожидаясь следующего чтения.

bool    is_utf8_valid_partial_char(const U8 * const s,
                                   const U8 * const e)

is_utf8_valid_partial_char_flags

Подобно "is_utf8_valid_partial_char", возвращает булевое значение, указывающее, является ли входной данные корректной частичной кодовой точкой UTF-8, но принимает дополнительный параметр, flags, который может дополнительно ограничить допустимые кодовые точки.

Если flags равно 0, это поведение идентично "is_utf8_valid_partial_char". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo принятых "utf8n_to_uvchr". Если существует какая-либо последовательность байтов, которая может завершить частичную кодовую точку ввода таким образом, что образуется недопустимый символ, функция возвращает ИСТИНА; в противном случае ЛОЖЬ. Кодовые точки, не являющиеся символами, не могут быть определены на основе частичного ввода кодовых точек. Но многие другие возможные исключённые типы могут быть определены только по первым одному или двум байтам.

bool    is_utf8_valid_partial_char_flags(
            const U8 * const s, const U8 * const e,
            const U32 flags
        )

isUTF8_CHAR

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не заходя дальше e - 1, являются корректными UTF-8, расширенными Perl, представляющими некоторую кодовую точку; в противном случае принимает значение 0. Если ненулевое, значение показывает, сколько байтов, начиная с s составляют представление кодовой точки. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первой кодовой точки в s, не проверяются.

Кодовая точка может быть любой, которая поместится в IV на этом компьютере, используя расширение Perl для официального UTF-8 для представления тех, которые выше максимального значения Unicode 0x10FFFF. Это означает, что этот макрос используется для эффективного определения, являются ли следующие несколько байтов в s допустимым UTF-8 для одного символа.

Используйте "isSTRICT_UTF8_CHAR" для ограничения допустимых кодовых точек теми, которые определены Unicode как полностью взаимозаменяемые в приложениях; "isC9_STRICT_UTF8_CHAR" для использования определения допустимых кодовых точек в Поправке Unicode #9; и "isUTF8_CHAR_flags" для более настраиваемого определения.

Используйте "is_utf8_string", "is_utf8_string_loc", и "is_utf8_string_loclen" для проверки целых строк.

Обратите также внимание, что "инвариантный" символ UTF-8 (т.е. ASCII на не-EBCDIC машинах) является допустимым символом UTF-8.

Size_t  isUTF8_CHAR(const U8 * const s0,
                    const U8 * const e)

isUTF8_CHAR_flags

Принимает ненулевое значение, если первые несколько байтов строки, начиная с s и не заходя дальше e - 1, являются корректным UTF-8, расширенным Perl, представляющим некоторую кодовую точку, в соответствии с ограничениями, заданными flags; в противном случае принимает значение 0. Если ненулевое, значение показывает, сколько байтов, начиная с s составляют представление кодовой точки. Любые оставшиеся байты перед e, но за пределами необходимых для формирования первой кодовой точки в s, не проверяются.

Если flags равно 0, это даёт те же результаты, что и "isUTF8_CHAR"; если flags равно UTF8_DISALLOW_ILLEGAL_INTERCHANGE, это даёт те же результаты, что и "isSTRICT_UTF8_CHAR"; а если flags равно UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE, это даёт те же результаты, что и "isC9_STRICT_UTF8_CHAR". В противном случае flags может быть любой комбинацией флагов UTF8_DISALLOW_foo понятых "utf8n_to_uvchr", с теми же значениями.

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

Используйте "is_utf8_string_flags", "is_utf8_string_loc_flags" и "is_utf8_string_loclen_flags" для проверки целых строк.

STRLEN  isUTF8_CHAR_flags(const U8 *s, const U8 *e,
                          const U32 flags)

LATIN1_TO_NATIVE

Возвращает эквивалент кодовой точки Latin-1 на родной платформе (включая ASCII и управляющие символы), заданный ch. Таким образом, LATIN1_TO_NATIVE(66) на платформах EBCDIC возвращает 194. Каждый из них представляет символ "B" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто возвращает свой входной параметр, не добавляя временных или пространственных требований к реализации.

Для преобразования кодовых точек, потенциально больших, чем символ, используйте "UNI_TO_NATIVE".

U8      LATIN1_TO_NATIVE(U8 ch)

NATIVE_TO_LATIN1

Возвращает эквивалент кодовой точки на родной платформе в Latin-1 (включая ASCII и управляющие символы), заданный ch. Таким образом, NATIVE_TO_LATIN1(193) на платформах EBCDIC возвращает 65. Каждый из них представляет символ "A" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто возвращает свой входной параметр, не добавляя временных или пространственных требований к реализации.

Для преобразования кодовых точек, потенциально больших, чем символ, используйте "NATIVE_TO_UNI".

U8      NATIVE_TO_LATIN1(U8 ch)

NATIVE_TO_UNI

Возвращает эквивалент кодовой точки на родной платформе в Unicode, заданный ch. Таким образом, NATIVE_TO_UNI(195) на платформах EBCDIC возвращает 67. Каждый из них представляет символ "C" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто возвращает свой входной параметр, не добавляя временных или пространственных требований к реализации.

UV      NATIVE_TO_UNI(UV ch)

pv_uni_display

Создаёт в скаляре dsv отображаемую версию строки UTF-8 spv, длиной len, при этом отображаемая версия имеет длину не более pvlim байт (если длиннее, остальная часть усекается, и добавляется "...").

Аргумент flags может иметь UNI_DISPLAY_ISPRINT для отображения символов как таковых, UNI_DISPLAY_BACKSLASH для отображения \\[nrfta\\] в виде обратного слэша (как "\n") (UNI_DISPLAY_BACKSLASH предпочтительнее UNI_DISPLAY_ISPRINT для "\\"). UNI_DISPLAY_QQ (и его псевдоним UNI_DISPLAY_REGEX) имеют включёнными как UNI_DISPLAY_BACKSLASH, так и UNI_DISPLAY_ISPRINT.

Кроме того, теперь есть UNI_DISPLAY_BACKSPACE, что позволяет отображать \b для символа Backspace, но только при включённом UNI_DISPLAY_BACKSLASH.

Возвращается указатель на PV скаляра dsv.

См. также "sv_uni_display".

char*   pv_uni_display(SV *dsv, const U8 *spv,
                       STRLEN len, STRLEN pvlim,
                       UV flags)

REPLACEMENT_CHARACTER_UTF8

Это макрос, который возвращает строковую константу байтов UTF-8, определяющих символ ЗАМЕЩЕНИЯ Unicode (U+FFFD) для платформы, на которой скомпилирован Perl. Это позволяет коду использовать мнемонику для этого символа, которая работает как на платформах ASCII, так и на платформах EBCDIC. sizeof(REPLACEMENT_CHARACTER_UTF8) - 1 может быть использован для получения его длины в байтах.

sv_cat_decode

encoding предполагается как Encode объект, PV ssv предполагается как октеты в этой кодировке, и декодирование входных данных начинается с позиции, на которую указывает (PV + *offset). dsv будет конкатенирован с декодированной UTF-8 строкой из ssv. Декодирование будет завершено, когда в выходных данных декодирования появится строка tstr или входные данные закончатся на PV ssv. Значение, на которое указывает offset, будет изменено на последнюю позицию входных данных в ssv.

Возвращает ИСТИНА, если терминатор был найден, в противном случае возвращает ЛОЖЬ.

bool    sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
                      int *offset, char* tstr, int tlen)

sv_recode_to_utf8

encoding предполагается как Encode объект, на вход PV sv предполагается как октеты в этой кодировке, а sv будет преобразовано в Unicode (и UTF-8).

Если sv уже является UTF-8 (или если это не POK) или если encoding не является ссылкой, ничего не делается с sv. Если encoding не является объектом кодировки Encode::XS, произойдут плохие вещи. (См. cpan/Encode/encoding.pm и Encode.)

Возвращается PV sv.

char*   sv_recode_to_utf8(SV* sv, SV *encoding)

sv_uni_display

Создаёт в скаляре dsv отображаемую версию скаляра sv, при этом отображаемая версия имеет длину не более pvlim байт (если длиннее, остальная часть усекается, и добавляется "...").

Аргумент flags аналогичен "pv_uni_display"().

Возвращается указатель на PV скаляра dsv.

char*   sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
                       UV flags)

UNICODE_REPLACEMENT

Возвращает 0xFFFD, кодовую точку символа ЗАМЕЩЕНИЯ Unicode.

UNI_TO_NATIVE

Возвращает родной эквивалент кода символа Юникода на входе, заданного ch. Таким образом, UNI_TO_NATIVE(68) на платформах EBCDIC возвращает 196. Каждый из них представляет символ "D" на соответствующих платформах. На платформах ASCII преобразование не требуется, поэтому этот макрос просто расширяется до своего входного значения, не добавляя временных или пространственных требований к реализации.

UV      UNI_TO_NATIVE(UV ch)

utf8n_to_uvchr

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кодов должны использовать "utf8_to_uvchr_buf"() вместо прямого вызова.

Базовый декодер UTF-8. Возвращает значение кода символа на родном языке первого символа в строке s, предполагая, что она закодирована в UTF-8 (или UTF-EBCDIC) и не превышает curlen байт; *retlen (если retlen не равно NULL) будет установлено в длину этого символа в байтах.

Значение flags определяет поведение, когда s не указывает на корректный символ UTF-8. Если flags равно 0, обнаружение некорректного символа вызывает возврат нуля и *retlen устанавливается так, что (s + *retlen) — это следующая возможная позиция в s, которая может начать корректный символ. Кроме того, если предупреждения UTF-8 не отключены лексически, генерируется предупреждение. Некоторые последовательности ввода UTF-8 могут содержать несколько ошибок. Эта функция пытается найти все возможные ошибки при каждом вызове, поэтому могут быть вызваны несколько предупреждений для одной и той же последовательности.

Различные флаги ALLOW могут быть установлены в flags для разрешения (и не вывода предупреждений) отдельных типов ошибок, таких как последовательность, превышающая допустимую длину (то есть, когда существует более короткая последовательность, которая может выразить тот же код символа; чрезмерно длинные последовательности прямо запрещены стандартом UTF-8 из-за потенциальных проблем безопасности). Другим примером ошибки является то, что первый байт символа не является допустимым первым байтом. См. utf8.h для списка таких флагов. Даже если ошибка разрешена, эта функция, как правило, возвращает заменяющий символ Юникода при обнаружении ошибки. В utf8.h есть флаги для отмены этого поведения для чрезмерно длинных последовательностей, но делайте это только в очень специализированных случаях.

Флаг UTF8_CHECK_ONLY переопределяет поведение при обнаружении неразрешённой (другими флагами) ошибки. Если этот флаг установлен, процедура предполагает, что вызывающая функция выведет предупреждение, и эта функция молча установит retlen в -1 (преобразовано в STRLEN) и вернёт ноль.

Обратите внимание, что этот API требует различения успешного декодирования символа NUL, и возврата ошибки (если не установлен флаг UTF8_CHECK_ONLY), поскольку в обоих случаях возвращается 0, и, в зависимости от ошибки, retlen может быть установлено в 1. Чтобы отличить, при возвращении нуля, проверьте, равен ли первый байт s нулю. Если да, входной символ был NUL; если нет, в вводе была ошибка. Или вы можете использовать "utf8n_to_uvchr_error".

Некоторые коды символов считаются проблемными. Это суррогаты Юникода, недопустимые символы Юникода и коды символов, превышающие максимальное значение Юникода 0x10FFFF. По умолчанию они считаются обычными кодами символов, но в определённых ситуациях требуется специальная обработка, которая может быть задана с помощью параметра flags. Если flags содержит UTF8_DISALLOW_ILLEGAL_INTERCHANGE, все три класса обрабатываются как ошибки и обрабатываются как таковые. Флаги UTF8_DISALLOW_SURROGATE, UTF8_DISALLOW_NONCHAR, и UTF8_DISALLOW_SUPER (означающие превышение допустимого максимального значения Юникода) могут быть установлены для запрета этих категорий по отдельности. UTF8_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входные данные строгим UTF-8, традиционно определённым Юникодом. Используйте UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE для использования определения строгости, указанного в Поправке Юникода № 9. Разница между традиционной и C9 строгостью заключается в том, что последняя не запрещает коды несимволов. (Однако они всё ещё не рекомендуются.) Для более подробной информации см. "Коды несимволов" в perlunicode.

Флаги UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_ILLEGAL_C9_INTERCHANGE, UTF8_WARN_SURROGATE, UTF8_WARN_NONCHAR, и UTF8_WARN_SUPER вызовут сообщения об ошибках для соответствующих категорий, но в противном случае коды символов считаются допустимыми (не являются ошибками). Чтобы заставить категорию обрабатываться как ошибку и выводить предупреждение, укажите оба флага WARN и DISALLOW. (Но обратите внимание, что предупреждения не выводятся, если они лексически отключены или если также указан UTF8_CHECK_ONLY.)

Чрезвычайно большие коды символов никогда не были указаны в каком-либо стандарте и требуют расширения UTF-8 для выражения, что Perl делает. Вероятно, программы, написанные на чём-либо кроме Perl, не смогут читать файлы, содержащие эти символы; Perl также не сможет понять файлы, написанные с использованием другого расширения. По этим причинам существует отдельный набор флагов, которые могут выводить предупреждения и/или запрещать чрезвычайно большие коды символов, даже если другие коды символов, превышающие Юникод, принимаются. Это флаги UTF8_WARN_PERL_EXTENDED и UTF8_DISALLOW_PERL_EXTENDED . Для получения более подробной информации см. "UTF8_GOT_PERL_EXTENDED". Конечно, UTF8_DISALLOW_SUPER будет обрабатывать все коды символов, превышающие Юникод, включая эти, как ошибки. (Обратите внимание, что стандарт Юникода считает всё, что превышает 0x10FFFF, недопустимым, но существуют стандарты, предшествующие ему, которые допускают значения до 0x7FFF_FFFF (2**31 -1))

Синоним UTF8_WARN_PERL_EXTENDED, имеющий несколько вводящее в заблуждение название, сохранён для обратной совместимости: UTF8_WARN_ABOVE_31_BIT. Аналогично, UTF8_DISALLOW_ABOVE_31_BIT можно использовать вместо более точного UTF8_DISALLOW_PERL_EXTENDED. Названия вводят в заблуждение, потому что эти флаги могут применяться к кодам символов, которые фактически подходят в 31 бит. Это происходит на платформах EBCDIC и иногда, когда присутствует также ошибка чрезмерно длинной последовательности. Новые названия точно описывают ситуацию во всех случаях.

Все остальные коды символов, соответствующие символам Юникода, включая символы частного использования и те, которые ещё предстоит назначить, никогда не считаются ошибочными и никогда не вызывают предупреждения.

UV      utf8n_to_uvchr(const U8 *s, STRLEN curlen,
                       STRLEN *retlen, const U32 flags)

utf8n_to_uvchr_error

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛИЗИРОВАННЫХ СЛУЧАЯХ. Большинство кода должно использовать "utf8_to_uvchr_buf"() вместо прямого вызова этой функции.

Эта функция предназначена для кода, которому необходимо знать точные нарушения при обнаружении ошибки. Если вам также нужно знать сгенерированные предупреждения, используйте "utf8n_to_uvchr_msgs"() вместо этого.

Она похожа на "utf8n_to_uvchr", но принимает дополнительный параметр, помещённый после всех остальных, errors. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr". В противном случае, errors должен быть указателем на переменную U32, которую эта функция устанавливает, чтобы указать на обнаруженные ошибки. При возврате, если *errors равно 0, ошибок не было. В противном случае, *errors — это побитовое OR битов, описанных в списке ниже. Некоторые из этих битов будут установлены, если обнаружено нарушение, даже если параметр ввода flags указывает, что данное нарушение разрешено; эти исключения отмечены:

UTF8_GOT_PERL_EXTENDED

Последовательность ввода не является стандартным UTF-8, а является расширением Perl. Этот бит устанавливается только в том случае, если параметр ввода flags содержит флаги UTF8_DISALLOW_PERL_EXTENDED или UTF8_WARN_PERL_EXTENDED.

Кодовые точки выше 0x7FFF_FFFF (2**31 - 1) никогда не специфицировались в каком-либо стандарте, поэтому для их выражения необходимо использовать какое-то расширение. Perl использует естественное расширение UTF-8 для представления кодовых точек до 2**36-1 и придумал дальнейшее расширение для представления ещё более высоких, так что любая кодовая точка, которая помещается в 64-битовое слово, может быть представлена. Текст, использующий эти расширения, вряд ли будет переносимым в код, не являющийся Perl. Мы объединили оба этих расширения и называем их расширенным UTF-8 Perl. Существуют и другие расширения, которые люди придумали, несовместимые с Perl.

На платформах EBCDIC, начиная с Perl v5.24, расширение Perl для представления очень высоких кодовых точек включается при 0x3FFF_FFFF (2**30 -1), что ниже, чем на ASCII. До этого кодовые точки 2**31 и выше просто не могли быть представлены, и использовался другой, несовместимый метод для представления кодовых точек между 2**30 и 2**31 - 1.

На обеих платформах, ASCII и EBCDIC, UTF8_GOT_PERL_EXTENDED устанавливается, если используется расширенный UTF-8 Perl.

В более ранних версиях Perl этот бит назывался UTF8_GOT_ABOVE_31_BIT, которое вы можете использовать для обратной совместимости. Это имя вводит в заблуждение, так как этот флаг может быть установлен, когда кодовая точка фактически помещается в 31 бит. Это происходит на платформах EBCDIC и иногда, когда также присутствует нарушение неполноты. Новое имя точно описывает ситуацию во всех случаях.

UTF8_GOT_CONTINUATION

Последовательность ввода была неправильной, так как первый байт был продолжением байта UTF-8.

UTF8_GOT_EMPTY

Параметр ввода curlen был равен 0.

UTF8_GOT_LONG

Последовательность ввода была неправильной, так как существует другая последовательность, которая даёт ту же кодовую точку, но эта последовательность короче.

До Unicode 3.1 программы могли принимать это нарушение, но было обнаружено, что это создаёт проблемы безопасности.

UTF8_GOT_NONCHAR

Кодовая точка, представленная последовательностью ввода UTF-8, относится к кодовой точке несимвола Unicode. Этот бит устанавливается только в том случае, если параметр ввода flags содержит флаги UTF8_DISALLOW_NONCHAR или UTF8_WARN_NONCHAR.

UTF8_GOT_NON_CONTINUATION

Последовательность ввода была неправильной, так как в позиции, где должен быть только байт продолжения, был обнаружен байт нетипа продолжения. См. также "UTF8_GOT_SHORT".

UTF8_GOT_OVERFLOW

Последовательность ввода была неправильной, так как она относится к кодовой точке, которая не может быть представлена количеством битов, доступных в IV на текущей платформе.

UTF8_GOT_SHORT

Последовательность ввода была неправильной, так как curlen меньше, чем требуется для полной последовательности. Другими словами, входной данные являются частью последовательности символов.

UTF8_GOT_SHORT и UTF8_GOT_NON_CONTINUATION оба указывают на слишком короткую последовательность. Разница в том, что UTF8_GOT_NON_CONTINUATION всегда указывает на ошибку, а UTF8_GOT_SHORT означает, что рассматривалась неполная последовательность. Если других флагов нет, это означает, что последовательность была валидной в той степени, в которой она была проверена. В зависимости от приложения это может означать три вещи:

Параметр длины curlen был слишком мал, и функция не смогла проверить все необходимые байты.
Буфер, на который ссылаются, основан на чтении данных, и полученные до сих пор данные остановились в середине символа, так что следующее чтение прочитает остаток этого символа. (От вызывающей стороны требуется каким-то образом обработать разделенные байты.)
Это реальная ошибка, и частичная последовательность — всё, что мы получим.

UTF8_GOT_SUPER

Последовательность ввода была неправильной, так как она относится к кодовой точке, не являющейся Unicode; то есть, превышающей максимальное разрешённое значение Unicode. Этот бит устанавливается только в том случае, если параметр ввода flags содержит флаги UTF8_DISALLOW_SUPER или UTF8_WARN_SUPER.

UTF8_GOT_SURROGATE

Последовательность ввода была неправильной, так как она относится к зарезервированной кодовой точке UTF-16. Этот бит устанавливается только в том случае, если параметр ввода flags содержит флаги UTF8_DISALLOW_SURROGATE или UTF8_WARN_SURROGATE.

Для собственной обработки ошибок вызовите эту функцию со флагом UTF8_CHECK_ONLY для подавления предупреждений, а затем проверьте возвращаемое значение *errors.

UV      utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
                             STRLEN *retlen,
                             const U32 flags,
                             U32 * errors)

utf8n_to_uvchr_msgs

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

Она аналогична "utf8n_to_uvchr_error" но принимает дополнительный параметр, размещённый после всех остальных, msgs. Если этот параметр равен 0, эта функция ведет себя идентично "utf8n_to_uvchr_error". В противном случае, msgs должен быть указателем на переменную AV *, в которой эта функция создаёт новый массив AV, содержащий все соответствующие сообщения. Элементы массива упорядочены так, что первое сообщение, которое должно было быть отображено, находится в элементе 0 и так далее. Каждый элемент является хешем с тремя парами ключ-значение, как показано ниже:

text: Текст сообщения в виде SVpv.
warn_categories: Категория предупреждения (или категории), упакованные в SVuv.
flag: Один флаг, связанный с этим сообщением, в виде SVuv . Бит соответствует какому-то биту в возвращаемом значении *errors, например, UTF8_GOT_LONG.

Важно отметить, что указание этого параметра как отличного от нуля приведёт к подавлению всех предупреждений, которые эта функция в противном случае генерировала бы, и вместо этого они будут помещены в *msgs. Вызывающая сторона может проверить состояние лексических предупреждений (или нет), выбирая, что делать с возвращёнными сообщениями.

Если передаётся флаг UTF8_CHECK_ONLY, предупреждения не генерируются, и, следовательно, AV не создаётся.

Вызывающая сторона, конечно, несёт ответственность за освобождение возвращённого AV.

UV      utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
                            STRLEN *retlen,
                            const U32 flags,
                            U32 * errors, AV ** msgs)

UTF8SKIP

возвращает количество байтов неиспорченного символа UTF-8, первый (возможно, единственный) байт которого указан в s.

Если есть возможность неправильного ввода, используйте вместо этого:

"UTF8_SAFE_SKIP", если вы знаете максимальный указатель окончания в буфере, на который указывает s; или
"UTF8_CHK_SKIP", если вы не знаете.

Лучше перестроить свой код так, чтобы указатель окончания передавался вниз, чтобы вы знали, что это на самом деле в момент этого вызова, но если это невозможно, "UTF8_CHK_SKIP" может свести к минимуму вероятность доступа за пределы буфера ввода.

STRLEN  UTF8SKIP(char* s)

UTF8_CHK_SKIP

Это более безопасная версия "UTF8SKIP", но всё ещё не такая безопасная, как "UTF8_SAFE_SKIP". Эта версия не слепо предполагает, что строка ввода, на которую указывает s, имеет правильный формат, но проверяет, что нет символа NULL перед ожидаемым концом следующего символа в s. Длина UTF8_CHK_SKIP возвращается как раз перед таким символом NULL.

Perl имеет тенденцию добавлять символы NULL, как страховочную меру, после окончания строк в SV, поэтому, скорее всего, использование этой макрокоманды предотвратит непреднамеренный доступ за пределы буфера ввода, даже если он имеет неправильный формат UTF-8.

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

STRLEN  UTF8_CHK_SKIP(char* s)

utf8_distance

Возвращает количество символов UTF-8 между указателями UTF-8 a и b.

ПРЕДУПРЕЖДЕНИЕ: используйте только если вы *знаете*, что указатели указывают внутри одного и того же буфера UTF-8.

IV      utf8_distance(const U8 *a, const U8 *b)

utf8_hop

Возвращает указатель UTF-8 s, смещённый на off символов вперёд или назад.

ПРЕДУПРЕЖДЕНИЕ: не используйте следующие функции, если вы не *знаете*, что off находится внутри данных UTF-8, на которые указывает s *и* что при входе s выровнен по первому байту символа или сразу после последнего байта символа.

U8*     utf8_hop(const U8 *s, SSize_t off)

utf8_hop_back

Возвращает указатель на UTF-8 последовательность s, смещённую назад на до off символов.

off должно быть не положительным.

s должно быть после или равно start.

При движении назад оно не будет перемещаться перед start.

Превышение этого ограничения не произойдёт, даже если строка не является валидной "UTF-8".

U8*     utf8_hop_back(const U8 *s, SSize_t off,
                      const U8 *start)

utf8_hop_forward

Возвращает указатель на UTF-8 последовательность s смещённый вперёд на до off символов.

off должно быть неотрицательным.

s должно быть перед или равно end.

При движении вперёд оно не будет перемещаться за end.

Превышение этого ограничения не произойдёт, даже если строка не является валидной "UTF-8".

U8*     utf8_hop_forward(const U8 *s, SSize_t off,
                         const U8 *end)

utf8_hop_safe

Возвращает указатель на UTF-8 последовательность s смещённый вперёд или назад на до off символов.

При движении назад оно не будет перемещаться перед start.

При движении вперёд оно не будет перемещаться за end.

Превышение этих ограничений не произойдёт, даже если строка не является валидной "UTF-8".

U8*     utf8_hop_safe(const U8 *s, SSize_t off,
                      const U8 *start, const U8 *end)

UTF8_IS_INVARIANT

Возвращает 1, если байт c представляет тот же символ при кодировании в UTF-8, что и без него; иначе возвращает 0. Инвариантные UTF-8 символы можно копировать без изменений при преобразовании в/из UTF-8, что экономит время.

Несмотря на название, эта макрокоманда даёт правильный результат, если входная строка, из которой берётся c, не закодирована в UTF-8.

См. "UVCHR_IS_INVARIANT" для проверки, является ли UV инвариантным.

bool    UTF8_IS_INVARIANT(char c)

UTF8_IS_NONCHAR

Возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше e - 1, являются корректной UTF-8 последовательностью, представляющей один из кодов Юникода, не являющийся символом; иначе возвращает 0. Если ненулевое, значение указывает количество байт, начиная с s, составляющих представление кода.

bool    UTF8_IS_NONCHAR(const U8 *s, const U8 *e)

UTF8_IS_SUPER

Отметим, что Perl распознаёт расширение UTF-8, которое может кодировать символы с кодами, большими, чем определенные Юникодом, которые находятся в диапазоне 0..0x10FFFF.

Эта макрокоманда возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше e - 1, являются частью этого расширения UTF-8; в противном случае возвращает 0. Если ненулевое, значение указывает количество байт, начиная с s, составляющих представление кода.

0 возвращается, если байты не являются корректной расширенной UTF-8 последовательностью или если они представляют код, который не может поместиться в UV на текущей платформе. Следовательно, эта макрокоманда может давать разные результаты при выполнении на 64-битной машине и на машине с 32-битным размером слова.

Обратите внимание, что использовать коды, которые больше, чем может поместиться в IV на текущей машине, запрещено.

bool    UTF8_IS_SUPER(const U8 *s, const U8 *e)

UTF8_IS_SURROGATE

Возвращает ненулевое значение, если первые байты строки, начиная с s и не дальше e - 1, являются корректной UTF-8 последовательностью, представляющей один из суррогатных кодов Юникода; иначе возвращает 0. Если ненулевое, значение указывает количество байт, начиная с s, составляющих представление кода.

bool    UTF8_IS_SURROGATE(const U8 *s, const U8 *e)

utf8_length

Возвращает количество символов в последовательности байтов UTF-8, начиная с s и заканчивая байтом перед e. Если <s> и <e> указывают на одно и то же место, возвращает 0 без вывода предупреждения.

Если e < s или если сканирование закончится за пределами e, выводится предупреждение UTF8, и возвращается количество корректных символов.

STRLEN  utf8_length(const U8* s, const U8 *e)

UTF8_MAXBYTES

Максимальная длина одного символа UTF-8 в байтах.

ПРИМЕЧАНИЕ: Строго говоря, UTF-8 Perl не следует называть UTF-8, так как UTF-8 — это кодировка Юникода, а максимальное значение в Юникоде, 0x10FFFF, может быть представлено 4 байтами. Однако Perl рассматривает UTF-8 как способ кодирования целых неотрицательных чисел в двоичном формате, даже тех, которые превышают Юникод.

UTF8_MAXBYTES_CASE

Максимальное количество байтов UTF-8, которое может занимать один символ Юникода при преобразовании в верхний/нижний регистр/заглавный регистр/свертку.

UTF8_SAFE_SKIP

возвращает 0, если s >= e; иначе возвращает количество байтов в символе UTF-8, первый байт которого указан в s. Но оно никогда не возвращает значение больше e. При отладке, оно проверяет, что s <= e.

STRLEN  UTF8_SAFE_SKIP(char* s, char* e)

UTF8_SKIP

Это синоним для "UTF8SKIP"

STRLEN  UTF8_SKIP(char* s)

utf8_to_bytes

ПРИМЕЧАНИЕ: эта функция экспериментальная и может быть изменена или удалена без уведомления.

Преобразует строку "s" длиной *lenp из UTF-8 в кодировку нативных байтов. В отличие от "bytes_to_utf8", эта функция перезаписывает исходную строку и обновляет *lenp для хранения новой длины. Возвращает ноль при ошибке (оставляя "s" без изменений), устанавливая *lenp в -1.

После успешного возврата количество вариантов в строке можно вычислить, сохранив значение *lenp до вызова и вычитая значение *lenp после вызова из него.

Если вам нужна копия строки, см. "bytes_from_utf8".

U8*     utf8_to_bytes(U8 *s, STRLEN *lenp)

utf8_to_uvchr_buf

Возвращает нативный код первого символа в строке s, которая предполагается закодированной в UTF-8; send указывает на байт, следующий за концом s. *retlen будет установлено в длину этого символа в байтах.

Если s не указывает на корректный UTF-8 символ и включены предупреждения UTF8, возвращается ноль, а *retlen устанавливается (если retlen не NULL) в -1. Если эти предупреждения выключены, вычисленное значение, если оно определено (или заменяющий символ Юникода, если нет), возвращается молча, а *retlen устанавливается (если retlen не NULL) так, что (s + *retlen) — это следующая возможная позиция в s, которая могла бы начать корректный символ. Смотрите "utf8n_to_uvchr" для получения подробностей о том, когда возвращается заменяющий символ.

UV      utf8_to_uvchr_buf(const U8 *s, const U8 *send,
                          STRLEN *retlen)

UVCHR_IS_INVARIANT

Возвращает 1, если представление кода cp одинаково независимо от того, закодировано ли оно в UTF-8; иначе возвращает 0. Инвариантные UTF-8 символы можно копировать без изменений при преобразовании в/из UTF-8, что экономит время. cp — это код Юникода, если больше 255; иначе — нативный код платформы.

bool    UVCHR_IS_INVARIANT(UV cp)

UVCHR_SKIP

Возвращает количество байтов, необходимых для представления кода cp при кодировании в UTF-8. cp — это нативный (ASCII или EBCDIC) код, если меньше 255; в противном случае — код Юникода.

STRLEN  UVCHR_SKIP(UV cp)

uvchr_to_utf8

Добавляет UTF-8 представление нативного кода uv в конец строки d; d должен иметь как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1) свободных байт. Значение возврата — указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8(d, uv);

является рекомендуемым способом работы с широкими нативными символами, учитывающими кодировку

*(d++) = uv;

Эта функция принимает любой код в диапазоне 0..IV_MAX в качестве входных данных. IV_MAX обычно равно 0x7FFF_FFFF в 32-битном слове.

Можно запретить или предупредить о кодах, не являющихся Юникодом, или о кодах, которые могут быть проблематичными, используя "uvchr_to_utf8_flags".

U8*     uvchr_to_utf8(U8 *d, UV uv)

uvchr_to_utf8_flags

Добавляет UTF-8 представление кодового пункта uv к концу строки d; у строки d должно быть как минимум UVCHR_SKIP(uv)+1 (до UTF8_MAXBYTES+1) свободных байтов. Значение возврата — указатель на байт после конца нового символа. Другими словами,

d = uvchr_to_utf8_flags(d, uv, flags);

или, в большинстве случаев,

d = uvchr_to_utf8_flags(d, uv, 0);

Это эквивалент записи с учетом Unicode

*(d++) = uv;

Если flags равно 0, эта функция принимает любые кодовые точки от 0 до IV_MAX в качестве входных данных. IV_MAX обычно равно 0x7FFF_FFFF в 32-битном слове.

Указание flags может дополнительно ограничить разрешённые значения и предупреждения следующим образом:

Если uv является суррогатным кодовым пунктом Unicode, и UNICODE_WARN_SURROGATE установлено, функция выведет предупреждение, если включены предупреждения UTF8. Если вместо этого установлено UNICODE_DISALLOW_SURROGATE, функция завершится ошибкой и вернёт NULL. Если оба флага установлены, функция выведет предупреждение и вернёт NULL.

Аналогично, флаги UNICODE_WARN_NONCHAR и UNICODE_DISALLOW_NONCHAR влияют на обработку символов Unicode, не являющихся символами.

И аналогично, флаги UNICODE_WARN_SUPER и UNICODE_DISALLOW_SUPER влияют на обработку кодовых точек, которые превышают максимальное значение Unicode 0x10FFFF. Языки, отличные от Perl, могут не поддерживать файлы, содержащие такие кодовые точки.

Флаг UNICODE_WARN_ILLEGAL_INTERCHANGE выбирает все три вышеуказанных флага WARN; а UNICODE_DISALLOW_ILLEGAL_INTERCHANGE выбирает все три флага DISALLOW. UNICODE_DISALLOW_ILLEGAL_INTERCHANGE ограничивает допустимые входные данные строго определённым UTF-8, традиционно используемым Unicode. Аналогично, UNICODE_WARN_ILLEGAL_C9_INTERCHANGE и UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE являются сокращениями для выбора флагов выше Unicode и суррогатных, но не флагов, связанных с символами, не являющимися символами, как определено в Поправке Unicode #9. См. "Кодовые точки, не являющиеся символами" в perlunicode.

Очень высокие кодовые точки никогда не были определены в каких-либо стандартах и требуют расширения UTF-8 для их представления, что делает Perl. Вероятно, программы, написанные на других языках, кроме Perl, не смогут прочитать файлы, содержащие такие точки; также Perl не сможет понять файлы, созданные с использованием других расширений. По этим причинам существует отдельный набор флагов, которые могут выводить предупреждения и/или запрещать эти очень высокие кодовые точки, даже если другие кодовые точки, превышающие Unicode, разрешены. Это флаги UNICODE_WARN_PERL_EXTENDED и UNICODE_DISALLOW_PERL_EXTENDED. Дополнительную информацию см. в "UTF8_GOT_PERL_EXTENDED". Конечно, UNICODE_DISALLOW_SUPER будет рассматривать все кодовые точки, превышающие Unicode, включая эти, как неверные. (Обратите внимание, что стандарт Unicode считает все значения выше 0x10FFFF незаконными, но есть стандарты, предшествующие ему, которые позволяют значения до 0x7FFF_FFFF (2**31 -1))

Синтаксический синоним, несколько вводящий в заблуждение, для UNICODE_WARN_PERL_EXTENDED сохраняется для обратной совместимости: UNICODE_WARN_ABOVE_31_BIT. Аналогично, UNICODE_DISALLOW_ABOVE_31_BIT можно использовать вместо более точного синонима UNICODE_DISALLOW_PERL_EXTENDED. Названия вводят в заблуждение, поскольку на платформах EBCDIC эти флаги могут относиться к кодовым точкам, которые фактически умещаются в 31 бит. Новые названия точно описывают ситуацию во всех случаях.

U8*     uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)

uvchr_to_utf8_flags_msgs

ЭТУ ФУНКЦИЮ СЛЕДУЕТ ИСПОЛЬЗОВАТЬ ТОЛЬКО В ОЧЕНЬ СПЕЦИАЛЬНЫХ СЛУЧАЯХ.

Большинство кодов должны использовать "uvchr_to_utf8_flags"() вместо прямого вызова этой функции.

Эта функция предназначена для кода, который хочет, чтобы все предупреждения и/или сообщения об ошибках возвращались вызывающему элементу, а не отображались. Все сообщения, которые были бы отображены, если бы были включены все лексические предупреждения, будут возвращены.

Это то же самое, что и "uvchr_to_utf8_flags", но она принимает дополнительный параметр после всех остальных, msgs. Если этот параметр равен 0, эта функция работает так же, как и "uvchr_to_utf8_flags". В противном случае, msgs должен быть указателем на переменную HV *, в которой эта функция создаст новый HV для хранения соответствующих сообщений. Хэш содержит три пары ключ-значение следующим образом:

text: Текст сообщения в виде SVpv.
warn_categories: Категория (или категории) предупреждений, упакованная в SVuv.
flag: Единый флаг бита, связанный с этим сообщением, в SVuv . Бит соответствует определённому биту в значении возврата *errors, таком как UNICODE_GOT_SURROGATE.

Важно отметить, что указание этого параметра как не равного нулю приведет к подавлению любых предупреждений, которые эта функция могла бы сгенерировать, и вместо этого помещению их в *msgs. Вызывающий элемент может проверить состояние лексических предупреждений (или нет), чтобы выбрать, что делать с возвращёнными сообщениями.

Конечно, вызывающий элемент отвечает за освобождение возвращённого HV.

U8*     uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags,
                                 HV ** msgs)

Переменные, созданные функциями `xsubpp` и внутренними функциями `xsubpp`

newXSproto

Используется xsubpp для подключения XSUB в качестве Perl подпрограмм. Добавляет Perl прототипы к подпрограммам.

XS_APIVERSION_BOOTCHECK

Макрос для проверки того, что версия API Perl, к которой скомпилирован модуль XS, соответствует версии API интерпретатора Perl, в который он загружается.

XS_APIVERSION_BOOTCHECK;

XS_VERSION

Идентификатор версии модуля XS. Обычно обрабатывается автоматически ExtUtils::MakeMaker. См. "XS_VERSION_BOOTCHECK".

XS_VERSION_BOOTCHECK

Макрос для проверки того, что переменная $VERSION модуля PM соответствует переменной XS_VERSION модуля XS. Обычно обрабатывается автоматически xsubpp. См. "Ключевое слово VERSIONCHECK: в perlxs.

XS_VERSION_BOOTCHECK;

Предупреждения и завершение работы

Во всех этих вызовах параметры U32 wn — это константы категорий предупреждений. Вы можете посмотреть доступные в данный момент в "Иерархия категорий" в warnings, просто запишите все буквы в именах заглавными и добавьте префикс WARN_. Например, категория void в Perl-программе станет WARN_VOID в XS-коде и будет передана одному из вызовов ниже.

ckWARN

Возвращает булево значение, указывающее, включены ли предупреждения для категории предупреждений w. Если категория по умолчанию включена, даже если она не входит в область действия use warnings, используйте вместо этого макрос "ckWARN_d".

bool    ckWARN(U32 w)

ckWARN2

Как "ckWARN", но принимает две категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если любая из категорий по умолчанию включена, даже если она не входит в область действия use warnings, используйте вместо этого макрос "ckWARN2_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN2(U32 w1, U32 w2)

ckWARN3

Как "ckWARN2", но принимает три категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если любая из категорий по умолчанию включена, даже если она не входит в область действия use warnings, используйте вместо этого макрос "ckWARN3_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN3(U32 w1, U32 w2, U32 w3)

ckWARN4

Как "ckWARN3", но принимает четыре категории предупреждений в качестве входных данных и возвращает ИСТИНУ, если хотя бы одна из них включена. Если любая из категорий по умолчанию включена, даже если она не входит в область действия use warnings, используйте вместо этого макрос "ckWARN4_d". Категории должны быть полностью независимыми, одна не может быть подклассом другой.

bool    ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)

ckWARN_d

Как "ckWARN", но предназначен для использования только в том случае, если категория предупреждений по умолчанию включена, даже если она не входит в область действия use warnings.

bool    ckWARN_d(U32 w)

ckWARN2_d

Как "ckWARN2", но предназначен для использования только в том случае, если хотя бы одна категория предупреждений по умолчанию включена, даже если она не входит в область действия use warnings.

bool    ckWARN2_d(U32 w1, U32 w2)

ckWARN3_d

Как "ckWARN3", но предназначен для использования только в том случае, если хотя бы одна из категорий предупреждений по умолчанию включена, даже если она не входит в область действия use warnings.

bool    ckWARN3_d(U32 w1, U32 w2, U32 w3)

ckWARN4_d

Как "ckWARN4", но предназначен для использования только в том случае, если хотя бы одна из категорий предупреждений по умолчанию включена, даже если она не входит в область действия use warnings.

bool    ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)

CLEAR_ERRSV

Очистить содержимое $@, установив его в пустую строку.

Это заменяет любое только для чтения SV свежим SV и удаляет любую магию.

void    CLEAR_ERRSV()

croak

Это интерфейс XS к функции Perl's die.

Принимает шаблон форматирования в стиле sprintf и список аргументов. Они используются для создания сообщения об ошибке. Если сообщение не заканчивается новой строкой, то оно будет дополнено указанием текущей позиции в коде, как описано для "mess_sv".

Сообщение об ошибке будет использовано как исключение, по умолчанию возвращая управление к ближайшему содержащему eval, но подлежит модификации обработчиком $SIG{__DIE__}. В любом случае, функция croak никогда не возвращается нормально.

По историческим причинам, если pat равно null, то содержимое ERRSV ($@) будет использовано как сообщение или объект об ошибке вместо создания сообщения об ошибке из аргументов. Если вы хотите выбросить объект, не являющийся строкой, или создать сообщение об ошибке в самом SV, предпочтительнее использовать функцию "croak_sv", которая не включает в себя перезапись ERRSV.

void    croak(const char* pat, ...)

croak_no_modify

Точно эквивалентно Perl_croak(aTHX_ "%s", PL_no_modify), но генерирует более компактный объектный код, чем использование Perl_croak. Меньше кода в путях обработки исключений уменьшает нагрузку на кэш ЦП.

void    croak_no_modify()

croak_sv

Это интерфейс XS к функции Perl's die.

baseex — это сообщение или объект об ошибке. Если это ссылка, она будет использоваться как есть. В противном случае она используется как строка, а если не заканчивается новой строкой, то дополняется указанием текущей позиции в коде, как описано для "mess_sv".

Сообщение или объект об ошибке будут использованы как исключение, по умолчанию возвращая управление к ближайшему содержащему eval, но подлежит модификации обработчиком $SIG{__DIE__}. В любом случае, функция croak_sv никогда не возвращается нормально.

Для выхода со простым текстовым сообщением, функция "croak" может быть удобнее.

void    croak_sv(SV *baseex)

die

Ведёт себя так же, как "croak", за исключением типа возвращаемого значения. Его следует использовать только там, где требуется тип возврата OP *. Функция фактически никогда не возвращает значение.

OP*     die(const char* pat, ...)

die_sv

Ведёт себя так же, как "croak_sv", за исключением типа возвращаемого значения. Его следует использовать только там, где требуется тип возврата OP *. Функция фактически никогда не возвращает значение.

OP*     die_sv(SV *baseex)

ERRSV

Возвращает SV для $@, создавая его при необходимости.

SV *    ERRSV

my_setenv

Обёртка для библиотечной функции C setenv(3). Не используйте последнюю, так как версия Perl имеет желательные меры предосторожности

void    my_setenv(const char* nam, const char* val)

rsignal

Обёртка для библиотечной функции C signal(2). Не используйте последнюю, так как версия Perl знает вещи, которые взаимодействуют с остальной частью интерпретатора Perl.

Sighandler_t rsignal(int i, Sighandler_t t)

SANE_ERRSV

Очистить ERRSV, чтобы мы могли безопасно его установить.

Это заменяет любое только для чтения SV свежей копией для записи и удаляет любую магию.

void    SANE_ERRSV()

vcroak

Это интерфейс XS к функции Perl's die.

pat и args представляют шаблон форматирования в стиле sprintf и инкапсулированный список аргументов. Они используются для создания сообщения об ошибке. Если сообщение не заканчивается новой строкой, оно будет дополнено указанием текущей позиции в коде, как описано для "mess_sv".

По историческим причинам, если pat равно null, то содержимое ERRSV ($@) будет использовано как сообщение об ошибке или объект вместо создания сообщения об ошибке из аргументов. Если вы хотите выбросить объект, не являющийся строкой, или создать сообщение об ошибке в самом SV, предпочтительнее использовать функцию "croak_sv", которая не включает в себя перезапись ERRSV.

void    vcroak(const char* pat, va_list* args)

vwarn

Это интерфейс XS к функции Perl's warn.

pat и args представляют собой шаблон форматирования в стиле sprintf и инкапсулированный список аргументов. Они используются для создания сообщения об ошибке. Если сообщение не заканчивается новой строкой, оно будет дополнено указанием текущей позиции в коде, как описано для "mess_sv".

Сообщение об ошибке или объект по умолчанию будут записаны в стандартный поток ошибок, но это подлежит модификации обработчиком $SIG{__WARN__}.

В отличие от "vcroak", pat не может быть null.

void    vwarn(const char* pat, va_list* args)

warn

Это интерфейс XS к функции Perl's warn.

В отличие от "croak", pat не может быть null.

void    warn(const char* pat, ...)

warn_sv

Это интерфейс XS к функции Perl's warn.

baseex — это сообщение или объект об ошибке. Если это ссылка, она будет использоваться как есть. В противном случае она используется как строка, и если не заканчивается новой строкой, то дополняется указанием текущей позиции в коде, как описано для "mess_sv".

Для вывода предупреждения с простым текстовым сообщением, функция "warn" может быть удобнее.

void    warn_sv(SV *baseex)

Функции без документации

Следующие функции были помечены как часть публичного API, но в настоящее время не задокументированы. Используйте их на свой страх и риск, так как интерфейсы могут быть изменены. Функции, которые не указаны в этом документе, не предназначены для публичного использования и НЕ должны использоваться ни при каких обстоятельствах.

Если вам кажется, что вам необходимо использовать одну из этих функций, отправьте электронное письмо по адресу perl5-porters@perl.org. Возможно, есть веская причина, по которой функция не задокументирована, и её следует удалить из этого списка; или может быть, просто никто ещё не добрался до её документации. В последнем случае вас попросят отправить патч с документацией функции. После принятия вашего патча интерфейс будет считаться стабильным (если явно не указано иное) и пригодным для использования.

CvDEPTH
CvGV
GetVars
Gv_AMupdate
PerlIO_close
PerlIO_context_layers
PerlIO_error
PerlIO_fill
PerlIO_flush
PerlIO_get_bufsiz
PerlIO_get_ptr
PerlIO_read
PerlIO_seek
PerlIO_set_cnt
PerlIO_setlinebuf
PerlIO_stdout
PerlIO_unread
SvAMAGIC_off
SvAMAGIC_on
amagic_call
amagic_deref_call
any_dup
atfork_lock
atfork_unlock
av_arylen_p
av_iter_p
block_gimme
call_atexit
call_list
calloc
cast_i32
cast_iv
cast_ulong
cast_uv
ck_warner
ck_warner_d
ckwarn
ckwarn_d
clear_defarray
clone_params_del
clone_params_new
croak_nocontext
csighandler
csighandler1
csighandler3
cx_dump
cx_dup
cxinc
deb
deb_nocontext
debop
debprofdump
debstack
debstackptrs
delimcpy
despatch_signals
die_nocontext
dirp_dup
do_aspawn
do_close
do_gv_dump
do_gvgv_dump
do_hv_dump
do_join
do_magic_dump
do_op_dump
do_open
do_openn
do_pmop_dump
do_spawn
do_spawn_nowait
do_sprintf
do_sv_dump
doing_taint
doref
dounwind
dowantarray
dump_eval
dump_form
dump_indent
dump_mstats
dump_sub
dump_vindent
filter_del
filter_read
foldEQ_latin1
form_nocontext
fp_dup
free_global_struct
free_tmps
get_context
get_mstats
get_op_descs
get_op_names
get_ppaddr
get_vtbl
gp_dup
gp_free
gp_ref
gv_AVadd
gv_HVadd
gv_IOadd
gv_SVadd
gv_add_by_type
gv_autoload4
gv_autoload_pv
gv_autoload_pvn
gv_autoload_sv
gv_check
gv_dump
gv_efullname3
gv_efullname4
gv_fetchfile
gv_fetchfile_flags
gv_fetchpv
gv_fetchpvn_flags
gv_fetchsv
gv_fullname3
gv_fullname4
gv_handler
gv_name_set
he_dup
hek_dup
hv_common
hv_common_key_len
hv_delayfree_ent
hv_eiter_p
hv_eiter_set
hv_free_ent
hv_ksplit
hv_name_set
hv_placeholders_get
hv_placeholders_set
hv_rand_set
hv_riter_p
hv_riter_set
ibcmp_utf8
init_global_struct
init_stacks
init_tm
is_lvalue_sub
leave_scope
load_module_nocontext
magic_dump
markstack_grow
mess_nocontext
mfree
mg_dup
mg_size
mini_mktime
moreswitches
mro_get_from_name
mro_set_mro
mro_set_private_data
my_atof
my_chsize
my_cxt_index
my_cxt_init
my_dirfd
my_failure_exit
my_fflush_all
my_fork
my_lstat
my_pclose
my_popen
my_popen_list
my_socketpair
my_stat
my_strftime
newANONATTRSUB
newANONHASH
newANONLIST
newANONSUB
newATTRSUB
newAVREF
newCVREF
newFORM
newGVREF
newGVgen
newGVgen_flags
newHVREF
newHVhv
newIO
newMYSUB
newPROG
newRV
newSUB
newSVREF
newSVpvf_nocontext
newSVsv_flags
new_stackinfo
op_refcnt_lock
op_refcnt_unlock
parser_dup
perl_alloc_using
perl_clone_using
perly_sighandler
pmop_dump
pop_scope
pregcomp
pregexec
pregfree
pregfree2
ptr_table_fetch
ptr_table_free
ptr_table_new
ptr_table_split
ptr_table_store
push_scope
re_compile
re_dup_guts
reentrant_free
reentrant_init
reentrant_retry
reentrant_size
ref
reg_named_buff_all
reg_named_buff_exists
reg_named_buff_fetch
reg_named_buff_firstkey
reg_named_buff_nextkey
reg_named_buff_scalar
regdump
regdupe_internal
regexec_flags
regfree_internal
reginitcolors
regnext
repeatcpy
rsignal_state
runops_debug
runops_standard
rvpv_dup
safesyscalloc
safesysfree
safesysmalloc
safesysrealloc
save_I16
save_I32
save_I8
save_adelete
save_aelem
save_aelem_flags
save_alloc
save_ary
save_bool
save_clearsv
save_delete
save_destructor
save_destructor_x
save_freeop
save_freepv
save_freesv
save_generic_pvref
save_generic_svref
save_hdelete
save_helem
save_helem_flags
save_hints
save_hptr
save_int
save_item
save_iv
save_mortalizesv
save_op
save_padsv_and_mortalize
save_pptr
save_pushi32ptr
save_pushptr
save_pushptrptr
save_re_context
save_set_svflags
save_shared_pvref
save_sptr
save_svref
save_vptr
savestack_grow
savestack_grow_cnt
scan_num
scan_vstring
seed
set_context
share_hek
si_dup
ss_dup
stack_grow
start_subparse
str_to_version
sv_2iv
sv_2pv
sv_2pvbyte_flags
sv_2pvutf8_flags
sv_2uv
sv_catpvf_mg_nocontext
sv_catpvf_nocontext
sv_dup
sv_dup_inc
sv_peek
sv_setpvf_mg_nocontext
sv_setpvf_nocontext
sys_init
sys_init3

END_OF_DOCUMENT_MARKER

sys_intern_clear
sys_intern_dup
sys_intern_init
sys_term
taint_env
taint_proper
unlnk
unsharepvn
vdeb
vform
vload_module
vnewSVpvf
vwarner
warn_nocontext
warner
warner_nocontext
whichsig
whichsig_pv
whichsig_pvn
whichsig_sv

АВТОРЫ

До мая 1997 года этот документ поддерживал Джефф Окамото <okamoto@corp.hp.com>. Сейчас он поддерживается в рамках самого Perl.

С большой помощью и предложениями от Дина Роэриха, Малькольма Битти, Андреаса Кёнига, Пола Хадсона, Ильи Захаревича, Пола Маркесса, Нила Боуэрса, Мэттью Грина, Тима Банса, Спайдер Бордмана, Ульриха Пфайфера, Стивена МакКэманта и Гурусами Сарати.

Список API первоначально был составлен Дином Роэрихом <roehrich@cray.com>.

Обновлено, чтобы автоматически генерироваться из комментариев в исходном коде, Бенджамином Штулем.

© 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/perlapi

perlapi

СОДЕРЖАНИЕ

НАЗВАНИЕ

ОПИСАНИЕ

Функции обработки массивов

Функции обратного вызова

Изменение регистра символов

Классификация символов

Клонирование интерпретатора

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

Хеши подсказок COP

Чтение подсказок COP

Операторы-пользователя

Функции манипулирования CV

xsubpp переменные и внутренние функции

Утилиты отладки

Функции отображения и вывода

Встраиваемые функции

Обработка исключений (простые) макросы

Функции в файле vutil.c

Значения "Gimme"

Глобальные переменные

Функции GV

Полезные значения

Функции управления хешами

Работа с крючками

Интерфейс лексического анализатора

Функции и макросы, связанные с языковым окружением

Магические функции

Управление памятью

Функции прочие

Функции MRO

Функции Multicall

Числовые функции

Функции устаревшей обратной совместимости

Построение Optree

Функции манипулирования Optree

Упаковщики и распаковщики

Структуры данных с заполнителями

Переменные на интерпретатор

Функции REGEXP

Макросы управления стеком

Флаги SV

Функции обработки SV

Поддержка Юникода

Переменные, созданные функциями xsubpp и внутренними функциями xsubpp

Предупреждения и завершение работы

Функции без документации

АВТОРЫ

СМОТРИТЕ ТАКЖЕ

`xsubpp` переменные и внутренние функции

Переменные, созданные функциями `xsubpp` и внутренними функциями `xsubpp`