class Regex

• Regex
• Reference
• Object

Overview

ARegex represents a regular expression, a pattern that describes the contents of strings. ARegex can determinewhether or not a string matches its description, and extract the parts of the string that match.

ARegex can be created using the literal syntax, inwhich it is delimited by forward slashes (/):

/hay/ =~ "haystack"   # => 0
/y/.match("haystack") # => Regex::MatchData("y")

SeeRegex literals in the language reference.

Interpolationworks in regular expression literals just as it does in string literals. Be aware that using this featurewill cause an exception to be raised at runtime, if the resulting stringwould not be a valid regular expression.

x = "a"
/#{x}/.match("asdf") # => Regex::MatchData("a")
x = "("
/#{x}/ # raises ArgumentError

Whenwe check to see if a particular regular expression describes a string, we can say thatwe are performing a match or matching one against the other. Ifwe find that a regular expression does describe a string,we say that it matches, andwe can refer to a part of the string thatwas described as a match.

Here"haystack" does not contain the pattern/needle/, so it doesn't match:

/needle/.match("haystack") # => nil

Here"haystack" contains the pattern/hay/, so it matches:

/hay/.match("haystack") # => Regex::MatchData("hay")

Regex methods that perform a match usually return a truthy value if therewas a match andnil if therewas no match. After performing a match, the special variable$~will be an instance ofRegex::MatchData if it matched,nil otherwise.

When matching a regular expression using#=~ (eitherString#=~ or Regex#=~), the returned valuewill be the index of the first match in the string if the expression matched,nil otherwise.

/stack/ =~ "haystack"  # => 3
"haystack" =~ /stack/  # => 3
$~                     # => Regex::MatchData("stack")
/needle/ =~ "haystack" # => nil
"haystack" =~ /needle/ # => nil
$~                     # raises Exception

When matching a regular expression using#match (eitherString#match or Regex#match), the returned valuewill be aRegex::MatchData if the expression matched,nil otherwise.

/hay/.match("haystack")    # => Regex::MatchData("hay")
"haystack".match(/hay/)    # => Regex::MatchData("hay")
$~                         # => Regex::MatchData("hay")
/needle/.match("haystack") # => nil
"haystack".match(/needle/) # => nil
$~                         # raises Exception

Regular expressions have their own language for describing strings.

Many programming languages and tools implement their own regular expression language, but Crystal usesPCRE2, a popular C library,with JIT compilation enabled for providing regular expressions. Here give a brief summary of the most basic features of regular expressions - grouping, repetition, and alternation - but the feature set of PCRE2 extends far beyond these, andwe don't attempt to describe it in full here. For more information, refer to the PCRE2 documentation, especially the full pattern syntax or syntax quick reference.

NOTE Prior to Crystal 1.8 the compiler expected regex literals to follow the originalPCRE pattern syntax. The following summary applies to both PCRE and PCRE2.

The regular expression language can be used to match much more than just the static substrings in the above examples. Certain characters, called metacharacters, are given special treatment in regular expressions, and can be used to describe more complex patterns. To match metacharacters literally in a regular expression, they must be escaped by being precededwith a backslash (\)..escapewill do this automatically for a given String.

A group of characters (often called a capture group or subpattern) can be identified by enclosing it in parentheses (()). The contents of each capture group can be extracted on a successful match:

/a(sd)f/.match("_asdf_")                     # => Regex::MatchData("asdf" 1:"sd")
/a(sd)f/.match("_asdf_").try &.[1]           # => "sd"
/a(?<grp>sd)f/.match("_asdf_")               # => Regex::MatchData("asdf" grp:"sd")
/a(?<grp>sd)f/.match("_asdf_").try &.["grp"] # => "sd"

Capture groups are indexed starting from 1. Methods that accept a capture group indexwill usually also accept 0 to refer to the full match. Capture groups can also be given names, using the(?<name>...) syntax, as in the previous example.

Following a match, the special variables $N (e.g., $1, $2, $3, ...) can be used to access a capture group. Trying to access an invalid capture groupwill raise an exception. Note that it is possible to have a successful matchwith a nil capture:

/(spice)(s)?/.match("spice") # => Regex::MatchData("spice" 1:"spice" 2:nil)
$1                           # => "spice"
$2                           # => raises Exception

