grammars: document action methods

Author: moritz

lib/Language/grammars.pod

@@ -171,8 +171,112 @@ the supplied string.
 Parses the contents of the file C<$filename> with the L<parse> method,
 passing any named options in C<%opts>.
 
-=head1 Action Classes
+=head1 Action Objects
 
-TODO
+A successful grammar match gives you a parse tree of L<Match|/type/Match>
+objects, and the deeper that match tree gets, and the more branches in the
+grammar are, the harder it becomes to navigate the match tree to get the
+information you are actually interested in.
+
+To avoid the need for diving deep into a match tree, you can supply an
+I<actions> object. After each successful parse of a named rule in your
+grammar, it tries to call a method of the same name as the grammar rule,
+giving it the newly create L<Match|/type/Match> object as a positional
+argument. If no such method exists, it is skipped.
+
+Here is a contrieved example of a grammar and actions in action:
+
+=begin code
+use v6;
+
+grammar TestGrammar {
+    token TOP { ^ \d+ $ }
+}
+
+class TestActions {
+    method TOP($/) {
+        $/.make(2 + ~$/);
+    }
+}
+
+my $actions = TestActions.new;
+my $match = TestGrammar.parse('40', :$actions);
+say $match;         # ｢40｣
+say $match.made;    # 42
+=end code
+
+An instance of C<TestActions> is passed as named argument C<actions> to the
+L<parse|/type/Grammar|method parse> call, and when token C<TOP> has matched
+successfully, it automatically calls method C<TOP>, passing the match object
+as an argument.
+
+To make it clear that the argument is a match object, the example uses C<$/>
+as a parameter name to the action method, though that's just a handy
+convention, notthing intrinsic. C<$match> would have worked too. (Though using
+C<$/> does give the advantage of providing C<< $<capture> >>> as a shortcut
+for C<< $/<capture> >>).
+
+A slightly more involved example follows:
+
+=begin code
+use v6;
+
+grammar KeyValuePairs {
+    token TOP {
+        [<pair> \n+]*
+    }
+    token ws { \h* }
+
+    rule pair {
+        <key=.identifier> '=' <value=.identifier>
+    }
+    token identifier {
+        \w+
+    }
+}
+
+class KeyValuePairsActions {
+    method identifier($/) { $/.make: ~$/                          }
+    method pair      ($/) { $/.make: $<key>.made => $<value>.made }
+    method TOP       ($/) { $/.make: $<pair>».made                }
+}
+
+my  $res = KeyValuePairs.parse(q:to/EOI/, :actions(KeyValuePairsActions)).made;
+    second=b
+    hits=42
+    perl=6
+    EOI
+
+for @$res -> $p {
+    say "Key: $p.key()\tValue: $p.value()";
+}
+=end code
+
+This produces the following ouput:
+
+=begin code
+Key: second     Value: b
+Key: hits       Value: 42
+Key: perl       Value: 6
+=end code
+
+Rule C<pair>, which parsed a pair separated by an equals sign, aliases the two
+calls to token C<identifier> to separate capture names to make them available
+more easily and intuitively. The corresponding action method constructs a
+L<Pair|/type/Pair> object, and uses the C<.made> property of the sub match
+objects. So it (like the action method C<TOP> too) exploits the fact that
+action methods for submatches are called before those of the calling/outer
+regex. So action methods are called in
+L<post-order|https://en.wikipedia.org/wiki/Tree_traversal#Post-order>.
+
+The action method C<TOP> simply collects all the objects that were C<.made> by
+the multiple matches of the C<pair> rule, and returns them in a list.
+
+Also note that C<KeyValuePairsActions> was passed as a type object to method
+C<parse>, which was possible because none of the action methods use attributes
+(which would only be available in an instance).
+
+In other cases, action methods might want to keep state in attributes. Then of
+course you must pass an instance to method parse.
 
 =end pod

lib/Type/Match.pod

@@ -31,9 +31,13 @@ Returns the index of the starting position of the match.
 
 Returns the index of the end position of the match.
 
+=head2 method made
+
+Returns the payload that was set with L<#method make>.
+
 =head2 method ast
 
-Returns the AST (i.e. payload).
+Alias for L<#method made>.
 
 =head2 method Str