=begin pod :tag<perl6>

=TITLE Regexes

=SUBTITLE Pattern matching against strings

Regular expressions, I<regexes> for short, are a sequence of characters that
describe a pattern of text. Pattern matching is the process of matching
those patterns to actual text.

=head1 X<Lexical conventions|quote,/ /;quote,rx;quote,m>

Perl 6 has special syntax for writing regexes:

    m/abc/;         # a regex that is immediately matched against $_
    rx/abc/;        # a Regex object
    /abc/;          # a Regex object

For the first two examples, delimiters other than the slash can be used:

    m{abc};
    rx{abc};

Note that neither the colon C<:> nor round parentheses can be delimiters;
the colon is forbidden because it clashes with adverbs, such as C<rx:i/abc/>
(case insensitive regexes), and round parentheses indicate a function call
instead.

Whitespace in regexes is generally ignored (except with the C<:s> or
C<:sigspace> adverb).

As with Perl 6, in general, comments in regexes start with a hash character
C<#> and go to the end of the line.

=head1 Literals

The simplest case for a regex is a match against a string literal:

    if 'properly' ~~ m/ perl / {
        say "'properly' contains 'perl'";
    }

Alphanumeric characters and the underscore C<_> are matched literally. All
other characters must either be escaped with a backslash (for example, C<\:>
to match a colon), or be within quotes:

    / 'two words' /;     # matches 'two words' including the blank
    / "a:b"       /;     # matches 'a:b' including the colon
    / '#' /;             # matches a hash character

Strings are searched left to right, so it's enough if only
part of the string matches the regex:

    if 'abcdef' ~~ / de / {
        say ~$/;            # OUTPUT: «de␤»
        say $/.prematch;    # OUTPUT: «abc␤»
        say $/.postmatch;   # OUTPUT: «f␤»
        say $/.from;        # OUTPUT: «3␤»
        say $/.to;          # OUTPUT: «5␤»
    };

Match results are stored in the C<$/> variable and are also returned from
the match. The result is of L<type Match|/type/Match> if the match was successful;
otherwise it's L<Nil|/type/Nil>.

=head1 Wildcards and character classes

=head2 X<The dot matches any character: C<.>|regex,.>

An unescaped dot C<.> in a regex matches any single character.

So, these all match:

    'perl' ~~ /per./;       # matches the whole string
    'perl' ~~ / per . /;    # the same; whitespace is ignored
    'perl' ~~ / pe.l /;     # the . matches the r
    'speller' ~~ / pe.l/;   # the . matches the first l

This doesn't match:

    'perl' ~~ /. per /;

because there's no character to match before C<per> in the target string.

=head2 Backslashed, predefined character classes

There are predefined character classes of the form C<\w>. Its negation is
written with an upper-case letter, C<\W>.

=item X<\d and \D|regex,\d;regex,\D>

C<\d> matches a single digit (Unicode property C<N>) and C<\D> matches a
single character that is not a digit.

    'ab42' ~~ /\d/ and say ~$/;     # OUTPUT: «4␤»
    'ab42' ~~ /\D/ and say ~$/;     # OUTPUT: «a␤»

Note that not only the Arabic digits (commonly used in the Latin alphabet)
match C<\d>, but also digits from other scripts.

Examples for digits are:

    =begin code :skip-test
    U+0035 5 DIGIT FIVE
    U+07C2 ߂ NKO DIGIT TWO
    U+0E53 ๓ THAI DIGIT THREE
    U+1B56 ᭖ BALINESE DIGIT SIX
    =end code

=item X<\h and \H|regex,\h;regex,\H>

C<\h> matches a single horizontal whitespace character. C<\H> matches a
single character that is not a horizontal whitespace character.

Examples for horizontal whitespace characters are

    =begin code :skip-test
    U+0020 SPACE
    U+00A0 NO-BREAK SPACE
    U+0009 CHARACTER TABULATION
    U+2001 EM QUAD
    =end code

Vertical whitespace like newline characters are explicitly excluded; those
can be matched with C<\v>, and C<\s> matches any kind of whitespace.

=item X<\n and \N|regex,\n;regex,\N>

C<\n> matches a single, logical newline character. C<\n> is supposed to also
match a Windows CR LF codepoint pair; though it's unclear whether the magic
happens at the time that external data is read, or at regex match time.
C<\N> matches a single character that's not a logical newline.

=item X<\s and \S|regex,\s;regex,\S>

C<\s> matches a single whitespace character. C<\S> matches a single
character that is not whitespace.

    if 'contains a word starting with "w"' ~~ / w \S+ / {
        say ~$/;        # OUTPUT: «word␤»
    }

=item X<\t and \T|regex,\t;regex,\T>

C<\t> matches a single tab/tabulation character, C<U+0009>. (Note that
exotic tabs like the C<U+000B VERTICAL TABULATION> character are not
included here). C<\T> matches a single character that is not a tab.

=item X<\v and \V|regex,\v;regex,\V>

C<\v> matches a single vertical whitespace character. C<\V> matches a single
character that is not vertical whitespace.

Examples for vertical whitespace characters:

    =begin code :skip-test
    U+000A LINE FEED
    U+000B VERTICAL TABULATION
    U+000C FORM FEED
    U+000D CARRIAGE RETURN
    U+0085 NEXT LINE
    U+2028 LINE SEPARATOR
    U+2029 PARAGRAPH SEPARATOR
    =end code

Use C<\s> to match any kind of whitespace, not just vertical whitespace.

=item X<\w and \W|regex,\w;regex,\W>

C<\w> matches a single word character; i.e., a letter (Unicode category L), a
digit or an underscore. C<\W> matches a single character that isn't a word
character.

Examples of word characters:

    =begin code :skip-test
    0041 A LATIN CAPITAL LETTER A
    0031 1 DIGIT ONE
    03B4 δ GREEK SMALL LETTER DELTA
    03F3 ϳ GREEK LETTER YOT
    0409 Љ CYRILLIC CAPITAL LETTER LJE
    =end code

Predefined subrules:

    =begin code :skip-test
    <alnum>   \w       'alpha' plus 'digit'
    <alpha>   <:L>     Alphabetic characters
    <blank>   \h       Horizontal whitespace
    <cntrl>            Control characters
    <digit>   \d       Decimal digits
    <graph>            'alnum' plus 'punct'
    <lower>   <:Ll>    Lowercase characters
    <print>            'graph' plus 'space', but no 'cntrl'
    <punct>            Punctuation and Symbols (only Punct beyond ASCII)
    <space>   \s       Whitespace
    <upper>   <:Lu>    Uppercase characters
    <|wb>               Word Boundary (zero-width assertion)
    <ww>               Within Word (zero-width assertion)
    <xdigit>           Hexadecimal digit [0-9A-Fa-f]
    =end code

