Regex
Regular expressions for Elixir built on top of the re module
in the Erlang Standard Library. More information can be found
in the re documentation.
Regular expressions in Elixir can be created using Regex.compile!/2
or using the special form with ~r:
# A simple regular expressions that matches foo anywhere in the string
~r/foo/
# A regular expression with case insensitive options
~r/foo/i
The re module provides several options, the ones available in Elixir, followed by
their shortcut in parenthesis, are:
caseless(i) - add case insensitivitydotall(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 documentationmultiline(m) - causes^and$to mark the beginning and end of each line. Use\Aand\zto match the end or beginning of the stringextended(x) - whitespace characters are ignored except when escaped and allow#to delimit commentsfirstline(f) - forces the unanchored pattern to match before or at the first newline, though the matched text may continue over the newlineungreedy(r) - inverts the "greediness" of the regexpgroups(g) - compiles with info about groups available
The options not available are:
anchored- not available, use^or\Ainsteaddollar_endonly- not available, use\zinsteadno_auto_capture- not available, use?:insteadnewline- not available, use(*CR)or(*LF)or(*CRLF)or(*ANYCRLF)or(*ANY)at the beginning of the regexp according to the re documentation
Summary
| compile!(source, options \\ "") | Compiles the regular expression according to the given options.
Fails with |
| compile(source, options \\ "") | Compiles the regular expression |
| escape(string) | Escapes a string to be literally matched in a regex |
| groups(arg1) | Returns a list of named groups in the regex |
| match?(arg1, string) | Returns a boolean indicating whether there was a match or not |
| named_captures(regex, string, options \\ []) | Returns the given captures as a keyword list or |
| opts(arg1) | Returns the regex options as a string |
| re_pattern(arg1) | Returns the underlying |
| replace(arg1, string, replacement, options \\ []) | Receives a regex, a binary and a replacement, returns a new binary where the all matches are replaced by 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 |
| scan(regex, string, options \\ []) | Same as |
| source(arg1) | Returns the regex source as a binary |
| split(regex, string, options \\ []) | Splits the given target into the number of parts specified.
If no number of parts is given, it defaults to |
Functions
Specs:
- 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 re docs.
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}}
Compiles the regular expression according to the given options.
Fails with Regex.CompileError if the regex cannot be compiled.
Specs:
Escapes a string to be literally matched in a regex.
Examples
iex> Regex.escape(".")
"\\."
iex> Regex.escape("\\what if")
"\\\\what\\ if"
Returns a list of named groups in the regex.
Examples
iex> Regex.groups(~r/(?<foo>bar)/g)
[:foo]
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
Returns the given captures as a keyword list or nil if no captures
are found. Requires the regex to be compiled with the groups option.
Examples
iex> Regex.named_captures(~r/c(?<foo>d)/g, "abcd")
[foo: "d"]
iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/g, "abcd")
[foo: "b", bar: "d"]
iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/g, "efgh")
nil
Returns the regex options as a string.
Examples
iex> Regex.opts(~r(foo)m)
"m"
Receives a regex, a binary and a replacement, returns a new binary where the all matches are replaced by replacement.
Inside the replacement, you can either give & to access the
whole regular expression or \N, where N is in integer to access
a specific matching parens. You can also set :global to false
if you want to replace just the first occurrence.
Examples
iex> Regex.replace(~r/d/, "abc", "d")
"abc"
iex> Regex.replace(~r/b/, "abc", "d")
"adc"
iex> Regex.replace(~r/b/, "abc", "[&]")
"a[b]c"
iex> Regex.replace(~r/b/, "abc", "[\\&]")
"a[&]c"
iex> Regex.replace(~r/(b)/, "abc", "[\\1]")
"a[b]c"
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.
When the option :capture is set to :groups, it will capture all
the groups in the regex.
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}]
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.
The captured contents defaults to :all, which includes the whole
regex match and each capture.
When the option :capture is set to :groups, it will capture all
the groups in the regex.
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")
[]
Returns the regex source as a binary.
Examples
iex> Regex.source(~r(foo))
"foo"
Splits the given target into the number of parts specified.
If no number of parts is given, it defaults to :infinity.
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//, "abc", trim: true)
["a", "b", "c"]