=begin pod :kind("Type") :subkind("class") :category("domain-specific")

=TITLE class Regex

=SUBTITLE String pattern

    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|/type/Match> object, which evaluates 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

X<|named regex> A named regex can be defined with the C<regex> declarator
followed by its definition in curly braces. Since any regex does C<Callable>
introspection requires referencing via C<&>-sigil.

    my regex R { \N };
    say &R.^name; # OUTPUT: «Regex␤»

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

    my $match = 'abc' ~~ rx/ ^ab /;
    say $match.Bool;                # OUTPUT: «True␤»
    say $match.orig;                # OUTPUT: «abc␤»
    say $match.Str;                 # OUTPUT: «ab␤»
    say $match.from;                # OUTPUT: «0␤»
    say $match.to;                  # OUTPUT: «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 method ACCEPTS

    multi method ACCEPTS(Regex:D: Mu --> 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|/type/Positional>, it returns the first successful match of any list item. If the
argument is L<Associative|/type/Associative>, it returns the first successful match of any key.
Otherwise it interprets the argument as a L<Str|/type/Str> and matches against it.

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

=head2 method Bool

    multi method Bool(Regex:D: --> Bool:D)

Matches against the caller's L<$_|/syntax/$_> variable, and returns C<True> for a match or
C<False> for no match.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