=head2 X«Unicode properties|regex,<:property>»

The character classes mentioned so far are mostly for convenience; another
approach is to use Unicode character properties. These come in the form C<<
<:property> >>, where C<property> can be a short or long Unicode General
Category name. These use pair syntax.

To match against a Unicode Property:

    "a".uniprop('Script');                 # OUTPUT: «Latin␤»
    "a" ~~ / <:Script<Latin>> /;
    "a".uniprop('Block');                  # OUTPUT: «Basic Latin␤»
    "a" ~~ / <:Block('Basic Latin')> /;

The following list of Unicode General Categories is stolen from the Perl 5
L<perlunicode|http://perldoc.perl.org/perlunicode.html> documentation:

=begin table

    Short       Long
    =====       =====
    L           Letter
    LC          Cased_Letter
    Lu          Uppercase_Letter
    Ll          Lowercase_Letter
    Lt          Titlecase_Letter
    Lm          Modifier_Letter
    Lo          Other_Letter
    M           Mark
    Mn          Nonspacing_Mark
    Mc          Spacing_Mark
    Me          Enclosing_Mark
    N           Number
    Nd          Decimal_Number (also Digit)
    Nl          Letter_Number
    No          Other_Number
    P           Punctuation (also punct)
    Pc          Connector_Punctuation
    Pd          Dash_Punctuation
    Ps          Open_Punctuation
    Pe          Close_Punctuation
    Pi          Initial_Punctuation
                (may behave like Ps or Pe depending on usage)
    Pf          Final_Punctuation
                (may behave like Ps or Pe depending on usage)
    Po          Other_Punctuation
    S           Symbol
    Sm          Math_Symbol
    Sc          Currency_Symbol
    Sk          Modifier_Symbol
    So          Other_Symbol
    Z           Separator
    Zs          Space_Separator
    Zl          Line_Separator
    Zp          Paragraph_Separator
    C           Other
    Cc          Control (also cntrl)
    Cf          Format
    Cs          Surrogate
    Co          Private_Use
    Cn          Unassigned

=end table

For example, C<< <:Lu> >> matches a single, upper-case letter.

It's negation is this: C<< <:!property> >>. So, C<< <:!Lu> >> matches a single
character that isn't an upper-case letter.

Categories can be used together, with an infix operator:

=begin table

    Operator    Meaning
    ========    =======
     +          set union
     |          set union
     &          set intersection
     -          set difference (first minus second)
     ^          symmetric set intersection / XOR

=end table

To match either a lower-case letter or a number, write
C<< <:Ll+:N> >> or C<< <:Ll+:Number> >> or C<< <+ :Lowercase_Letter + :Number> >>.

It's also possible to group categories and sets of categories with
parentheses; for example:

    'perl6' ~~ m{\w+(<:Ll+:N>)}  # OUTPUT: «0 => ｢6｣␤»

=head2 X«Enumerated character classes and ranges|regex,<[ ]>;regex,<-[ ]>»

Sometimes the pre-existing wildcards and character classes are not enough.
Fortunately, defining your own is fairly simple. Within C<< <[ ]> >>, you
can put any number of single characters and ranges of characters (expressed
with two dots between the end points), with or without whitespace.

    "abacabadabacaba" ~~ / <[ a .. c 1 2 3 ]> /;
    # Unicode hex codepoint range
    "ÀÁÂÃÄÅÆ" ~~ / <[ \x[00C0] .. \x[00C6] ]> /;
    # Unicode named codepoint range
    "ÀÁÂÃÄÅÆ" ~~ / <[ \c[LATIN CAPITAL LETTER A WITH GRAVE] .. \c[LATIN CAPITAL LETTER AE] ]> /;

Within the C<< < > >> you can use C<+> and C<-> to add or
remove multiple range definitions and
even mix in some of the unicode categories above. You can also
write the backslashed forms for character classes between the C< [ ] >.

    / <[\d] - [13579]> /;
    # starts with \d and removes odd ASCII digits, but not quite the same as
    / <[02468]> /;
    # because the first one also contains "weird" unicodey digits

