Merge pull request #2940 from perl6/traps

Improvement of regex-interpolation trap section

Author: JJ

doc/Language/traps.pod6

@@ -921,29 +921,25 @@ of the assignment operators instead:
 
 =head1 Regexes
 
-=head1 Interpolation constructs
+=head2 C«$x» vs C«<$x>», and C«$(code)» vs C«<{code}>» 
 
 Perl 6 offers several constructs to generate regexes at runtime through
 interpolation (see their detailed description
-L<here|/language/regexes#Regex_interpolation>). When a thus generated regex
-contains only characters that match themselves, some of these constructs behave
-identically, as if they are equivalent alternatives. As soon as the generated
-regex contains metacharacters, however, they behave differently, which may come
-as an unpleasant and confusing surprise.
+L<here|/language/regexes#Regex_interpolation>). When a regex generated this way
+contains only literals, the above constructs behave (pairwise) identically, as
+if they are equivalent alternatives. As soon as the generated regex contains
+metacharacters, however, they behave differently, which may come as a confusing
+surprise.
 
 The first two constructs that may easily be confused with each other are
-C«$variable» and C«<$variable>». The former causes the (stringified) variable to
-match literally, while the latter causes the (stringified) variable to match as
-a regex. As long as the variable comprises only characters that, in a regex,
-match themselves (i.e. alphanumeric characters and the underscore), there is no
-distinction between the constructs:
+C«$variable» and C«<$variable>»:
 
     my $variable = 'camelia';
     say ‘I ♥ camelia’ ~~ /  $variable  /;   # OUTPUT: ｢camelia｣
     say ‘I ♥ camelia’ ~~ / <$variable> /;   # OUTPUT: ｢camelia｣
 
-But when the variable is changed to comprise regex metacharacters, i.e.
-characters that are neither alphanumeric nor the underscore C<_>, the outputs
+Here they act the same because the value of C<$variable> consists of literals.
+But when the variable is changed to comprise regex metacharacters the outputs
 become different:
 
     my $variable = '#camelia';
@@ -957,12 +953,9 @@ runs until the end of the line, which in turn causes the regex not to be
 terminated, and thus to be malformed.
 
 Two other constructs that must similarly be distinguished from one another are
-C«$(code)» and C«<{code}>». The former construct runs user-specified code within
-the regex and interpolates the (stringified) return value literally. The latter
-also runs user-specified code within the regex, but interpolates the
-(stringified) return value as a regex. So, like before, as long as the return
-value comprises only characters that match literally in a regex, there is no
-distinction between the two:
+C«$(code)» and C«<{code}>». Like before, as long as the (stringified) return
+value of C<code> comprises only literals, there is no distinction between the
+two:
 
     my $variable = 'ailemac;
     say ‘I ♥ camelia’ ~~ / $($variable.flip)   /;   # OUTPUT: ｢camelia｣