Provides regular expressions for Elixir.
Regex is based on PCRE (Perl Compatible Regular Expressions) and built on top of Erlang’s :re
module. More information can be found in the :re
module documentation.
Regular expressions in Elixir can be created using the sigils ~r
or ~R
:
# 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
Regular expressions created via sigils are pre-compiled and stored in the .beam
file. Notice this may be a problem if you are precompiling Elixir, see the “Precompilation” section for more information.
A Regex is represented internally as the Regex
struct. Therefore, %Regex{}
can be used whenever there is a need to match on them. Keep in mind it is not guaranteed two regular expressions from the same source are equal, for example:
~r/(?<foo>.)(?<bar>.)/ == ~r/(?<foo>.)(?<bar>.)/
may return true
or false
depending on your machine, endianness, available optimizations and others. You can, however, retrieve the source of a compiled regular expression by accessing the source
field, and then compare those directly:
~r/(?<foo>.)(?<bar>.)/.source == ~r/(?<foo>.)(?<bar>.)/.source
Regular expressions built with sigil are precompiled and stored in .beam
files. This may be a problem if you are precompiling Elixir to run in different OTP releases, as OTP releases may update the underlying regular expression engine at any time.
For such reasons, we always recommend precompiling Elixir projects using the Erlang/OTP version meant to run in production. In case cross-compilation is really necessary, you can manually invoke Regex.recompile/1
or Regex.recompile!/1
to perform a runtime version check and recompile the regex if necessary.
The modifiers available when creating a Regex are:
unicode
(u) - enables Unicode specific patterns like \p
and change modifiers like \w
, \W
, \s
and friends to also match on Unicode. It expects valid Unicode strings to be given on match
caseless
(i) - adds case insensitivity
dotall
(s) - causes dot to match newlines and also set newline to anycrlf; the new line setting can be overridden by setting (*CR)
or (*LF)
or (*CRLF)
or (*ANY)
according to re documentation
multiline
(m) - causes ^
and $
to mark the beginning and end of each line; use \A
and \z
to match the end or beginning of the string
extended
(x) - whitespace characters are ignored except when escaped and allow #
to delimit comments
firstline
(f) - forces the unanchored pattern to match before or at the first newline, though the matched text may continue over the newline
ungreedy
(U) - inverts the “greediness” of the regexp (the previous r
option is deprecated in favor of U
)
The options not available are:
anchored
- not available, use ^
or \A
instead dollar_endonly
- not available, use \z
instead no_auto_capture
- not available, use ?:
instead newline
- not available, use (*CR)
or (*LF)
or (*CRLF)
or (*ANYCRLF)
or (*ANY)
at the beginning of the regexp according to the re documentation Many functions in this module handle what to capture in a regex match via the :capture
option. The supported values are:
:all
- all captured subpatterns including the complete matching string (this is the default)
:first
- only the first captured subpattern, which is always the complete matching part of the string; all explicitly captured subpatterns are discarded
:all_but_first
- all but the first matching subpattern, i.e. all explicitly captured subpatterns, but not the complete matching part of the string
:none
- does not return matching subpatterns at all
:all_names
- captures all names in the Regex
list(binary)
- a list of named captures to capture
Compiles the regular expression and raises Regex.CompileError
in case of errors
Compiles the regular expression
Escapes a string to be literally matched in a regex
Returns a boolean indicating whether there was a match or not
Returns the given captures as a map or nil
if no captures are found
Returns a list of names in the regex
Returns the regex options as a string
Returns the underlying re_pattern
in the regular expression
Recompiles the existing regular expression and raises Regex.CompileError
in case of errors
Recompiles the existing regular expression if necessary
Returns true
if the given term
is a regex. Otherwise returns false
Receives a regex, a binary and a replacement, returns a new binary where all matches are replaced by the replacement
Runs the regular expression against the given string until the first match. It returns a list with all captures or nil
if no match occurred
Same as run/3
, but scans the target several times collecting all matches of the regular expression
Returns the regex source as a binary
Splits the given target based on the given pattern and in the given number of parts
Returns the version of the underlying Regex engine
t() :: %Regex{ opts: binary(), re_pattern: term(), re_version: term(), source: binary() }
compile!(binary(), binary() | [term()]) :: t()
Compiles the regular expression and raises Regex.CompileError
in case of errors.
compile(binary(), binary() | [term()]) :: {:ok, t()} | {:error, any()}
Compiles the regular expression.
The given options can either be a binary with the characters representing the same regex options given to the ~r
sigil, or a list of options, as expected by the Erlang’s :re
module.
It returns {:ok, regex}
in case of success, {:error, reason}
otherwise.
iex> Regex.compile("foo") {:ok, ~r/foo/} iex> Regex.compile("*foo") {:error, {'nothing to repeat', 0}}
escape(String.t()) :: String.t()
Escapes a string to be literally matched in a regex.
iex> Regex.escape(".") "\\." iex> Regex.escape("\\what if") "\\\\what\\ if"
match?(t(), String.t()) :: boolean()
Returns a boolean indicating whether there was a match or not.
iex> Regex.match?(~r/foo/, "foo") true iex> Regex.match?(~r/foo/, "bar") false
named_captures(t(), String.t(), [term()]) :: map() | nil
Returns the given captures as a map or nil
if no captures are found.
:return
- set to :index
to return byte index and match length. Defaults to :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(t()) :: [String.t()]
Returns a list of names in the regex.
iex> Regex.names(~r/(?<foo>bar)/) ["foo"]
opts(t()) :: String.t()
Returns the regex options as a string.
iex> Regex.opts(~r(foo)m) "m"
re_pattern(t()) :: term()
Returns the underlying re_pattern
in the regular expression.
recompile!(t()) :: t()
Recompiles the existing regular expression and raises Regex.CompileError
in case of errors.
recompile(t()) :: t()
Recompiles the existing regular expression if necessary.
This checks the version stored in the regular expression and recompiles the regex in case of version mismatch.
regex?(any()) :: boolean()
Returns true
if the given term
is a regex. Otherwise returns false
.
iex> Regex.regex?(~r/foo/) true iex> Regex.regex?(0) false
replace(t(), String.t(), String.t() | (... -> String.t()), [term()]) :: String.t()
Receives a regex, a binary and a replacement, returns a new binary where all matches are replaced by the replacement.
The replacement can be either a string or a function. The string is used as a replacement for every match and it allows specific captures to be accessed via \N
or \g{N}
, where N
is the capture. In case \0
is used, the whole match is inserted. Note that in regexes the backslash needs to be escaped, hence in practice you’ll need to use \\N
and \\g{N}
.
When the replacement is a function, the function may have arity N where each argument maps to a capture, with the first argument being the whole match. If the function expects more arguments than captures found, the remaining arguments will receive ""
.
:global
- when false
, replaces only the first occurrence (defaults to 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(t(), binary(), [term()]) :: nil | [binary()] | [{integer(), integer()}]
Runs the regular expression against the given string until the first match. It returns a list with all captures or nil
if no match occurred.
:return
- set to :index
to return byte index and match length. Defaults to :binary
. :capture
- what to capture in the result. Check the moduledoc for Regex
to see the possible capture values. 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(t(), String.t(), [term()]) :: [[String.t()]]
Same as run/3
, but scans the target several times collecting all matches of the regular expression.
A list of lists is returned, where each entry in the primary list represents a match and each entry in the secondary list represents the captured contents.
:return
- set to :index
to return byte index and match length. Defaults to :binary
. :capture
- what to capture in the result. Check the moduledoc for Regex
to see the possible capture values. 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(t()) :: String.t()
Returns the regex source as a binary.
iex> Regex.source(~r(foo)) "foo"
split(t(), String.t(), [term()]) :: [String.t()]
Splits the given target based on the given pattern and in the given number of parts.
:parts
- when specified, splits the string into the given number of parts. If not specified, :parts
defaults to :infinity
, which will split the string into the maximum number of parts possible based on the given pattern.
:trim
- when true
, removes empty strings (""
) from the result. Defaults to false
.
:on
- specifies which captures to split the string on, and in what order. Defaults to :first
which means captures inside the regex do not affect the splitting process.
:include_captures
- when true
, includes in the result the matches of the regular expression. Defaults to 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() :: term()
Returns the version of the underlying Regex engine.
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.7.3/Regex.html