1 package Catalyst::DispatchType::Chained;
4 use base qw/Catalyst::DispatchType/;
6 use Catalyst::ActionChain;
9 # please don't perltidy this. hairy code within.
13 Catalyst::DispatchType::Chained - Path Part DispatchType
17 # root action - captures one argument after it
18 sub foo_setup : Chained('/') PathPart('foo') CaptureArgs(1) {
19 my ( $self, $c, $foo_arg ) = @_;
23 # child action endpoint - takes one argument
24 sub bar : Chained('foo_setup') Args(1) {
25 my ( $self, $c, $bar_arg ) = @_;
35 =head2 $self->list($c)
37 Debug output for Path Part dispatch points
42 my ( $self, $c ) = @_;
44 return unless $self->{endpoints};
46 my $paths = Text::SimpleTable->new(
47 [ 35, 'Path Spec' ], [ 36, 'Private' ]
50 ENDPOINT: foreach my $endpoint (
51 sort { $a->reverse cmp $b->reverse }
52 @{ $self->{endpoints} }
54 my $args = $endpoint->attributes->{Args}->[0];
55 my @parts = (defined($args) ? (("*") x $args) : '...');
60 if (my $cap = $curr->attributes->{CaptureArgs}) {
61 unshift(@parts, (("*") x $cap->[0]));
63 if (my $pp = $curr->attributes->{PartPath}) {
64 unshift(@parts, $pp->[0])
65 if (defined $pp->[0] && length $pp->[0]);
67 $parent = $curr->attributes->{Chained}->[0];
68 $curr = $self->{actions}{$parent};
69 unshift(@parents, $curr) if $curr;
71 next ENDPOINT unless $parent eq '/'; # skip dangling action
73 foreach my $p (@parents) {
75 if (my $cap = $p->attributes->{CaptureArgs}) {
76 $name .= ' ('.$cap->[0].')';
78 unless ($p eq $parents[0]) {
81 push(@rows, [ '', $name ]);
83 push(@rows, [ '', (@rows ? "=> " : '')."/${endpoint}" ]);
84 $rows[0][0] = join('/', '', @parts);
85 $paths->row(@$_) for @rows;
88 $c->log->debug( "Loaded Chained actions:\n" . $paths->draw . "\n" );
91 =head2 $self->match( $c, $path )
93 Calls C<recurse_match> to see if a chain matches the C<$path>.
98 my ( $self, $c, $path ) = @_;
100 return 0 if @{$c->req->args};
102 my @parts = split('/', $path);
104 my ($chain, $captures, $parts) = $self->recurse_match($c, '/', \@parts);
105 push @{$c->req->args}, @$parts if $parts && @$parts;
107 return 0 unless $chain;
109 my $action = Catalyst::ActionChain->from_chain($chain);
111 $c->req->action("/${action}");
112 $c->req->match("/${action}");
113 $c->req->captures($captures);
115 $c->namespace( $action->namespace );
120 =head2 $self->recurse_match( $c, $parent, \@path_parts )
122 Recursive search for a matching chain.
127 my ( $self, $c, $parent, $path_parts ) = @_;
128 my $children = $self->{children_of}{$parent};
129 return () unless $children;
132 TRY: foreach my $try_part (sort { length($b) <=> length($a) }
134 # $b then $a to try longest part first
135 my @parts = @$path_parts;
136 if (length $try_part) { # test and strip PathPart
138 ($try_part eq join('/', # assemble equal number of parts
139 splice( # and strip them off @parts as well
140 @parts, 0, scalar(@{[split('/', $try_part)]})
141 ))); # @{[]} to avoid split to @_
143 my @try_actions = @{$children->{$try_part}};
144 TRY_ACTION: foreach my $action (@try_actions) {
145 if (my $capture_attr = $action->attributes->{CaptureArgs}) {
147 # Short-circuit if not enough remaining parts
148 next TRY_ACTION unless @parts >= $capture_attr->[0];
151 my @parts = @parts; # localise
153 # strip CaptureArgs into list
154 push(@captures, splice(@parts, 0, $capture_attr->[0]));
156 # try the remaining parts against children of this action
157 my ($actions, $captures, $action_parts) = $self->recurse_match(
158 $c, '/'.$action->reverse, \@parts
160 if ($actions && (!$best_action || $#$action_parts < $#{$best_action->{parts}})){
162 actions => [ $action, @$actions ],
163 captures=> [ @captures, @$captures ],
164 parts => $action_parts
170 local $c->req->{arguments} = [ @{$c->req->args}, @parts ];
171 next TRY_ACTION unless $action->match($c);
173 my $args_attr = $action->attributes->{Args}->[0];
175 # No best action currently
176 # OR This one matches with fewer parts left than the current best action,
177 # And therefore is a better match
178 # OR No parts and this expects 0
179 # The current best action might also be Args(0),
180 # but we couldn't chose between then anyway so we'll take the last seen
183 @parts < @{$best_action->{parts}} ||
184 (!@parts && $args_attr eq 0)){
186 actions => [ $action ],
194 return @$best_action{qw/actions captures parts/} if $best_action;
198 =head2 $self->register( $c, $action )
200 Calls register_path for every Path attribute for the given $action.
205 my ( $self, $c, $action ) = @_;
207 my @chained_attr = @{ $action->attributes->{Chained} || [] };
209 return 0 unless @chained_attr;
211 if (@chained_attr > 1) {
212 Catalyst::Exception->throw(
213 "Multiple Chained attributes not supported registering ${action}"
217 my $parent = $chained_attr[0];
219 if (defined($parent) && length($parent)) {
220 if ($parent eq '.') {
221 $parent = '/'.$action->namespace;
222 } elsif ($parent !~ m/^\//) {
223 if ($action->namespace) {
224 $parent = '/'.join('/', $action->namespace, $parent);
226 $parent = '/'.$parent; # special case namespace '' (root)
233 $action->attributes->{Chained} = [ $parent ];
235 my $children = ($self->{children_of}{$parent} ||= {});
237 my @path_part = @{ $action->attributes->{PathPart} || [] };
239 my $part = $action->name;
241 if (@path_part == 1 && defined $path_part[0]) {
242 $part = $path_part[0];
243 } elsif (@path_part > 1) {
244 Catalyst::Exception->throw(
245 "Multiple PathPart attributes not supported registering ${action}"
249 if ($part =~ m(^/)) {
250 Catalyst::Exception->throw(
251 "Absolute parameters to PathPart not allowed registering ${action}"
255 $action->attributes->{PartPath} = [ $part ];
257 unshift(@{ $children->{$part} ||= [] }, $action);
259 ($self->{actions} ||= {})->{'/'.$action->reverse} = $action;
261 unless ($action->attributes->{CaptureArgs}) {
262 unshift(@{ $self->{endpoints} ||= [] }, $action);
268 =head2 $self->uri_for_action($action, $captures)
270 Get the URI part for the action, using C<$captures> to fill
276 my ( $self, $action, $captures ) = @_;
278 return undef unless ($action->attributes->{Chained}
279 && !$action->attributes->{CaptureArgs});
282 my @captures = @$captures;
283 my $parent = "DUMMY";
286 if (my $cap = $curr->attributes->{CaptureArgs}) {
287 return undef unless @captures >= $cap->[0]; # not enough captures
289 unshift(@parts, splice(@captures, -$cap->[0]));
292 if (my $pp = $curr->attributes->{PartPath}) {
293 unshift(@parts, $pp->[0])
294 if (defined($pp->[0]) && length($pp->[0]));
296 $parent = $curr->attributes->{Chained}->[0];
297 $curr = $self->{actions}{$parent};
300 return undef unless $parent eq '/'; # fail for dangling action
302 return undef if @captures; # fail for too many captures
304 return join('/', '', @parts);
312 The C<Chained> attribute allows you to chain public path parts together
313 by their private names. A chain part's path can be specified with
314 C<PathPart> and can be declared to expect an arbitrary number of
315 arguments. The endpoint of the chain specifies how many arguments it
316 gets through the C<Args> attribute. C<:Args(0)> would be none at all,
317 C<:Args> without an integer would be unlimited. The path parts that
318 aren't endpoints are using C<CaptureArgs> to specify how many parameters
319 they expect to receive. As an example setup:
321 package MyApp::Controller::Greeting;
322 use base qw/ Catalyst::Controller /;
324 # this is the beginning of our chain
325 sub hello : PathPart('hello') Chained('/') CaptureArgs(1) {
326 my ( $self, $c, $integer ) = @_;
327 $c->stash->{ message } = "Hello ";
328 $c->stash->{ arg_sum } = $integer;
331 # this is our endpoint, because it has no :CaptureArgs
332 sub world : PathPart('world') Chained('hello') Args(1) {
333 my ( $self, $c, $integer ) = @_;
334 $c->stash->{ message } .= "World!";
335 $c->stash->{ arg_sum } += $integer;
337 $c->response->body( join "<br/>\n" =>
338 $c->stash->{ message }, $c->stash->{ arg_sum } );
341 The debug output provides a separate table for chained actions, showing
342 the whole chain as it would match and the actions it contains. Here's an
343 example of the startup output with our actions above:
346 [debug] Loaded Path Part actions:
347 .-----------------------+------------------------------.
348 | Path Spec | Private |
349 +-----------------------+------------------------------+
350 | /hello/*/world/* | /greeting/hello (1) |
351 | | => /greeting/world |
352 '-----------------------+------------------------------'
355 As you can see, Catalyst only deals with chains as whole paths and
356 builds one for each endpoint, which are the actions with C<:Chained> but
357 without C<:CaptureArgs>.
359 Let's assume this application gets a request at the path
360 C</hello/23/world/12>. What happens then? First, Catalyst will dispatch
361 to the C<hello> action and pass the value C<23> as an argument to it
362 after the context. It does so because we have previously used
363 C<:CaptureArgs(1)> to declare that it has one path part after itself as
364 its argument. We told Catalyst that this is the beginning of the chain
365 by specifying C<:Chained('/')>. Also note that instead of saying
366 C<:PathPart('hello')> we could also just have said C<:PathPart>, as it
367 defaults to the name of the action.
369 After C<hello> has run, Catalyst goes on to dispatch to the C<world>
370 action. This is the last action to be called: Catalyst knows this is an
371 endpoint because we did not specify a C<:CaptureArgs>
372 attribute. Nevertheless we specify that this action expects an argument,
373 but at this point we're using C<:Args(1)> to do that. We could also have
374 said C<:Args> or left it out altogether, which would mean this action
375 would get all arguments that are there. This action's C<:Chained>
376 attribute says C<hello> and tells Catalyst that the C<hello> action in
377 the current controller is its parent.
379 With this we have built a chain consisting of two public path parts.
380 C<hello> captures one part of the path as its argument, and also
381 specifies the path root as its parent. So this part is
382 C</hello/$arg>. The next part is the endpoint C<world>, expecting one
383 argument. It sums up to the path part C<world/$arg>. This leads to a
384 complete chain of C</hello/$arg/world/$arg> which is matched against the
387 This example application would, if run and called by e.g.
388 C</hello/23/world/12>, set the stash value C<message> to "Hello" and the
389 value C<arg_sum> to "23". The C<world> action would then append "World!"
390 to C<message> and add C<12> to the stash's C<arg_sum> value. For the
391 sake of simplicity no view is shown. Instead we just put the values of
392 the stash into our body. So the output would look like:
397 And our test server would have given us this debugging output for the
401 [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
402 [debug] Path is "/greeting/world"
403 [debug] Arguments are "12"
404 [info] Request took 0.164113s (6.093/s)
405 .------------------------------------------+-----------.
407 +------------------------------------------+-----------+
408 | /greeting/hello | 0.000029s |
409 | /greeting/world | 0.000024s |
410 '------------------------------------------+-----------'
413 What would be common uses of this dispatch technique? It gives the
414 possibility to split up logic that contains steps that each depend on
415 each other. An example would be, for example, a wiki path like
416 C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
419 sub wiki : PathPart('wiki') Chained('/') CaptureArgs(1) {
420 my ( $self, $c, $page_name ) = @_;
421 # load the page named $page_name and put the object
425 sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) {
426 my ( $self, $c, $revision_id ) = @_;
427 # use the page object in the stash to get at its
428 # revision with number $revision_id
431 sub view : PathPart Chained('rev') Args(0) {
432 my ( $self, $c ) = @_;
433 # display the revision in our stash. Another option
434 # would be to forward a compatible object to the action
435 # that displays the default wiki pages, unless we want
436 # a different interface here, for example restore
440 It would now be possible to add other endpoints, for example C<restore>
441 to restore this specific revision as the current state.
443 You don't have to put all the chained actions in one controller. The
444 specification of the parent through C<:Chained> also takes an absolute
445 action path as its argument. Just specify it with a leading C</>.
447 If you want, for example, to have actions for the public paths
448 C</foo/12/edit> and C</foo/12>, just specify two actions with
449 C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
450 path needs a C<:CaptureArgs(1)> attribute and a endpoint with
451 C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
452 the action just a C<:Args(1)> to mark it as endpoint. This sums up to
453 this debugging output:
456 [debug] Loaded Path Part actions:
457 .-----------------------+------------------------------.
458 | Path Spec | Private |
459 +-----------------------+------------------------------+
460 | /foo/* | /controller/foo_view |
461 | /foo/*/edit | /controller/foo_load (1) |
462 | | => /controller/edit |
463 '-----------------------+------------------------------'
466 Here's a more detailed specification of the attributes belonging to
475 Sets the name of this part of the chain. If it is specified without
476 arguments, it takes the name of the action as default. So basically
477 C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
478 This can also contain slashes to bind to a deeper level. An action
479 with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
480 C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
481 effect as using C<:PathPart>, it would default to the action name.
485 Has to be specified for every child in the chain. Possible values are
486 absolute and relative private action paths, with the relatives pointing
487 to the current controller, or a single slash C</> to tell Catalyst that
488 this is the root of a chain. The attribute C<:Chained> without arguments
489 also defaults to the C</> behavior.
491 Because you can specify an absolute path to the parent action, it
492 doesn't matter to Catalyst where that parent is located. So, if your
493 design requests it, you can redispatch a chain through any controller or
496 Another interesting possibility gives C<:Chained('.')>, which chains
497 itself to an action with the path of the current controller's namespace.
500 # in MyApp::Controller::Foo
501 sub bar : Chained CaptureArgs(1) { ... }
503 # in MyApp::Controller::Foo::Bar
504 sub baz : Chained('.') Args(1) { ... }
506 This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
507 as the argument to Chained here chains the C<baz> action to an action
508 with the path of the current controller namespace, namely
509 C</foo/bar>. That action chains directly to C</>, so the C</bar/*/baz/*>
510 chain comes out as the end product.
514 Must be specified for every part of the chain that is not an
515 endpoint. With this attribute Catalyst knows how many of the following
516 parts of the path (separated by C</>) this action wants to capture as
517 its arguments. If it doesn't expect any, just specify
518 C<:CaptureArgs(0)>. The captures get passed to the action's C<@_> right
519 after the context, but you can also find them as array references in
520 C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
521 level of the action in the chain that captured the parts of the path.
523 An action that is part of a chain (that is, one that has a C<:Chained>
524 attribute) but has no C<:CaptureArgs> attribute is treated by Catalyst
529 By default, endpoints receive the rest of the arguments in the path. You
530 can tell Catalyst through C<:Args> explicitly how many arguments your
531 endpoint expects, just like you can with C<:CaptureArgs>. Note that this
532 also affects whether this chain is invoked on a request. A chain with an
533 endpoint specifying one argument will only match if exactly one argument
536 You can specify an exact number of arguments like C<:Args(3)>, including
537 C<0>. If you just say C<:Args> without any arguments, it is the same as
538 leaving it out altogether: The chain is matched regardless of the number
539 of path parts after the endpoint.
541 Just as with C<:CaptureArgs>, the arguments get passed to the action in
542 C<@_> after the context object. They can also be reached through
543 C<$c-E<gt>request-E<gt>arguments>.
547 =head2 Auto actions, dispatching and forwarding
549 Note that the list of C<auto> actions called depends on the private path
550 of the endpoint of the chain, not on the chained actions way. The
551 C<auto> actions will be run before the chain dispatching begins. In
552 every other aspect, C<auto> actions behave as documented.
554 The C<forward>ing to other actions does just what you would expect. But if
555 you C<detach> out of a chain, the rest of the chain will not get called
560 Matt S Trout <mst@shadowcatsystems.co.uk>
564 This program is free software, you can redistribute it and/or modify it under
565 the same terms as Perl itself.