Elixir v1.1.0 Regex

Regular expressions for Elixir built on top of Erlang’s :re module.

As the :re module, Regex is based on PCRE (Perl Compatible Regular Expressions). More information can be found in the :re module documentation.

Regular expressions in Elixir can be created using Regex.compile!/2 or using the special form with ~r or ~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

A Regex is represented internally as the Regex struct. Therefore, %Regex{} can be used whenever there is a need to match on them.

Modifiers

The modifiers available when creating a Regex are:

unicode (u) - enables unicode specific patterns like \p and changes modifiers like \w, \W, \s and friends to also match on unicode. It expects valid unicode strings to be given on match
caseless (i) - add 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

Captures

Many functions in this module allows 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 - do not return matching subpatterns at all
:all_names - captures all names in the Regex
list(binary) - a list of named captures to capture

Summary

Functions

compile(source, options \\ "")

Compiles the regular expression

compile!(source, options \\ "")

Compiles the regular expression according to the given options. Fails with Regex.CompileError if the regex cannot be compiled

escape(string)

Escapes a string to be literally matched in a regex

match?(regex, string)

Returns a boolean indicating whether there was a match or not

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

Returns the given captures as a map or nil if no captures are found. The option :return can be set to :index to get indexes back

names(regex)

Returns a list of names in the regex

opts(regex)

Returns the regex options as a string

re_pattern(regex)

Returns the underlying re_pattern in the regular expression

regex?(term)

Returns true if the given term is a regex. Otherwise returns false

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

Receives a regex, a binary and a replacement, returns a new binary where all matches are replaced by the replacement

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

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

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

Same as run/3, but scans the target several times collecting all matches of the regular expression

source(regex)

Returns the regex source as a binary

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

Splits the given target based on the given pattern and in the given number of parts

Types

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

Functions

compile(source, options \\ "")

Specs

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

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

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.

Examples

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

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

compile!(source, options \\ "")

Compiles the regular expression according to the given options. Fails with Regex.CompileError if the regex cannot be compiled.

escape(string)

Specs

escape(String.t) :: String.t

Escapes a string to be literally matched in a regex.

Examples

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

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

match?(regex, string)

Specs

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

Returns a boolean indicating whether there was a match or not.

Examples

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

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

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

Specs

named_captures(t, String.t, [term]) :: map | nil

Returns the given captures as a map or nil if no captures are found. The option :return can be set to :index to get indexes back.

Examples

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)

Specs

names(t) :: [String.t]

Returns a list of names in the regex.

Examples

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

opts(regex)

Specs

opts(t) :: String.t

Returns the regex options as a string.

Examples

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

re_pattern(regex)

Specs

re_pattern(t) :: term

Returns the underlying re_pattern in the regular expression.

regex?(term)

Specs

regex?(t) :: true

regex?(any) :: false

Returns true if the given term is a regex. Otherwise returns false.

Examples

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

iex> Regex.regex?(0)
false

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

Specs

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.

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

Options

:global - when false, replaces only the first occurrence (defaults to true)

Examples

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

Specs

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.

Options

:return - set to :index to return indexes. Defaults to :binary.
:capture - what to capture in the result. Check the moduledoc for Regex to see the possible capture values.

Examples

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

Specs

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.

Options

:return - set to :index to return indexes. Defaults to :binary.
:capture - what to capture in the result. Check the moduledoc for Regex to see the possible capture values.

Examples

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

source(regex)

Specs

source(t) :: String.t

Returns the regex source as a binary.

Examples

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

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

Specs

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

Splits the given target based on the given pattern and in the given number of parts.

Options

: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.
: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.

Examples

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