Fix arg constraints example in doc

[catagits/Catalyst-Runtime.git] / lib / Catalyst / RouteMatching.pod

diff --git a/lib/Catalyst/RouteMatching.pod b/lib/Catalyst/RouteMatching.pod
index 5867368..e5f567c 100644 (file)
--- a/lib/Catalyst/RouteMatching.pod
+++ b/lib/Catalyst/RouteMatching.pod
@@ -10,6 +10,73 @@ This is a WIP document intended to help people understand the logic that L<Catal
 uses to determine how to match in incoming request to an action (or action chain)
 in a controller.
 
+=head2 Request to Controller/Action Matching
+
+L<Catalyst> maps requests to action using a 'longest path wins' approach.  That means
+that if the request is '/foo/bar/baz' That means the action 'baz' matches:
+
+    package MyApp::Controller::Foo;
+
+    use Moose;
+    use MooseX::MethodAttributes
+
+    extends 'Catalyst::Controller';
+
+    sub bar :Path('bar') Args(1) { ...}
+    sub baz :Path('bar/baz') Args(0) { ... }
+
+Path length matches take precidence over all other types of matches (included HTTP
+Method, Scheme, etc.).  The same holds true for Chained actions.  Generally the
+chain that matches the most PathParts wins.
+
+=head2 Args(N) versus Args
+
+'Args' matches any number of args.  Because this functions as a sort of catchall, we
+treat 'Args' as the lowest precedence of any Args(N) when N is 0 to infinity.  An
+action with 'Args' always get the last chance to match.
+
+=head2 When two or more actions match a given Path
+
+Sometimes two or more actions match the same path and all have the same pathpart
+length.  For example:
+
+    package MyApp::Controller::Root;
+
+    use Moose;
+    use MooseX::MethodAttributes
+
+    extends 'Catalyst::Controller';
+
+    sub root :Chained(/) CaptureArgs(0) { }
+
+      sub one :Chained(root) PathPart('') Args(0) { }
+      sub two :Chained(root) PathPart('') Args(0) { }
+      sub three :Chained(root) PathPart('') Args(0) { }
+
+    __PACKAGE__->meta->make_immutable;
+
+In this case the last defined action wins (for the example that is action 'three').
+
+This is most common to happen when you are using action matching beyond paths, such as
+when using method matching:
+
+    package MyApp::Controller::Root;
+
+    use Moose;
+    use MooseX::MethodAttributes
+
+    extends 'Catalyst::Controller';
+
+    sub root :Chained(/) CaptureArgs(0) { }
+
+      sub any :Chained(root) PathPart('') Args(0) { }
+      sub get :GET Chained(root) PathPart('') Args(0) { }
+
+    __PACKAGE__->meta->make_immutable;
+
+In the above example GET /root could match both actions.  In this case you should define
+your 'catchall' actions higher in the controller.
+
 =head2 Type Constraints in Args and Capture Args
 
 Beginning in Version 5.90090+ you may use L<Moose>, L<MooseX::Types> or L<Type::Tiny>
@@ -20,6 +87,7 @@ is a simple example:
 
     use Moose;
     use MooseX::MethodAttributes;
+    use MooseX::Types::Moose qw(Int);
 
     extends 'Catalyst::Controller';
 
@@ -42,11 +110,18 @@ easily understood and declarative actions.
 More than one argument may be added by comma separating your type constraint names, for
 example:
 
+    use Types::Standard qw/Int Str/;
+
     sub find :Path('') Args(Int,Int,Str) {
       my ($self, $c, $int1, $int2, $str) = @_;
     }
 
-Would require three arguments, an integer, integer and a string.
+Would require three arguments, an integer, integer and a string.  Note in this example we
+constrained the args using imported types via L<Types::Standard>.  Although you may use
+stringy Moose types, we recommend imported types since this is less ambiguous to your readers.
+If you want to use Moose stringy types. you must quote them (either "Int" or 'Int' is fine).
+
+Conversely, you should not quote types that are imported!
 
 =head3 Using type constraints in a controller
 
@@ -60,7 +135,7 @@ the L<Types::Standard> library that is packaged with L<Type::Tiny>:
 
     use Moose;
     use MooseX::MethodAttributes;
-    use Types::Standard qw/StrMatch/;
+    use Types::Standard qw/StrMatch Int/;
     
     extends 'Catalyst::Controller';
 
@@ -111,6 +186,8 @@ Using type constraints in Chained actions works the same as it does for Path and
 actions.  The only difference is that you may declare type constraints on CaptureArgs as
 well as Args.  For Example:
 
+  use Types::Standard qw/Int Tuple/;
+  
   sub chain_base :Chained(/) CaptureArgs(1) { }
 
     sub any_priority_chain :GET Chained(chain_base) PathPart('') Args(1) {  }
@@ -199,10 +276,6 @@ parent controller or consumed role.
 
 Please note that your declared type constraint names will now appear in the debug console.
 
-=head1 Conclusion
-
-    TBD
-
 =head1 Author
 
 John Napiorkowski L<jjnapiork@cpan.org|email:jjnapiork@cpan.org>