Split match primitive into str and reg

Also split Scanner#match into match_string and match_regexp.

Author: booch

README.md

@@ -67,13 +67,13 @@ class Arithmetic < Grammy::Grammar
   root :expression
 
   # Define the rules.
-  rule(:expression) { term + (match("+") + term)[0..] }
-  rule(:term) { factor + (match("*") + factor)[0..] }
+  rule(:expression) { term + (str("+") + term)[0..] }
+  rule(:term) { factor + (str("*") + factor)[0..] }
   rule(:factor) { number | parens(expression) }
-  rule(:number) { match(/\d+/) }
+  rule(:number) { reg(/\d+/) }
 
   # Define any custom combinators.
-  def parens(exp) = match("(") + expression + match(")")
+  def parens(exp) = str("(") + expression + str(")")
 end
 ~~~
 
@@ -87,13 +87,13 @@ class Arithmetic < Grammy::Grammar
   root :expression
 
   # Define the rules.
-  rule def expression = term + (match("+") + term)[0..]
-  rule def term = factor + (match("*") + factor)[0..]
+  rule def expression = term + (str("+") + term)[0..]
+  rule def term = factor + (str("*") + factor)[0..]
   rule def factor = number | parens(expression)
-  rule def number = match(/\d+/)
+  rule def number = reg(/\d+/)
 
   # Define any custom combinators.
-  def parens(exp) = match("(") + expression + match(")")
+  def parens(exp) = str("(") + expression + str(")")
 end
 ~~~
 
@@ -107,13 +107,13 @@ class Arithmetic < Grammy::Grammar
   start :expression
 
   # Define the rules.
-  def expression = rule { term + (match("+") + term)[0..] }
-  def term = rule { factor + (match("*") + factor)[0..] }
+  def expression = rule { term + (str("+") + term)[0..] }
+  def term = rule { factor + (str("*") + factor)[0..] }
   def factor = rule { number | parens(expression) }
-  def number = rule { match(/\d+/) }
+  def number = rule { reg(/\d+/) }
 
   # Define any custom combinators.
-  def parens(exp) = match("(") + expression + match(")")
+  def parens(exp) = str("(") + expression + str(")")
 end
 ~~~
 
@@ -124,23 +124,31 @@ Combinators are functions that take one or more parsers as arguments and return
 
 Only a few primitive combinators are needed.
 
-### Match
+### String
 
-The `match` combinator is used to match a string or a regular expression.
+The `str` combinator is used to match a string.
 
 ~~~ ruby
-match("return")
-match(/\d+/)
+str("return")
 ~~~
 
+### Regex
+
+The `reg` combinator is used to match a regular expression.
+
+~~~ ruby
+reg(/\d+/)
+~~~
+
+
 ### Sequence
 
 You use the `seq` combinator to specify a sequence of what to match.
 
 This example matches a sequence of a term, a plus sign, and another term.
 
 ~~~ ruby
-seq(term, match("+"), term)
+seq(term, str("+"), term)
 ~~~
 
 ### Alternatives
@@ -150,14 +158,15 @@ The `alt` combinator is used to specify alternatives (multiple choices) of what
 This example matches either a plus sign or a minus sign.
 
 ~~~ ruby
-alt(match("+"), match("-"))
+alt(str("+"), str("-"))
 ~~~
 
-NOTE: This would most likely done with a single `match` call:
-
-~~~ ruby
-match(/[+-]/)
-~~~
+> [!NOTE]
+> In practical use, this would most likely be done with a single `reg` call:
+>
+> ~~~ ruby
+> reg(/[+-]/)
+> ~~~
 
 ### Repetition
 
@@ -167,7 +176,7 @@ You can specify the minimum and maximum number of repetitions, using a range.
 This example matches one or more digits.
 
 ~~~ ruby
-rep(match(/\d+/), 1..)
+rep(reg(/\d+/), 1..)
 ~~~
 
 ### Operator DSL
@@ -180,8 +189,8 @@ The `[]` operator can be used in place of the `rep` combinator.
 For example, the following two lines are equivalent:
 
 ~~~ ruby
-seq(term, match("+"), term)
-term + match("+") + term
+seq(term, str("+"), term)
+term + str("+") + term
 ~~~
 
 ## Parse Tree

docs/TODO.md

@@ -13,10 +13,9 @@ Here's a list of things I'd like to complete to make Grammy **great**.
 
 ## Grammar
 
+- [x] primitive combinators: `str` and `reg`
 - [x] primitive combinators: `seq`, `alt`, `rep`
 - [x] add `_` to canonical names
-- [ ] separate `match` and `regex`?
-- [ ] maybe rename `match` to `str` and `rex`?
 - [ ] try out the decorated methods syntax
 - [ ] try out the instance methods syntax
 

