Исходный код Regex

Предоставляет регулярные выражения для Elixir.

Regex основан на PCRE (Perl Compatible Regular Expressions) и построен поверх модуля Erlang :re. Дополнительную информацию можно найти в документации модуля :re.

Регулярные выражения в Elixir можно создавать, используя сигилы ~r (см. sigil_r/2):

# A simple regular expression that matches foo anywhere in the string
~r/foo/

# A regular expression with case insensitive and Unicode options
~r/foo/iu

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

Regex представляется во внутренней структуре в виде структуры Regex. Поэтому, %Regex{} можно использовать всякий раз, когда нужно выполнить сопоставление с ними. Имейте в виду, что все поля структур являются закрытыми. Также нет гарантии, что два регулярных выражения из одного источника равны, например:

~r/(?<foo>.)(?<bar>.)/ == ~r/(?<foo>.)(?<bar>.)/

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

~r/(?<foo>.)(?<bar>.)/.source == ~r/(?<foo>.)(?<bar>.)/.source

Экранирование

Последовательности экранирования делятся на две категории.

Непечатаемые символы

\a - Звуковой сигнал, то есть символ BEL (шестнадцатерично 07)
\e - Экранирование (шестнадцатерично 1B)
\f - Формативный символ (шестнадцатерично 0C)
\n - Перевод строки (шестнадцатерично 0A)
\r - Возврат каретки (шестнадцатерично 0D)
\t - Табуляция (шестнадцатерично 09)
\xhh - Символ с шестнадцатеричным кодом hh
\x{hhh..} - Символ с шестнадцатеричным кодом hhh..

\u и \U не поддерживаются. Другие последовательности экранирования, такие как \ddd для восьмеричных кодов, поддерживаются, но не рекомендуются.

Общие типы символов

\d - Любая десятичная цифра
\D - Любой символ, который не является десятичной цифрой
\h - Любой символ горизонтальной вкладки
\H - Любой символ, который не является символом горизонтальной вкладки
\s - Любой символ пробела
\S - Любой символ, который не является символом пробела
\v - Любой символ вертикальной вкладки
\V - Любой символ, который не является символом вертикальной вкладки
\w - Любой символ "слова"
\W - Любой символ "не слова"

Модификаторы

Доступные модификаторы при создании Regex:

:unicode (u) - включает Unicode-специфичные шаблоны, такие как \p и заставляет классы символов, такие как \w, \W, \s, и т. п., также соответствовать Unicode (см. примеры ниже в разделе «Классы символов»). Ожидает, что при сопоставлении будут предоставлены допустимые строки Unicode.
:caseless (i) - добавляет отсутствие учета регистра
:dotall (s) - заставляет точку соответствовать символам новой строки, а также устанавливает новую строку в любой CRLF; настройка новой строки может быть переопределена установкой (*CR) или (*LF) или (*CRLF) или (*ANY) в соответствии с документацией :re
:multiline (m) - заставляет ^ и $ отмечать начало и конец каждой строки; используйте \A и \z для соответствия концу или началу строки
:extended (x) - символы пробела игнорируются, кроме случаев экранирования или внутри [..], и позволяют # разделять комментарии
:firstline (f) - принудительно заставляет неявный шаблон соответствовать символу новой строки до или на первом символе новой строки, хотя совпадающий текст может продолжаться через символ новой строки
:ungreedy (U) - инвертирует «жадность» регулярного выражения (предыдущий параметр r устарел в пользу U).

Недоступные параметры:

:anchored - недоступен, используйте ^ или \A вместо этого
:dollar_endonly - недоступен, используйте \z вместо этого
:no_auto_capture - недоступен, используйте ?: вместо этого
:newline - недоступен, используйте (*CR) или (*LF) или (*CRLF) или (*ANYCRLF) или (*ANY) в начале регулярного выражения согласно документации :re

Захват

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

:all - все захваченные подшаблоны, включая полную совпадающую строку (это значение по умолчанию)
:first - только первый захваченный подшаблон, который всегда является полным совпадающим фрагментом строки; все явно захваченные подшаблоны отбрасываются
:all_but_first - все, кроме первого совпадающего подшаблона, т. е. все явно захваченные подшаблоны, но не полная совпадающая часть строки
:none - не возвращает совпадающие подшаблоны вообще
:all_names - захватывает все совпадения именованных подшаблонов в Regex в виде списка, упорядоченного по алфавиту по именам подшаблонов
list(binary | atom) - список именованных захватов для захвата

Классы символов