This can be mitigated by using the nilable version of the above: $N?, (e.g., $1? $2?, $3?, ...). Changing the above to use$2? instead of$2 would returnnil.$2?.nil?would returntrue.

A character or group can be repeated or made optional using an asterisk (* - zero or more), a plus sign (#+ - one or more), integer bounds in curly braces ({n,m}) (at leastn, no more thanm), or a question mark (?) (zero or one).

/fo*/.match("_f_")         # => Regex::MatchData("f")
/fo+/.match("_f_")         # => nil
/fo*/.match("_foo_")       # => Regex::MatchData("foo")
/fo{3,}/.match("_foo_")    # => nil
/fo{1,3}/.match("_foo_")   # => Regex::MatchData("foo")
/fo*/.match("_foo_")       # => Regex::MatchData("foo")
/fo*/.match("_foooooooo_") # => Regex::MatchData("foooooooo")
/fo{,3}/.match("_foooo_")  # => nil
/f(op)*/.match("fopopo")   # => Regex::MatchData("fopop" 1:"op")
/foo?bar/.match("foobar")  # => Regex::MatchData("foobar")
/foo?bar/.match("fobar")   # => Regex::MatchData("fobar")

Alternatives can be separated using a vertical bar (|). Any single character can be represented by dot (.). When matching only one character, specific alternatives can be expressed as a character class, enclosed in square brackets ([]):

/foo|bar/.match("foo")     # => Regex::MatchData("foo")
/foo|bar/.match("bar")     # => Regex::MatchData("bar")
/_(x|y)_/.match("_x_")     # => Regex::MatchData("_x_" 1:"x")
/_(x|y)_/.match("_y_")     # => Regex::MatchData("_y_" 1:"y")
/_(x|y)_/.match("_(x|y)_") # => nil
/_(x|y)_/.match("_(x|y)_") # => nil
/_._/.match("_x_")         # => Regex::MatchData("_x_")
/_[xyz]_/.match("_x_")     # => Regex::MatchData("_x_")
/_[a-z]_/.match("_x_")     # => Regex::MatchData("_x_")
/_[^a-z]_/.match("_x_")    # => nil
/_[^a-wy-z]_/.match("_x_") # => Regex::MatchData("_x_")

Regular expressions can be definedwith these 3 optional flags:

• i: ignore case (Regex::Options::IGNORE_CASE)
• m: multiline (Regex::Options::MULTILINE)
• x: extended (Regex::Options::EXTENDED)

/asdf/ =~ "ASDF"    # => nil
/asdf/i =~ "ASDF"   # => 0
/^z/i =~ "ASDF\nZ"  # => nil
/^z/im =~ "ASDF\nZ" # => 5

PCRE2 supports other encodings, but Crystal strings are UTF-8 only, so Crystal regular expressions are also UTF-8 only (by default). Crystal strings are expected to contain only valid UTF-8 encodings, but that's not guaranteed. There's a chance that a stringcan contain invalid bytes. Especially data read from external sources must not be trusted to be valid encoding. The regex engine demands valid UTF-8, so it checks the encoding for every match. This can be unnecessary if the string is already validated (for example viaString#valid_encoding? or because it has already been used in a previous regex match). If that's the case, it's profitable to skip UTF-8 validation viaMatchOptions::NO_UTF_CHECK (orCompileOptions::NO_UTF_CHECK for the pattern).

PCRE2 optionally permits named capture groups (named subpatterns) to not be unique. Crystal exposes the name table of aRegex as a Hash ofString =>Int32, and therefore requires named capture groups to have unique nameswithin a singleRegex.

Included Modules

• Regex::PCRE2

Defined in:

Constant Summary

SPECIAL_CHARACTERS = {' ', '.', '\\', '+', '*', '?', '[', '^', ']', '$', '(', ')', '{', '}', '=', '!', '<', '>', '|', ':', '-'}

List of metacharacters that need to be escaped.

SeeRegex.needs_escape? andRegex.escape.

Constructors

• .literal(pattern : String, *, i : Bool = false, m : Bool = false, x : Bool = false) : self

  Creates a newRegex instance from a literal consisting of apattern and the named parameter modifiers.

• .new(source : String, options : Options = Options::None) : self

  Creates a newRegex out of the given sourceString.

• .union(patterns : Enumerable(Regex | String)) : self

  Union.

• .union(*patterns : Regex | String) : self

  Union.

Class Method Summary

• .error?(source : String) : String | Nil

  Determines Regex's source validity.

• .escape(str : String) : String

  Returns aString constructed by escaping any metacharacters instr.

• .needs_escape?(char : Char) : Bool

  Returnstrue ifchar need to be escaped,false otherwise.

• .needs_escape?(str : String) : Bool

  Returnstrue ifstr need to be escaped,false otherwise.

• .supports_compile_options?(options : CompileOptions) : Bool

  Returnstrue if the regex engine supports alloptions flagswhen compiling a pattern.

• .supports_match_options?(options : MatchOptions) : Bool

  Returnstrue if the regex engine supports alloptions flagswhen matching a pattern.

Instance Method Summary

• #+(other) : Regex

  Union.

• #==(other : Regex) : Bool

  Equality.

• #===(other : String) : Bool

  Case equality.

• #===(other : JSON::Any)
• #===(other : YAML::Any)
• #=~(other : String) : Int32 | Nil

  Match.

• #=~(other) : Nil

  Match.

• #capture_count : Int32

  Returns the number of (named& non-named) capture groups.

• #clone : Regex
• #dup

  Returns a shallow copy of this object.

• #hash(hasher)

  SeeObject#hash(hasher)

• #inspect(io : IO) : Nil

  Prints toio an unambiguous string representation of this regular expression object.

• #match(str : String, pos : Int32 = 0, options : Regex::MatchOptions = :none) : MatchData | Nil

  Match at character index.

• #match(str, pos, _options) : MatchData | Nil

  Match at character index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #match(str, pos = 0, *, options) : MatchData | Nil

  Match at character index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #match!(str : String, pos : Int32 = 0, *, options : Regex::MatchOptions = :none) : MatchData

  Matches a regular expression againststr.

• #match_at_byte_index(str : String, byte_index : Int32 = 0, options : Regex::MatchOptions = :none) : MatchData | Nil

  Match at byte index.

• #match_at_byte_index(str, byte_index, _options) : MatchData | Nil

  Match at byte index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #match_at_byte_index(str, byte_index = 0, *, options) : MatchData | Nil

  Match at byte index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #matches?(str : String, pos : Int32 = 0, options : Regex::MatchOptions = :none) : Bool

  Match at character index.

• #matches?(str, pos, _options) : Bool

  Match at character index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #matches?(str, pos = 0, *, options) : Bool

  Match at character index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #matches_at_byte_index?(str : String, byte_index : Int32 = 0, options : Regex::MatchOptions = :none) : Bool

  Match at byte index.

• #matches_at_byte_index?(str, byte_index, _options) : Bool

  Match at byte index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #matches_at_byte_index?(str, byte_index = 0, *, options) : Bool

  Match at byte index.

  DEPRECATED Use the overloadwithRegex::MatchOptions instead.

• #name_table : Hash(Int32, String)

  Returns aHashwhere the values are the names of capture groups and the keys are their indexes.

• #options : Options

  Returns aRegex::CompileOptions representing the optional flags applied to thisRegex.

• #source : String

  Returns the originalString representation of theRegex pattern.

• #to_s(io : IO) : Nil

  Convert toString in subpattern format.

Constructor Detail

Regex.new("^a-z+:\\s+\\w+")                          # => /^a-z+:\s+\w+/
Regex.new("cat", Regex::CompileOptions::IGNORE_CASE) # => /cat/i
options = Regex::CompileOptions::IGNORE_CASE | Regex::CompileOptions::EXTENDED
Regex.new("dog", options) # => /dog/ix

re = Regex.union([/skiing/i, "sledding"])
re.match("Skiing")   # => Regex::MatchData("Skiing")
re.match("sledding") # => Regex::MatchData("sledding")
re = Regex.union({/skiing/i, "sledding"})
re.match("Skiing")   # => Regex::MatchData("Skiing")
re.match("sledding") # => Regex::MatchData("sledding")

re = Regex.union(/skiing/i, "sledding")
re.match("Skiing")   # => Regex::MatchData("Skiing")
re.match("sledding") # => Regex::MatchData("sledding")

Class Method Detail

Regex.error?("(foo|bar)") # => nil
Regex.error?("(foo|bar")  # => "missing ) at 8"

string = Regex.escape("*?{}.") # => "\\*\\?\\{\\}\\."
/#{string}/                    # => /\*\?\{\}\./

Regex.needs_escape?('*') # => true
Regex.needs_escape?('@') # => false

Regex.needs_escape?("10$") # => true
Regex.needs_escape?("foo") # => false

Instance Method Detail

re = /skiing/i + /sledding/
re.match("Skiing")   # => Regex::MatchData("Skiing")
re.match("sledding") # => Regex::MatchData("sledding")

/abc/ == /abc/i  # => false
/abc/i == /ABC/i # => false
/abc/i == /abc/i # => true

a = "HELLO"
b = case a
    when /^[a-z]*$/
      "Lower case"
    when /^[A-Z]*$/
      "Upper case"
    else
      "Mixed case"
    end
b # => "Upper case"

/at/ =~ "input data" # => 7
/ax/ =~ "input data" # => nil

/at/ =~ "input data" # => 7
/ax/ =~ "input data" # => nil

/(?:.+)/.capture_count     # => 0
/(?<foo>.+)/.capture_count # => 1
/(.)/.capture_count        # => 1
/(.)|(.)/.capture_count    # => 2

/ab+c/ix.inspect                     # => "/ab+c/ix"
Regex.new("ab+c", :anchored).inspect # => Regex.new("ab+c", Regex::Options::ANCHORED)

/(.)(.)(.)/.match("abc").try &.[2]   # => "b"
/(.)(.)/.match("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match("クリスタル", 3).try &.[2] # => "ル"

/(.)(.)(.)/.match("abc").try &.[2]   # => "b"
/(.)(.)/.match("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match("クリスタル", 3).try &.[2] # => "ル"

/(.)(.)(.)/.match("abc").try &.[2]   # => "b"
/(.)(.)/.match("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match("クリスタル", 3).try &.[2] # => "ル"

/(.)(.)(.)/.match!("abc")[2]   # => "b"
/(.)(.)/.match!("abc", 1)[2]   # => "c"
/(.)(タ)/.match!("クリスタル", 3)[2] # raises Exception

/(.)(.)(.)/.match_at_byte_index("abc").try &.[2]   # => "b"
/(.)(.)/.match_at_byte_index("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match_at_byte_index("クリスタル", 3).try &.[2] # => "ス"

/(.)(.)(.)/.match_at_byte_index("abc").try &.[2]   # => "b"
/(.)(.)/.match_at_byte_index("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match_at_byte_index("クリスタル", 3).try &.[2] # => "ス"

/(.)(.)(.)/.match_at_byte_index("abc").try &.[2]   # => "b"
/(.)(.)/.match_at_byte_index("abc", 1).try &.[2]   # => "c"
/(.)(.)/.match_at_byte_index("クリスタル", 3).try &.[2] # => "ス"

/foo/.matches?("bar") # => false
/foo/.matches?("foo") # => true

# `$~` is not set even if last match succeeds.
$~ # raises Exception

/foo/.matches?("bar") # => false
/foo/.matches?("foo") # => true

# `$~` is not set even if last match succeeds.
$~ # raises Exception

/foo/.matches?("bar") # => false
/foo/.matches?("foo") # => true

# `$~` is not set even if last match succeeds.
$~ # raises Exception

/(.)/.name_table                         # => {}
/(?<foo>.)/.name_table                   # => {1 => "foo"}
/(?<foo>.)(?<bar>.)/.name_table          # => {2 => "bar", 1 => "foo"}
/(.)(?<foo>.)(.)(?<bar>.)(.)/.name_table # => {4 => "bar", 2 => "foo"}

/ab+c/ix.options      # => Regex::CompileOptions::IGNORE_CASE | Regex::CompileOptions::EXTENDED
/ab+c/ix.options.to_s # => "IGNORE_CASE | EXTENDED"

/ab+c/x.source # => "ab+c"

re = /A*/i                 # => /A*/i
re.to_s                    # => "(?i-msx:A*)"
"Crystal".match(/t#{re}l/) # => Regex::MatchData("tal")
re = /A*/                  # => "(?-imsx:A*)"
"Crystal".match(/t#{re}l/) # => nil