To negate a character class, put a C<-> after the opening angle:

    say 'no quotes' ~~ /  <-[ " ]> + /;  # matches characters except "

A common pattern for parsing quote-delimited strings involves negated
character classes:

    say '"in quotes"' ~~ / '"' <-[ " ]> * '"'/;

This first matches a quote, then any characters that aren't quotes, and then
a quote again. The meaning of C<*> and C<+> in the examples above are
explained in L<section Quantifier|#Quantifiers>.

Just as you can use the C<-> for both set difference and negation of a
single value, you can also explicitly put a C<+> in front:

    / <+[123]> /  # same as <[123]>

=head1 Quantifiers

A quantifier makes the preceding atom match a
variable number of times. For example, C<a+> matches one or more C<a>
characters.

Quantifiers bind tighter than concatenation, so C<ab+> matches one C<a>
followed by one or more C<b>s. This is different for quotes, so C<'ab'+>
matches the strings C<ab>, C<abab>, C<ababab> etc.

=head2 X<One or more: C<+>|regex,+>

The C<+> quantifier makes the preceding atom match one or more times, with
no upper limit.

For example, to match strings of the form C<key=value>, you can write a regex
like this:

    / \w+ '=' \w+ /

=head2 X<Zero or more: C<*>|regex,*>

The C<*> quantifier makes the preceding atom match zero or more times, with
no upper limit.

For example, to allow optional whitespace between C<a> and C<b> you can write

    / a \s* b /

=head2 X<Zero or one match: C<?>|regex,?>

The C<?> quantifier makes the preceding atom match zero or once.

=head2 X<General quantifier: C<** min..max>|regex quantifier,**>

To quantify an atom an arbitrary number of times, you can write something like
C<a ** 2..5> to match the character C<a> at least twice and at most 5 times.

=begin code
say so 'a' ~~ /a ** 2..5/;        # OUTPUT: «False␤»
say so  'aaa' ~~ /a ** 2..5/;     # OUTPUT: «True␤»
=end code

If the minimal and maximal number of matches are the same, a single integer
is possible: C<a ** 5> matches C<a> exactly five times.

=begin code
say so 'aaaaa' ~~ /a ** 5/;       # OUTPUT: «True␤»
=end code

It's also possible to use non inclusive ranges using a caret:

=begin code
say so 'a'    ~~ /a ** 1^..^6/;   # OUTPUT: «False␤» -- there are 2 to 5 'a's in a row
say so 'aaaa' ~~ /a ** 1^..^6/;   # OUTPUT: «True␤»
=end code

This includes the numeric ranges starting from 0:

=begin code
say so 'aaa' ~~ /a ** ^6/;        # OUTPUT: «True␤» -- there are 0 to 5 'a's in a row
=end code

or a Whatever C<*> operator for an infinite range with a non inclusive minimum:

=begin code
say so 'aaaa' ~~ /a ** 1^..*/;    # OUTPUT: «True␤» -- there are 2 or more 'a's in a row
=end code

=head2 X<Modified quantifier: C<%>|regex,%;regex,%%>

To more easily match things like comma separated values, you can tack on a
C<%> modifier to any of the above quantifiers to specify a separator that must
occur between each of the matches. For example, C<a+ % ','> will match
C<a> or C<a,a> or C<a,a,a> or so on, but it will not match C<a,> or C<a,a,>.
To match those as well, use C<%%> instead of C<%>.

=head2 X<Greedy versus frugal quantifiers: C<?>|regex,?>

By default, quantifiers request a greedy match:

=begin code
'abababa' ~~ /a .* a/ && say ~$/;   # OUTPUT: «abababa␤»
=end code

You can attach a C<?> modifier to the quantifier to enable frugal
matching:

=begin code
'abababa' ~~ /a .*? a/ && say ~$/;   # OUTPUT: «aba␤»
=end code

You can also explicitly request greedy matching with the C<!> modifier.

=head2 X<Preventing backtracking: C<:>|regex,:>

You can prevent backtracking in regexes by attaching a C<:> modifier
to the quantifier:

=begin code
say so 'abababa' ~~ /a .* aba/;    # OUTPUT: «True␤»
say so 'abababa' ~~ /a .*: aba/;   # OUTPUT: «False␤»
=end code

=head1 X<Alternation: C<||>|regex,||>

To match one of several possible alternatives, separate them by C<||>; the
first matching alternative wins.

For example, C<ini> files have the following form:

    =begin code :skip-test
    [section]
    key = value
    =end code

Hence, if you parse a single line of an C<ini> file, it can be either a
section or a key-value pair and the regex would be (to a first
approximation):

    / '[' \w+ ']' || \S+ \s* '=' \s* \S* /

That is, either a word surrounded by square brackets, or a string of
non-whitespace characters, followed by zero or more spaces, followed by the
equals sign C<=>, followed again by optional whitespace, followed by another
string of non-whitespace characters.

=head1 X<Longest Alternation: C<|>|regex,|>

In regexes branches separated by C<|>, the longest match wins, independent of
the lexical ordering in the regexes.

    say ('abc' ~~ / a | .b /).Str;    # OUTPUT: «ab␤»

=head1 Anchors

The regex engine tries to find a match inside a string by searching from
left to right.

    say so 'properly' ~~ / perl/;   # OUTPUT: «True␤»
    #          ^^^^

But sometimes this is not what you want. Instead, you may only want to
match a whole string, or a whole line, or exactly one or several whole words.
I<Anchors> or I<assertions> can help with this.

Assertions need to match successfully in order for the whole regex to match but
they do not use up characters while matching.

=head2 X«C<^>, Start of String and C<$>, End of String|regex,^;regex,$»

The C<^> assertion only matches at the start of the string:

    say so 'properly' ~~ /  perl/;    # OUTPUT: «True␤»
    say so 'properly' ~~ /^ perl/;    # OUTPUT: «False␤»
    say so 'perly'    ~~ /^ perl/;    # OUTPUT: «True␤»
    say so 'perl'     ~~ /^ perl/;    # OUTPUT: «True␤»

The C<$> assertion only matches at the end of the string:

    say so 'use perl' ~~ /  perl  /;   # OUTPUT: «True␤»
    say so 'use perl' ~~ /  perl $/;   # OUTPUT: «True␤»
    say so 'perly'    ~~ /  perl $/;   # OUTPUT: «False␤»

You can combine both assertions:

    say so 'use perl' ~~ /^ perl $/;   # OUTPUT: «False␤»
    say so 'perl'     ~~ /^ perl $/;   # OUTPUT: «True␤»

Keep in mind that C<^> matches the start of a B<string>, not the start of a B<line>.
Likewise, C<$> matches the end of a B<string>, not the end of a B<line>.

The following is a multi-line string:

    my $str = q:to/EOS/;
       Keep it secret
       and keep it safe
       EOS

    say so $str ~~ /safe   $/;   # OUTPUT: «True␤»  -- 'safe' is at the end of the string
    say so $str ~~ /secret $/;   # OUTPUT: «False␤» -- 'secret' is at the end of a line -- not the string
    say so $str ~~ /^Keep   /;   # OUTPUT: «True␤»  -- 'Keep' is at the start of the string
    say so $str ~~ /^and    /;   # OUTPUT: «False␤» -- 'and' is at the start of a line -- not the string

=head2 X«C<^^>, Start of Line and C<$$>, End of Line|regex,^^;regex,$$»

The C<^^> assertion matches at the start of a logical line. That is, either
at the start of the string, or after a newline character. However, it does not match
at the end of the string, even if it ends with a newline character.

C<$$> matches only at the end of a logical line, that is, before a newline
character, or at the end of the string when the last character is not a
newline character.

(To understand the following example, it's important to know that the
C<q:to/EOS/...EOS> "heredoc" syntax removes leading indention to the same
level as the C<EOS> marker, so that the first, second and last lines have no
leading space and the third and fourth lines have two leading spaces each).

=begin code
my $str = q:to/EOS/;
    There was a young man of Japan
    Whose limericks never would scan.
      When asked why this was,
      He replied "It's because
    I always try to fit as many syllables into the last line as ever I possibly can."
    EOS

say so $str ~~ /^^ There/;        # OUTPUT: «True␤»  -- start of string
say so $str ~~ /^^ limericks/;    # OUTPUT: «False␤» -- not at the start of a line
say so $str ~~ /^^ I/;            # OUTPUT: «True␤»  -- start of the last line
say so $str ~~ /^^ When/;         # OUTPUT: «False␤» -- there are blanks between
                                  #                       start of line and the "When"

say so $str ~~ / Japan $$/;       # OUTPUT: «True␤»  -- end of first line
say so $str ~~ / scan $$/;        # OUTPUT: «False␤» -- there's a . between "scan"
                                  #                      and the end of line
say so $str ~~ / '."' $$/;        # OUTPUT: «True␤»  -- at the last line
=end code


=head2 X«C«<|w>» and C«<!|w>», word boundary|regex, <|w>;regex, <!|w>»

To match any word boundary, use C«<|w>». This is similar to other
languages’ X«C<\b>|regex deprecated,\b».
To match not a word boundary, use <!|w>, similar to other languages X<C<\B>|regex deprecated, \B >.
These are both zero width assertions.

=head2 X<<<<C<<< << >>> and C<<< >> >>>, left and right word boundary|regex,<<;regex,>>;regex,«;regex,»>>>>

C<<< << >>> matches a left word boundary. It matches positions where there
is a non-word character at the left (or the start of the string) and a word
character to the right.

C<<< >> >>> matches a right word boundary. It matches positions where there
is a word character at the left and a non-word character at the right (or
the end of the string).

    my $str = 'The quick brown fox';
    say so $str ~~ /br/;              # OUTPUT: «True␤»
    say so $str ~~ /<< br/;           # OUTPUT: «True␤»
    say so $str ~~ /br >>/;           # OUTPUT: «False␤»
    say so $str ~~ /own/;             # OUTPUT: «True␤»
    say so $str ~~ /<< own/;          # OUTPUT: «False␤»
    say so $str ~~ /own >>/;          # OUTPUT: «True␤»

You can also use the variants C<«> and C<»> :

    my $str = 'The quick brown fox';
    say so $str ~~ /« own/;          # OUTPUT: «False␤»
    say so $str ~~ /own »/;          # OUTPUT: «True␤»

=head1 X«Grouping and Capturing|regex,( );regex,[ ];regex,$<capture> =»

In regular (non-regex) Perl 6, you can use parentheses to group things
together, usually to override operator precedence:

    say 1 + 4 * 2;      # 9, parsed as 1 + (4 * 2)
    say (1 + 4) * 2;    # OUTPUT: «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

An unquantified capture produces a L<Match> object. When a capture is
quantified (except with the C<?> quantifier) the capture becomes a list of
L<Match> objects instead.

=head2 Capturing

The round parentheses don't just group, they also I<capture>; that is, they
make the string matched within the group available as a variable, and also as
an element of the resulting L<Match|/type/Match> object:

    my $str =  'number 42';
    if $str ~~ /'number ' (\d+) / {
        say "The number is $0";         # the number is 42
        # or
        say "The number is $/[0]";      # the number is 42
    }

Pairs of parentheses are numbered left to right, starting from zero.

    if 'abc' ~~ /(a) b (c)/ {
        say "0: $0; 1: $1";             # OUTPUT: «0: a; 1: c␤»
    }

The C<$0> and C<$1> etc. syntax is shorthand. These captures
are canonically available from the match object C<$/> by using it as a list,
so C<$0> is actually syntactic sugar for 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: ', '  # OUTPUT: «a, c␤»
    }

=head2 Non-capturing grouping

The parentheses 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 square brackets C<[ ... ]>
instead.

    if 'abc' ~~ / [a||b] (c) / {
        say ~$0;                # OUTPUT: «c␤»
    }

If you do not need the captures, using non-capturing groups provides three
benefits: they more cleanly communicate the regex intent; they make it easier to
count the capturing groups that you do care about; and matching is bit faster.

=head2 Capture numbers

It is stated above that captures are numbered from left to right. While true
in principle, this is also over simplification.

The following rules are listed for the sake of completeness. When you find
yourself using them regularly, it's worth considering named captures (and
possibly subrules) instead.

