[Bps-public-commit] r16381 - in Path-Dispatcher/trunk: lib/Path/Dispatcher

[sartak at bestpractical.com]

Author: sartak
Date: Sun Oct 19 09:44:29 2008
New Revision: 16381

Modified:
   Path-Dispatcher/trunk/   (props changed)
   Path-Dispatcher/trunk/lib/Path/Dispatcher/Rule.pm

Log:
 r74167 at onn:  sartak | 2008-10-19 09:44:26 -0400
 Doc for Path::Dispatcher::Rule


Modified: Path-Dispatcher/trunk/lib/Path/Dispatcher/Rule.pm
==============================================================================
--- Path-Dispatcher/trunk/lib/Path/Dispatcher/Rule.pm	(original)
+++ Path-Dispatcher/trunk/lib/Path/Dispatcher/Rule.pm	Sun Oct 19 09:44:29 2008
@@ -73,3 +73,61 @@
 
 1;
 
+__END__
+
+=head1 NAME
+
+Path::Dispatcher::Rule - predicate and codeblock
+
+=head1 SYNOPSIS
+
+    my $rule = Path::Dispatcher::Rule::Regex->new(
+        regex => qr/^quit/,
+        block => sub { die "Program terminated by user.\n" },
+    );
+
+    $rule->match("die"); # undef, because "die" !~ /^quit/
+
+    my $match = $rule->match("quit"); # creates a Path::Dispatcher::Match
+
+    $rule->run; # exits the program
+
+=head1 DESCRIPTION
+
+A rule has a predicate and an optional codeblock. Rules can be matched (which
+checks the predicate against the path) and they can be ran (which invokes the
+codeblock).
+
+This class is not meant to be instantiated directly, because there is no
+predicate matching function. Instead use one of the subclasses such as
+L<Path::Dispatcher::Rule::Tokens>.
+
+=head1 ATTRIBUTES
+
+=head2 block
+
+An optional block of code to be run. Please use the C<run> method instead of
+invoking this attribute directly.
+
+=head2 prefix
+
+A boolean indicating whether this rule can match a prefix of a path. If false,
+then the predicate must match the entire path. One use-case is that you may
+want a catch-all rule that matches anything beginning with the token C<ticket>.
+The unmatched, latter part of the path will be available in the match object.
+
+=head1 METHODS
+
+=head2 match path -> match
+
+Takes a path and returns a L<Path::Dispatcher::Match> object if it matched the
+predicate, otherwise C<undef>. The match object contains information about the
+match, such as the results (e.g. for regex, a list of the captured variables),
+the C<leftover> path if C<prefix> matching was used, etc.
+
+=head2 run
+
+Runs the rule's codeblock. If none is present, it throws an exception.
+
+=cut
+