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

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

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

Регулярные выражения в Elixir можно создавать, используя сигилы ~r или ~R:

# A simple regular expressions 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, используя версию OTP, предназначенную для работы в рабочей среде. В случае, если перекомпиляция действительно необходима, вы можете вручную вызвать Regex.recompile/1 или Regex.recompile!/1 для выполнения проверки версии во время выполнения и перекомпиляции regex при необходимости.

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

Доступные модификаторы при создании 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 если захваты не найдены. Параметр :return можно установить в :index, чтобы получить индексы обратно

names(regex)

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

opts(regex)

Возвращает параметры regex в виде строки

re_pattern(regex)

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

recompile(regex)

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

recompile!(regex)

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

regex?(term)

Возвращает true если данное term является regex. В противном случае возвращает 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, или списком параметров, как ожидается от модуля 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, чтобы получить индексы обратно.

Примеры

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()

Возвращает параметры regex в виде строки.

Примеры

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

re_pattern(regex)

re_pattern(t()) :: term()

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

recompile(regex)

recompile(t()) :: t()

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

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

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 €")
[["$"], ["£"], ["€"]]

source(regex)

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

Возвращает исходный код regex в виде двоичной строки.

Примеры

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 - при указании включает в результат совпадения регулярного выражения. По умолчанию 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()

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