lib/grammy/combinator/primitives.rb

@@ -1,4 +1,5 @@
-require "grammy/matcher"
+require "grammy/matcher/string"
+require "grammy/matcher/regexp"
 require "grammy/matcher/sequence"
 require "grammy/matcher/alternative"
 require "grammy/matcher/repetition"
@@ -8,16 +9,18 @@ module Grammy
   module Combinator
     module Primitives
 
-      protected def match(pattern) = Grammy::Matcher.new(pattern)
+      protected def str(pattern) = Grammy::Matcher::String.new(pattern)
+      protected def reg(pattern) = Grammy::Matcher::Regexp.new(pattern)
       protected def seq(*matchers) = Grammy::Matcher::Sequence.new(*matchers)
       protected def alt(*matchers) = Grammy::Matcher::Alternative.new(*matchers)
       protected def rep(matcher, count_range) = Grammy::Matcher::Repetition.new(matcher, count_range)
 
       # Use these aliases if you have naming conflicts with your grammar.
-      alias _match match
       alias _seq seq
       alias _alt alt
       alias _rep rep
+      alias _str str
+      alias _reg reg
 
     end
   end

lib/grammy/grammar.rb

@@ -1,5 +1,4 @@
 require "grammy/combinator/primitives"
-require "grammy/matcher"
 require "grammy/errors"
 require "grammy/scanner"
 require "grammy/parse_tree"

lib/grammy/matcher.rb

@@ -6,8 +6,7 @@ class Matcher
 
     def initialize(pattern) = @pattern = pattern
 
-    # Returns a Match, if the pattern matches, else `nil`.
-    def match(scanner) = scanner.match(@pattern)
+    def match(scanner) = fail NotImplementedError, "abstract method -- must override in derived classes"
 
     # DSL for sequence, alternative, and repetition.
     def +(other) = Matcher::Sequence.new(self, other)

lib/grammy/matcher/regexp.rb

@@ -0,0 +1,16 @@
+require "grammy/matcher"
+
+
+module Grammy
+  class Matcher
+    class Regexp < Matcher
+
+      def initialize(pattern) = @pattern = pattern
+
+      def match(scanner)
+        scanner.match_regexp(@pattern)
+      end
+
+    end
+  end
+end

lib/grammy/matcher/string.rb

@@ -0,0 +1,16 @@
+require "grammy/matcher"
+
+
+module Grammy
+  class Matcher
+    class String < Matcher
+
+      def initialize(string) = @string = string
+
+      def match(scanner)
+        scanner.match_string(@string)
+      end
+
+    end
+  end
+end

lib/grammy/scanner.rb

@@ -16,27 +16,20 @@ def initialize(input)
       @marks = [] # stack of Locations
     end
 
-    # Try to match given String or Regexp at current location.
+    # Try to match given String at current location.
     # Returns `nil` if pattern does not match.
     # Otherwise, updates @location and returns a Match object.
-    def match(pattern)
-      return nil if @location.index >= @input.size
-
-      if pattern.is_a?(String)
-        match_string(pattern)
-      elsif pattern.is_a?(Regexp)
-        match_regex(pattern)
-      else
-        fail ArgumentError, "Unsupported pattern type: #{pattern.class}"
-      end
-    end
-
     def match_string(pattern)
+      return nil if @location.index >= @input.size
       return nil unless remaining_input.start_with?(pattern)
       match_text(pattern)
     end
 
-    def match_regex(pattern)
+    # Try to match given Regexp at current location.
+    # Returns `nil` if pattern does not match.
+    # Otherwise, updates @location and returns a Match object.
+    def match_regexp(pattern)
+      return nil if @location.index >= @input.size
       anchored_regex = Regexp.new("\\A(?:#{pattern.source})", pattern.options)
       match = remaining_input.match(anchored_regex)
       return nil unless match

spec/alternative_spec.rb

@@ -7,8 +7,8 @@
   subject(:matcher) { described_class.new(*alternatives) }
   let(:alternatives) {
     [
-      Grammy::Matcher.new(/\d+/),
-      Grammy::Matcher.new(/abc/)
+      Grammy::Matcher::Regexp.new(/\d+/),
+      Grammy::Matcher::Regexp.new(/abc/)
     ]
   }
   let(:scanner) { Grammy::Scanner.new(input) }

spec/grammar/alt_spec.rb

@@ -2,7 +2,7 @@
 
 class AltGrammar < Grammy::Grammar
   root(:greeting)
-  rule(:greeting) { alt(match("hello"), match("hi"), match("hey")) }
+  rule(:greeting) { alt(str("hello"), str("hi"), str("hey")) }
 end
 
 RSpec.describe AltGrammar do