Browse files

document Regex

  • Loading branch information...
1 parent dad8272 commit d0769cd24a3bf5c9d13b4185c64d405d1d96df8d @moritz moritz committed Aug 25, 2012
Showing with 61 additions and 0 deletions.
  1. +61 −0 lib/Regex.pod
View
61 lib/Regex.pod
@@ -0,0 +1,61 @@
+=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

0 comments on commit d0769cd

Please sign in to comment.