From 5590009c35ae9da71745e56552410d86a5024217 Mon Sep 17 00:00:00 2001
From: JJ Merelo <jjmerelo@gmail.com>
Date: Thu, 9 Aug 2018 12:00:11 +0200
Subject: [PATCH] Adds example to grammar tutorial

Including use of $/, as requested by #2210.
---
 doc/Language/grammar_tutorial.pod6 | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/doc/Language/grammar_tutorial.pod6 b/doc/Language/grammar_tutorial.pod6
index 2217ec298..ce2b9b5c7 100644
--- a/doc/Language/grammar_tutorial.pod6
+++ b/doc/Language/grammar_tutorial.pod6
@@ -57,7 +57,7 @@ grammar defined, you call it and pass in a string for parsing.
 
 Now, you may be wondering, if I have all these regexes defined that just return
 their results, how does that help with parsing strings that may be ahead
-or backwards in a string, or things that need to be combined from many of
+or backwards in another string, or things that need to be combined from many of
 those regexes... And that's where grammar actions come in.
 
 For every "method" you match in your grammar, you get an action you can use
@@ -70,7 +70,7 @@ method is called C<TOP> by default.
 As already mentioned, grammars are declared using the I<grammar> keyword and its
 "methods" are declared with I<regex>, or I<token>, or I<rule>.
 
-=item Regex methods are slow but thorough, which will look back in the string
+=item Regex methods are slow but thorough, they will look back in the string
 and really try.
 
 =item Token methods are faster than regex methods and ignore whitespace.
@@ -78,9 +78,9 @@ and really try.
 =item Rule methods are the same as token methods except whitespace
 is not ignored.
 
-When a method (regex, token or rule) matches in the grammar,
-the string matched is put into a L<match object|/type/Match> and
-keyed with the same name as the method.
+When a method (regex, token or rule) matches in the grammar, the string matched
+is put into a L<match object|/type/Match> and keyed with the same name as the
+method.
 
     =begin code
     grammar G {
@@ -92,7 +92,25 @@ keyed with the same name as the method.
 If you were to use C<my $match = G.parse($string)> and your
 string started with 'clever_text_keyword', you would get a match
 object back that contained 'clever_text_keyword' keyed by
-the name of C«<thingy>» in your match object.
+the name of C«<thingy>» in your match object. For instance:
+
+=begin code
+grammar G {
+    token TOP { <thingy> .* }
+    token thingy { 'Þor' }
+}
+
+my $match = G.parse("Þor is mighty");
+say $match.perl;     # OUTPUT: «Match.new(made => Any, pos => 13, orig => "Þor is mighty",...»
+say $/.perl;         # OUTPUT: «Match.new(made => Any, pos => 13, orig => "Þor is mighty",...»
+say $/<thingy>.perl;
+# OUTPUT: «Match.new(made => Any, pos => 3, orig => "Þor is mighty", hash => Map.new(()), list => (), from => 0)␤»
+=end code
+
+The two first output lines show that C<$match> contains a C<Match> objects with
+the results of the parsing; but those results are also assigned to the L<match variable C<$/>|/syntax/$$SOLIDUS>.
+Either match object can be keyed, as
+indicated above, by C<thingy> to return the match for that particular C<token>.
 
 The C<TOP> method (whether regex, token, or rule) is the overarching pattern
 that must match everything (by default). If the parsed string doesn't