make it less easy to want moose stringy types

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

diff --git a/lib/Catalyst/RouteMatching.pod b/lib/Catalyst/RouteMatching.pod
index e155b28..e91b560 100644 (file)
--- a/lib/Catalyst/RouteMatching.pod
+++ b/lib/Catalyst/RouteMatching.pod
@@ -23,7 +23,7 @@ is a simple example:
 
     extends 'Catalyst::Controller';
 
-    sub find :Path('') Args(Int) {
+    sub find :Path('') Args('Int') {
       my ($self, $c, $int) = @_;
     }
 
@@ -42,11 +42,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 +67,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,9 +118,11 @@ 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 :Chained(chain_base) PathPart('') Args(1) {  }
+    sub any_priority_chain :GET Chained(chain_base) PathPart('') Args(1) {  }
 
     sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) {  }
 
@@ -121,37 +130,69 @@ well as Args.  For Example:
 
       sub any_priority_link_any :Chained(link_any) PathPart('') Args(1) {  }
 
-      sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) { }
+      sub int_priority_link_any :Chained(link_any) PathPart('') Args(Int) {  }
     
     sub link_int :Chained(chain_base) PathPart('') CaptureArgs(Int) { }
 
-      sub any_priority_link :Chained(link_int) PathPart('') Args(1) { }
+      sub any_priority_link :Chained(link_int) PathPart('') Args(1) {  }
+
+      sub int_priority_link :Chained(link_int) PathPart('') Args(Int) {  }
+
+    sub link_int_int :Chained(chain_base) PathPart('') CaptureArgs(Int,Int) { }
+
+      sub any_priority_link2 :Chained(link_int_int) PathPart('') Args(1) {  }
 
-      sub int_priority_link :Chained(link_int) PathPart('') Args(Int) { }
+      sub int_priority_link2 :Chained(link_int_int) PathPart('') Args(Int) {  }
+
+    sub link_tuple :Chained(chain_base) PathPart('') CaptureArgs(Tuple[Int,Int,Int]) { }
+
+      sub any_priority_link3 :Chained(link_tuple) PathPart('') Args(1) {  }
+
+      sub int_priority_link3 :Chained(link_tuple) PathPart('') Args(Int) {  }
 
 These chained actions migth create match tables like the following:
 
     [debug] Loaded Chained actions:
-    .----------------------------------------------+----------------------------------------------.
-    | Path Spec                                    | Private                                      |
-    +----------------------------------------------+----------------------------------------------+
-    | /chain_base/*/*                              | /chain_base (1)                              |
-    |                                              | => /any_priority_chain                       |
-    | /chain_base/*/*/*                            | /chain_base (1)                              |
-    |                                              | -> /link_int (1)                             |
-    |                                              | => /any_priority_link                        |
-    | /chain_base/*/*/*                            | /chain_base (1)                              |
-    |                                              | -> /link_any (1)                             |
-    |                                              | => /any_priority_link_any                    |
-    | /chain_base/*/*                              | /chain_base (1)                              |
-    |                                              | => /int_priority_chain                       |
-    | /chain_base/*/*/*                            | /chain_base (1)                              |
-    |                                              | -> /link_int (1)                             |
-    |                                              | => /int_priority_link                        |
-    | /chain_base/*/*/*                            | /chain_base (1)                              |
-    |                                              | -> /link_any (1)                             |
-    |                                              | => /int_priority_link_any                    |
-    '----------------------------------------------+----------------------------------------------'
+    .-------------------------------------+--------------------------------------.
+    | Path Spec                           | Private                              |
+    +-------------------------------------+--------------------------------------+
+    | /chain_base/*/*                     | /chain_base (1)                      |
+    |                                     | => GET /any_priority_chain (1)       |
+    | /chain_base/*/*/*                   | /chain_base (1)                      |
+    |                                     | -> /link_int (Int)                   |
+    |                                     | => /any_priority_link (1)            |
+    | /chain_base/*/*/*/*                 | /chain_base (1)                      |
+    |                                     | -> /link_int_int (Int,Int)           |
+    |                                     | => /any_priority_link2 (1)           |
+    | /chain_base/*/*/*/*/*               | /chain_base (1)                      |
+    |                                     | -> /link_tuple (Tuple[Int,Int,Int])  |
+    |                                     | => /any_priority_link3 (1)           |
+    | /chain_base/*/*/*                   | /chain_base (1)                      |
+    |                                     | -> /link_any (1)                     |
+    |                                     | => /any_priority_link_any (1)        |
+    | /chain_base/*/*/*/*/*/*             | /chain_base (1)                      |
+    |                                     | -> /link_tuple (Tuple[Int,Int,Int])  |
+    |                                     | -> /link2_int (UserId)               |
+    |                                     | => GET /finally (Int)                |
+    | /chain_base/*/*/*/*/*/...           | /chain_base (1)                      |
+    |                                     | -> /link_tuple (Tuple[Int,Int,Int])  |
+    |                                     | -> /link2_int (UserId)               |
+    |                                     | => GET /finally2 (...)               |
+    | /chain_base/*/*                     | /chain_base (1)                      |
+    |                                     | => /int_priority_chain (Int)         |
+    | /chain_base/*/*/*                   | /chain_base (1)                      |
+    |                                     | -> /link_int (Int)                   |
+    |                                     | => /int_priority_link (Int)          |
+    | /chain_base/*/*/*/*                 | /chain_base (1)                      |
+    |                                     | -> /link_int_int (Int,Int)           |
+    |                                     | => /int_priority_link2 (Int)         |
+    | /chain_base/*/*/*/*/*               | /chain_base (1)                      |
+    |                                     | -> /link_tuple (Tuple[Int,Int,Int])  |
+    |                                     | => /int_priority_link3 (Int)         |
+    | /chain_base/*/*/*                   | /chain_base (1)                      |
+    |                                     | -> /link_any (1)                     |
+    |                                     | => /int_priority_link_any (Int)      |
+    '-------------------------------------+--------------------------------------'
 
 As you can see the same general path could be matched by various action chains.  In this case
 the rule described in the previous section should be followed, which is that L<Catalyst>
@@ -165,6 +206,8 @@ Although this reverse order checking may seen counter intuitive it does have the
 when inheriting controllers any new actions added would take check precedence over those in your
 parent controller or consumed role.
 
+Please note that your declared type constraint names will now appear in the debug console.
+
 =head1 Conclusion
 
     TBD