X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=blobdiff_plain;f=lib%2FCatalyst%2FDispatchType%2FChained.pm;h=28886075d40dbee2e5acc2ab7160a5b55a9d0c51;hp=2fb0a0b8086f4805b6f85ab1c6a7f174d4342c57;hb=0ca510f0aa1cabe138d81897d38111d7b772449c;hpb=05a90578a1a58925942d520bf21333c59c6eac01 diff --git a/lib/Catalyst/DispatchType/Chained.pm b/lib/Catalyst/DispatchType/Chained.pm index 2fb0a0b..2888607 100644 --- a/lib/Catalyst/DispatchType/Chained.pm +++ b/lib/Catalyst/DispatchType/Chained.pm @@ -1,10 +1,37 @@ package Catalyst::DispatchType::Chained; -use strict; -use base qw/Catalyst::DispatchType/; +use Moose; +extends 'Catalyst::DispatchType'; + use Text::SimpleTable; use Catalyst::ActionChain; +use Catalyst::Utils; use URI; +use Scalar::Util (); +use Encode 2.21 'decode_utf8'; + +has _endpoints => ( + is => 'rw', + isa => 'ArrayRef', + required => 1, + default => sub{ [] }, + ); + +has _actions => ( + is => 'rw', + isa => 'HashRef', + required => 1, + default => sub{ {} }, + ); + +has _children_of => ( + is => 'rw', + isa => 'HashRef', + required => 1, + default => sub{ {} }, + ); + +no Moose; # please don't perltidy this. hairy code within. @@ -14,6 +41,8 @@ Catalyst::DispatchType::Chained - Path Part DispatchType =head1 SYNOPSIS +Path part matching, allowing several actions to sequentially take care of processing a request: + # root action - captures one argument after it sub foo_setup : Chained('/') PathPart('foo') CaptureArgs(1) { my ( $self, $c, $foo_arg ) = @_; @@ -28,7 +57,16 @@ Catalyst::DispatchType::Chained - Path Part DispatchType =head1 DESCRIPTION -See L. +Dispatch type managing default behaviour. For more information on +dispatch types, see: + +=over 4 + +=item * L for how they affect application authors + +=item * L for implementation information. + +=back =head1 METHODS @@ -41,53 +79,92 @@ Debug output for Path Part dispatch points sub list { my ( $self, $c ) = @_; - return unless $self->{endpoints}; + return unless $self->_endpoints; + my $avail_width = Catalyst::Utils::term_width() - 9; + my $col1_width = ($avail_width * .50) < 35 ? 35 : int($avail_width * .50); + my $col2_width = $avail_width - $col1_width; my $paths = Text::SimpleTable->new( - [ 35, 'Path Spec' ], [ 36, 'Private' ] - ); + [ $col1_width, 'Path Spec' ], [ $col2_width, 'Private' ], + ); + + my $has_unattached_actions; + my $unattached_actions = Text::SimpleTable->new( + [ $col1_width, 'Private' ], [ $col2_width, 'Missing parent' ], + ); ENDPOINT: foreach my $endpoint ( sort { $a->reverse cmp $b->reverse } - @{ $self->{endpoints} } + @{ $self->_endpoints } ) { - my $args = $endpoint->attributes->{Args}->[0]; + my $args = $endpoint->list_extra_info->{Args}; my @parts = (defined($args) ? (("*") x $args) : '...'); my @parents = (); my $parent = "DUMMY"; + my $extra = $self->_list_extra_http_methods($endpoint); + my $consumes = $self->_list_extra_consumes($endpoint); my $curr = $endpoint; while ($curr) { - if (my $cap = $curr->attributes->{CaptureArgs}) { - unshift(@parts, (("*") x $cap->[0])); + if (my $cap = $curr->list_extra_info->{CaptureArgs}) { + unshift(@parts, (("*") x $cap)); } - if (my $pp = $curr->attributes->{PartPath}) { + if (my $pp = $curr->attributes->{PathPart}) { unshift(@parts, $pp->[0]) if (defined $pp->[0] && length $pp->[0]); } $parent = $curr->attributes->{Chained}->[0]; - $curr = $self->{actions}{$parent}; + $curr = $self->_actions->{$parent}; unshift(@parents, $curr) if $curr; } - next ENDPOINT unless $parent eq '/'; # skip dangling action + if ($parent ne '/') { + $has_unattached_actions = 1; + $unattached_actions->row('/' . ($parents[0] || $endpoint)->reverse, $parent); + next ENDPOINT; + } my @rows; foreach my $p (@parents) { my $name = "/${p}"; - if (my $cap = $p->attributes->{CaptureArgs}) { - $name .= ' ('.$cap->[0].')'; + + if (defined(my $extra = $self->_list_extra_http_methods($p))) { + $name = "${extra} ${name}"; + } + if (defined(my $cap = $p->list_extra_info->{CaptureArgs})) { + $name .= ' ('.$cap.')'; } + if (defined(my $ct = $p->list_extra_info->{Consumes})) { + $name .= ' :'.$ct; + } + unless ($p eq $parents[0]) { $name = "-> ${name}"; } push(@rows, [ '', $name ]); } - push(@rows, [ '', (@rows ? "=> " : '')."/${endpoint}" ]); - $rows[0][0] = join('/', '', @parts); + push(@rows, [ '', (@rows ? "=> " : '').($extra ? "$extra " : '')."/${endpoint}". ($consumes ? " :$consumes":"" ) ]); + my @display_parts = map { $_ =~s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; decode_utf8 $_ } @parts; + $rows[0][0] = join('/', '', @display_parts) || '/'; $paths->row(@$_) for @rows; } - $c->log->debug( "Loaded Path Part actions:\n" . $paths->draw ); + $c->log->debug( "Loaded Chained actions:\n" . $paths->draw . "\n" ); + $c->log->debug( "Unattached Chained actions:\n", $unattached_actions->draw . "\n" ) + if $has_unattached_actions; +} + +sub _list_extra_http_methods { + my ( $self, $action ) = @_; + return unless defined $action->list_extra_info->{HTTP_METHODS}; + return join(', ', @{$action->list_extra_info->{HTTP_METHODS}}); + } +sub _list_extra_consumes { + my ( $self, $action ) = @_; + return unless defined $action->list_extra_info->{CONSUMES}; + return join(', ', @{$action->list_extra_info->{CONSUMES}}); +} + + =head2 $self->match( $c, $path ) Calls C to see if a chain matches the C<$path>. @@ -97,19 +174,27 @@ Calls C to see if a chain matches the C<$path>. sub match { my ( $self, $c, $path ) = @_; - return 0 if @{$c->req->args}; + my $request = $c->request; + return 0 if @{$request->args}; my @parts = split('/', $path); - my ($chain, $captures) = $self->recurse_match($c, '/', \@parts); + my ($chain, $captures, $parts) = $self->recurse_match($c, '/', \@parts); + + if ($parts && @$parts) { + for my $arg (@$parts) { + $arg =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; + push @{$request->args}, $arg; + } + } return 0 unless $chain; my $action = Catalyst::ActionChain->from_chain($chain); - $c->req->action("/${action}"); - $c->req->match("/${action}"); - $c->req->captures($captures); + $request->action("/${action}"); + $request->match("/${action}"); + $request->captures($captures); $c->action($action); $c->namespace( $action->namespace ); @@ -124,8 +209,9 @@ Recursive search for a matching chain. sub recurse_match { my ( $self, $c, $parent, $path_parts ) = @_; - my $children = $self->{children_of}{$parent}; + my $children = $self->_children_of->{$parent}; return () unless $children; + my $best_action; my @captures; TRY: foreach my $try_part (sort { length($b) <=> length($a) } keys %$children) { @@ -141,29 +227,70 @@ sub recurse_match { my @try_actions = @{$children->{$try_part}}; TRY_ACTION: foreach my $action (@try_actions) { if (my $capture_attr = $action->attributes->{CaptureArgs}) { + my $capture_count = $capture_attr->[0] || 0; + + # Short-circuit if not enough remaining parts + next TRY_ACTION unless @parts >= $capture_count; + my @captures; my @parts = @parts; # localise # strip CaptureArgs into list - push(@captures, splice(@parts, 0, $capture_attr->[0])); + push(@captures, splice(@parts, 0, $capture_count)); + + # check if the action may fit, depending on a given test by the app + if ($action->can('match_captures')) { next TRY_ACTION unless $action->match_captures($c, \@captures) } # try the remaining parts against children of this action - my ($actions, $captures) = $self->recurse_match( + my ($actions, $captures, $action_parts, $n_pathparts) = $self->recurse_match( $c, '/'.$action->reverse, \@parts ); - if ($actions) { - return [ $action, @$actions ], [ @captures, @$captures ]; + # No best action currently + # OR The action has less parts + # OR The action has equal parts but less captured data (ergo more defined) + if ($actions && + (!$best_action || + $#$action_parts < $#{$best_action->{parts}} || + ($#$action_parts == $#{$best_action->{parts}} && + $#$captures < $#{$best_action->{captures}} && + $n_pathparts > $best_action->{n_pathparts}))) { + my @pathparts = split /\//, $action->attributes->{PathPart}->[0]; + $best_action = { + actions => [ $action, @$actions ], + captures=> [ @captures, @$captures ], + parts => $action_parts, + n_pathparts => scalar(@pathparts) + $n_pathparts, + }; } - } else { + } + else { { local $c->req->{arguments} = [ @{$c->req->args}, @parts ]; next TRY_ACTION unless $action->match($c); } - push(@{$c->req->args}, @parts); - return [ $action ], [ ]; + my $args_attr = $action->attributes->{Args}->[0]; + my @pathparts = split /\//, $action->attributes->{PathPart}->[0]; + # No best action currently + # OR This one matches with fewer parts left than the current best action, + # And therefore is a better match + # OR No parts and this expects 0 + # The current best action might also be Args(0), + # but we couldn't chose between then anyway so we'll take the last seen + + if (!$best_action || + @parts < @{$best_action->{parts}} || + (!@parts && defined($args_attr) && $args_attr eq "0")){ + $best_action = { + actions => [ $action ], + captures=> [], + parts => \@parts, + n_pathparts => scalar(@pathparts), + }; + } } } } + return @$best_action{qw/actions captures parts n_pathparts/} if $best_action; return (); } @@ -173,6 +300,32 @@ Calls register_path for every Path attribute for the given $action. =cut +sub _check_args_attr { + my ( $self, $action, $name ) = @_; + + return unless exists $action->attributes->{$name}; + + if (@{$action->attributes->{$name}} > 1) { + Catalyst::Exception->throw( + "Multiple $name attributes not supported registering " . $action->reverse() + ); + } + my $args = $action->attributes->{$name}->[0]; + if (defined($args) and not ( + Scalar::Util::looks_like_number($args) and + int($args) == $args and $args >= 0 + )) { + require Data::Dumper; + local $Data::Dumper::Terse = 1; + local $Data::Dumper::Indent = 0; + $args = Data::Dumper::Dumper($args); + Catalyst::Exception->throw( + "Invalid $name($args) for action " . $action->reverse() . + " (use '$name' or '$name()')" + ); + } +} + sub register { my ( $self, $c, $action ) = @_; @@ -180,27 +333,18 @@ sub register { return 0 unless @chained_attr; - if (@chained_attr > 2) { + if (@chained_attr > 1) { Catalyst::Exception->throw( "Multiple Chained attributes not supported registering ${action}" ); } + my $chained_to = $chained_attr[0]; - my $parent = $chained_attr[0]; - - if (defined($parent) && length($parent)) { - if ($parent eq '.') { - $parent = '/'.$action->namespace; - } elsif ($parent !~ m/^\//) { - $parent = '/'.join('/', $action->namespace, $parent); - } - } else { - $parent = '/' - } - - $action->attributes->{Chained} = [ $parent ]; + Catalyst::Exception->throw( + "Actions cannot chain to themselves registering /${action}" + ) if ($chained_to eq '/' . $action); - my $children = ($self->{children_of}{$parent} ||= {}); + my $children = ($self->_children_of->{ $chained_to } ||= {}); my @path_part = @{ $action->attributes->{PathPart} || [] }; @@ -210,24 +354,38 @@ sub register { $part = $path_part[0]; } elsif (@path_part > 1) { Catalyst::Exception->throw( - "Multiple PathPart attributes not supported registering ${action}" + "Multiple PathPart attributes not supported registering " . $action->reverse() ); } if ($part =~ m(^/)) { Catalyst::Exception->throw( - "Absolute parameters to PathPart not allowed registering ${action}" + "Absolute parameters to PathPart not allowed registering " . $action->reverse() ); } - $action->attributes->{PartPath} = [ $part ]; + my $encoded_part = URI->new($part)->canonical; + $encoded_part =~ s{(?<=[^/])/+\z}{}; - unshift(@{ $children->{$part} ||= [] }, $action); + $action->attributes->{PathPart} = [ $encoded_part ]; - ($self->{actions} ||= {})->{'/'.$action->reverse} = $action; + unshift(@{ $children->{$encoded_part} ||= [] }, $action); + + $self->_actions->{'/'.$action->reverse} = $action; + + foreach my $name (qw(Args CaptureArgs)) { + $self->_check_args_attr($action, $name); + } + + if (exists $action->attributes->{Args} and exists $action->attributes->{CaptureArgs}) { + Catalyst::Exception->throw( + "Combining Args and CaptureArgs attributes not supported registering " . + $action->reverse() + ); + } unless ($action->attributes->{CaptureArgs}) { - unshift(@{ $self->{endpoints} ||= [] }, $action); + unshift(@{ $self->_endpoints }, $action); } return 1; @@ -244,7 +402,7 @@ sub uri_for_action { my ( $self, $action, $captures ) = @_; return undef unless ($action->attributes->{Chained} - && $action->attributes->{Args}); + && !$action->attributes->{CaptureArgs}); my @parts = (); my @captures = @$captures; @@ -252,15 +410,17 @@ sub uri_for_action { my $curr = $action; while ($curr) { if (my $cap = $curr->attributes->{CaptureArgs}) { - return undef unless @captures >= $cap->[0]; # not enough captures - unshift(@parts, splice(@captures, -$cap->[0])); + return undef unless @captures >= ($cap->[0]||0); # not enough captures + if ($cap->[0]) { + unshift(@parts, splice(@captures, -$cap->[0])); + } } - if (my $pp = $curr->attributes->{PartPath}) { + if (my $pp = $curr->attributes->{PathPart}) { unshift(@parts, $pp->[0]) - if (defined $pp->[0] && length $pp->[0]); + if (defined($pp->[0]) && length($pp->[0])); } $parent = $curr->attributes->{Chained}->[0]; - $curr = $self->{actions}{$parent}; + $curr = $self->_actions->{$parent}; } return undef unless $parent eq '/'; # fail for dangling action @@ -268,21 +428,49 @@ sub uri_for_action { return undef if @captures; # fail for too many captures return join('/', '', @parts); - + +} + +=head2 $c->expand_action($action) + +Return a list of actions that represents a chained action. See +L for more info. You probably want to +use the expand_action it provides rather than this directly. + +=cut + +sub expand_action { + my ($self, $action) = @_; + + return unless $action->attributes && $action->attributes->{Chained}; + + my @chain; + my $curr = $action; + + while ($curr) { + push @chain, $curr; + my $parent = $curr->attributes->{Chained}->[0]; + $curr = $self->_actions->{$parent}; + } + + return Catalyst::ActionChain->from_chain([reverse @chain]); } +__PACKAGE__->meta->make_immutable; +1; + =head1 USAGE =head2 Introduction The C attribute allows you to chain public path parts together -by their private names. A chain part's path can be specified with C -and can be declared to expect an arbitrary number of arguments. The endpoint -of the chain specifies how many arguments it gets through the C -attribute. C<:Args(0)> would be none at all, C<:Args> without an integer -would be unlimited. The path parts that aren't endpoints are using -C to specify how many parameters they expect to receive. As an -example setup: +by their private names. A chain part's path can be specified with +C and can be declared to expect an arbitrary number of +arguments. The endpoint of the chain specifies how many arguments it +gets through the C attribute. C<:Args(0)> would be none at all, +C<:Args> without an integer would be unlimited. The path parts that +aren't endpoints are using C to specify how many parameters +they expect to receive. As an example setup: package MyApp::Controller::Greeting; use base qw/ Catalyst::Controller /; @@ -305,8 +493,8 @@ example setup: } The debug output provides a separate table for chained actions, showing -the whole chain as it would match and the actions it contains. Here's -an example of the startup output with our actions above: +the whole chain as it would match and the actions it contains. Here's an +example of the startup output with our actions above: ... [debug] Loaded Path Part actions: @@ -318,48 +506,49 @@ an example of the startup output with our actions above: '-----------------------+------------------------------' ... -As you can see, Catalyst only deals with chains as whole path and -builds one for each endpoint, which are the actions with C<:Chained> -but without C<:CaptureArgs>. +As you can see, Catalyst only deals with chains as whole paths and +builds one for each endpoint, which are the actions with C<:Chained> but +without C<:CaptureArgs>. Let's assume this application gets a request at the path -C, what happens then? First, Catalyst will dispatch -to the C action and pass the value C<23> as argument to it after -the context. It does so because we have previously used C<:CaptureArgs(1)> -to declare that it has one path part after itself as it's argument. We -told Catalyst that this is the beginning of the chain by specifying -C<:Chained('/')>. Also note that instead of saying C<:PathPart('hello')> -we could also just have said C<:PathPart>, as it defaults to the name of -the action. +C. What happens then? First, Catalyst will dispatch +to the C action and pass the value C<23> as an argument to it +after the context. It does so because we have previously used +C<:CaptureArgs(1)> to declare that it has one path part after itself as +its argument. We told Catalyst that this is the beginning of the chain +by specifying C<:Chained('/')>. Also note that instead of saying +C<:PathPart('hello')> we could also just have said C<:PathPart>, as it +defaults to the name of the action. After C has run, Catalyst goes on to dispatch to the C -action. This is the last action to be called, as Catalyst knows this -is an endpoint because we specified no C<:CaptureArgs> attribute. Nevertheless -we specify that this action expects an argument, but at this point we're -using C<:Args(1)> to do that. We could also have said C<:Args> or leave -it out alltogether, which would mean this action gets all arguments that -are there. This action's C<:Chained> attribute says C and tells -Catalyst that the C action in the current controller is it's -parent. +action. This is the last action to be called: Catalyst knows this is an +endpoint because we did not specify a C<:CaptureArgs> +attribute. Nevertheless we specify that this action expects an argument, +but at this point we're using C<:Args(1)> to do that. We could also have +said C<:Args> or left it out altogether, which would mean this action +would get all arguments that are there. This action's C<:Chained> +attribute says C and tells Catalyst that the C action in +the current controller is its parent. With this we have built a chain consisting of two public path parts. -C captures one part of the path as it's argument, and also specifies -the path root as it's parent. So this part is C. The next part -is the endpoint C, expecting one argument. It sums up to the path -part C. This leads to a complete chain of -C which is matched against the requested paths. - -This example application would, if run and called by e.g. -C, set the stash value C to C and -the value C to C<23>. The C action would then append -C to C and add C<12> to the stash's C value. -For the sake of simplicity no view is shown. Instead we just put the -values of the stash into our body. So the output would look like: +C captures one part of the path as its argument, and also +specifies the path root as its parent. So this part is +C. The next part is the endpoint C, expecting one +argument. It sums up to the path part C. This leads to a +complete chain of C which is matched against the +requested paths. + +This example application would, if run and called by e.g. +C, set the stash value C to "Hello" and the +value C to "23". The C action would then append "World!" +to C and add C<12> to the stash's C value. For the +sake of simplicity no view is shown. Instead we just put the values of +the stash into our body. So the output would look like: Hello World! 35 -And our test server would've given us this debugging output for the +And our test server would have given us this debugging output for the request: ... @@ -375,9 +564,9 @@ request: '------------------------------------------+-----------' ... -What would be common usecases of this dispatching technique? It gives the -possibility to split up logic that contains steps that each depend on each -other. An example would be, for example, a wiki path like +What would be common uses of this dispatch technique? It gives the +possibility to split up logic that contains steps that each depend on +each other. An example would be, for example, a wiki path like C. This chain can be easily built with these actions: @@ -389,31 +578,30 @@ these actions: sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) { my ( $self, $c, $revision_id ) = @_; - # use the page object in the stash to get at it's + # use the page object in the stash to get at its # revision with number $revision_id } sub view : PathPart Chained('rev') Args(0) { my ( $self, $c ) = @_; - # display the revision in our stash. An other option + # display the revision in our stash. Another option # would be to forward a compatible object to the action # that displays the default wiki pages, unless we want # a different interface here, for example restore # functionality. } -It would now be possible to add other endpoints. For example C to -restore this specific revision as current state. +It would now be possible to add other endpoints, for example C +to restore this specific revision as the current state. -Also, you of course don't have to put all the chained actions in one -controller. The specification of the parent through C<:Chained> also takes -an absolute action path as it's argument. Just specify it with a leading -C. +You don't have to put all the chained actions in one controller. The +specification of the parent through C<:Chained> also takes an absolute +action path as its argument. Just specify it with a leading C. If you want, for example, to have actions for the public paths -C and C, just specify two actions with +C and C, just specify two actions with C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former -path needs a C<:CaptureArgs(1)> attribute and a endpoint with +path needs a C<:CaptureArgs(1)> attribute and a endpoint with C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give the action just a C<:Args(1)> to mark it as endpoint. This sums up to this debugging output: @@ -429,7 +617,7 @@ this debugging output: '-----------------------+------------------------------' ... -Here's a more detailed specification of the attributes belonging to +Here's a more detailed specification of the attributes belonging to C<:Chained>: =head2 Attributes @@ -446,21 +634,26 @@ with C would bind to C. If you don't specify C<:PathPart> it has the same effect as using C<:PathPart>, it would default to the action name. +=item PathPrefix + +Sets PathPart to the path_prefix of the current controller. + =item Chained Has to be specified for every child in the chain. Possible values are -absolute and relative private action paths, with the relatives pointing -to the current controller, or a single slash C to tell Catalyst that -this is the root of a chain. The attribute C<:Chained> without aguments -also defaults to the C behaviour. +absolute and relative private action paths or a single slash C to +tell Catalyst that this is the root of a chain. The attribute +C<:Chained> without arguments also defaults to the C behavior. +Relative action paths may use C<../> to refer to actions in parent +controllers. -Due to the fact that you can specify an absolute path to the parent -action, it doesn't matter to Catalyst where that parent is located. So, -if your design requests it, you can redispatch a chain through every -controller or namespace you want. +Because you can specify an absolute path to the parent action, it +doesn't matter to Catalyst where that parent is located. So, if your +design requests it, you can redispatch a chain through any controller or +namespace you want. Another interesting possibility gives C<:Chained('.')>, which chains -itself to an action with the path of the current controllers namespace. +itself to an action with the path of the current controller's namespace. For example: # in MyApp::Controller::Foo @@ -470,63 +663,86 @@ For example: sub baz : Chained('.') Args(1) { ... } This builds up a chain like C. The specification of C<.> -as argument to Chained here chains the C action to an action with -the path of the current controller namespace, namely C. That -action chains directly to C, so the above chain comes out as end -product. +as the argument to Chained here chains the C action to an action +with the path of the current controller namespace, namely +C. That action chains directly to C, so the C +chain comes out as the end product. + +=item ChainedParent + +Chains an action to another action with the same name in the parent +controller. For Example: + + # in MyApp::Controller::Foo + sub bar : Chained CaptureArgs(1) { ... } + + # in MyApp::Controller::Foo::Moo + sub bar : ChainedParent Args(1) { ... } + +This builds a chain like C. =item CaptureArgs -Also has to be specified for every part of the chain that is not an +Must be specified for every part of the chain that is not an endpoint. With this attribute Catalyst knows how many of the following -parts of the path (separated by C) this action wants to captures as -it's arguments. If it doesn't expect any, just specify C<:CaptureArgs(0)>. -The captures get passed to the action's C<@_> right after the context, -but you can also find them as array reference in +parts of the path (separated by C) this action wants to capture as +its arguments. If it doesn't expect any, just specify +C<:CaptureArgs(0)>. The captures get passed to the action's C<@_> right +after the context, but you can also find them as array references in C<$c-Erequest-Ecaptures-E[$level]>. The C<$level> is the level of the action in the chain that captured the parts of the path. -An action that is part of a chain (read: that has a C<:Chained> attribute) -but has no C<:CaptureArgs> attribute is treated by Catalyst as a chain end. +An action that is part of a chain (that is, one that has a C<:Chained> +attribute) but has no C<:CaptureArgs> attribute is treated by Catalyst +as a chain end. =item Args By default, endpoints receive the rest of the arguments in the path. You can tell Catalyst through C<:Args> explicitly how many arguments your endpoint expects, just like you can with C<:CaptureArgs>. Note that this -also influences if this chain is invoked on a request. A chain with an +also affects whether this chain is invoked on a request. A chain with an endpoint specifying one argument will only match if exactly one argument exists in the path. You can specify an exact number of arguments like C<:Args(3)>, including C<0>. If you just say C<:Args> without any arguments, it is the same as -leaving it out alltogether: The chain is matched independent of the number +leaving it out altogether: The chain is matched regardless of the number of path parts after the endpoint. -Just like with C<:CaptureArgs>, the arguments get passed to the action in +Just as with C<:CaptureArgs>, the arguments get passed to the action in C<@_> after the context object. They can also be reached through C<$c-Erequest-Earguments>. =back -=head2 auto actions, dispatching and forwarding +=head2 Auto actions, dispatching and forwarding Note that the list of C actions called depends on the private path -of the endpoint of the chain, not on the chained actions way. The C -actions will be run before the chain dispatching begins. In every other -aspect, C actions behave as documented. +of the endpoint of the chain, not on the chained actions way. The +C actions will be run before the chain dispatching begins. In +every other aspect, C actions behave as documented. + +The Cing to other actions does just what you would expect. i.e. +only the target action is run. The actions that that action is chained +to are not run. +If you C out of a chain, the rest of the chain will not get +called after the C. + +=head2 match_captures + +A method which can optionally be implemented by actions to +stop chain matching. -The Cing to other actions does just what you would expect. But if -you C out of a chain, the rest of the chain will not get called -after the C returned. +See L for further details. -=head1 AUTHOR +=head1 AUTHORS -Matt S Trout +Catalyst Contributors, see Catalyst.pm =head1 COPYRIGHT -This program is free software, you can redistribute it and/or modify it under +This library is free software. You can redistribute it and/or modify it under the same terms as Perl itself. =cut