Регулярные выражения

Предоставляет регулярные выражения для 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. Поэтому, %Regex{} может использоваться всякий раз, когда необходимо сопоставить их. Имейте в виду, что не гарантируется, что два регулярных выражения из одного и того же источника равны, например:

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

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

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

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

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

По этим причинам мы всегда рекомендуем предварительно компилировать проекты Elixir с использованием версии Erlang/OTP, предназначенной для использования в производстве. В случае, если кросс-компиляция действительно необходима, вы можете вручную вызвать Regex.recompile/1 или Regex.recompile!/1 для выполнения проверки версии во время выполнения и перекомпиляции регулярного выражения при необходимости.

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

Доступные модификаторы при создании 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) - инвертирует «жадность» regexp (предыдущий r параметр устарел в пользу U)

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

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

Захваты

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

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

Резюме

Типы

t()

Функции

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

Типы

t()

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

Функции

compile(source, options \\ "")

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

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

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

Возвращает {: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()

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

Примеры

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)

(since 1.4.0)

recompile(t()) :: t()

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

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

recompile!(regex)

(since 1.4.0)

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

(since 1.4.0)

version() :: term()

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