Add Documentation for Higher Order Parsers (#212)

* Add documentation of higher-order parsers

* Fix error in higher order example

* Fix incorrect assert in higher order example

Author: cwfitzgerald

fastparse/test/src/fastparse/ExampleTests.scala

@@ -512,6 +512,15 @@ object ExampleTests extends TestSuite{
       }
     }
 
+    'higherorder{
+      def Indexed[_: P, T](p: => P[T]): P[(Int, T, Int)] = P( Index ~ p ~ Index )
+
+      def Add[_: P] = P( Num ~ "+" ~ Num )
+      def Num[_: P] = Indexed( CharsWhileIn("0-9").rep.! )
+
+      val Parsed.Success((0, "1", 1, (2, "2", 3)), _) = parse("1+2", Add(_))
+    }
+
     'folding{
       sealed trait AndOr
       case object And extends AndOr

readme/WritingParsers.scalatex

@@ -418,3 +418,19 @@
                 To explicitly isolate a cut to one branch of a parser, place that branch within @hl.scala{NoCut}.  Cuts within that branch will prevent backtracking inside that branch, but if that branch fails alternate branches will be tried as normal.
 
             @hl.ref(tests/"ExampleTests.scala", Seq("'composenocut", ""))
+
+    @sect{Higher Order Parsers}
+
+        @p
+            It is possible to write functions that take parsers as arguments and return other parsers. These are useful because it allows for the programmatic modification of many different parsers. This can be used to generate a large amount of parsers that only vary in minor ways.
+
+        @p
+            Parser arguments @b{must be passed by name}! Parsers are immediately evaluated, so if they aren't passed by name they will be evaluated when they are passed into a function, not within it, causing either a warning about @hl.scala{a pure expression does nothing in statement position} at compile time or a @hl.scala{ClassCastException} at runtime.
+
+        @p
+            A simple example of a higher order parser is one that adds index information to the beginning and end of the parse.
+
+        @hl.ref(tests/"ExampleTests.scala", Seq("'higherorder", ""))
+
+        @p
+            While this is a simple example, this concept to be extended to your hearts content.