Regex поддерживает несколько встроенных именованных классов символов. Они используются путем помещения имени класса в [: :] внутри группы. Например:

iex> String.match?("123", ~r/^[[:alnum:]]+$/)
true
iex> String.match?("123 456", ~r/^[[:alnum:][:blank:]]+$/)
true

Поддерживаемые имена классов:

alnum - Буквы и цифры
alpha - Буквы
blank - Только пробел или табуляция
cntrl - Управляющие символы
digit - Десятичные цифры (также как \d)
graph - Печатаемые символы, за исключением пробела
lower - Строчные буквы
print - Печатаемые символы, включая пробел
punct - Печатаемые символы, исключая буквы, цифры и пробел
space - Пробелы (так же, как \s из PCRE 8.34)
upper - Прописные буквы
word - Символы "слова" (также как \w)
xdigit - Шестнадцатеричные цифры

Существует другой класс символов, ascii, который ошибочно соответствует символам Latin-1 вместо диапазона 0-127, указанного POSIX. Это невозможно исправить без изменения поведения других классов, поэтому мы рекомендуем соответствовать диапазону с [\\0-\x7f] вместо этого.

Обратите внимание, что поведение этих классов может изменяться в зависимости от Unicode и других модификаторов:

iex> String.match?("josé", ~r/^[[:lower:]]+$/)
false
iex> String.match?("josé", ~r/^[[:lower:]]+$/u)
true
iex> Regex.replace(~r/\s/, "Unicode\u00A0spaces", "-")
"Unicode spaces"
iex> Regex.replace(~r/\s/u, "Unicode\u00A0spaces", "-")
"Unicode-spaces"

Предварительная компиляция

Регулярные выражения, созданные с помощью сигила, предварительно компилируются и хранятся в файлах .beam. Предварительно скомпилированные регулярные выражения будут проверятся во время выполнения и могут работать медленнее между операционными системами и выпусками OTP. Это редко является проблемой, так как большая часть кода Elixir, используемого во время разработки, компилируется на целевой системе (такие как зависимости, архивы и скрипты escript), а при работе в рабочей среде код должен быть либо скомпилирован на целевой системе (через mix compile или аналогично), либо выпущен на хосте (через mix releases или аналогично) с соответствующей версией OTP, операционной системой и архитектурой, как на целевой системе.

Если вы знаете, что работаете на другой системе, чем текущая, и выполняете несколько сопоставлений с регулярным выражением, вы можете вручную вызвать Regex.recompile/1 или Regex.recompile!/1, чтобы выполнить проверку версии во время выполнения и перекомпилировать регулярное выражение при необходимости.

Краткое описание

Типы

t()

Функции

compile(source, opts \\ ""): Компилирует регулярное выражение.
compile!(source, options \\ ""): Компилирует регулярное выражение и вызывает Regex.CompileError в случае ошибок.
escape(string): Экранирует строку для буквального соответствия в регулярном выражении.
match?(regex, string): Возвращает булево значение, указывающее, было ли совпадение.
named_captures(regex, string, options \\ []): Возвращает заданные захватчики в виде карты или nil в случае отсутствия захватов.
names(regex): Возвращает список имён в регулярном выражении.
opts(regex): Возвращает параметры регулярного выражения.
re_pattern(regex): Возвращает базовое re_pattern в регулярном выражении.
recompile(regex): Перекомпилирует существующее регулярное выражение при необходимости.
recompile!(regex): Перекомпилирует существующее регулярное выражение и вызывает Regex.CompileError в случае ошибок.
replace(regex, string, replacement, options \\ []): Получает регулярное выражение, двоичную строку и замену, возвращает новую двоичную строку, где все совпадения заменены заменой.
run(regex, string, options \\ []): Выполняет регулярное выражение на заданной строке до первого совпадения. Возвращает список со всеми захваченными группами или nil в случае отсутствия совпадения.
scan(regex, string, options \\ []): То же, что и run/3, но возвращает все неперекрывающиеся совпадения регулярного выражения.
source(regex): Возвращает исходный код регулярного выражения в виде двоичной строки.
split(regex, string, options \\ []): Разбивает заданную строку по заданному шаблону на заданное количество частей.
version(): Возвращает версию базового движка регулярных выражений.

Типы

t()Source

@type t() :: %Regex{
  opts: binary() | [term()],
  re_pattern: term(),
  re_version: term(),
  source: binary()
}

Функции

compile(source, opts \\ "")Source

@spec compile(binary(), binary() | [term()]) :: {:ok, t()} | {:error, any()}

