exactly, at_least, at_most, between

1 files changed, 126 insertions, 2 deletions

diff --git a/src/parcom/parser.cr b/src/parcom/parser.cr
index 8ee3f68..0b09e95 100644
--- a/src/parcom/parser.cr
+++ b/src/parcom/parser.cr
@@ -259,11 +259,135 @@ module Parcom
       end
     end
 
-    # Creates a new parser from `self` that parses with `self` as many times
-    # as possible. Raises `ParserFail` it never succeeds.
+    # Creates a new parser from `self` that repeatedly parses with `self`
+    # at least once. Raises `ParserFail` it never succeeds.
     def some : Parser(T, Array(U))
       many.assert { |arr| !arr.empty? }.named("Some: #{@name}")
     end
+
+    # Creates a new parser from `self` that tries to parse with `self`
+    # exactly `n` times. If `self` ever fails, the whole parser fails.
+    # Raises `ArgumentError` if `n` is negative, but will accept `0`. 
+    def exactly(n : Int) : Parser(T, Array(U))
+      if n.negative?
+        raise ArgumentError.new("`n` must be non-negative (got #{n})")
+      end
+
+      p = self
+      Parser(T, Array(U)).new("#Exactly #{n} <#{@name}>") do |tokens|
+        values = [] of U
+        n.times do
+          result = p.parse(tokens)
+          values << result.value
+          tokens = result.tokens
+        end
+        Result.new(tokens, values)
+      end
+    end
+
+    # :ditto:
+    def *(n : Int) : Parser(T, Array(U))
+      exactly(n)
+    end
+
+    # Creates a new parser from `self` that tries to parse with `self`
+    # at least `n` times. If `self` fails before it is able to parse `n` times,
+    # the whole parser fails. If it is able to parse `n` times, it will continue
+    # to parse until `self` fails.
+    # Raises `ArgumentError` if `n` is negative, but will accept `0`.
+    # TODO: Maybe introduce a `>=` shorthand?
+    def at_least(n : Int) : Parser(T, Array(U))
+      if n.negative?
+        raise ArgumentError.new("`n` must be non-negative (got #{n})")
+      end
+
+      (exactly(n) + many).map do |t|
+        t.first + t.last
+      end.named("At least #{n} #{@name}")
+    end
+
+    # Creates a new parser from `self` that tries to parse with `self`
+    # at most `n` times. If `self` succeeds `n` times, parsing will stop
+    # and the accumulated results will be returned. It will not fail the
+    # chain if `self` fails, but will return all previous results.
+    # Raises `ArgumentError` if `n` is negative, but will accept `0`.
+    # TODO: Maybe introduce a `<=` shorthand?
+    # TODO: could be made faster by not depending on `#exactly`
+    def at_most(n : Int) : Parser(T, Array(U))
+      if n.negative?
+        raise ArgumentError.new("`n` must be non-negative (got #{n})")
+      end
+
+      optional.exactly(n).map(&.compact).named("At least #{n} #{@name}")
+    end
+
+    # Creates a new parser from `self` that tries to parse with `self`
+    # between `n` and `m` times (inclusive). The order that `n` and `m`
+    # are specified does not matter, this method will figure out the
+    # lower and greater values. If `self` does not succeed the minimum
+    # number of times, the whole parser will fail. If `self` succeeds
+    # the maximum number of times, or if `self` fails after succeeding
+    # the minimum number of times, parsing stops and the success values
+    # are returned.
+    # Raises `ArgumentError` if `n` or `m` is negative, but will accept `0`.
+    # TODO: Add support for `Range` objects
+    def between(n : Int, m : Int) : Parser(T, Array(U))
+      if n.negative?
+        raise ArgumentError.new("`n` must be non-negative (got #{n})")
+      end
+
+      if m.negative?
+        raise ArgumentError.new("`m` must be non-negative (got #{m})")
+      end
+
+      if n == m
+        return exactly(n).named("Between #{n}-#{n} <#{@name}>")
+      end
+
+      min = n < m ? n : m
+      extra = (n - m).abs
+
+      p = self
+      (exactly(min) + at_most(extra)).map do |t|
+        t.first + t.last
+      end.named("Between #{min}-#{extra} <#{@name}>")
+    end
+
+    # Creates a new parser from `self` that tries to parse with `self`
+    # a number of times within the given range. If `self` does not succeed
+    # the minimum number of times, the whole parser will fail. If `self`
+    # succeeds the maximum number of times, or if `self` fails after
+    # succeeding the minimum number of times, parsing stops and the
+    # success values are returned.
+    # Raises `ArgumentError` if the range includes negative numbers,
+    # but will accept `0`.
+    def between(r : Range(Int, Int)) : Parser(T, Array(U))
+      if r.begin.negative? || r.end.negative?
+        raise ArgumentError.new("All values in Range must be non-negative (got #{r})")
+      end
+
+      between(r.begin, r.end)
+    end
+
+    # Special overload of `#between` for beginless ranges.
+    # Raises `ArgumentError` if the range end is negative.
+    def between(r : Range(Nil, Int)) : Parser(T, Array(U))
+      if r.end.negative?
+        raise ArgumentError.new("End of beginless range must be non-negative (got #{r})")
+      end
+
+      at_most(r.end).named("Between 0-#{r.end} <#{@name}>")
+    end
+
+    # Special overload of `#between` for endless ranges.
+    # Raises `ArgumentError` if the range start is negative.
+    def between(r : Range(Int, Nil)) : Parser(T, Array(U))
+      if r.begin.negative?
+        raise ArgumentError.new("Start of endless range must be non-negative (got #{r})")
+      end
+
+      at_least(r.begin).named("Between #{r.begin}-infinity <#{@name}> (from inifnite range)")
+    end
   end
 end