Unify Type/Grammar.pod and Language/grammars.pod on methods. See issue #58.

Author: jdv

lib/Language/grammars.pod

@@ -70,107 +70,12 @@ into effect for the Regex:
 
 =SUBTITLE Group of named regexes that form a formal grammar
 
-    class Grammar is Cursor { }
-
-C<Grammar> is the superclass that classes automatically get when they are
-declared with the C<grammar> keyword instead of C<class>. Grammars should
-only be used to parse text; if you wish to extract complex data, an L<action
-object|/language/grammars#Action_Objects> is recommended to be used in
+L<Grammar|/type/Grammar> is the superclass that classes automatically get when
+they are declared with the C<grammar> keyword instead of C<class>. Grammars
+should only be used to parse text; if you wish to extract complex data, an
+L<action object|/language/grammars#Action_Objects> is recommended to be used in
 conjunction with the grammar.
 
-    =begin code :allow<B L>
-    B<grammar> CSV {
-        token TOP { [ <line> \n? ]+ }
-        token line {
-            ^^            # Beginning of a line
-            <value>* % \, # Any number of <value>s with commas in between them
-            $$            # End of a line
-        }
-        token value {
-            [
-            | <-[",\n]>     # Anything not a double quote, comma or newline
-            | <quoted-text> # Or some quoted text
-            ]*              # Any number of times
-        }
-        token quoted-text {
-            \"
-            [
-            | <-["\\]> # Anything not a " or \
-            | '\"'     # Or \", an escaped quotation mark
-            ]*         # Any number of times
-            \"
-        }
-    }
-
-    say "Valid CSV file!" if CSV.L<parse>( q:to/EOCSV/ );
-        Year,Make,Model,Length
-        1997,Ford,E350,2.34
-        2000,Mercury,Cougar,2.38
-        EOCSV
-    =end code
-
-=head2 Methods
-
-=head3 method parse
-
-    method parse($str, :$rule = 'TOP', :$actions) returns Match:D
-
-Matches the grammar against C<$str>, using C<$rule> as the starting rule,
-optionally applying C<$actions> as its actions object.
-
-This will fail if the grammar does not parse the I<entire> string. If a
-parse of only a part of the string is desired, use L<subparse>.
-
-The method returns the resulting L<Match> object and also sets the caller's
-C<$/> variable to the Match object.
-
-    =begin code :allow<B>
-    say CSVB<.parse>( q:to/EOCSV/ );
-        Year,Make,Model,Length
-        1997,Ford,E350,2.34
-        2000,Mercury,Cougar,2.38
-        EOCSV
-    =end code
-
-This outputs:
-
-    ｢Year,Make,Model,Length
-    1997,Ford,E350,2.34
-    2000,Mercury,Cougar,2.38
-    ｣
-     line => ｢Year,Make,Model,Length｣
-      value => ｢Year｣
-      value => ｢Make｣
-      value => ｢Model｣
-      value => ｢Length｣
-     line => ｢1997,Ford,E350,2.34｣
-      value => ｢1997｣
-      value => ｢Ford｣
-      value => ｢E350｣
-      value => ｢2.34｣
-     line => ｢2000,Mercury,Cougar,2.38 ｣
-      value => ｢2000｣
-      value => ｢Mercury｣
-      value => ｢Cougar｣
-      value => ｢2.38 ｣
-
-=head3 method subparse
-
-    method subparse($str, :$rule = 'TOP', :$actions) returns Match:D
-
-Matches the grammar against C<$str>, using C<$rule> as the starting rule,
-optionally applying C<$actions> as its actions object.
-
-Unlike L<parse>, C<subparse> will allow the grammar to match only part of
-the supplied string.
-
-=head3 method parsefile
-
-    method parsefile(Str(Cool) $filename, *%opts) returns Match:D
-
-Parses the contents of the file C<$filename> with the L<parse> method,
-passing any named options in C<%opts>.
-
 =head1 Action Objects
 
 A successful grammar match gives you a parse tree of L<Match|/type/Match>

lib/Type/Grammar.pod

@@ -27,7 +27,7 @@ More L<documentation on grammars|/language/grammars> is available.
 
 =head2 method parse
 
-    method parse($target, :$rule = 'TOP', Parcel :$args = (), Mu :$actions, *%opts)
+    method parse($target, :$rule = 'TOP',  Parcel :$args = (), Mu :$actions = Mu, *%opt) {
 
 Parses the C<$target> (which will be coerced to L<Str|/type/Str> if it isn't
 one), using C<$rule> as the starting rule. Additional C<$args> will be given
@@ -49,9 +49,58 @@ if you want to be able to stop in the middle.
 Returns a L<Match object|/type/Match> on success, and L<Nil|/type/Nil> on
 failure.
 
+    grammar CSV {
+        token TOP { [ <line> \n? ]+ }
+        token line {
+            ^^            # Beginning of a line
+            <value>* % \, # Any number of <value>s with commas in between them
+            $$            # End of a line
+        }
+        token value {
+            [
+            | <-[",\n]>     # Anything not a double quote, comma or newline
+            | <quoted-text> # Or some quoted text
+            ]*              # Any number of times
+        }
+        token quoted-text {
+            \"
+            [
+            | <-["\\]> # Anything not a " or \
+            | '\"'     # Or \", an escaped quotation mark
+            ]*         # Any number of times
+            \"
+        }
+    }.parse( q:to/EOCSV/ ).say;
+        Year,Make,Model,Length
+        1997,Ford,E350,2.34
+        2000,Mercury,Cougar,2.38
+        EOCSV
+
+This outputs:
+
+    ｢Year,Make,Model,Length
+    1997,Ford,E350,2.34
+    2000,Mercury,Cougar,2.38
+    ｣
+     line => ｢Year,Make,Model,Length｣
+      value => ｢Year｣
+      value => ｢Make｣
+      value => ｢Model｣
+      value => ｢Length｣
+     line => ｢1997,Ford,E350,2.34｣
+      value => ｢1997｣
+      value => ｢Ford｣
+      value => ｢E350｣
+      value => ｢2.34｣
+     line => ｢2000,Mercury,Cougar,2.38 ｣
+      value => ｢2000｣
+      value => ｢Mercury｣
+      value => ｢Cougar｣
+      value => ｢2.38 ｣
+
 =head2 method subparse
 
-    method subparse($target, :$rule = 'TOP', Parcel :$args = (), Mu :$actions, *%opts)
+    method subparse($target, :$rule = 'TOP', Parcel :$args = (),  Mu :$actions = Mu, *%opt) {
 
 Does exactly the same as L<method parse|/routine/parse>, except that cursor
 doesn't have to reach the end of the string to succeed. (That is, it doesn't
@@ -66,7 +115,7 @@ have to match the whole string).
 
 =head2 method parsefile
 
-    method parsefile(Cool $filename, *%opts);
+    method parsefile(Str(Cool) $filename, :$enc, *%opts) {
 
 Reads file C<$filename>, and parses it. All named arguments are passsed on to
 L<method parse|/routine/parse>.