Documentation for Some

2 files changed, 33 insertions, 14 deletions

diff --git a/src/parcom.cr b/src/parcom.cr
index c7dde7b..4f35420 100644
--- a/src/parcom.cr
+++ b/src/parcom.cr
@@ -119,20 +119,6 @@ module Parcom
     end
   end
 
-  class Some(T, V) < Parser(T, Array(V))
-    @p : Assert(T, Array(V))
-
-    def initialize(p : Parser(T, V))
-      @p = Many.new(p).assert { |arr| !arr.empty? }
-    end
-
-    def parse(tokens : Tokens(T)) : Result(T, Array(V))
-      @p.parse(tokens)
-    rescue ex : ParserFail
-      raise ParserFail.new("Some: #{ex.message}")
-    end
-  end
-
   class Exactly(T, V) < Parser(T, Array(V))
     @p : Sequence(T, V)
 
diff --git a/src/parcom/some.cr b/src/parcom/some.cr
new file mode 100644
index 0000000..a2e3563
--- /dev/null
+++ b/src/parcom/some.cr
@@ -0,0 +1,33 @@
+require "./parser.cr"
+require "./assert.cr"
+require "./many.cr"
+
+module Parcom
+  # `Some` is a `Parser` that repeatedly tries to parse with another parser.
+  # The `Some` object will collect all success values in an array, and
+  # return them with the final state of the input stream. If the wrapped
+  # parser ever fails or succeeds without parsing any input, the `Some`
+  # object will stop attempting to parse and will return the array of
+  # previous successes.
+  #
+  # `Some` will raise a `ParserFail` exception if the parser never succeeds
+  # or consumes input. For cases where parsing should allow for 0 successes,
+  # use `Many`.
+  class Some(T, V) < Parser(T, Array(V))
+    @p : Assert(T, Array(V))
+
+    # Accepts the parser to use.
+    def initialize(p : Parser(T, V)) 
+      @p = Many.new(p).assert { |arr| !arr.empty? }
+    end 
+
+    # Continuously parses with the wrapped parser, returns all successes.
+    # Fails if there are no successes.
+    def parse(tokens : Tokens(T)) : Result(T, Array(V))
+      @p.parse(tokens)
+    rescue ex : ParserFail
+      raise ParserFail.new("Some: #{ex.message}")
+    end 
+  end
+end
+