re

СОДЕРЖАНИЕ

• ИМЯ
• СИНОПСИС
• ОПИСАНИЕ
  • режим 'taint'
  • режим 'eval'
  • режим 'strict'
  • режим '/flags'
  • режим 'debug'
  • режим 'Debug'
  • Экспортируемые функции
• СМОТРИТЕ ТАКЖЕ

ИМЯ

re - Perl-pragma для изменения поведения регулярных выражений

СИНОПСИС

use re 'taint';
($x) = ($^X =~ /^(.*)$/s);     # $x is tainted here

$pat = '(?{ $foo = 1 })';
use re 'eval';
/foo${pat}bar/;                # won't fail (when not under -T
                               # switch)

{
    no re 'taint';             # the default
    ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here

    no re 'eval';              # the default
    /foo${pat}bar/;            # disallowed (with or without -T
                               # switch)
}

use re 'strict';               # Raise warnings for more conditions

use re '/ix';
"FOO" =~ / foo /; # /ix implied
no re '/x';
"FOO" =~ /foo/; # just /i implied

use re 'debug';                # output debugging info during
/^(.*)$/s;                     # compile and run time


use re 'debugcolor';           # same as 'debug', but with colored
                               # output
...

use re qw(Debug All);          # Same as "use re 'debug'", but you
                               # can use "Debug" with things other
                               # than 'All'
use re qw(Debug More);         # 'All' plus output more details
no re qw(Debug ALL);           # Turn on (almost) all re debugging
                               # in this scope

use re qw(is_regexp regexp_pattern); # import utility functions
my ($pat,$mods)=regexp_pattern(qr/foo/i);
if (is_regexp($obj)) {
    print "Got regexp: ",
        scalar regexp_pattern($obj); # just as perl would stringify
}                                    # it but no hassle with blessed
                                     # re's.

(В этих примерах используется $^X, так как он по умолчанию является заражённым.)

ОПИСАНИЕ

режим 'taint'

