1 package Catalyst::DispatchType::Chained;
4 extends 'Catalyst::DispatchType';
7 use Catalyst::ActionChain;
34 # please don't perltidy this. hairy code within.
38 Catalyst::DispatchType::Chained - Path Part DispatchType
42 # root action - captures one argument after it
43 sub foo_setup : Chained('/') PathPart('foo') CaptureArgs(1) {
44 my ( $self, $c, $foo_arg ) = @_;
48 # child action endpoint - takes one argument
49 sub bar : Chained('foo_setup') Args(1) {
50 my ( $self, $c, $bar_arg ) = @_;
60 =head2 $self->list($c)
62 Debug output for Path Part dispatch points
67 my ( $self, $c ) = @_;
69 return unless $self->_endpoints;
71 my $column_width = Catalyst::Utils::term_width() - 35 - 9;
72 my $paths = Text::SimpleTable->new(
73 [ 35, 'Path Spec' ], [ $column_width, 'Private' ],
76 my $has_unattached_actions;
77 my $unattached_actions = Text::SimpleTable->new(
78 [ 35, 'Private' ], [ 36, 'Missing parent' ],
81 ENDPOINT: foreach my $endpoint (
82 sort { $a->reverse cmp $b->reverse }
83 @{ $self->_endpoints }
85 my $args = $endpoint->attributes->{Args}->[0];
86 my @parts = (defined($args) ? (("*") x $args) : '...');
91 if (my $cap = $curr->attributes->{CaptureArgs}) {
92 unshift(@parts, (("*") x $cap->[0]));
94 if (my $pp = $curr->attributes->{PartPath}) {
95 unshift(@parts, $pp->[0])
96 if (defined $pp->[0] && length $pp->[0]);
98 $parent = $curr->attributes->{Chained}->[0];
99 $curr = $self->_actions->{$parent};
100 unshift(@parents, $curr) if $curr;
102 if ($parent ne '/') {
103 $has_unattached_actions = 1;
104 $unattached_actions->row('/'.$parents[0]->reverse, $parent);
108 foreach my $p (@parents) {
110 if (my $cap = $p->attributes->{CaptureArgs}) {
111 $name .= ' ('.$cap->[0].')';
113 unless ($p eq $parents[0]) {
114 $name = "-> ${name}";
116 push(@rows, [ '', $name ]);
118 push(@rows, [ '', (@rows ? "=> " : '')."/${endpoint}" ]);
119 $rows[0][0] = join('/', '', @parts);
120 $paths->row(@$_) for @rows;
123 $c->log->debug( "Loaded Chained actions:\n" . $paths->draw . "\n" );
124 $c->log->debug( "Unattached Chained actions:\n", $unattached_actions->draw . "\n" )
125 if $has_unattached_actions;
128 =head2 $self->match( $c, $path )
130 Calls C<recurse_match> to see if a chain matches the C<$path>.
135 my ( $self, $c, $path ) = @_;
137 my $request = $c->request;
138 return 0 if @{$request->args};
140 my @parts = split('/', $path);
142 my ($chain, $captures, $parts) = $self->recurse_match($c, '/', \@parts);
143 push @{$request->args}, @$parts if $parts && @$parts;
145 return 0 unless $chain;
147 my $action = Catalyst::ActionChain->from_chain($chain);
149 $request->action("/${action}");
150 $request->match("/${action}");
151 $request->captures($captures);
153 $c->namespace( $action->namespace );
158 =head2 $self->recurse_match( $c, $parent, \@path_parts )
160 Recursive search for a matching chain.
165 my ( $self, $c, $parent, $path_parts ) = @_;
166 my $children = $self->_children_of->{$parent};
167 return () unless $children;
170 TRY: foreach my $try_part (sort { length($b) <=> length($a) }
172 # $b then $a to try longest part first
173 my @parts = @$path_parts;
174 if (length $try_part) { # test and strip PathPart
176 ($try_part eq join('/', # assemble equal number of parts
177 splice( # and strip them off @parts as well
178 @parts, 0, scalar(@{[split('/', $try_part)]})
179 ))); # @{[]} to avoid split to @_
181 my @try_actions = @{$children->{$try_part}};
182 TRY_ACTION: foreach my $action (@try_actions) {
183 if (my $capture_attr = $action->attributes->{CaptureArgs}) {
185 # Short-circuit if not enough remaining parts
186 next TRY_ACTION unless @parts >= $capture_attr->[0];
189 my @parts = @parts; # localise
191 # strip CaptureArgs into list
192 push(@captures, splice(@parts, 0, $capture_attr->[0]));
194 # try the remaining parts against children of this action
195 my ($actions, $captures, $action_parts) = $self->recurse_match(
196 $c, '/'.$action->reverse, \@parts
198 # No best action currently
199 # OR The action has less parts
200 # OR The action has equal parts but less captured data (ergo more defined)
203 $#$action_parts < $#{$best_action->{parts}} ||
204 ($#$action_parts == $#{$best_action->{parts}} &&
205 $#$captures < $#{$best_action->{captures}}))){
207 actions => [ $action, @$actions ],
208 captures=> [ @captures, @$captures ],
209 parts => $action_parts
215 local $c->req->{arguments} = [ @{$c->req->args}, @parts ];
216 next TRY_ACTION unless $action->match($c);
218 my $args_attr = $action->attributes->{Args}->[0];
220 # No best action currently
221 # OR This one matches with fewer parts left than the current best action,
222 # And therefore is a better match
223 # OR No parts and this expects 0
224 # The current best action might also be Args(0),
225 # but we couldn't chose between then anyway so we'll take the last seen
228 @parts < @{$best_action->{parts}} ||
229 (!@parts && $args_attr eq 0)){
231 actions => [ $action ],
239 return @$best_action{qw/actions captures parts/} if $best_action;
243 =head2 $self->register( $c, $action )
245 Calls register_path for every Path attribute for the given $action.
250 my ( $self, $c, $action ) = @_;
252 my @chained_attr = @{ $action->attributes->{Chained} || [] };
254 return 0 unless @chained_attr;
256 if (@chained_attr > 1) {
257 Catalyst::Exception->throw(
258 "Multiple Chained attributes not supported registering ${action}"
261 my $chained_to = $chained_attr[0];
263 Catalyst::Exception->throw(
264 "Actions cannot chain to themselves registering /${action}"
265 ) if ($chained_to eq '/' . $action);
267 my $children = ($self->_children_of->{ $chained_to } ||= {});
269 my @path_part = @{ $action->attributes->{PathPart} || [] };
271 my $part = $action->name;
273 if (@path_part == 1 && defined $path_part[0]) {
274 $part = $path_part[0];
275 } elsif (@path_part > 1) {
276 Catalyst::Exception->throw(
277 "Multiple PathPart attributes not supported registering " . $action->reverse()
281 if ($part =~ m(^/)) {
282 Catalyst::Exception->throw(
283 "Absolute parameters to PathPart not allowed registering " . $action->reverse()
287 $action->attributes->{PartPath} = [ $part ];
289 unshift(@{ $children->{$part} ||= [] }, $action);
291 $self->_actions->{'/'.$action->reverse} = $action;
293 unless ($action->attributes->{CaptureArgs}) {
294 unshift(@{ $self->_endpoints }, $action);
300 =head2 $self->uri_for_action($action, $captures)
302 Get the URI part for the action, using C<$captures> to fill
308 my ( $self, $action, $captures ) = @_;
310 return undef unless ($action->attributes->{Chained}
311 && !$action->attributes->{CaptureArgs});
314 my @captures = @$captures;
315 my $parent = "DUMMY";
318 if (my $cap = $curr->attributes->{CaptureArgs}) {
319 return undef unless @captures >= $cap->[0]; # not enough captures
321 unshift(@parts, splice(@captures, -$cap->[0]));
324 if (my $pp = $curr->attributes->{PartPath}) {
325 unshift(@parts, $pp->[0])
326 if (defined($pp->[0]) && length($pp->[0]));
328 $parent = $curr->attributes->{Chained}->[0];
329 $curr = $self->_actions->{$parent};
332 return undef unless $parent eq '/'; # fail for dangling action
334 return undef if @captures; # fail for too many captures
336 return join('/', '', @parts);
340 =head2 $c->expand_action($action)
342 Return a list of actions that represents a chained action. See
343 L<Catalyst::Dispatcher> for more info. You probably want to
344 use the expand_action it provides rather than this directly.
349 my ($self, $action) = @_;
351 return unless $action->attributes && $action->attributes->{Chained};
358 my $parent = $curr->attributes->{Chained}->[0];
359 $curr = $self->_actions->{$parent};
362 return Catalyst::ActionChain->from_chain([reverse @chain]);
365 __PACKAGE__->meta->make_immutable;
371 The C<Chained> attribute allows you to chain public path parts together
372 by their private names. A chain part's path can be specified with
373 C<PathPart> and can be declared to expect an arbitrary number of
374 arguments. The endpoint of the chain specifies how many arguments it
375 gets through the C<Args> attribute. C<:Args(0)> would be none at all,
376 C<:Args> without an integer would be unlimited. The path parts that
377 aren't endpoints are using C<CaptureArgs> to specify how many parameters
378 they expect to receive. As an example setup:
380 package MyApp::Controller::Greeting;
381 use base qw/ Catalyst::Controller /;
383 # this is the beginning of our chain
384 sub hello : PathPart('hello') Chained('/') CaptureArgs(1) {
385 my ( $self, $c, $integer ) = @_;
386 $c->stash->{ message } = "Hello ";
387 $c->stash->{ arg_sum } = $integer;
390 # this is our endpoint, because it has no :CaptureArgs
391 sub world : PathPart('world') Chained('hello') Args(1) {
392 my ( $self, $c, $integer ) = @_;
393 $c->stash->{ message } .= "World!";
394 $c->stash->{ arg_sum } += $integer;
396 $c->response->body( join "<br/>\n" =>
397 $c->stash->{ message }, $c->stash->{ arg_sum } );
400 The debug output provides a separate table for chained actions, showing
401 the whole chain as it would match and the actions it contains. Here's an
402 example of the startup output with our actions above:
405 [debug] Loaded Path Part actions:
406 .-----------------------+------------------------------.
407 | Path Spec | Private |
408 +-----------------------+------------------------------+
409 | /hello/*/world/* | /greeting/hello (1) |
410 | | => /greeting/world |
411 '-----------------------+------------------------------'
414 As you can see, Catalyst only deals with chains as whole paths and
415 builds one for each endpoint, which are the actions with C<:Chained> but
416 without C<:CaptureArgs>.
418 Let's assume this application gets a request at the path
419 C</hello/23/world/12>. What happens then? First, Catalyst will dispatch
420 to the C<hello> action and pass the value C<23> as an argument to it
421 after the context. It does so because we have previously used
422 C<:CaptureArgs(1)> to declare that it has one path part after itself as
423 its argument. We told Catalyst that this is the beginning of the chain
424 by specifying C<:Chained('/')>. Also note that instead of saying
425 C<:PathPart('hello')> we could also just have said C<:PathPart>, as it
426 defaults to the name of the action.
428 After C<hello> has run, Catalyst goes on to dispatch to the C<world>
429 action. This is the last action to be called: Catalyst knows this is an
430 endpoint because we did not specify a C<:CaptureArgs>
431 attribute. Nevertheless we specify that this action expects an argument,
432 but at this point we're using C<:Args(1)> to do that. We could also have
433 said C<:Args> or left it out altogether, which would mean this action
434 would get all arguments that are there. This action's C<:Chained>
435 attribute says C<hello> and tells Catalyst that the C<hello> action in
436 the current controller is its parent.
438 With this we have built a chain consisting of two public path parts.
439 C<hello> captures one part of the path as its argument, and also
440 specifies the path root as its parent. So this part is
441 C</hello/$arg>. The next part is the endpoint C<world>, expecting one
442 argument. It sums up to the path part C<world/$arg>. This leads to a
443 complete chain of C</hello/$arg/world/$arg> which is matched against the
446 This example application would, if run and called by e.g.
447 C</hello/23/world/12>, set the stash value C<message> to "Hello" and the
448 value C<arg_sum> to "23". The C<world> action would then append "World!"
449 to C<message> and add C<12> to the stash's C<arg_sum> value. For the
450 sake of simplicity no view is shown. Instead we just put the values of
451 the stash into our body. So the output would look like:
456 And our test server would have given us this debugging output for the
460 [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
461 [debug] Path is "/greeting/world"
462 [debug] Arguments are "12"
463 [info] Request took 0.164113s (6.093/s)
464 .------------------------------------------+-----------.
466 +------------------------------------------+-----------+
467 | /greeting/hello | 0.000029s |
468 | /greeting/world | 0.000024s |
469 '------------------------------------------+-----------'
472 What would be common uses of this dispatch technique? It gives the
473 possibility to split up logic that contains steps that each depend on
474 each other. An example would be, for example, a wiki path like
475 C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
478 sub wiki : PathPart('wiki') Chained('/') CaptureArgs(1) {
479 my ( $self, $c, $page_name ) = @_;
480 # load the page named $page_name and put the object
484 sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) {
485 my ( $self, $c, $revision_id ) = @_;
486 # use the page object in the stash to get at its
487 # revision with number $revision_id
490 sub view : PathPart Chained('rev') Args(0) {
491 my ( $self, $c ) = @_;
492 # display the revision in our stash. Another option
493 # would be to forward a compatible object to the action
494 # that displays the default wiki pages, unless we want
495 # a different interface here, for example restore
499 It would now be possible to add other endpoints, for example C<restore>
500 to restore this specific revision as the current state.
502 You don't have to put all the chained actions in one controller. The
503 specification of the parent through C<:Chained> also takes an absolute
504 action path as its argument. Just specify it with a leading C</>.
506 If you want, for example, to have actions for the public paths
507 C</foo/12/edit> and C</foo/12>, just specify two actions with
508 C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
509 path needs a C<:CaptureArgs(1)> attribute and a endpoint with
510 C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
511 the action just a C<:Args(1)> to mark it as endpoint. This sums up to
512 this debugging output:
515 [debug] Loaded Path Part actions:
516 .-----------------------+------------------------------.
517 | Path Spec | Private |
518 +-----------------------+------------------------------+
519 | /foo/* | /controller/foo_view |
520 | /foo/*/edit | /controller/foo_load (1) |
521 | | => /controller/edit |
522 '-----------------------+------------------------------'
525 Here's a more detailed specification of the attributes belonging to
534 Sets the name of this part of the chain. If it is specified without
535 arguments, it takes the name of the action as default. So basically
536 C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
537 This can also contain slashes to bind to a deeper level. An action
538 with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
539 C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
540 effect as using C<:PathPart>, it would default to the action name.
544 Sets PathPart to the path_prefix of the current controller.
548 Has to be specified for every child in the chain. Possible values are
549 absolute and relative private action paths or a single slash C</> to
550 tell Catalyst that this is the root of a chain. The attribute
551 C<:Chained> without arguments also defaults to the C</> behavior.
552 Relative action paths may use C<../> to refer to actions in parent
555 Because you can specify an absolute path to the parent action, it
556 doesn't matter to Catalyst where that parent is located. So, if your
557 design requests it, you can redispatch a chain through any controller or
560 Another interesting possibility gives C<:Chained('.')>, which chains
561 itself to an action with the path of the current controller's namespace.
564 # in MyApp::Controller::Foo
565 sub bar : Chained CaptureArgs(1) { ... }
567 # in MyApp::Controller::Foo::Bar
568 sub baz : Chained('.') Args(1) { ... }
570 This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
571 as the argument to Chained here chains the C<baz> action to an action
572 with the path of the current controller namespace, namely
573 C</foo/bar>. That action chains directly to C</>, so the C</bar/*/baz/*>
574 chain comes out as the end product.
578 Chains an action to another action with the same name in the parent
579 controller. For Example:
581 # in MyApp::Controller::Foo
582 sub bar : Chained CaptureArgs(1) { ... }
584 # in MyApp::Controller::Foo::Moo
585 sub bar : ChainedParent Args(1) { ... }
587 This builds a chain like C</bar/*/bar/*>.
591 Must be specified for every part of the chain that is not an
592 endpoint. With this attribute Catalyst knows how many of the following
593 parts of the path (separated by C</>) this action wants to capture as
594 its arguments. If it doesn't expect any, just specify
595 C<:CaptureArgs(0)>. The captures get passed to the action's C<@_> right
596 after the context, but you can also find them as array references in
597 C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
598 level of the action in the chain that captured the parts of the path.
600 An action that is part of a chain (that is, one that has a C<:Chained>
601 attribute) but has no C<:CaptureArgs> attribute is treated by Catalyst
606 By default, endpoints receive the rest of the arguments in the path. You
607 can tell Catalyst through C<:Args> explicitly how many arguments your
608 endpoint expects, just like you can with C<:CaptureArgs>. Note that this
609 also affects whether this chain is invoked on a request. A chain with an
610 endpoint specifying one argument will only match if exactly one argument
613 You can specify an exact number of arguments like C<:Args(3)>, including
614 C<0>. If you just say C<:Args> without any arguments, it is the same as
615 leaving it out altogether: The chain is matched regardless of the number
616 of path parts after the endpoint.
618 Just as with C<:CaptureArgs>, the arguments get passed to the action in
619 C<@_> after the context object. They can also be reached through
620 C<$c-E<gt>request-E<gt>arguments>.
624 =head2 Auto actions, dispatching and forwarding
626 Note that the list of C<auto> actions called depends on the private path
627 of the endpoint of the chain, not on the chained actions way. The
628 C<auto> actions will be run before the chain dispatching begins. In
629 every other aspect, C<auto> actions behave as documented.
631 The C<forward>ing to other actions does just what you would expect. But if
632 you C<detach> out of a chain, the rest of the chain will not get called
637 Catalyst Contributors, see Catalyst.pm
641 This program is free software, you can redistribute it and/or modify it under
642 the same terms as Perl itself.