Regex

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

Regex основан на PCRE (Perl Compatible Regular Expressions) и построен поверх модуля Erlang's :re. Более подробная информация доступна в документации модуля :re.

Регулярные выражения в Elixir можно создавать с использованием сигилов ~r (см. Kernel.sigil_r/2) или ~R (см. Kernel.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{} можно использовать всякий раз, когда необходимо выполнить сопоставление с ними. Имейте в виду, что не гарантируется, что два регулярных выражения из одного и того же источника будут равны, например:

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

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

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

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

Доступные модификаторы при создании 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) - список именованных захватов для захвата

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

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

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

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

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

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

iex> String.match?("josé", ~r/^[[:lower:]]+$/)
false
iex> String.match?("josé", ~r/^[[:lower:]]+$/u)
true

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

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

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

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

Типы

t()

Функции

compile(source, options \\ ""): Компилирует регулярное выражение.
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.
regex?(term): Возвращает true если заданный term является регулярным выражением. В противном случае возвращает false.
replace(regex, string, replacement, options \\ []): Принимает регулярное выражение, двоичное значение и замену, возвращает новую строку, где все совпадения заменяются заменой.
run(regex, string, options \\ []): Выполняет регулярное выражение над заданной строкой до первого совпадения. Возвращает список со всеми захватами или nil если совпадение не найдено.
scan(regex, string, options \\ []): Аналогично run/3, но сканирует целевую строку несколько раз, собирая все совпадения регулярного выражения.
source(regex): Возвращает исходный код регулярного выражения как двоичное значение.
split(regex, string, options \\ []): Разделяет заданную целевую строку на основе заданного шаблона и заданного числа частей.
version(): Возвращает версию подлежащего движка Regex.

Типы

t()

Specs

t() :: %Regex{
  opts: binary(),
  re_pattern: term(),
  re_version: term(),
  source: binary()
}

END_OF_DOCUMENT_MARKER

Функции

compile(source, options \\ "")

Спецификации

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

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

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

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

Примеры

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

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

compile!(source, options \\ "")

Спецификации

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

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

escape(string)

Спецификации

escape(String.t()) :: String.t()

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

Примеры

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

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

match?(regex, string)

Спецификации

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

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

Примеры

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

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

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

Спецификации

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)

Спецификации

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

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

Примеры

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

opts(regex)

Спецификации

opts(t()) :: String.t()

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

Примеры

iex> Regex.opts(~r(foo)m)
"m"

re_pattern(regex)

Спецификации

re_pattern(t()) :: term()

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

recompile(regex)

Спецификации

recompile(t()) :: t()

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

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

recompile!(regex)

Спецификации

recompile!(t()) :: t()

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

regex?(term)

Спецификации

regex?(any()) :: boolean()

Возвращает true если заданное term является регулярным выражением. В противном случае возвращает false.

Примеры

iex> Regex.regex?(~r/foo/)
true

iex> Regex.regex?(0)
false

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

Спецификации

replace(t(), String.t(), String.t() | (... -> String.t()), [term()]) ::
  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/a/, "abcadc", "A", global: false)
"Abcadc"

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

Спецификации

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

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

Опции

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

Примеры

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}]

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

Спецификации

scan(t(), String.t(), [term()]) :: [[String.t()]]

Аналогично run/3, но сканирует целевой текст несколько раз, собирая все совпадения регулярного выражения.

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

Опции

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

Примеры

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/\p{Sc}/u, "$, £, and €")
[["$"], ["£"], ["€"]]

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

source(regex)

Спецификации

source(t()) :: String.t()

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

Примеры

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

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

Спецификации

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

Разбивает заданный целевой текст на основе заданного шаблона и заданного числа частей.

Опции

:parts - при указании разбивает строку на заданное количество частей. Если не указано, :parts по умолчанию :infinity, что разделит строку на максимальное возможное количество частей на основе данного шаблона.
:trim - при указании удаляет пустые строки ("") из результата. По умолчанию false.
:on - указывает, на какие захваты разбивать строку и в каком порядке. По умолчанию :first, что означает, что захваты внутри регулярного выражения не влияют на процесс разделения.
:include_captures - если указано, включает в результат совпадения регулярного выражения. Совпадения не учитываются в максимальном количестве частей, если объединены с опцией :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"]

version()

Спецификации

version() :: term()

Возвращает версию базового движка Regex.