=begin pod

=TITLE class Match

=SUBTITLE Result of a successful regex match

    class Match is Capture is Cool { ... }

C<Match> objects are the result of a successful regex match. They store
a reference to the original string (C<.orig>), positional and
named captures, the positions of the start and end of the match
in the original string, and a payload referred to as I<AST>
(abstract syntax tree), which can be used to build data structures
from complex regexes and grammars.

Submatches are also C<Match> objects (or lists of C<Match> objects,
if the corresponding regex was quantified), so each match object
can be seen as the root of a tree of match objects.

=head1 Methods

=head2 method orig

Returns the original string that the regex was matched against.

=head2 method from

Returns the index of the starting position of the match.

=head2 method to

Returns the index of the end position of the match.

=head2 method made

Returns the payload that was set with L<#method make>.

=head2 method ast

Alias for L<#method made>.

=head2 method Str

Returns the matched text.

=head2 method caps

Returns a list of pairs, with the index or submatch name as key and
the submatches as values. The list is ordered by starting position
of the submatches.

=head2 method chunks

Returns a list of pairs, with the index or submatch name as key and
the submatches as values. The list is ordered by starting position
of the submatches.

Those parts of the string that were not matched by submatches are
interleaved with the other pairs, with the string C<~> as key.

=head2 method list

Returns a list of positional submatches.

=head2 method hash

Returns a hash of named submatches.

=head2 method prematch

Returns the part of the original string leading up to the match.

=head2 method postmatch

Returns the part of the original string following the match.

=head2 method make

    method make(Match:D: Mu $ast)

Sets the AST to C<$ast>, and returns it.

This is just a little sugar for C<$/.made = $ast> which is a very common
operation in actions. C<$ast> may be anything that makes sense for the
use case. It's typically some tree node.

=end pod
