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) - заставляет точку соответствовать новым строкам, а также устанавливает новую строку на anycrlf; настройка новой строки может быть переопределена установкой (*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

Захваты

Многие функции в этом модуле обрабатывают, что захватывать в совпадении regexp, через параметр :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 - Буквы
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, используемого во время разработки, компилируется на целевой системе (например, зависимости, архивы и escripts), а при работе в производстве код должен быть либо скомпилирован на целевой системе (через mix compile или аналогично), либо выпущен на хосте (через mix releases или аналогично) с совместимым OTP, операционной системой и архитектурой с целевой системой.

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

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

Типы

t()

Функции

compile!(source, options \\ ""): Компилирует регулярное выражение и вызывает исключение Regex.CompileError в случае ошибок.
compile(source, options \\ ""): Компилирует регулярное выражение.
escape(string): Экранирует строку, чтобы она соответствовала литералу в регулярном выражении.
match?(regex, string): Возвращает логическое значение, указывающее, было ли совпадение.
named_captures(regex, string, options \\ []): Возвращает заданные захватчики как карту или nil в случае отсутствия захватов.
names(regex): Возвращает список имён в регулярном выражении.
opts(regex): Возвращает параметры регулярного выражения в виде строки.
re_pattern(regex): Возвращает базовую re_pattern в регулярном выражении.
recompile!(regex): Перекомпилирует существующее регулярное выражение и вызывает исключение Regex.CompileError в случае ошибок.
recompile(regex): Перекомпилирует существующее регулярное выражение при необходимости.
regex?(term) deprecated: Возвращает 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()Source

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

Функции

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

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

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

compile(source, options \\ "")Source

@spec 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}}

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 также предоставляет Kernel.=~/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()) :: String.t()

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

Примеры

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

re_pattern(regex)Source

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

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

recompile!(regex)Source

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

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

recompile(regex)Source

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

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

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

regex?(term)Source

Эта функция устарела. Используйте Kernel.is_struct/2 или сопоставление с образцом %Regex{} вместо неё.

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

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

@spec 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 \\ [])Source

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

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

Опции

:return - если установлено в :index, возвращает индекс байта и длину совпадения. По умолчанию :binary.
:capture - что захватывать в результате. Проверьте moduledoc для Regex, чтобы увидеть возможные значения захватов.
:offset - (с версии v1.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}]

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

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

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

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

Опции

:return - если установлено в :index, возвращает индекс байта и длину совпадения. По умолчанию :binary.
:capture - что захватывать в результате. Проверьте moduledoc для Regex, чтобы увидеть возможные значения захватов.
:offset - (с версии v1.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/\p{Sc}/u, "$, £, and €")
[["$"], ["£"], ["€"]]

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

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

version()Source

@spec version() :: term()

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

Настройки Regex

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

Захваты

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

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

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

Типы

Функции

Типы

t()Source

Функции

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

compile(source, options \\ "")Source

Примеры

escape(string)Source

Примеры

match?(regex, string)Source

Примеры

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

Опции

Примеры

names(regex)Source

Примеры

opts(regex)Source

Примеры

re_pattern(regex)Source

recompile!(regex)Source

recompile(regex)Source

regex?(term)Source

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

Опции

Примеры

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

Опции

Примеры

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

Опции

Примеры

source(regex)Source

Примеры

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

Параметры

Примеры

version()Source

Regex