wip

Author: threadless-screw

doc/Language/regexes.pod6

@@ -12,20 +12,13 @@ matching those patterns to actual text.
 
 =head1 X<Lexical conventions|quote,/ /;quote,rx;quote,m>
 
-Fundamentally, regexes are very much like subroutines: both are code objects,
-and just as you can have anonymous subs and named subs, you can have anonymous
-and named regexes.
+Fundamentally, Perl 6 regexes are very much like subroutines: both are code
+objects, and just as you can have anonymous subs and named subs, you can have
+anonymous and named regexes.
 
 A regex, whether anonymous or named, is represented by a L<C<Regex>|/type/Regex>
-object. The syntax for constructing anonymous and named C<Regex> objects
-differs, as do their intended uses.
-
-In short, anonymous regexes may be used anywhere where a regex is needed with
-the exception of L<C<Grammars>|/type/Grammar>, which are the domain of named
-regexes. Named regexes form the building blocks of grammars, in which they serve
-as methods (also known as 'subrules') that can be called from other regexes to
-effectively parse textual data.
-
+object. Yet, the syntax for constructing anonymous and named C<Regex> objects
+differs. We will therefore discuss them in turn.
 
 =head2 Anonymous regex definition syntax
 
@@ -34,7 +27,7 @@ An anonymous regex may be constructed in one of the following ways:
     rx/pattern/;          # an anonymous Regex object; 'rx' stands for 'regex'
     /pattern/;            # an anonymous Regex object; shorthand for 'rx/.../'
 
-    regex { pattern }     # keyword-declared anonymous regex; this form is
+    regex { pattern };    # keyword-declared anonymous regex; this form is
                           # intended for defining named regexes and is discussed
                           # in that context in the next section
 
@@ -43,8 +36,8 @@ The C<rx/ /> form has two advantages over the bare shorthand form C</ />.
 Firstly, it enables the use of delimiters other than the slash, which may be
 used to improve the readability of the regex definition:
 
-    rx{ '/tmp/'.* }       # the use of curly braces as delimiters makes this first
-    rx/ '/tmp/'.* /       # definition somewhat easier on the eyes than the second
+    rx{ '/tmp/'.* };      # the use of curly braces as delimiters makes this first
+    rx/ '/tmp/'.* /;      # definition somewhat easier on the eyes than the second
 
 Although the choice is vast, not every character may be chosen as an alternative
 regex delimiter:
@@ -87,8 +80,8 @@ given a name by putting them inside a named variable, after which they can be
 referenced, e.g. direcly or by means of
 L<interpolation|/language/regexes#Regex_interpolation>:
 
-  my $regex = / k \w+ /;
-  say "Made in a low firing kiln" ~~ $regex;  # OUTPUT: ｢kiln｣
+  my $regex = / R \w+ /;
+  say "Zen Buddists like Raku too" ~~ $regex; # OUTPUT: ｢Raku｣
 
   my $regex = /pottery/;
   "Japanese pottery rocks!" ~~ / <$regex> /;  # Interpolation of $regex into /.../
@@ -98,7 +91,7 @@ L<interpolation|/language/regexes#Regex_interpolation>:
 
 A named regex may be constructed using the C<regex> declarator as follows:
 
-    regex R { pattern }         # a named Regex object, named 'R'
+    regex R { pattern };        # a named Regex object, named 'R'
 
 Unlike with the C<rx> form, you cannot chose your preferred delimiter: curly
 braces are mandatory. In this regard it should be noted that the definition of a
@@ -111,28 +104,34 @@ of a subroutine:
 which emphasizes the fact that a L<C<Regex>|/type/Regex> object represents code
 rather than data:
 
-    &S ~~ Code                  # OUTPUT: True
+    &S ~~ Code;                 # OUTPUT: True
 
-    &R ~~ Code                  # OUTPUT: True
-    &R ~~ Method                # OUTPUT: True (A Regex is really a Method!)
+    &R ~~ Code;                 # OUTPUT: True
+    &R ~~ Method;               # OUTPUT: True (A Regex is really a Method!)
 
 Also unlike with the C<rx> form for defining an anonymous regex, the definition
 of a named regex using the C<regex> form does not allow for adverbs to be
 inserted before the opening delimiter. Instead, adverbs that are to modify the
 entire regex pattern may be included first thing within the curly braces:
 
-    regex R { :i pattern }      # :i (:ignorecase), renders pattern case insensitive
+    regex R { :i pattern };     # :i (:ignorecase), renders pattern case insensitive
 
 Alternatively, by way of shorthand, it is also possible (and recommended) to use
 the C<rule> and C<token> variants of the C<regex> declarator for defining a
 C<Regex> when the C<:ratchet> and C<:sigspace> adverbs are of interest:
 
-    regex R { :r pattern }      # apply :r (:ratchet) to entire pattern
-    token R { pattern }         # same thing: 'token' implies ':r'
+    regex R { :r pattern };     # apply :r (:ratchet) to entire pattern
+    token R { pattern };        # same thing: 'token' implies ':r'
 
-    regex R { :r :s pattern }   # apply :r (:ratchet) and :s (:sigspace) to pattern
-    rule  R { pattern }         # same thing: 'rule' implies ':r:s'
+    regex R { :r :s pattern };  # apply :r (:ratchet) and :s (:sigspace) to pattern
+    rule  R { pattern };        # same thing: 'rule' implies ':r:s'
 
+Named regexes may be used as building blocks for other regexes, as they are
+methods that may called from within other regexes using the C«<regex-name>»
+syntax. When they are used this way, they are often referred to as 'subrules';
+see for more details on their use L<here|/language/regexes#Subrules>.
+L<C<Grammars>|/type/Grammar> are the natural niche for subrules, but many common
+predefined character classes are also implemented as named regexes.
 
 =head2 Regex readability: whitespace and comments