Documentation for FirstOf + minor refactor

2 files changed, 40 insertions, 27 deletions

diff --git a/src/parcom.cr b/src/parcom.cr
index 0170fdc..8c55014 100644
--- a/src/parcom.cr
+++ b/src/parcom.cr
@@ -81,33 +81,6 @@ module Parcom
     end
   end
 
-  class FirstOf(T, V) < Parser(T, V)
-    @p : Parser(T, V)
-
-    def initialize(ps : Iterable(Parser(T, V)))
-      ps_iter = ps.each
-      p = ps_iter.next
-
-      if p.is_a?(Iterator::Stop)
-        raise ArgumentError.new("FirstOf requires atleast one parser, got none")
-      end
-
-      @p = p
-      p = ps_iter.next
-
-      until p.is_a?(Iterator::Stop)
-        @p = @p | p
-        p = ps_iter.next
-      end
-    end
-
-    def parse(tokens : Tokens(T)) : Result(T, V)
-      @p.parse(tokens)
-    rescue ex : ParserFail
-      raise ParserFail.new("FirstOf: #{ex.message}")
-    end
-  end
-
   class SepBy(T, V, U) < Parser(T, Array(V))
     @p : Map(T, {V, Array(V)}, Array(V))
 
diff --git a/src/parcom/first_of.cr b/src/parcom/first_of.cr
new file mode 100644
index 0000000..c4077eb
--- /dev/null
+++ b/src/parcom/first_of.cr
@@ -0,0 +1,40 @@
+require "./parser.cr"
+
+module Parcom
+  # `FirstOf` is a `Parser` that accepts multiple parsers, and tries to parse
+  # with all of them, in order. As soon as one of the parsers succeeds,
+  # that parser's result is returned. If none of the parsers are successful,
+  # the parsing fails.
+  class FirstOf(T, V) < Parser(T, V)
+    @p : Parser(T, V)
+
+    # Accepts the parsers to use. Raises an `ArgumentError` if
+    # no parsers are provided.
+    def initialize(ps : Iterable(Parser(T, V)))
+      ps_iter = ps.each
+      p = ps_iter.next
+
+      if p.is_a?(Iterator::Stop)
+        raise ArgumentError.new("FirstOf requires atleast one parser, got none")
+      end
+
+      # Combine all the parsers into one by wrapping them with `Alt`.
+      @p = p
+
+      loop do
+        p = ps_iter.next
+        break if p.is_a?(Iterator::Stop)
+        @p = @p | p
+      end
+    end
+
+    # Tries to parse with each of the given parsers. Either returns the first
+    # successful result or fails if no parsers succeed.
+    def parse(tokens : Tokens(T)) : Result(T, V)
+      @p.parse(tokens)
+    rescue ex : ParserFail
+      raise ParserFail.new("FirstOf: #{ex.message}")
+    end
+  end
+end
+