=begin pod

=TITLE class Regex

    class Regex is Method { }

A regex is a kind of pattern that describes a set of strings. The process of
finding out whether a given string is in the set is called I<matching>. The
result of such a matching is a L<Match> object, which evalutes to C<True> in
boolean context if the string is in the set.

A regex is typically constructed by a regex literal

    rx/ ^ab /;      # describes all strings starting with 'ab'
    / ^ ab /;       # same
    rx/ \d ** 2/;   # describes all strings containing at least two digits

To match a string against a regex, you can use the smart match operator:

    my $match = 'abc' ~~ rx/ ^ab /;
    say $match.True;                # True
    say $match.orig;                # abc
    say $match.Str;                 # ab
    say $match.from;                # 0
    say $match.to;                  # 2

Or you can evaluate the regex in boolean context, in which case it matches
against the C<$_> variable

    $_ = 'abc';
    if / ^ab / {
        say '"abc" begins with "ab"';
    }
    else {
        say 'This is a weird alternative Universe';
    }

=head1 Methods

=head2 ACCEPTS

    multi method ACCEPTS(Regex:D: Mu) returns Match:D
    multi method ACCEPTS(Regex:D: @)
    multi method ACCEPTS(Regex:D: %)

Matches the regex against the argument passed in.
If the argument is L<Positional>, it returns the first successful match of any
list item. If the argument is L<Associative>, it returns the first successful
match of any key. Otherwise it interprets the argument as a L<Str> and matches
against it.

In the case of Positional and Associative matches, L<Nil> is returned on
failure.

=head2 Bool

    multi method Bool(Regex:D:) returns Bool:D

Matches against the caller's L<$_> variable, and returns the L<Match> object

=end pod