document Match

lib/Match.pod

@@ -0,0 +1,75 @@
+=begin pod
+
+    class Match is Capture is Cool { ... }
+
+C<Match> objects are the result of a regex match. They store
+a reference to the original string (C<.orig>), positional and
+named captures, the start and end of the match in the original
+string, and a payload refered to as I<AST> (abstract syntax tree),
+which can be used to build data structures from complex regexes
+and gramamrs.
+
+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.
+
+=head2 Methods
+
+=head3 orig
+
+Returns the original string that the regex was matched against.
+
+=head3 from
+
+Returns the index of the starting position of the match.
+
+=head3 to
+
+Returns the index of the end position of the match.
+
+=head3 ast
+
+Returns the AST (ie payload).
+
+=head3 Str
+
+Returns the matched text.
+
+=head3 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.
+
+=head3 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.
+
+=head3 list
+
+Returns a list of positional submatches.
+
+=head3 hash
+
+Returns a hash of named submatches.
+
+=head3 prematch
+
+Returns the part of the original string in front of the match.
+
+=head3 postmatch
+
+Returns the part of the original string behind the match.
+
+=head3 make
+
+    method make(Match:D: Mu $ast)
+
+Sets the AST to C<$ast>, and returns it.
+
+=end pod