Alternations reset the capture count:

    / (x) (y)  || (a) (.) (.) /
    # $0  $1      $0  $1  $2

Example:

    if 'abc' ~~ /(x)(y) || (a)(.)(.)/ {
        say ~$1;            # b
    }

If two (or more) alternations have a different number of captures,
the one with the most captures determines the index of the next capture:

=begin code
$_ = 'abcd';

if / a [ b (.) || (x) (y) ] (.) / {
    #      $0     $0  $1    $2
    say ~$2;            # d
}
=end code


Captures can be nested, in which case they are numbered per level

    if 'abc' ~~ / ( a (.) (.) ) / {
        say "Outer: $0";                # Outer: abc
        say "Inner: $0[0] and $0[1]";   # Inner: b and c
    }

=head2 Named captures

Instead of numbering captures, you can also give them names. The generic --
and slightly verbose -- way of naming captures is like this:

    if 'abc' ~~ / $<myname> = [ \w+ ] / {
        say ~$<myname>      # OUTPUT: «abc␤»
    }

The access to the named capture, C<< $<myname> >>, is a shorthand for indexing
the match object as a hash, in other words: C<$/{ 'myname' }> or C<< $/<myname> >>.

Named captures can also be nested using regular capture group syntax:

    if 'abc-abc-abc' ~~ / $<string>=( [ $<part>=[abc] ]* % '-' ) / {
        say ~$<string>;         # OUTPUT: «abc-abc-abc␤»
        say ~$<string><part>;   # OUTPUT: «[abc, abc, abc]␤»
    }

Coercing the match object to a hash gives you easy programmatic access to
all named captures:

    if 'count=23' ~~ / $<variable>=\w+ '=' $<value>=\w+ / {
        my %h = $/.hash;
        say %h.keys.sort.join: ', ';        # OUTPUT: «value, variable␤»
        say %h.values.sort.join: ', ';      # OUTPUT: «23, count␤»
        for %h.kv -> $k, $v {
            say "Found value '$v' with key '$k'";
            # outputs two lines:
            #   Found value 'count' with key 'variable'
            #   Found value '23' with key 'value'
        }
    }

A more convenient way to get named captures is discussed in
the Subrules section.
=head2 X«Capture markers: C«<( )>»|regex,<( )>»

