Documentation for Assert

2 files changed, 45 insertions, 18 deletions

diff --git a/src/parcom.cr b/src/parcom.cr
index 39329f7..c1d9791 100644
--- a/src/parcom.cr
+++ b/src/parcom.cr
@@ -81,24 +81,6 @@ module Parcom
     end
   end
 
-  class Assert(T, V) < Parser(T, V)
-    def initialize(@p : Parser(T, V), &block : V -> Bool)
-      @f = block
-    end
-
-    def parse(tokens : Tokens(T)) : Result(T, V)
-      result = @p.parse(tokens)
-    rescue ex : ParserFail
-      raise ParserFail.new("Assert (pre-assertion): #{ex.message}")
-    else
-      unless @f.call(result.value)
-        raise ParserFail.new("Assert: predicate failed for <#{result.value}>")
-      end
-
-      return result
-    end
-  end
-
   class Satisfy(T) < Parser(T, T)
     @p : Assert(T, T)
 
diff --git a/src/parcom/assert.cr b/src/parcom/assert.cr
new file mode 100644
index 0000000..5a3e621
--- /dev/null
+++ b/src/parcom/assert.cr
@@ -0,0 +1,45 @@
+require "./parser.cr"
+
+module Parcom
+  # `Assert` is a `Parser` that runs another `Parser` and then
+  # performs a test on its result. The parser will then either fail if
+  # the result does not pass the test, or forward it on if it does.
+  #
+  # Example:
+  # ```
+  # letter = Assert.new(AnyToken(Char).new) { |x| x.letter? }
+  # non_letter = Assert.new(AnyToken(Char).new) { |x| !x.letter? }
+  # input = Tokens.from_string("hi")
+  # letter.parse(input) # this succeeds
+  # non_letter.parse(input) # this fails
+  # ```
+  #
+  # `Assert` instance can also be created by calling
+  # `Parser#assert` on any parser:
+  # ```
+  # # This parser is identical to the above example.
+  # letter = AnyToken.new(Char).assert { |x| x.letter? }
+  # ```
+  class Assert(T, V) < Parser(T, V)
+    # Accepts the parser to run and a `Bool`-retuning block
+    # containing the test to perform on the other parser's result.
+    def initialize(@p : Parser(T, V), &block : V -> Bool)
+      @f = block
+    end 
+
+    # Runs the parser it was initialized with, and returns that parser's
+    # result if it passes the provided test. Raises `ParserFail` otherwise.
+    def parse(tokens : Tokens(T)) : Result(T, V)
+      result = @p.parse(tokens)
+    rescue ex : ParserFail
+      raise ParserFail.new("Assert (pre-assertion): #{ex.message}")
+    else
+      unless @f.call(result.value)
+        raise ParserFail.new("Assert: predicate failed for <#{result.value}>")
+      end
+
+      return result
+    end
+  end
+end
+