Add StringLiteral#match (#16464)

Author: HertzDevil

spec/compiler/macro/macro_methods_spec.cr

@@ -598,6 +598,12 @@ module Crystal
         assert_macro %q({{ "bar".gsub /(foo)/ { "STR" } }}), %("bar")                                                                                 # No match at all
       end
 
+      it "executes match" do
+        assert_macro %({{ "hello world".match(/x/) }}), %(nil)
+        assert_macro %({{ "hello world".match(/o.*o/) }}), %({0 => "o wo"} of ::Int32 | ::String => ::String | ::Nil)
+        assert_macro %({{ "hello world".match(/(?:(x)|e)(?<name>\\S+)/) }}), %({0 => "ello", 1 => nil, "name" => "llo"} of ::Int32 | ::String => ::String | ::Nil)
+      end
+
       it "executes scan" do
         assert_macro %({{"Crystal".scan(/(Cr)(?<name1>y)(st)(?<name2>al)/)}}), %([{0 => "Crystal", 1 => "Cr", "name1" => "y", 3 => "st", "name2" => "al"} of ::Int32 | ::String => ::String | ::Nil] of ::Hash(::Int32 | ::String, ::String | ::Nil))
         assert_macro %({{"Crystal".scan(/(Cr)?(stal)/)}}), %([{0 => "stal", 1 => nil, 2 => "stal"} of ::Int32 | ::String => ::String | ::Nil] of ::Hash(::Int32 | ::String, ::String | ::Nil))

src/compiler/crystal/macros.cr

@@ -14,7 +14,7 @@ private macro def_string_methods(klass)
   def [](range : RangeLiteral) : {{klass}}
   end
 
-  # Similar to `String#=~`.
+  # Similar to `String#matches?`.
   def =~(range : RegexLiteral) : BoolLiteral
   end
 
@@ -68,10 +68,17 @@ private macro def_string_methods(klass)
   def includes?(search : StringLiteral | CharLiteral) : BoolLiteral
   end
 
+  # Matches the given *regex* against this string and returns a capture hash, or
+  # `nil` if a match cannot be found.
+  #
+  # The capture hash has the same form as `Regex::MatchData#to_h`.
+  def match(regex : RegexLiteral) : HashLiteral(NumberLiteral | StringLiteral, StringLiteral | NilLiteral)
+  end
+
   # Returns an array of capture hashes for each match of *regex* in this string.
   #
   # Capture hashes have the same form as `Regex::MatchData#to_h`.
-  def scan(regex : RegexLiteral) : ArrayLiteral(HashLiteral(NumberLiteral | StringLiteral), StringLiteral | NilLiteral)
+  def scan(regex : RegexLiteral) : ArrayLiteral(HashLiteral(NumberLiteral | StringLiteral, StringLiteral | NilLiteral))
   end
 
   # Similar to `String#size`.

src/compiler/crystal/macros/methods.cr

@@ -791,6 +791,20 @@ module Crystal
           end
           BoolLiteral.new(@value.includes?(piece))
         end
+      when "match"
+        interpret_check_args do |arg|
+          unless arg.is_a?(RegexLiteral)
+            raise "StringLiteral#match expects a regex, not #{arg.class_desc}"
+          end
+
+          regex = regex_value(arg)
+
+          if match_data = @value.match(regex)
+            regex_captures_hash(match_data)
+          else
+            NilLiteral.new
+          end
+        end
       when "scan"
         interpret_check_args do |arg|
           unless arg.is_a?(RegexLiteral)
@@ -810,32 +824,7 @@ module Crystal
           )
 
           @value.scan(regex) do |match_data|
-            captures = HashLiteral.new(
-              of: HashLiteral::Entry.new(
-                Union.new([Path.global("Int32"), Path.global("String")] of ASTNode),
-                Union.new([Path.global("String"), Path.global("Nil")] of ASTNode),
-              )
-            )
-
-            match_data.to_h.each do |capture, substr|
-              case capture
-              in Int32
-                key = NumberLiteral.new(capture)
-              in String
-                key = StringLiteral.new(capture)
-              end
-
-              case substr
-              in String
-                value = StringLiteral.new(substr)
-              in Nil
-                value = NilLiteral.new
-              end
-
-              captures.entries << HashLiteral::Entry.new(key, value)
-            end
-
-            matches.elements << captures
+            matches.elements << regex_captures_hash(match_data)
           end
 
           matches
@@ -3381,6 +3370,35 @@ private def empty_no_return_array
   Crystal::ArrayLiteral.new(of: Crystal::Path.global("NoReturn"))
 end
 
+private def regex_captures_hash(match_data : Regex::MatchData)
+  captures = Crystal::HashLiteral.new(
+    of: Crystal::HashLiteral::Entry.new(
+      Crystal::Union.new([Crystal::Path.global("Int32"), Crystal::Path.global("String")] of Crystal::ASTNode),
+      Crystal::Union.new([Crystal::Path.global("String"), Crystal::Path.global("Nil")] of Crystal::ASTNode),
+    )
+  )
+
+  match_data.to_h.each do |capture, substr|
+    case capture
+    in Int32
+      key = Crystal::NumberLiteral.new(capture)
+    in String
+      key = Crystal::StringLiteral.new(capture)
+    end
+
+    case substr
+    in String
+      value = Crystal::StringLiteral.new(substr)
+    in Nil
+      value = Crystal::NilLiteral.new
+    end
+
+    captures.entries << Crystal::HashLiteral::Entry.new(key, value)
+  end
+
+  captures
+end
+
 private def filter(object, klass, block, interpreter, keep = true)
   block_arg = block.args.first?