Компилирует регулярное выражение.

Указанные опции могут быть либо двоичной строкой с символами, представляющими те же опции регулярного выражения, что и для сигила ~r (см. sigil_r/2), либо списком опций, как ожидается модулем Erlang's :re.

Возвращает {:ok, regex} в случае успеха, {:error, reason} в противном случае.

Примеры

iex> Regex.compile("foo")
{:ok, ~r/foo/}

iex> Regex.compile("*foo")
{:error, {~c"nothing to repeat", 0}}

iex> Regex.compile("foo", "i")
{:ok, ~r/foo/i}

iex> Regex.compile("foo", [:caseless])
{:ok, Regex.compile!("foo", [:caseless])}

compile!(source, options \\ "")Source

@spec compile!(binary(), binary() | [term()]) :: t()

Компилирует регулярное выражение и вызывает исключение Regex.CompileError в случае ошибок.

escape(string)Source

@spec escape(String.t()) :: String.t()

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

Примеры

iex> Regex.escape(".")
"\\."

iex> Regex.escape("\\what if")
"\\\\what\\ if"

match?(regex, string)Source

@spec match?(t(), String.t()) :: boolean()

Возвращает логическое значение, указывающее, было ли совпадение или нет.

Примеры

iex> Regex.match?(~r/foo/, "foo")
true

iex> Regex.match?(~r/foo/, "bar")
false

Elixir также предоставляет текстовый оператор сопоставления =~/2 и функцию String.match?/2 в качестве альтернативы для проверки строк на соответствие регулярным выражениям и строкам.

named_captures(regex, string, options \\ [])Source

@spec named_captures(t(), String.t(), [term()]) :: map() | nil

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

Опции

:return - при установке в :index возвращает индекс байта и длину совпадения. По умолчанию :binary.

Примеры

iex> Regex.named_captures(~r/c(?<foo>d)/, "abcd")
%{"foo" => "d"}

iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/, "abcd")
%{"bar" => "d", "foo" => "b"}

iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/, "efgh")
nil

names(regex)Source

@spec names(t()) :: [String.t()]

Возвращает список имён в регулярном выражении.

Примеры

iex> Regex.names(~r/(?<foo>bar)/)
["foo"]

opts(regex)Source

@spec opts(t()) :: [term()]

Возвращает опции регулярного выражения.

См. документацию Regex.compile/2 для получения дополнительной информации.

Примеры

iex> Regex.opts(~r/foo/m)
[:multiline]

iex> Regex.opts(Regex.compile!("foo", [:caseless]))
[:caseless]

re_pattern(regex)Source

@spec re_pattern(t()) :: term()

Возвращает базовое re_pattern в регулярном выражении.

recompile(regex)Source

@spec recompile(t()) :: {:ok, t()} | {:error, any()}

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

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

recompile!(regex)Source

@spec recompile!(t()) :: t()

Перекомпилирует существующее регулярное выражение и вызывает исключение Regex.CompileError в случае ошибок.

replace(regex, string, replacement, options \\ [])Source

@spec replace(t(), String.t(), String.t() | (... -> String.t()), [
  {:global, boolean()}
]) :: String.t()

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

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

Когда замена — строка, она позволяет определять конкретные захватчики совпадения с использованием скобок в выражении регулярного выражения и получать доступ к ним в замене через \N или \g{N}, где N — номер захватчика. В случае использования \0, вставляется всё совпадение. Обратите внимание, что в регулярных выражениях обратная косая черта должна быть экранирована, поэтому на практике вам нужно использовать \\N и \\g{N}.

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

Опции

:global - если false, заменяется только первое вхождение (по умолчанию true)

Примеры

iex> Regex.replace(~r/d/, "abc", "d")
"abc"

iex> Regex.replace(~r/b/, "abc", "d")
"adc"

iex> Regex.replace(~r/b/, "abc", "[\\0]")
"a[b]c"

iex> Regex.replace(~r/a(b|d)c/, "abcadc", "[\\1]")
"[b][d]"

iex> Regex.replace(~r/\.(\d)$/, "500.5", ".\\g{1}0")
"500.50"

iex> Regex.replace(~r/a(b|d)c/, "abcadc", fn _, x -> "[#{x}]" end)
"[b][d]"

iex> Regex.replace(~r/(\w+)@(\w+).(\w+)/, "abc@def.com", fn _full, _c1, _c2, c3 -> "TLD: #{c3}" end)
"TLD: com"

