From: John Napiorkowski <jjnapiork@cpan.org>
Date: Tue, 12 Feb 2013 23:12:37 +0000 (-0500)
Subject: some sort of docs for controller action subroutine attributes
X-Git-Tag: 5.90020~9
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=5b41c28c51565fdb5325f597edf9371649e3f5db

some sort of docs for controller action subroutine attributes
---

diff --git a/lib/Catalyst/Action.pm b/lib/Catalyst/Action.pm
index fb5c9c6..b5b2f48 100644
--- a/lib/Catalyst/Action.pm
+++ b/lib/Catalyst/Action.pm
@@ -88,13 +88,13 @@ sub _match_has_expected_args {
   return scalar( @{$req_args} ) == $args;
 }
 
-sub _match_has_expected_capture_args {
-  my ($self, $req_args) = @_;
-  return 1 unless exists $self->attributes->{CaptureArgs};
-  my $args = $self->attributes->{CaptureArgs}[0];
-  return 1 unless defined($args) && length($args);
-  return scalar( @{$req_args} ) == $args;
-}
+#sub _match_has_expected_capture_args {
+#  my ($self, $req_args) = @_;
+#  return 1 unless exists $self->attributes->{CaptureArgs};
+#  my $args = $self->attributes->{CaptureArgs}[0];
+#  return 1 unless defined($args) && length($args);
+#  return scalar( @{$req_args} ) == $args;
+#}
 
 sub _match_has_expected_http_method {
   my ($self, $method) = @_;
diff --git a/lib/Catalyst/Controller.pm b/lib/Catalyst/Controller.pm
index cc2da5e..0b197b0 100644
--- a/lib/Catalyst/Controller.pm
+++ b/lib/Catalyst/Controller.pm
@@ -700,6 +700,145 @@ Gathers the list of roles to apply to an action with the given %action_args.
 
 Returns the application instance stored by C<new()>
 
+=head1 ACTION SUBROUTINE ATTRIBUTES
+
+Please see L<Catalyst::Manual::Intro> for more details
+
+Think of action attributes as a sort of way to record metadata about an action,
+similar to how annotations work in other languages you might have heard of.
+Generally L<Catalyst> uses these to influence how the dispatcher sees your
+action and when it will run it in response to an incoming request.  They can
+also be used for other things.  Here's a summary, but you should refer to the
+liked manual page for additional help.
+
+=head2 Global
+
+  sub homepage :Global { ... }
+
+A global action defined in any controller always runs relative to your root.
+So the above is the same as:
+
+  sub myaction :Path("/homepage") { ... }
+
+=head2 Absolute
+
+Status: Deprecated alias to L</Global>.
+
+=head2 Local
+
+Alias to "Path("$action_name").  The following two actions are the same:
+
+  sub myaction :Local { ... }
+  sub myaction :Path('myaction') { ... }
+
+=head2 Relative
+
+Status: Deprecated alias to L</Local>
+
+=head2 Path
+
+Handle various types of paths:
+
+  package MyApp::Controller::Baz {
+
+    ...
+
+    sub myaction1 :Path { ... }  # -> /baz
+    sub myaction2 :Path('foo') { ... } # -> /baz/bar
+    sub myaction2 :Path('/bar') { ... } # -> /bar
+  }
+
+This is a general toolbox for attaching your action to a give path.
+
+
+=head2 Regex
+
+=head2 Regexp
+
+Status: Deprecated.  Use Chained methods or other techniques
+
+A global way to match a give regular expression in the incoming request path.
+
+=head2 LocalRegex
+
+=head2 LocalRegexp
+
+Like L</Regex> but scoped under the namespace of the containing controller
+
+=head2 Chained 
+
+=head2 ChainedParent
+
+=head2 PathPrefix
+
+=head2 PathPart
+
+=head2 CaptureArgs
+
+Please see L<Catalyst::DispatchType::Chained>
+
+=head2 ActionClass
+
+Set the base class for the action, defaults to L</Catalyst::Action>.  It is now
+preferred to use L</Does>.
+
+=head2 MyAction
+
+Set the ActionClass using a custom Action in your project namespace (such as
+C<MyApp::Action::MyAction> => MyAction('MyAction').
+
+=head2 Does
+
+    package MyApp::Controller::Zoo;
+
+    sub foo  : Local Does('Moo')  { ... } # Catalyst::ActionRole::
+    sub bar  : Local Does('~Moo') { ... } # MyApp::ActionRole::Moo
+    sub baz  : Local Does('+MyApp::ActionRole::Moo') { ... }
+
+=head2 GET
+
+=head2 POST
+
+=head2 PUT
+
+=head2 DELETE
+
+=head2 OPTION
+
+=head2 HEAD
+
+Sets the give action path to match the specified HTTP method.
+
+=head2 Args
+
+When used with L</Path> indicates the number of arguments expected in
+the path.  However if no Args value is set, assumed to 'slurp' all
+remaining path pars under this namespace.
+
+=head1 OPTIONAL METHODS
+
+=head2 _parse_[$name]_attr
+
+Allows you to customize parsing of subroutine attributes.
+
+    sub myaction1 :Path TwoArgs { ... }
+
+    sub _parse_TwoArgs_attr {
+      my ( $self, $c, $name, $value ) = @_;
+      # $self -> controller instance
+      #
+      return(Args => 2);
+    }
+
+Please note that this feature does not let you actually assign new functions
+to actions via subroutine attributes, but is really more for creating useful
+aliases to existing core and extended attributes, and transforms based on 
+existing information (like from configuration).  Code for actually doing
+something meaningful with the subroutine attributes will be located in the
+L<Catalyst::Action> classes (or your subclasses), L<Catalyst::Dispatcher> and
+in subclasses of L<Catalyst::DispatchType>.  Remember these methods only get
+called basically once when the application is starting, not per request!
+
 =head1 AUTHORS
 
 Catalyst Contributors, see Catalyst.pm
diff --git a/t/author/spelling.t b/t/author/spelling.t
index 80348dc..edb24e6 100644
--- a/t/author/spelling.t
+++ b/t/author/spelling.t
@@ -18,6 +18,7 @@ add_stopwords(qw(
     wiki bitmask uri url urls dir hostname proxied http https IP SSL
     inline INLINE plugins
     FastCGI Stringifies Rethrows DispatchType Wishlist Refactor ROADMAP HTTPS Unescapes Restarter Nginx Refactored
+    ActionClass LocalRegex LocalRegexp MyAction metadata
     Andreas
     Ashton
     Axel