Когда use re 'taint' активен, и заражённая строка является целевой для регулярного выражения, памяти регулярного выражения (или значения, возвращаемые оператором m// в контексте списка) также заражаются. Эта функция полезна, когда операции с регулярными выражениями над заражёнными данными не предназначены для извлечения безопасных подстрок, а для выполнения других преобразований.

режим 'eval'

Когда use re 'eval' активен, регулярное выражение может содержать (?{ ... }) утверждения нулевой ширины и (??{ ... }) отложенные подвыражения, полученные из интерполяции переменных, а не появляться буквально в регулярном выражении. Обычно это запрещено, поскольку это потенциальный риск для безопасности. Обратите внимание, что это pragma игнорируется, когда регулярное выражение получено из заражённых данных, т.е. вычисление всегда запрещено для заражённых регулярных выражений. См. "(?{ code })" в perlre и "(??{ code })" в perlre.

Для целей данного pragma интерполяция предварительно скомпилированных регулярных выражений (т.е., результат qr//) не считается интерполяцией переменных. Таким образом:

/foo${pat}bar/

разрешено, если $pat — предварительно скомпилированное регулярное выражение, даже если $pat содержит (?{ ... }) утверждения или (??{ ... }) подвыражения.

режим 'strict'

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

Когда use re 'strict' активен, применяются более строгие проверки при компиляции шаблонов регулярных выражений. Это может привести к появлению большего числа предупреждений, чем обычно, и к более серьёзным ошибкам, вместо просто предупреждений. Цель этого — найти и сообщить о некоторых вещах во время компиляции, которые могут быть допустимы, но имеют разумную вероятность не соответствовать предполагаемому намерению программиста. Это автоматически включает категорию предупреждений "regexp" (если она ещё не включена) в пределах своего действия.

Например, такой шаблон

qr/\xABC/

Конструкции "\x" без фигурных скобок должны следовать ровно двум шестнадцатеричным цифрам; этот шаблон следует трём. В настоящее время это эквивалентно

qr/\x{AB}C/

то есть символ с кодовым значением 0xAB, за которым следует буква C. Но поскольку C является шестнадцатеричной цифрой, существует вероятность, что предполагалось

qr/\x{ABC}/

то есть одиночный символ в позиции 0xABC. В режиме 'strict' считаем ошибкой не следовать за \x ровно двумя шестнадцатеричными цифрами. В режиме без 'strict' генерируется предупреждение, если есть только одна шестнадцатеричная цифра, и не генерируется, если их больше двух.

Ожидается, что то, как именно 'strict' будет работать, будет развиваться со временем, поскольку мы будем накапливать опыт. Это означает, что программы, которые компилируются с ним в сегодняшнем Perl, могут не компилироваться или могут иметь больше или меньше предупреждений в будущих версиях Perl. Нет никаких гарантий обратной совместимости по этому вопросу. Кроме того, уже существуют предложения по альтернативному синтаксису для его включения. По этим причинам его использование вызовет предупреждение класса experimental::re_strict, если эта категория не отключена.

Обратите внимание, что если шаблон, скомпилированный в режиме 'strict', перекомпилируется, скажем, путём интерполяции в другой шаблон, вне режима 'strict', он не проверяется на строгость повторно. Это потому, что если он работает в строгом режиме, он должен работать и в нестрогом.

режим '/flags'

При указании use re '/flags', заданные флаги автоматически добавляются к каждому регулярному выражению до конца лексической области. Флаги могут быть любой комбинацией 'a', 'aa', 'd', 'i', 'l', 'm', 'n', 'p', 's', 'u', 'x', и/или 'xx'.

no re '/flags' отключит действие use re '/flags' для заданных флагов.

Например, если вы хотите, чтобы все ваши регулярные выражения по умолчанию имели /msxx, просто поместите

use re '/msxx';

вверху вашего кода.

Множество флагов множеств символов /adul взаимно исключают друг друга. Таким образом, в этом примере

use re "/u";
"ss" =~ /\xdf/;
use re "/d";
"ss" =~ /\xdf/;

второе use re выполняет неявное no re '/u'.

Аналогично

use re "/xx";   # Doubled-x
...
use re "/x";    # Single x from here on
...

Включение одного из флагов набора символов с помощью use re имеет приоритет над locale pragma и feature pragma 'unicode_strings' для регулярных выражений. Отключение одного из этих флагов при его активации возвращает поведение, заданное другими pragmas. Например:

use feature "unicode_strings";
no re "/u"; # does nothing
use re "/l";
no re "/l"; # reverts to unicode_strings behaviour

режим 'debug'

При активации use re 'debug' perl выводит сообщения отладки при компиляции и использовании регулярных выражений. Вывод соответствует тому, что получается при запуске интерпретатора perl с включённой отладкой регулярных выражений (-Dr). Он может быть довольно объёмным в зависимости от сложности совпадения. Использование debugcolor вместо debug позволяет получить вывод, который можно использовать для получения красочного отображения на терминалах, понимающих цветные последовательности termcap. Установите $ENV{PERL_RE_TC} в список через запятую termcap свойств для включения/выключения подсветки строк, частей до точки. См. "Отладка регулярных выражений" в perldebug для дополнительной информации.

ПРИМЕЧАНИЕ, что точный формат режима debug НЕ считается официально поддерживаемым API Perl. Он предназначен только для отладки и может измениться по мере того, как основная команда разработчиков сочтёт необходимым без предварительного уведомления или устаревания в любом выпуске Perl, главном или второстепенном. Любое описание вывода носит чисто рекомендательный характер.

С версии 5.9.5 директива use re 'debug' и её аналоги имеют лексический охват, как и другие директивы. Однако у них есть как эффекты времени компиляции, так и времени выполнения.

См. "Pragmatic Modules" в perlmodlib.

режим 'Debug'

Аналогично, use re 'Debug' генерирует вывод отладки, разница в том, что он позволяет тонко настроить выводимые сообщения отладки. Опции разделены на три группы: связанные с компиляцией, связанные с выполнением и связанные со специальными целями.

ПРИМЕЧАНИЕ, что опции, предоставляемые в режиме Debug, и точный формат создаваемого ими вывода НЕ считаются официально поддерживаемым API Perl. Они предназначены только для отладки и могут измениться по мере того, как основная команда разработчиков сочтёт необходимым без предварительного уведомления или устаревания в любом выпуске Perl, главном или второстепенном. Любое описание формата или доступных опций носит лишь рекомендательный характер и может измениться без предварительного уведомления.

Доступные опции:

Параметры, связанные с компиляцией

COMPILE

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

PARSE

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

OPTIMISE

Включает вывод, связанный с фазой оптимизации компиляции.

TRIEC

Подробная информация о компиляции trie.

DUMP

Вывести итоговую программу после компиляции и оптимизации.

FLAGS

Вывести флаги, связанные с программой.

TEST

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

Параметры, связанные с выполнением

EXECUTE

Включает все параметры отладки, связанные с выполнением, кроме дополнительных.

MATCH

Включает отладку основного цикла сопоставления.

TRIEE

Дополнительная отладка выполнения trie.

INTUIT

Включить отладку оптимизаций начальной точки.

Дополнительные параметры отладки

EXTRA

Включает все дополнительные параметры отладки.

BUFFERS

Включить отладку хранения групп захвата во время сопоставления. Предупреждение: это может привести к очень большому выводу.

TRIEM

Включить расширенную отладку TRIE. Расширяет как TRIEE, так и TRIEC.

STATE

Включить отладку состояний в движке.

STACK

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

GPOS

Включить отладку модификатора \G.

OPTIMISEM

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

DUMP_PRE_OPTIMIZE

Включить вывод скомпилированного шаблона перед фазой оптимизации.

WILDCARD

Когда Perl сталкивается с подшаблоном со «звездочкой» (см. "Звездочки в значениях свойств" в perlunicode), он приостанавливает компиляцию основного шаблона, компилирует подшаблон и затем сопоставляет его со всеми допустимыми возможностями, чтобы определить фактические код-точки, которые подшаблон соответствует. После этого он добавляет их к основному шаблону и продолжает свою компиляцию.

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

Вы можете использовать параметр WILDCARD, чтобы включить вывод отладки этого сопоставления подшаблонов. Осторожно! Это может привести к большим выводам, и вам может быть непонятно, что и почему Perl делает то, что делает. Но это может быть полезно, чтобы понять, почему вещи не происходят так, как вы ожидаете.

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

Другие полезные флаги

Это полезные сокращения для экономии времени набора.

ALL

Включить все параметры сразу, кроме BUFFERS, WILDCARD и DUMP_PRE_OPTIMIZE. (Чтобы получить каждый параметр без исключения, используйте ALL и EXTRA или, начиная с 5.30 на -DDEBUGGING-активированном интерпретаторе Perl, используйте командные переключатели -Drv.)

All

Включить DUMP и все параметры выполнения, кроме дополнительных. Эквивалентно:

use re 'debug';

MORE

More

Включить параметры, включенные в «All», плюс STATE, TRIEC и TRIEM.

Начиная с версии 5.9.5, директива use re 'debug' и её аналоги имеют лексический объем, как и другие директивы. Однако они имеют как компиляционные, так и выполняемые эффекты.

Экспортируемые функции

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

is_regexp($ref)

Возвращает true, если аргумент является скомпилированным регулярным выражением, как возвращается qr//, и false, если нет.

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

regexp_pattern($ref)

Если аргумент является скомпилированным регулярным выражением, как возвращается qr//, то эта функция возвращает шаблон.

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

my ($pat, $mods) = regexp_pattern($ref);

В скалярном контексте она возвращает то же, что и perl при строковом представлении необработанного qr// с тем же шаблоном внутри. Если аргумент не является скомпилированной ссылкой, эта процедура возвращает false, но определённую в скалярном контексте, и пустой список в контексте списка. Таким образом, следующее

if (regexp_pattern($ref) eq '(?^i:foo)')

будет предупреждать независимо от того, что на самом деле является $ref.

Как is_regexp эта функция не будет вводиться в заблуждение перегрузкой или благословением объекта.

regname($name,$all)

Возвращает содержимое именованного буфера последнего успешного совпадения. Если $all истинно, то возвращает массив ссылок, содержащий по одной записи на буфер; в противном случае возвращает первый определённый буфер.

regnames($all)

Возвращает список всех именованных буферов, определённых в последнем успешном совпадении. Если $all истинно, то возвращает все определённые имена; в противном случае возвращает только имена, которые были задействованы в совпадении.

regnames_count()

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

Примечание: этот результат всегда является фактическим количеством различных именованных буферов, определённых, он может не соответствовать тому, что возвращается regnames() и связанными процедурами, когда эти процедуры не были вызваны с установленным параметром $all.

regmust($ref)

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

Фиксированная строка определяется как подстрока, которая должна появиться для соответствия шаблону. Закреплённая фиксированная строка — это фиксированная строка, которая должна появиться в определённом смещении от начала совпадения. Плавающая фиксированная строка определяется как фиксированная строка, которая может появиться в любой точке в диапазоне позиций относительно начала совпадения. Например,

my $qr = qr/here .* there/x;
my ($anchored, $floating) = regmust($qr);
print "anchored:'$anchored'\nfloating:'$floating'\n";

результаты в

anchored:'here'
floating:'there'

Потому что here находится перед .* в шаблоне, её положение можно определить точно. Однако это неверно для there; она может появиться в любой точке после того, где появилась закреплённая строка. Perl использует оба для оптимизации, отдавая предпочтение более длинной или, если они равны, плавающей.

ПРИМЕЧАНИЕ: Это необязательно может быть окончательно самой длинной закреплённой и плавающей строкой. Это будет тем, что оптимизатор используемого Perl считает самым длинным. Если вы считаете, что результат неверен, сообщите об этом с помощью утилиты perlbug.

optimization($ref)

Если аргумент является скомпилированным регулярным выражением, как возвращается qr//, то эта функция возвращает hashref с информацией об оптимизации, обнаруженной во время компиляции, чтобы мы могли писать тесты вокруг неё. Если предоставлен любой другой аргумент, возвращает undef.

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

Для текущей версии хэш будет иметь следующее содержимое:

minlen

Целое число, минимальное количество символов в любой строке, которая может соответствовать.

minlenret

Целое число, минимальное количество символов, которое может находиться в $& после совпадения. (Рассмотрите, например, /ns(?=\d)/ .)

gofs

Целое число, количество символов перед pos() для начала совпадения.

noscan

Булево значение, TRUE указывает, что любые закреплённые/плавающие подстроки, найденные, не должны использоваться. (CHECKME: по-видимому, это установлено для закреплённого шаблона без плавающей подстроки, но никогда не используется.)

isall

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

anchor SBOL

Булево значение, TRUE если шаблон закреплён в начале строки.

anchor MBOL

Булево значение, TRUE если шаблон закреплён в любом начале строки в строке.

anchor GPOS

Булево значение, TRUE если шаблон закреплён в конце предыдущего совпадения.

skip

Булево значение, TRUE если начальный класс может совпадать только с первым в последовательности.

implicit

Булево значение, TRUE если /.*/ было неявно преобразовано в /^.*/.

anchored/floating

Строка байтов, представляющая закреплённую или плавающую подстроку соответственно, которую должно содержать любое совпадение, или undef, если такая подстрока не найдена, или если подстрока требует utf8 для представления.

anchored utf8/floating utf8

Строка utf8, представляющая закреплённую или плавающую подстроку соответственно, которую должно содержать любое совпадение, или undef, если такая подстрока не найдена, или если подстрока содержит только символы ASCII 7-битного кодирования.

anchored min offset/floating min offset

Целое число, первое смещение в символах от места совпадения, в котором мы должны искать соответствующую подстроку.

anchored max offset/floating max offset

Целое число, последнее смещение в символах от места совпадения, в котором мы должны искать соответствующую подстроку.

Игнорируется для закреплённого, поэтому может быть 0 или таким же, как минимум.

anchored end shift/floating end shift

FIXME: не уверен, что это такое, что-то связанное с lookbehind. regcomp.c говорит: Когда окончательный шаблон компилируется и данные перемещаются из структуры scan_data_t в структуру regexp, информация о lookbehind учитывается, а информация, которая была бы потеряна, предварительно вычисляется в поле end_shift для связанной строки.

checking

Константная строка, одна из «anchored», «floating» или «none», указывающая, какая подстрока (если есть) должна проверяться в первую очередь.

stclass

Строковое представление символьного класса («начальный класс»), которое должно быть первым символом любого совпадения.

TODO: объяснить представления.

SEE ALSO

"Практические модули" в perlmodlib.