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

[sartak at bestpractical.com]

Author: sartak
Date: Sun Oct 19 09:28:11 2008
New Revision: 16380

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

Log:
 r74164 at onn:  sartak | 2008-10-19 09:28:04 -0400
 Doc for the primary Path::Dispatcher module


Modified: Path-Dispatcher/trunk/lib/Path/Dispatcher.pm
==============================================================================
--- Path-Dispatcher/trunk/lib/Path/Dispatcher.pm	(original)
+++ Path-Dispatcher/trunk/lib/Path/Dispatcher.pm	Sun Oct 19 09:28:11 2008
@@ -120,15 +120,16 @@
 
     $dispatcher->add_rule(
         Path::Dispacher::Rule::Regex->new(
-            regex => qr{^/(foo)/.*},
+            regex => qr{^/(foo)/},
             block => sub { warn $1; }, # foo
         )
     );
 
     $dispatcher->add_rule(
-        Path::Dispacher::Rule::CodeRef->new(
-            matcher => sub { /^\d+$/ && $_ % 2 == 0 },
-            block   => sub { warn "$_ is an even number" },
+        Path::Dispacher::Rule::Tokens->new(
+            tokens    => ['ticket', 'delete', qr/^\d+$/],
+            delimiter => '/',
+            block     => sub { delete_ticket($3) },
         )
     );
 
@@ -140,7 +141,47 @@
 
 We really like L<Jifty::Dispatcher> and wanted to use it for the command line.
 
-More documentation coming later, there's a lot here..
+The basic operation is that of dispatch. Dispatch takes a path and a list of
+rules, and it returns a list of matches. From there you can "run" the rules
+that matched. These phases are distinct so that, if you need to, you can
+inspect which rules were matched without ever running their codeblocks.
+
+=head1 ATTRIBUTES
+
+=head2 rules
+
+A list of L<Path::Dispatcher::Rule> objects.
+
+=head2 name
+
+A human-readable name; this will be used in the (currently nonexistent)
+debugging hooks.
+
+=head2 super_dispatcher
+
+Another Path::Dispatcher to defer to when no rules match in the current
+dispatcher. This is intended for "subclassing" dispatchers, such as when you
+have a framework dispatcher and an application dispatcher.
+
+WARNING: The super dispatcher feature is currently unstable. I'm still trying
+to figure out the right way to have them.
+
+=head1 METHODS
+
+=head2 add_rule
+
+Adds a L<Path::Dispatcher::Rule> to the end of this dispatcher's rule set.
+
+=head2 dispatch path -> dispatch
+
+Takes a string (the path) and returns a L<Path::Dispatcher::Dispatch> object
+representing a list of matches (L<Path::Dispatcher::Match> objects).
+
+=head2 run path, args
+
+Dispatches on the path and then invokes the C<run> method on the
+L<Path::Dispatcher::Dispatch> object, for when you don't need to inspect the
+dispatch.
 
 =head1 AUTHOR
 
@@ -148,8 +189,6 @@
 
 =head1 BUGS
 
-The order matches when a super dispatch is added B<will> change.
-
 Please report any bugs or feature requests to
 C<bug-path-dispatcher at rt.cpan.org>, or through the web interface at
 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Path-Dispatcher>.