[regexes] describe capturing and groups

Author: moritz

lib/Language/regexes.pod

@@ -347,7 +347,68 @@ non-whitespace characters.
 
 =head1 Grouping and Capturing
 
-TODO
+In regular (non-regex) Perl 6, you can use parenthesis to group things
+together, usually to override operator precedence:
+
+    say 1 + 4 * 2;      # 9, because it is parsed as 1 + (4 * 2)
+    say (1 + 4) * 2;    # 10
+
+The same grouping facility is available in regexes:
+
+    / a || b c /        # matches 'a' or 'bc'
+    / ( a || b ) c /    # matches 'ac' or 'bc'
+
+The same grouping applies to quantifiers:
+
+    / a b+ /            # Matches an 'a' followed by one or more 'b's
+    / (a b)+ /          # Matches one or more sequences of 'ab'
+    / (a || b)+ /       # Matches a sequence of 'a's and 'b's, at least one long
+
+=head2 Capturing
+
+The round parenthesis don't just group, they also I<capture>; that is, they
+make the string that is matched by grouped part available:
+
+    my $str =  'number 42';
+    if $str ~~ /'number ' (\d+) / {
+        say "The number is $0";
+    }
+
+Pairs of parenthesis are numbered left to right, starting from zero.
+
+    if 'abc' ~~ /(a) b (c)/ {
+        say "0: $0; 1: $1";     # 0: a; 1: c
+    }
+
+The C<$0> and C<$1> etc. syntax is actually just a short-hand; these  captures
+are canonically available from the match object C<$/> by using it as a list,
+so C<$0> is actually a short way to write C<$/[0]>.
+
+Coercing the match object to a list gives an easy way to programmatically
+access all elements:
+
+    if 'abc' ~~ /(a) b (c)/ {
+        say $/.list.join: ', '  # a, c
+    }
+
+=head2 Non-capturing grouping
+
+The parenthesis in regexes perform a double role: they group the regex
+elements inside, and they capture what is matched by the sub-regex inside.
+
+To get only the grouping behavior, you can use brackets C<[ ... ]> instead.
+
+    if 'abc' ~~ / [a||b] (c) / {
+        say ~$0;                # c
+    }
+
+If you do not need the captures, using non-capturing groups provides three
+benefits: it communicates the intent more clearly, it makes it easier to count
+the capturing groups that you do care about, and it is a bit faster.
+
+=head2 Capture Numbers
+
+TODO: describe how alternations affect capturing numbers; nested captures
 
 =head1 Adverbs