Documentation for recover

2 files changed, 27 insertions, 12 deletions

diff --git a/src/parcom.cr b/src/parcom.cr
index fdf7e31..6715e07 100644
--- a/src/parcom.cr
+++ b/src/parcom.cr
@@ -81,18 +81,6 @@ module Parcom
     end
   end
 
-  class Recover(T, V) < Parser(T, V)
-    @p : Map(T, V?, V)
-
-    def initialize(p : Parser(T, V), default : V)
-      @p = Optional.new(p).map { |x| x.nil? ? default : x }
-    end
-
-    def parse(tokens : Tokens(T)) : Result(T, V)
-      @p.parse(tokens)
-    end
-  end
-
   class Sequence(T, V) < Parser(T, Array(V))
     def initialize(@ps : Iterable(Parser(T, V)))
     end
diff --git a/src/parcom/recover.cr b/src/parcom/recover.cr
new file mode 100644
index 0000000..378f8d6
--- /dev/null
+++ b/src/parcom/recover.cr
@@ -0,0 +1,27 @@
+require "./parser.cr"
+require "./optional.cr"
+require "./map.cr"
+
+module Parcom
+  # `Recover` is a `Parser` that tries to parse with another parser,
+  # but does not fail the parser chain if the wrapped parser fails.
+  # If the wrapped parser fails, a `Recover` will not modify the input
+  # stream, and return an arbitrary value of type `V` instead.
+  class Recover(T, V) < Parser(T, V)
+    @p : Map(T, V?, V)
+
+    # Accepts the parser to use, and the default value
+    # to return if the parser fails.
+    def initialize(p : Parser(T, V), default : V)
+      @p = Optional.new(p).map { |x| x.nil? ? default : x }
+    end
+
+    # Tries to parse with the given parser, succeeds with the
+    # default value instead of failing. This parser does not
+    # consume input if the wrapped parser fails.
+    def parse(tokens : Tokens(T)) : Result(T, V)
+      @p.parse(tokens)
+    end
+  end
+end
+