Further iteration with corrections and additions

Author: threadless-screw

doc/Language/regexes.pod6

@@ -1598,19 +1598,24 @@ pattern, which may be summarized as follows:
 
     Syntax         | Description
     ===============+===========================================================
-    C«$variable»   | Evaluates stringified contents of variable literally.
-    C«$(code)      | Runs Perl6 code inside the regex, and evaluates the
-                   | stringified result literally.
-    C«<$variable>» | Evaluates stringified contents of variable as a regex.
-    C«<{code}>»    | Runs Perl6 code inside the regex, and evaluates the
-                   | result as a regex.
+    C«$variable»   | Interpolates stringified contents of variable literally.
+    C«$(code)»     | Runs Perl6 code inside the regex, and interpolates the
+                   | stringified return value literally.
+    C«<$variable>» | Interpolates stringified contents of variable as a regex.
+    C«<{code}>»    | Runs Perl6 code inside the regex, and interpolates the
+                   | return value as a regex.
 
 =end table
 
-Let's start with the first two syntactical forms. These forms will interpolate
-the stringified value of the variable or the stringified return value of the
-code literally, assuming the respective value isn't a Regex. If the value is a
-Regex, it is evaluated as such.
+Let's start with the first two syntactical forms: C«$variable» and C«$(code)».
+These forms will interpolate the stringified value of the variable or the
+stringified return value of the code literally, provided that the respective
+value isn't a L<Regex object|/type/Regex>. If the value is a Regex, it will not
+be stringified, but instead be interpolated as such. 'Literally' means
+I<strictly literally>, that is: as if the respective stringified value is quoted
+with a basic C<Q> string L<C<Q[...]>|/language/quoting#Literal_strings:_Q>.
+Consequently, the stringified value will not itself undergo any (second-level)
+interpolation.
 
     my $string   = 'Is this a regex or a string: 123\w+False ?';
     my $pattern1 = 'string';
@@ -1642,41 +1647,53 @@ C<｢Is｣>. Statement C<[4]> shows how the stringified number is used as a matc
 pattern.
 
 Statement C<[5]> does not work as intended. To the human reader, the dot C<.>
-may seem to represent the L<method call operator|/language/operators#methodop_.>,
+may seem to represent the L<method call operator|/language/operators#methodop_.>, 
 but given the regex context the compiler will parse it as the regex wildcard
 L<.|/language/regexes#Wildcards> that matches any character. The apparent
 ambiguity may be resolved in various ways, for instance through the use of
-straightforward L<string interpolation|/language/quoting#Interpolation:_qq>
-from the regex as in statement C<[6]> (note that the inclusion of the call
-operator C<()> is key here), or by using the second syntax form from the above
-table as in statement C<[7]>, in which case the match pattern 'string' first
-emerges as the return value of the C<flip> method call. Since general Perl6
-code may be run from within the parentheses of C<$( )>, the same effect can
-also be achieved with a bit more effort, like in statement C<[8]>. Statement
-C<[9]> illustrates how the stringified version of the code's return value
-(the boolean value C<False>) is matched literally.
-
-Now consider the second two syntactical forms from the table above. These forms
-will stringify the value of the variable or the return value of the code and
-evaluate it as a regex. If the respective value is a Regex, it is evalued as
-such.
-
-    my $string   = 'Is this a regex or a string: 123\w+ ?';
-    my $pattern1 = '\w+';
-    my $number   = 123;
+straightforward L<string interpolation|/language/quoting#Interpolation:_qq> from
+the regex as in statement C<[6]> (note that the inclusion of the call operator
+C<()> is key here), or by using the second syntax form from the above table as
+in statement C<[7]>, in which case the match pattern C<'string'> first emerges
+as the return value of the C<flip> method call. Since general Perl6 code may be
+run from within the parentheses of C<$( )>, the same effect can also be achieved
+with a bit more effort, like in statement C<[8]>. Statement C<[9]> illustrates
+how the stringified version of the code's return value (the boolean value
+C<False>) is matched literally.
+
+Now consider the second two syntactical forms from the table above:
+C«<$variable>» and C«<${code}>». These forms will stringify the value of the
+variable or the return value of the code and interpolate it as a regex. If the
+respective value is a Regex, it is interpolated as such. 'Interpolated as a
+regex' means interpolated/inserted into the target Regex without protective
+quoting. Consequently, the further evaluation of the target Regex may trigger
+the (second-level) interpolation of any variables it contains.   
+
+    my $string         = 'Is this a regex or a string: 123\w+$x ?';
+    my $pattern1       = '\w+';
+    my $number         = 123;
     my sub f1          { return /s\w+/ };
     my sub f2 (Str $x) { return /$x x/ };
+    my sub f3          { return Q[$x]  };
 
     say $string.match: / <$pattern1>  /;                  # [1] OUTPUT: ｢Is｣
     say $string.match: / <$number>    /;                  # [2] OUTPUT: ｢123｣
     say $string.match: / <{ f1 }>     /;                  # [3] OUTPUT: ｢string｣
+
     my $x = "rege";
     say $string.match: / <{ f2($x) }> /;                  # [4] OUTPUT: ｢regex｣
-
-In statement C<[4]> use if made of function C<f2>, which acts as a (very simple)
-"regex factory": you can pass it a string variable, and it will return a Regex
-object into which the variable has been interpolated. In this case, C<f2> appends
-the letter 'x' to whatever string it is passed. 
+    say $string.match: / <{ f3     }> /;                  # [5] OUTPUT: ｢rege｣
+
+In statement C<[4]> use is made of the function C<f2>, which acts as a (very
+simple) "regex factory": you can pass it a string variable, and it will return a
+Regex object into which the variable has been interpolated. In this case, C<f2>
+appends the letter 'x' to whatever string it is passed. The Regex that is
+returned by C<f2> is in turn inserted into target Regex by the C<{...}>
+construct. Statement C<[5]> illustrates another case of two-fold regex
+interpolation. When the target Regex is constructed, the strictly literal string
+value C<$x> is interpolated into it by the C<{...}> construct. When the Regex is
+evaluated further, the unprotected variable C<$x> is interpolated, i.e. replaced
+by the string value C<rege>, which explains the match.
 
 Note: it may be desired to run arbitrary code from within the regex I<without>
 making use of its return value inside the regex. This may, for instance, come in