A C«<(» token indicates the start of the match's overall capture, while the corresponding C«)>»
token indicates its endpoint. The C«<(» is similar to other languages X<\K|regex deprecated,\K> to discard any matches
found before the C<\K>.

=head1 Substitution

Regular expressions can also be used to substitute one piece of text for
another. You can use this for anything, from correcting a spelling error
(e.g., replacing 'Perl Jam' with 'Pearl Jam'), to reformatting an ISO8601
date from C<yyyy-mm-ddThh:mm:ssZ> to C<mm-dd-yy h:m {AM,PM}> and beyond.

Just like the search-and-replace editor's dialog box, the C<s/ / /> operator
has two sides, a left and right side. The left side is where your matching
expression goes, and the right side is what you want to replace it with.

=head2 X<Lexical conventions|quote,s/ / />

Substitutions are written similarly to matching, but the substitution operator
has both an area for the regex to match, and the text to substitute:

    =begin code :skip-test
    s/replace/with/;           # a substitution that is applied to $_
    $str ~~ s/replace/with/;   # a substitution applied to a scalar
    =end code

The substitution operator allows delimiters other than the slash:

    s|replace|with|;
    s!replace!with!;
    s,replace,with,;

Note that neither the colon C<:> nor balancing delimiters such as C<{}> or
C<()> can be substitution delimiters. Colons clash with adverbs such as C<s:i/Foo/bar/>
and the other delimiters are used for other purposes.

Like the C<m//> operator, whitespace is ignored in general. Comments, as in
Perl 6 in general, start with the hash character C<#> and go to the end of
the current line.

=head2 Replacing string literals

The simplest thing to replace is a string literal. The string you want to
replace goes on the left-hand side of the substitution operator, and the string
you want to replace it with goes on the right-hand side; for example:

    $_ = 'The Replacements';
    s/Replace/Entrap/;
    .say;                    # OUTPUT: «The Entrapments␤»

Alphanumeric characters and the underscore are literal matches, just as in its
cousin the C<m//> operator. All other characters must be escaped with a
backslash C<\> or included in quotes:

    $_ = 'Space: 1999';
    s/Space\:/Party like it's/;
    .say                        # OUTPUT: «Party like it's 1999␤»

Note that the matching restrictions only apply to the left-hand side of the
substitution expression.

By default, substitutions are only done on the first match:

    $_ = 'There can be twly two';
    s/tw/on/;                     # replace 'tw' with 'on' once
    .say;                         # OUTPUT: «there can be only two␤»

=head2 Wildcards and character classes

Anything that can go into the C<m//> operator can go into the left-hand side
of the substitution operator, including wildcards and character classes. This
is handy when the text you're matching isn't static, such as trying to match
a number in the middle of a string:

    $_ = "Blake's 9";
    s/\d+/7/;         # replace any sequence of digits with '7'
    .say;             # OUTPUT: «Blake's 7␤»

Of course, you can use any of the C<+>, C<*> and C<?> modifiers, and they'll
behave just as they would in the C<m//> operator's context.

=head2 Capturing Groups

Just as in the match operator, capturing groups are allowed on the left-hand
side, and the matched contents populate the C<$0>..C<$n> variables and the
C<$/> object:

    $_ = '2016-01-23 18:09:00';
    s/ (\d+)\-(\d+)\-(\d+) /today/;   # replace YYYY-MM-DD with 'today'
    .say;                             # OUTPUT: «today 18:09:00␤»
    "$1-$2-$0".say;                   # OUTPUT: «01-23-2016␤»
    "$/[1]-$/[2]-$/[0]".say;          # OUTPUT: «01-23-2016␤»

Any of these variables C<$0>, C<$1>, C<$/> can be used on the right-hand side
of the operator as well, so you can manipulate what you've just matched. This
way you can separate out the C<YYYY>, C<MM> and C<DD> parts of a date and
reformat them into C<MM-DD-YYYY> order:

    $_ = '2016-01-23 18:09:00';
    s/ (\d+)\-(\d+)\-(\d+) /$1-$2-$0/;    # transform YYYY-MM-DD to MM-DD-YYYY
    .say;                                 # OUTPUT: «01-23-2016 18:09:00␤»

Since the right-hand side is effectively a regular Perl 6 interpolated string,
you can reformat the time from C<HH:MM> to C<h:MM {AM,PM}> like so:

    $_ = '18:38';
    s/(\d+)\:(\d+)/{$0 % 12}\:$1 {$0 < 12 ?? 'AM' !! 'PM'}/;
    .say;                                                    # OUTPUT: «6:38 PM␤»

Using the modulo C<%> operator above keeps the sample code under 80 characters,
but is otherwise the same as C« $0 < 12 ?? $0 !! $0 - 12 ». When combined with
the power of the Parser Expression Grammars that B<really> underlies what you're
seeing here, you can use "regular expressions" to parse pretty much any
text out there.

=head3 Common adverbs

The full list of adverbs that you can apply to regular expressions can be found
elsewhere in this document (L<section Adverbs|#Adverbs>), but the most
common are probably C<:g> and C<:i>.

=item Global adverb C<:g>

Ordinarily, matches are only made once in a given string, but adding the
C<:g> modifier overrides that behavior, so that substitutions are made
everywhere possible. Substitutions are non-recursive; for example:

    $_ = q{I can say "banana" but I don't know when to stop};
    s:g/na/nana,/;    # substitute 'nana,' for 'na'
    .say;             # OUTPUT: «I can say "banana,nana," but I don't ...␤»

Here, C<na> was found twice in the original string and each time there was a
substitution. The substitution only
applied to the original string, though. The resulting string was not impacted.

=item Insensitive adverb C<:i>

Ordinarily, matches are case-sensitive. C<s/foo/bar/> will only match
C<'foo'> and not C<'Foo'>. If the adverb C<:i> is used, though, matches become
case-insensitive.

    $_ = 'Fruit';
    s/fruit/vegetable/;
    .say;                          # OUTPUT: «Fruit␤»

    s:i/fruit/vegetable/;
    .say;                          # OUTPUT: «vegetable␤»

For more information on what these adverbs are actually
doing, refer to the L<section Adverbs|#Adverbs> section of this document.

These are just a few of the transformations you can apply with the substitution
operator. Some of the simpler uses in the real world include removing personal
data from log files, editing mySQL timestamps into PostgreSQL format, changing
copyright information in HTML files and sanitizing form fields in a web
application.

As an aside, novices to regular expressions often get overwhelmed and think
that their regular expression needs to match every piece of data in the line,
including what they want to match. Write just enough to match the data you're
looking for, no more, no less.

=head1 X<Tilde for nesting structures|tilde,regex;~,regex>

The ~ operator is a helper for matching nested subrules with a
specific terminator as the goal. It is designed to be placed between
an opening and closing bracket, like so:

    / '(' ~ ')' <expression> /

However, it mostly ignores the left argument, and operates on the next
two atoms (which may be quantified). Its operation on those next two
atoms is to "twiddle" them so that they are actually matched in
reverse order. Hence the expression above, at first blush, is merely
shorthand for:

    / '(' <expression> ')' /

But beyond that, when it rewrites the atoms it also inserts the
apparatus that will set up the inner expression to recognize the
terminator, and to produce an appropriate error message if the inner
expression does not terminate on the required closing atom. So it
really does pay attention to the left bracket as well, and it actually
rewrites our example to something more like:

    =begin code :skip-test
    $<OPEN> = '(' <SETGOAL: ')'> <expression> [ $GOAL || <FAILGOAL> ]
    =end code

FAILGOAL is a special method that can be defined by the user and it
will be called on parse failure:

    grammar A { token TOP { '[' ~ ']' \w+  };
                method FAILGOAL($goal) {
                    die "Cannot find $goal near position {self.pos}"
                }
    }

    A.parse: '[good]';  # OUTPUT: «｢[good]｣␤»
    A.parse: '[bad';    # will throw FAILGOAL exception
    CATCH { default { put .^name, ': ', .Str } };
    # OUTPUT: «X::AdHoc: Cannot find ']'  near position 5␤»

Note that you can use this construct to set up expectations for a
closing construct even when there's no opening bracket:

    "3)"  ~~ / <?> ~ ')' \d+ /;  # RESULT: «｢3)｣»
    "(3)" ~~ / <?> ~ ')' \d+ /;  # RESULT: «｢3)｣»

Here <?> returns true on the first null string.

The order of the regex capture is original:

    "abc" ~~ /a ~ (c) (b)/;
    say $0; # OUTPUT: «｢c｣␤»
    say $1; # OUTPUT: «｢b｣␤»

=head1 X<Subrules|declarator,regex>

Just like you can put pieces of code into subroutines, you can also put
pieces of regex into named rules.

    my regex line { \N*\n }
    if "abc\ndef" ~~ /<line> def/ {
        say "First line: ", $<line>.chomp;      # OUTPUT: «First line: abc␤»
    }

A named regex can be declared with C<my regex regex_name { body here }>, and
called with C<< <regex_name> >>. At the same time, calling a named regex
installs a named capture with the same name.

To give the capture a different name from the regex, use the
syntax C<< <capture_name=regex_name> >>. If no capture is desired, a
leading dot will suppress it: C<< <.regex_name> >>.

Here's more complete code for parsing C<ini>
files:

    my regex header { \s* '[' (\w+) ']' \h* \n+ }
    my regex identifier  { \w+ }
    my regex kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }
    my regex section {
        <header>
        <kvpair>*
    }

    my $contents = q:to/EOI/;
        [passwords]
            jack=password1
            joy=muchmoresecure123
        [quotas]
            jack=123
            joy=42
    EOI

    my %config;
    if $contents ~~ /<section>*/ {
        for $<section>.list -> $section {
            my %section;
            for $section<kvpair>.list -> $p {
                say $p<value>;
                %section{ $p<key> } = ~$p<value>;
            }
            %config{ $section<header>[0] } = %section;
        }
    }
    say %config.perl;
    # OUTPUT: «("passwords" => {"jack" => "password1", "joy" => "muchmoresecure123"},␤
    #          "quotas" => {"jack" => "123", "joy" => "42"}).hash»

Named regexes can and should be grouped in L<grammars|/language/grammars>. A
list of predefined subrules is listed in
L<S05|https://design.perl6.org/S05.html#Predefined_Subrules>.

=head1 Adverbs

Adverbs modify how regexes work and provide convenient shortcuts for
certain kinds of recurring tasks.

There are two kinds of adverbs: regex adverbs apply at the point where a
regex is defined and matching adverbs apply at the point that a regex
matches against a string.

This distinction often blurs, because matching and declaration are often
textually close but using the method form of matching makes the distinction
clear.

C<'abc' ~~ /../> is roughly equivalent to C<'abc'.match(/../)>, or even more
clearly written in separate lines:

    my $regex = /../;           # definition
    if 'abc'.match($regex) {    # matching
        say "'abc' has at least two characters";
    }

Regex adverbs like C<:i> go into the definition line and matching adverbs
like C<:overlap> are appended to the match call:

    my $regex = /:i . a/;
    for 'baA'.match($regex, :overlap) -> $m {
        say ~$m;
    }
    # OUTPUT: «ba␤aA␤»

=head2 X<Regex Adverbs|regex adverb,:ignorecase;regex adverb,:i>

Adverbs that appear at the time of a regex declaration are part of the
actual regex and influence how the Perl 6 compiler translates the regex into
binary code.

For example, the C<:ignorecase> (C<:i>) adverb tells the compiler to ignore
the distinction between upper case, lower case and title case letters.

So C<'a' ~~ /A/> is false, but C<'a' ~~ /:i A/> is a successful match.

Regex adverbs can come before or inside a regex declaration and only affect
the part of the regex that comes afterwards, lexically.
Note that regex adverbs appearing before the regex must appear after
something that introduces the regex to the parser, like 'rx' or 'm' or a bare '/'.
This is NOT valid:

    =begin code :skip-test
    my $rx1 = :i/a/;      # adverb is before the regex is recognized => exception
    =end code

but these are valid:

    my $rx1 = rx:i/a/;     # before
    my $rx2 = m:i/a/;      # before
    my $rx3 = /:i a/;      # inside

These two regexes are equivalent:

    my $rx1 = rx:i/a/;      # before
    my $rx2 = rx/:i a/;     # inside

Whereas these two are not:

    my $rx3 = rx/a :i b/;   # matches only the b case insensitively
    my $rx4 = rx/:i a b/;   # matches completely case insensitively

Brackets and parentheses limit the scope of an adverb:

    / (:i a b) c /;         # matches 'ABc' but not 'ABC'
    / [:i a b] c /;         # matches 'ABc' but not 'ABC'

=head3 X<Ratchet|regex adverb,:ratchet;regex adverb,:r>

The C<:ratchet> or C<:r> adverb causes the regex engine not to backtrack.

Without this adverb, parts of a regex will try different ways to match a
string in order to make it possible for other parts of the regex to match.
For example, in C<'abc' ~~ /\w+ ./>, the C<\w+> first eats up the whole
string, C<abc> but then the C<.> fails. Thus C<\w+> gives up a character,
matching only C<ab>, and the C<.> can successfully match the string C<c>.
This process of giving up characters (or in the case of alternations, trying
a different branch) is known as backtracking.

    say so 'abc' ~~ / \w+ . /;        # OUTPUT: «True␤»
    say so 'abc' ~~ / :r \w+ . /;     # OUTPUT: «False␤»

Ratcheting can be an optimization, because backtracking is costly. But more
importantly, it closely corresponds to how humans parse a text. If you have
a regex C<my regex identifier { \w+ }> and
C<my regex keyword { if | else | endif }>, you intuitively expect the
C<identifier> to gobble up a whole word and not have it give up its end to
the next rule, if the next rule otherwise fails.

For example, you don't
expect the word C<motif> to be parsed as the identifier C<mot> followed by
the keyword C<if>. Instead, you expect C<motif> to be parsed as one identifier;
and if the parser expects an C<if> afterwards, best that it should fail than
have it parse the input in a way you don't expect.

Since ratcheting behavior is often desirable in parsers, there's a
shortcut to declaring a ratcheting regex:

    =begin code :skip-test
    my token thing { .... }
    # short for
    my regex thing { :r ... }
    =end code

=head3 X<Sigspace|regex adverb,:sigspace;regex adverb,:s>

The B<C<:sigspace>> or B<C<:s>> adverb makes whitespace significant in a
regex.

    =begin code :allow<B> :skip-test
    say so "I used Photoshop®"   ~~ m:i/   photo shop /;      # OUTPUT: «True␤»
    say so "I used a photo shop" ~~ m:iB<:s>/ photo shop /;   # OUTPUT: «True␤»
    say so "I used Photoshop®"   ~~ m:iB<:s>/ photo shop /;   # OUTPUT: «False␤»
    =end code

C<m:s/ photo shop /> acts the same as
C<m/ photo <.ws> shop <.ws> />. By default, C<< <.ws> >> makes sure that
words are separated, so C<a    b> and C<^&> will match C<< <.ws> >> in the
middle, but C<ab> won't.

Where whitespace in a regex turns into C«<.ws>» depends on what comes before
the whitespace. In the above example, whitespace in the beginning of a regex
doesn't turn into C«<.ws>», but whitespace after characters does. In
general, the rule is that if a term might match something, whitespace after
it will turn into C«<.ws>».

In addition, if whitespace comes after a term but I<before> a quantifier
(C<+>, C<*>, or C<?>), C«<.ws>» will be matched after every match of the
term. So, C<foo +> becomes C«[ foo <.ws> ]+». On the other hand, whitespace
I<after> a quantifier acts as normal significant whitespace; e.g., "C<foo+>"
becomes C«foo+ <.ws>».

In all, this code:

    =begin code :allow<B> :skip-test
    rx :s {
        ^^
        {
            say "No sigspace after this";
        }
        <.assertion_and_then_ws>
        characters_with_ws_after+
        ws_separated_characters *
        [
        | some "stuff" .. .
        | $$
        ]
        :my $foo = "no ws after this";
        $foo
    }
    =end code

Becomes:

    =begin code :allow<B> :skip-test
    rx {
        ^^ B«<.ws>»
        {
            say "No space after this";
        }
        <.assertion_and_then_ws> B«<.ws>»
        characters_with_ws_after+ B«<.ws>»
        [ws_separated_characters B«<.ws>»]* B«<.ws>»
        [
        | some B«<.ws>» "stuff" B«<.ws>» .. B«<.ws>» . B«<.ws>»
        | $$ B«<.ws>»
        ] B«<.ws>»
        :my $foo = "no ws after this";
        $foo B«<.ws>»
    }
    =end code

If a regex is declared with the C<rule> keyword, both the C<:sigspace> and
C<:ratchet> adverbs are implied.

Grammars provide an easy way to override what C«<.ws>» matches:

    grammar Demo {
        token ws {
            <!ww>       # only match when not within a word
            \h*         # only match horizontal whitespace
        }
        rule TOP {      # called by Demo.parse;
            a b '.'
        }
    }

    # doesn't parse, whitespace required between a and b
    say so Demo.parse("ab.");                 # OUTPUT: «False␤»
    say so Demo.parse("a b.");                # OUTPUT: «True␤»
    say so Demo.parse("a\tb .");              # OUTPUT: «True␤»

    # \n is vertical whitespace, so no match
    say so Demo.parse("a\tb\n.");             # OUTPUT: «False␤»

When parsing file formats where some whitespace (for example, vertical
whitespace) is significant, it's advisable to override C<ws>.

=head2 Matching adverbs

In contrast to regex adverbs, which are tied to the declaration of a regex,
matching adverbs only make sense when matching a string against a regex.

They can never appear inside a regex, only on the outside – either as part
of an C<m/.../> match or as arguments to a match method.

=head3 X<Continue|matching adverb,:continue;matching adverb,:c>

The C<:continue> or short C<:c> adverb takes an argument. The argument is
the position where the regex should start to search. By default, it searches
from the start of the string, but C<:c> overrides that. If no position is
specified for C<:c>, it will default to C<0> unless C<$/> is set, in which
case, it defaults to C<$/.to>.

    given 'a1xa2' {
        say ~m/a./;         # OUTPUT: «a1␤»
        say ~m:c(2)/a./;    # OUTPUT: «a2␤»
    }

I<Note:> unlike C<:pos>, a match with :continue() will attempt to
match further in the string, instead of failing:

    say "abcdefg" ~~ m:c(3)/e.+/; # OUTPUT: «｢efg｣␤»
    say "abcdefg" ~~ m:p(3)/e.+/; # OUTPUT: «False␤»

=head3 X<Exhaustive|matching adverb,:exhaustive;matching adverb,:ex>

To find all possible matches of a regex – including overlapping ones – and
several ones that start at the same position, use the C<:exhaustive> (short
C<:ex>) adverb.

    given 'abracadabra' {
        for m:exhaustive/ a .* a / -> $match {
            say ' ' x $match.from, ~$match;
        }
    }

The above code produces this output:

=begin code :skip-test
abracadabra
abracada
abraca
abra
   acadabra
   acada
   aca
     adabra
     ada
       abra
=end code

=head3 X<Global|regex adverb,:global;regex adverb,:g>

Instead of searching for just one match and returning a
L<Match object|/type/Match>, search for every non-overlapping match and
return them in a L<List|/type/List>. In order to do this, use the C<:global>
adverb:

    given 'several words here' {
        my @matches = m:global/\w+/;
        say @matches.elems;         # OUTPUT: «3␤»
        say ~@matches[2];           # OUTPUT: «here␤»
    }

C<:g> is shorthand for C<:global>.

=head3 X<Pos|regex adverb,:pos;regex adverb,:p>

Anchor the match at a specific position in the string:

    given 'abcdef' {
        my $match = m:pos(2)/.*/;
        say $match.from;        # OUTPUT: «2␤»
        say ~$match;            # OUTPUT: «cdef␤»
    }

C<:p> is shorthand for C<:pos>.

I<Note:> unlike C<:continue>, a match anchored with :pos() will fail,
instead of attempting to match further down the string:

    say "abcdefg" ~~ m:c(3)/e.+/; # OUTPUT: «｢efg｣␤»
    say "abcdefg" ~~ m:p(3)/e.+/; # OUTPUT: «False␤»

=head3 X<Overlap|regex adverb,:overlap;regex adverb,:ov>

To get several matches, including overlapping matches, but only one (the
longest) from each starting position, specify the C<:overlap> (short C<:ov>)
adverb:

    given 'abracadabra' {
        for m:overlap/ a .* a / -> $match {
            say ' ' x $match.from, ~$match;
        }
    }

produces

=begin code :skip-test
abracadabra
   acadabra
     adabra
       abra
=end code

=head1 Look-around assertions

=head2 X<Lookahead assertions|regex,before;regex,after>

To check that a pattern appears before another pattern, use a
lookahead assertion via the C<before> assertion. This has the form:

    <?before pattern>

Thus, to search for the string C<foo> which is immediately followed by the
string C<bar>, use the following regexp:

    rx{ foo <?before bar> }

For example:

    say "foobar" ~~ rx{ foo <?before bar> };   # OUTPUT: «foo␤»

However, if you want to search for a pattern which is B<not> immediately
followed by some pattern, then you need to use a negative lookahead
assertion, this has the form:

    <!before pattern>

Hence, all occurrences of C<foo> which I<is not> before C<bar> would
match with

    rx{ foo <!before bar> }

=head2 Lookbehind assertions

To check that a pattern appears before another pattern, use a
lookbehind assertion via the C<after> assertion. This has the form:

    <?after pattern>

Therefore, to search for the string C<bar> immediately preceded by the
string C<foo>, use the following regexp:

    rx{ <?after foo> bar }

For example:

    say "foobar" ~~ rx{ <?after foo> bar };   # OUTPUT: «bar␤»

However, if you want to search for a pattern which is B<not> immediately
preceded by some pattern, then you need to use a negative lookbehind
assertion, this has the form:

    <!after pattern>

Hence all occurrences of C<bar> which I<do not> have C<foo> before them
would be matched by

    rx{ <!after foo> bar }

=head1 Best practices and gotchas

To help with robust regexes and grammars, here are some best practices
for code layout and readability, what to actually match, and avoiding common
pitfalls.

=head2 Code layout

Without the C<:sigspace> adverb, whitespace is not significant in Perl 6
regexes. Use that to your own advantage and insert whitespace where it
increases readability. Also, insert comments where necessary.

Compare the very compact

    my regex float { <[+-]>?\d*'.'\d+[e<[+-]>?\d+]? }

to the more readable

    my regex float {
         <[+-]>?        # optional sign
         \d*            # leading digits, optional
         '.'
         \d+
         [              # optional exponent
            e <[+-]>?  \d+
         ]?
    }

As a rule of thumb, use whitespace around atoms and inside groups; put
quantifiers directly after the atom; and vertically
align opening and closing brackets and parentheses.

When you use a list of alternations inside a parenthesis or brackets, align
the vertical bars:

    my regex example {
        <preamble>
        [
        || <choice_1>
        || <choice_2>
        || <choice_3>
        ]+
        <postamble>
    }

=head2 Keep it small

Regexes are often more compact than regular code. Because they do so much with
so little, keep regexes short.

When you can name a part of a regex, it's usually best to
put it into a separate, named regex.

For example, you could take the float regex from earlier:

    my regex float {
         <[+-]>?        # optional sign
         \d*            # leading digits, optional
         '.'
         \d+
         [              # optional exponent
            e <[+-]>?  \d+
         ]?
    }

And decompose it into parts:

    my token sign { <[+-]> }
    my token decimal { \d+ }
    my token exponent { 'e' <sign>? <decimal> }
    my regex float {
        <sign>?
        <decimal>?
        '.'
        <decimal>
        <exponent>?
    }

That helps, especially when the regex becomes more complicated. For example,
you might want to make the decimal point optional in the presence of an exponent.

    my regex float {
        <sign>?
        [
        || <decimal>?  '.' <decimal> <exponent>?
        || <decimal> <exponent>
        ]
    }

=head2 What to match

Often the input data format has no clear-cut specification, or the
specification is not known to the programmer. Then, it's good to be liberal
in what you expect, but only so long as there are no possible ambiguities.

For example, in C<ini> files:

    =begin code :skip-test
    [section]
    key=value
    =end code

What can be inside the section header? Allowing only a word might be too
restrictive. Somebody might write C<[two words]>, or use dashes, or so on.
Instead of asking what's allowed on the inside, it might be worth asking
instead: I<what's not allowed?>

Clearly, closing brackets are not allowed, because C<[a]b]> would be
ambiguous. By the same argument, opening brackets should be forbidden.
This leaves us with

    token header { '[' <-[ \[\] ]>+ ']' }

which is fine if you are only processing one line. But if you're processing
a whole file, suddenly the regex parses

    =begin code :skip-test
    [with a
    newline in between]
    =end code

which might not be a good idea.  A compromise would be

    token header { '[' <-[ \[\] \n ]>+ ']' }

and then, in the post-processing, strip leading and trailing spaces and tabs
from the section header.

=head2 Matching Whitespace

The C<:sigspace> adverb (or using the C<rule> declarator instead of C<token>
or C<regex>) is very handy for implicitly parsing whitespace that can appear
in many places.

Going back to the example of parsing C<ini> files, we have

    my regex kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }

which is probably not as liberal as we want it to be, since the user might
put spaces around the equals sign. So, then we may try this:

    my regex kvpair { \s* <key=identifier> \s* '=' \s* <value=identifier> \n+ }

But that's looking unwieldy, so we try something else:

    my rule kvpair { <key=identifier> '=' <value=identifier> \n+ }

But wait! The implicit whitespace matching after the value uses up all
whitespace, including newline characters, so the C<\n+> doesn't have
anything left to match (and C<rule> also disables backtracking, so no luck
there).

Therefore, it's important to redefine your definition of implicit whitespace
to whitespace that is not significant in the input format.

This works by redefining the token C<ws>; however, it only works for
L<grammars|/language/grammars>:

    grammar IniFormat {
        token ws { <!ww> \h* }
        rule header { \s* '[' (\w+) ']' \n+ }
        token identifier  { \w+ }
        rule kvpair { \s* <key=identifier> '=' <value=identifier> \n+ }
        token section {
            <header>
            <kvpair>*
        }

        token TOP {
            <section>*
        }
    }

    my $contents = q:to/EOI/;
        [passwords]
            jack = password1
            joy = muchmoresecure123
        [quotas]
            jack = 123
            joy = 42
    EOI
    say so IniFormat.parse($contents);

Besides putting all regexes into a grammar and turning them into tokens
(because they don't need to backtrack anyway), the interesting new bit is

        token ws { <!ww> \h* }

which gets called for implicit whitespace parsing. It matches when it's not
between two word characters (C<< <!ww> >>, negated "within word" assertion),
and zero or more horizontal space characters. The limitation to horizontal
whitespace is important, because newlines (which are vertical whitespace)
delimit records and shouldn't be matched implicitly.

Still, there's some whitespace-related trouble lurking. The regex C<\n+>
won't match a string like C<"\n \n">, because there's a blank between the
two newlines. To allow such input strings, replace C<\n+> with C<\n\s*>.

=end pod

# vim: expandtab shiftwidth=4 ft=perl6