iex> Regex.replace(~r/a/, "abcadc", "A", global: false)
"Abcadc"

run(regex, string, options \\ [])Source

@spec run(t(), binary(), [term()]) :: nil | [binary()] | [{integer(), integer()}]

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

Опции

:return - если установлено в :index, возвращает индекс байта и длину совпадения. По умолчанию :binary.
:capture - что захватить в результате. См. раздел "Захваты" для возможных значений захватов.
:offset - (с версии 1.12.0) определяет начальное смещение для поиска совпадений в заданной строке. По умолчанию ноль.

Примеры

iex> Regex.run(~r/c(d)/, "abcd")
["cd", "d"]

iex> Regex.run(~r/e/, "abcd")
nil

iex> Regex.run(~r/c(d)/, "abcd", return: :index)
[{2, 2}, {3, 1}]

iex> Regex.run(~r/c(d)/, "abcd", capture: :first)
["cd"]

iex> Regex.run(~r/c(?<foo>d)/, "abcd", capture: ["foo", "bar"])
["d", ""]

scan(regex, string, options \\ [])Source

@spec scan(t(), String.t(), [term()]) :: [[String.t()]] | [[{integer(), integer()}]]

То же, что и run/3, но возвращает все неперекрывающиеся совпадения регулярного выражения.

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

Опции

:return - при установке в :index возвращает индекс байта и длину совпадения. По умолчанию :binary.
:capture - что захватить в результате. См. раздел "Захваты" для возможных значений захватов.
:offset - (с версии 1.12.0) определяет начальное смещение для поиска совпадений в заданной строке. По умолчанию ноль.

Примеры

iex> Regex.scan(~r/c(d|e)/, "abcd abce")
[["cd", "d"], ["ce", "e"]]

iex> Regex.scan(~r/c(?:d|e)/, "abcd abce")
[["cd"], ["ce"]]

iex> Regex.scan(~r/e/, "abcd")
[]

iex> Regex.scan(~r/ab|bc|cd/, "abcd")
[["ab"], ["cd"]]

iex> Regex.scan(~r/ab|bc|cd/, "abbccd")
[["ab"], ["bc"], ["cd"]]

iex> Regex.scan(~r/\p{Sc}/u, "$, £, and €")
[["$"], ["£"], ["€"]]

iex> Regex.scan(~r/=+/, "=ü†ƒ8===", return: :index)
[[{0, 1}], [{9, 3}]]

iex> Regex.scan(~r/c(d|e)/, "abcd abce", capture: :first)
[["cd"], ["ce"]]

source(regex)Source

@spec source(t()) :: String.t()

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

Примеры

iex> Regex.source(~r/foo/)
"foo"

END_OF_DOCUMENT_MARKER

split(regex, string, options \\ [])Source

@spec split(t(), String.t(), [term()]) :: [String.t()]

Разделяет заданную строку на части по заданному шаблону.

Параметры

:parts - при указании, разделяет строку на заданное количество частей. Если не указано, :parts по умолчанию :infinity, что будет разделять строку на максимальное количество частей, возможных по заданному шаблону.
:trim - при true, удаляет пустые строки ("") из результата. По умолчанию false.
:on - указывает, на каких группах захвата разделять строку, и в каком порядке. По умолчанию :first, что означает, что группы захвата внутри регулярного выражения не влияют на процесс разделения. Смотрите раздел "Группы захвата", чтобы увидеть возможные значения.
:include_captures - при true, включает в результат совпадения с регулярным выражением. Совпадения не учитываются при подсчёте максимального количества частей, если использовано вместе с опцией :parts. По умолчанию false.

Примеры

iex> Regex.split(~r{-}, "a-b-c")
["a", "b", "c"]

iex> Regex.split(~r{-}, "a-b-c", parts: 2)
["a", "b-c"]

iex> Regex.split(~r{-}, "abc")
["abc"]

iex> Regex.split(~r{}, "abc")
["", "a", "b", "c", ""]

iex> Regex.split(~r{a(?<second>b)c}, "abc")
["", ""]

iex> Regex.split(~r{a(?<second>b)c}, "abc", on: [:second])
["a", "c"]

iex> Regex.split(~r{(x)}, "Elixir", include_captures: true)
["Eli", "x", "ir"]

iex> Regex.split(~r{a(?<second>b)c}, "abc", on: [:second], include_captures: true)
["a", "b", "c"]

iex> Regex.split(~r{-}, "-a-b--c", trim: true)
["a", "b", "c"]

version()Source

@spec version() :: term()

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