lib/Catalyst/DispatchType/Chained.pm

   1 package Catalyst::DispatchType::Chained;
   2
   3 use Moose;
   4 extends 'Catalyst::DispatchType';
   5
   6 use Text::SimpleTable;
   7 use Catalyst::ActionChain;
   8 use Catalyst::Utils;
   9 use URI;
  10 use Scalar::Util ();
  11 use Encode 2.21 'decode_utf8';
  12
  13 has _endpoints => (
  14                    is => 'rw',
  15                    isa => 'ArrayRef',
  16                    required => 1,
  17                    default => sub{ [] },
  18                   );
  19
  20 has _actions => (
  21                  is => 'rw',
  22                  isa => 'HashRef',
  23                  required => 1,
  24                  default => sub{ {} },
  25                 );
  26
  27 has _children_of => (
  28                      is => 'rw',
  29                      isa => 'HashRef',
  30                      required => 1,
  31                      default => sub{ {} },
  32                     );
  33
  34 no Moose;
  35
  36 # please don't perltidy this. hairy code within.
  37
  38 =head1 NAME
  39
  40 Catalyst::DispatchType::Chained - Path Part DispatchType
  41
  42 =head1 SYNOPSIS
  43
  44 Path part matching, allowing several actions to sequentially take care of processing a request:
  45
  46   #   root action - captures one argument after it
  47   sub foo_setup : Chained('/') PathPart('foo') CaptureArgs(1) {
  48       my ( $self, $c, $foo_arg ) = @_;
  49       ...
  50   }
  51
  52   #   child action endpoint - takes one argument
  53   sub bar : Chained('foo_setup') Args(1) {
  54       my ( $self, $c, $bar_arg ) = @_;
  55       ...
  56   }
  57
  58 =head1 DESCRIPTION
  59
  60 Dispatch type managing default behaviour.  For more information on
  61 dispatch types, see:
  62
  63 =over 4
  64
  65 =item * L<Catalyst::Manual::Intro> for how they affect application authors
  66
  67 =item * L<Catalyst::DispatchType> for implementation information.
  68
  69 =back
  70
  71 =head1 METHODS
  72
  73 =head2 $self->list($c)
  74
  75 Debug output for Path Part dispatch points
  76
  77 =cut
  78
  79 sub list {
  80     my ( $self, $c ) = @_;
  81
  82     return unless $self->_endpoints;
  83
  84     my $avail_width = Catalyst::Utils::term_width() - 9;
  85     my $col1_width = ($avail_width * .50) < 35 ? 35 : int($avail_width * .50);
  86     my $col2_width = $avail_width - $col1_width;
  87     my $paths = Text::SimpleTable->new(
  88         [ $col1_width, 'Path Spec' ], [ $col2_width, 'Private' ],
  89     );
  90
  91     my $has_unattached_actions;
  92     my $unattached_actions = Text::SimpleTable->new(
  93         [ $col1_width, 'Private' ], [ $col2_width, 'Missing parent' ],
  94     );
  95
  96     ENDPOINT: foreach my $endpoint (
  97                   sort { $a->reverse cmp $b->reverse }
  98                            @{ $self->_endpoints }
  99                   ) {
 100         my $args = $endpoint->list_extra_info->{Args};
 101         my @parts = (defined($args) ? (("*") x $args) : '...');
 102         my @parents = ();
 103         my $parent = "DUMMY";
 104         my $extra  = $self->_list_extra_http_methods($endpoint);
 105         my $consumes = $self->_list_extra_consumes($endpoint);
 106         my $curr = $endpoint;
 107         while ($curr) {
 108             if (my $cap = $curr->list_extra_info->{CaptureArgs}) {
 109                 unshift(@parts, (("*") x $cap));
 110             }
 111             if (my $pp = $curr->attributes->{PathPart}) {
 112                 unshift(@parts, $pp->[0])
 113                     if (defined $pp->[0] && length $pp->[0]);
 114             }
 115             $parent = $curr->attributes->{Chained}->[0];
 116             $curr = $self->_actions->{$parent};
 117             unshift(@parents, $curr) if $curr;
 118         }
 119         if ($parent ne '/') {
 120             $has_unattached_actions = 1;
 121             $unattached_actions->row('/' . ($parents[0] || $endpoint)->reverse, $parent);
 122             next ENDPOINT;
 123         }
 124         my @rows;
 125         foreach my $p (@parents) {
 126             my $name = "/${p}";
 127
 128             if (defined(my $extra = $self->_list_extra_http_methods($p))) {
 129                 $name = "${extra} ${name}";
 130             }
 131             if (defined(my $cap = $p->list_extra_info->{CaptureArgs})) {
 132                 $name .= ' ('.$cap.')';
 133             }
 134             if (defined(my $ct = $p->list_extra_info->{Consumes})) {
 135                 $name .= ' :'.$ct;
 136             }
 137
 138             unless ($p eq $parents[0]) {
 139                 $name = "-> ${name}";
 140             }
 141             push(@rows, [ '', $name ]);
 142         }
 143         push(@rows, [ '', (@rows ? "=> " : '').($extra ? "$extra " : '')."/${endpoint}". ($consumes ? " :$consumes":"" ) ]);
 144         my @display_parts = map { $_ =~s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg; decode_utf8 $_ } @parts;
 145         $rows[0][0] = join('/', '', @display_parts) || '/';
 146         $paths->row(@$_) for @rows;
 147     }
 148
 149     $c->log->debug( "Loaded Chained actions:\n" . $paths->draw . "\n" );
 150     $c->log->debug( "Unattached Chained actions:\n", $unattached_actions->draw . "\n" )
 151         if $has_unattached_actions;
 152 }
 153
 154 sub _list_extra_http_methods {
 155     my ( $self, $action ) = @_;
 156     return unless defined $action->list_extra_info->{HTTP_METHODS};
 157     return join(', ', @{$action->list_extra_info->{HTTP_METHODS}});
 158
 159 }
 160
 161 sub _list_extra_consumes {
 162     my ( $self, $action ) = @_;
 163     return unless defined $action->list_extra_info->{CONSUMES};
 164     return join(', ', @{$action->list_extra_info->{CONSUMES}});
 165 }
 166
 167
 168 =head2 $self->match( $c, $path )
 169
 170 Calls C<recurse_match> to see if a chain matches the C<$path>.
 171
 172 =cut
 173
 174 sub match {
 175     my ( $self, $c, $path ) = @_;
 176
 177     my $request = $c->request;
 178     return 0 if @{$request->args};
 179
 180     my @parts = split('/', $path);
 181
 182     my ($chain, $captures, $parts) = $self->recurse_match($c, '/', \@parts);
 183
 184     if ($parts && @$parts) {
 185         for my $arg (@$parts) {
 186             $arg =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
 187             push @{$request->args}, $arg;
 188         }
 189     }
 190
 191     return 0 unless $chain;
 192
 193     my $action = Catalyst::ActionChain->from_chain($chain);
 194
 195     $request->action("/${action}");
 196     $request->match("/${action}");
 197     $request->captures($captures);
 198     $c->action($action);
 199     $c->namespace( $action->namespace );
 200
 201     return 1;
 202 }
 203
 204 =head2 $self->recurse_match( $c, $parent, \@path_parts )
 205
 206 Recursive search for a matching chain.
 207
 208 =cut
 209
 210 sub recurse_match {
 211     my ( $self, $c, $parent, $path_parts ) = @_;
 212     my $children = $self->_children_of->{$parent};
 213     return () unless $children;
 214     my $best_action;
 215     my @captures;
 216     TRY: foreach my $try_part (sort { length($b) <=> length($a) }
 217                                    keys %$children) {
 218                                # $b then $a to try longest part first
 219         my @parts = @$path_parts;
 220         if (length $try_part) { # test and strip PathPart
 221             next TRY unless
 222               ($try_part eq join('/', # assemble equal number of parts
 223                               splice( # and strip them off @parts as well
 224                                 @parts, 0, scalar(@{[split('/', $try_part)]})
 225                               ))); # @{[]} to avoid split to @_
 226         }
 227         my @try_actions = @{$children->{$try_part}};
 228         TRY_ACTION: foreach my $action (@try_actions) {
 229             if (my $capture_attr = $action->attributes->{CaptureArgs}) {
 230                 my $capture_count = $capture_attr->[0] || 0;
 231
 232                 # Short-circuit if not enough remaining parts
 233                 next TRY_ACTION unless @parts >= $capture_count;
 234
 235                 my @captures;
 236                 my @parts = @parts; # localise
 237
 238                 # strip CaptureArgs into list
 239                 push(@captures, splice(@parts, 0, $capture_count));
 240
 241                 # check if the action may fit, depending on a given test by the app
 242                 if ($action->can('match_captures')) { next TRY_ACTION unless $action->match_captures($c, \@captures) }
 243
 244                 # try the remaining parts against children of this action
 245                 my ($actions, $captures, $action_parts, $n_pathparts) = $self->recurse_match(
 246                                              $c, '/'.$action->reverse, \@parts
 247                                            );
 248                 #    No best action currently
 249                 # OR The action has less parts
 250                 # OR The action has equal parts but less captured data (ergo more defined)
 251                 if ($actions    &&
 252                     (!$best_action                                 ||
 253                      $#$action_parts < $#{$best_action->{parts}}   ||
 254                      ($#$action_parts == $#{$best_action->{parts}} &&
 255                       $#$captures < $#{$best_action->{captures}} &&
 256                       $n_pathparts > $best_action->{n_pathparts}))) {
 257                     my @pathparts = split /\//, $action->attributes->{PathPart}->[0];
 258                     $best_action = {
 259                         actions => [ $action, @$actions ],
 260                         captures=> [ @captures, @$captures ],
 261                         parts   => $action_parts,
 262                         n_pathparts => scalar(@pathparts) + $n_pathparts,
 263                     };
 264                 }
 265             }
 266             else {
 267                 {
 268                     local $c->req->{arguments} = [ @{$c->req->args}, @parts ];
 269                     next TRY_ACTION unless $action->match($c);
 270                 }
 271                 my $args_attr = $action->attributes->{Args}->[0];
 272                 my @pathparts = split /\//, $action->attributes->{PathPart}->[0];
 273                 #    No best action currently
 274                 # OR This one matches with fewer parts left than the current best action,
 275                 #    And therefore is a better match
 276                 # OR No parts and this expects 0
 277                 #    The current best action might also be Args(0),
 278                 #    but we couldn't chose between then anyway so we'll take the last seen
 279
 280                 if (!$best_action                       ||
 281                     @parts < @{$best_action->{parts}}   ||
 282                     (!@parts && defined($args_attr) && $args_attr eq "0")){
 283                     $best_action = {
 284                         actions => [ $action ],
 285                         captures=> [],
 286                         parts   => \@parts,
 287                         n_pathparts => scalar(@pathparts),
 288                     };
 289                 }
 290             }
 291         }
 292     }
 293     return @$best_action{qw/actions captures parts n_pathparts/} if $best_action;
 294     return ();
 295 }
 296
 297 =head2 $self->register( $c, $action )
 298
 299 Calls register_path for every Path attribute for the given $action.
 300
 301 =cut
 302
 303 sub _check_args_attr {
 304     my ( $self, $action, $name ) = @_;
 305
 306     return unless exists $action->attributes->{$name};
 307
 308     if (@{$action->attributes->{$name}} > 1) {
 309         Catalyst::Exception->throw(
 310           "Multiple $name attributes not supported registering " . $action->reverse()
 311         );
 312     }
 313     my $args = $action->attributes->{$name}->[0];
 314     if (defined($args) and not (
 315         Scalar::Util::looks_like_number($args) and
 316         int($args) == $args and $args >= 0
 317     )) {
 318         require Data::Dumper;
 319         local $Data::Dumper::Terse = 1;
 320         local $Data::Dumper::Indent = 0;
 321         $args = Data::Dumper::Dumper($args);
 322         Catalyst::Exception->throw(
 323           "Invalid $name($args) for action " . $action->reverse() .
 324           " (use '$name' or '$name(<number>)')"
 325         );
 326     }
 327 }
 328
 329 sub register {
 330     my ( $self, $c, $action ) = @_;
 331
 332     my @chained_attr = @{ $action->attributes->{Chained} || [] };
 333
 334     return 0 unless @chained_attr;
 335
 336     if (@chained_attr > 1) {
 337         Catalyst::Exception->throw(
 338           "Multiple Chained attributes not supported registering ${action}"
 339         );
 340     }
 341     my $chained_to = $chained_attr[0];
 342
 343     Catalyst::Exception->throw(
 344       "Actions cannot chain to themselves registering /${action}"
 345     ) if ($chained_to eq '/' . $action);
 346
 347     my $children = ($self->_children_of->{ $chained_to } ||= {});
 348
 349     my @path_part = @{ $action->attributes->{PathPart} || [] };
 350
 351     my $part = $action->name;
 352
 353     if (@path_part == 1 && defined $path_part[0]) {
 354         $part = $path_part[0];
 355     } elsif (@path_part > 1) {
 356         Catalyst::Exception->throw(
 357           "Multiple PathPart attributes not supported registering " . $action->reverse()
 358         );
 359     }
 360
 361     if ($part =~ m(^/)) {
 362         Catalyst::Exception->throw(
 363           "Absolute parameters to PathPart not allowed registering " . $action->reverse()
 364         );
 365     }
 366
 367     my $encoded_part = URI->new($part)->canonical;
 368     $encoded_part =~ s{(?<=[^/])/+\z}{};
 369
 370     $action->attributes->{PathPart} = [ $encoded_part ];
 371
 372     unshift(@{ $children->{$encoded_part} ||= [] }, $action);
 373
 374     $self->_actions->{'/'.$action->reverse} = $action;
 375
 376     foreach my $name (qw(Args CaptureArgs)) {
 377         $self->_check_args_attr($action, $name);
 378     }
 379
 380     if (exists $action->attributes->{Args} and exists $action->attributes->{CaptureArgs}) {
 381         Catalyst::Exception->throw(
 382           "Combining Args and CaptureArgs attributes not supported registering " .
 383           $action->reverse()
 384         );
 385     }
 386
 387     unless ($action->attributes->{CaptureArgs}) {
 388         unshift(@{ $self->_endpoints }, $action);
 389     }
 390
 391     return 1;
 392 }
 393
 394 =head2 $self->uri_for_action($action, $captures)
 395
 396 Get the URI part for the action, using C<$captures> to fill
 397 the capturing parts.
 398
 399 =cut
 400
 401 sub uri_for_action {
 402     my ( $self, $action, $captures ) = @_;
 403
 404     return undef unless ($action->attributes->{Chained}
 405                            && !$action->attributes->{CaptureArgs});
 406
 407     my @parts = ();
 408     my @captures = @$captures;
 409     my $parent = "DUMMY";
 410     my $curr = $action;
 411     while ($curr) {
 412         if (my $cap = $curr->attributes->{CaptureArgs}) {
 413             return undef unless @captures >= ($cap->[0]||0); # not enough captures
 414             if ($cap->[0]) {
 415                 unshift(@parts, splice(@captures, -$cap->[0]));
 416             }
 417         }
 418         if (my $pp = $curr->attributes->{PathPart}) {
 419             unshift(@parts, $pp->[0])
 420                 if (defined($pp->[0]) && length($pp->[0]));
 421         }
 422         $parent = $curr->attributes->{Chained}->[0];
 423         $curr = $self->_actions->{$parent};
 424     }
 425
 426     return undef unless $parent eq '/'; # fail for dangling action
 427
 428     return undef if @captures; # fail for too many captures
 429
 430     return join('/', '', @parts);
 431
 432 }
 433
 434 =head2 $c->expand_action($action)
 435
 436 Return a list of actions that represents a chained action. See
 437 L<Catalyst::Dispatcher> for more info. You probably want to
 438 use the expand_action it provides rather than this directly.
 439
 440 =cut
 441
 442 sub expand_action {
 443     my ($self, $action) = @_;
 444
 445     return unless $action->attributes && $action->attributes->{Chained};
 446
 447     my @chain;
 448     my $curr = $action;
 449
 450     while ($curr) {
 451         push @chain, $curr;
 452         my $parent = $curr->attributes->{Chained}->[0];
 453         $curr = $self->_actions->{$parent};
 454     }
 455
 456     return Catalyst::ActionChain->from_chain([reverse @chain]);
 457 }
 458
 459 __PACKAGE__->meta->make_immutable;
 460 1;
 461
 462 =head1 USAGE
 463
 464 =head2 Introduction
 465
 466 The C<Chained> attribute allows you to chain public path parts together
 467 by their private names. A chain part's path can be specified with
 468 C<PathPart> and can be declared to expect an arbitrary number of
 469 arguments. The endpoint of the chain specifies how many arguments it
 470 gets through the C<Args> attribute. C<:Args(0)> would be none at all,
 471 C<:Args> without an integer would be unlimited. The path parts that
 472 aren't endpoints are using C<CaptureArgs> to specify how many parameters
 473 they expect to receive. As an example setup:
 474
 475   package MyApp::Controller::Greeting;
 476   use base qw/ Catalyst::Controller /;
 477
 478   #   this is the beginning of our chain
 479   sub hello : PathPart('hello') Chained('/') CaptureArgs(1) {
 480       my ( $self, $c, $integer ) = @_;
 481       $c->stash->{ message } = "Hello ";
 482       $c->stash->{ arg_sum } = $integer;
 483   }
 484
 485   #   this is our endpoint, because it has no :CaptureArgs
 486   sub world : PathPart('world') Chained('hello') Args(1) {
 487       my ( $self, $c, $integer ) = @_;
 488       $c->stash->{ message } .= "World!";
 489       $c->stash->{ arg_sum } += $integer;
 490
 491       $c->response->body( join "<br/>\n" =>
 492           $c->stash->{ message }, $c->stash->{ arg_sum } );
 493   }
 494
 495 The debug output provides a separate table for chained actions, showing
 496 the whole chain as it would match and the actions it contains. Here's an
 497 example of the startup output with our actions above:
 498
 499   ...
 500   [debug] Loaded Path Part actions:
 501   .-----------------------+------------------------------.
 502   | Path Spec             | Private                      |
 503   +-----------------------+------------------------------+
 504   | /hello/*/world/*      | /greeting/hello (1)          |
 505   |                       | => /greeting/world           |
 506   '-----------------------+------------------------------'
 507   ...
 508
 509 As you can see, Catalyst only deals with chains as whole paths and
 510 builds one for each endpoint, which are the actions with C<:Chained> but
 511 without C<:CaptureArgs>.
 512
 513 Let's assume this application gets a request at the path
 514 C</hello/23/world/12>. What happens then? First, Catalyst will dispatch
 515 to the C<hello> action and pass the value C<23> as an argument to it
 516 after the context. It does so because we have previously used
 517 C<:CaptureArgs(1)> to declare that it has one path part after itself as
 518 its argument. We told Catalyst that this is the beginning of the chain
 519 by specifying C<:Chained('/')>. Also note that instead of saying
 520 C<:PathPart('hello')> we could also just have said C<:PathPart>, as it
 521 defaults to the name of the action.
 522
 523 After C<hello> has run, Catalyst goes on to dispatch to the C<world>
 524 action. This is the last action to be called: Catalyst knows this is an
 525 endpoint because we did not specify a C<:CaptureArgs>
 526 attribute. Nevertheless we specify that this action expects an argument,
 527 but at this point we're using C<:Args(1)> to do that. We could also have
 528 said C<:Args> or left it out altogether, which would mean this action
 529 would get all arguments that are there. This action's C<:Chained>
 530 attribute says C<hello> and tells Catalyst that the C<hello> action in
 531 the current controller is its parent.
 532
 533 With this we have built a chain consisting of two public path parts.
 534 C<hello> captures one part of the path as its argument, and also
 535 specifies the path root as its parent. So this part is
 536 C</hello/$arg>. The next part is the endpoint C<world>, expecting one
 537 argument. It sums up to the path part C<world/$arg>. This leads to a
 538 complete chain of C</hello/$arg/world/$arg> which is matched against the
 539 requested paths.
 540
 541 This example application would, if run and called by e.g.
 542 C</hello/23/world/12>, set the stash value C<message> to "Hello" and the
 543 value C<arg_sum> to "23". The C<world> action would then append "World!"
 544 to C<message> and add C<12> to the stash's C<arg_sum> value.  For the
 545 sake of simplicity no view is shown. Instead we just put the values of
 546 the stash into our body. So the output would look like:
 547
 548   Hello World!
 549   35
 550
 551 And our test server would have given us this debugging output for the
 552 request:
 553
 554   ...
 555   [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
 556   [debug] Path is "/greeting/world"
 557   [debug] Arguments are "12"
 558   [info] Request took 0.164113s (6.093/s)
 559   .------------------------------------------+-----------.
 560   | Action                                   | Time      |
 561   +------------------------------------------+-----------+
 562   | /greeting/hello                          | 0.000029s |
 563   | /greeting/world                          | 0.000024s |
 564   '------------------------------------------+-----------'
 565   ...
 566
 567 What would be common uses of this dispatch technique? It gives the
 568 possibility to split up logic that contains steps that each depend on
 569 each other. An example would be, for example, a wiki path like
 570 C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
 571 these actions:
 572
 573   sub wiki : PathPart('wiki') Chained('/') CaptureArgs(1) {
 574       my ( $self, $c, $page_name ) = @_;
 575       #  load the page named $page_name and put the object
 576       #  into the stash
 577   }
 578
 579   sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) {
 580       my ( $self, $c, $revision_id ) = @_;
 581       #  use the page object in the stash to get at its
 582       #  revision with number $revision_id
 583   }
 584
 585   sub view : PathPart Chained('rev') Args(0) {
 586       my ( $self, $c ) = @_;
 587       #  display the revision in our stash. Another option
 588       #  would be to forward a compatible object to the action
 589       #  that displays the default wiki pages, unless we want
 590       #  a different interface here, for example restore
 591       #  functionality.
 592   }
 593
 594 It would now be possible to add other endpoints, for example C<restore>
 595 to restore this specific revision as the current state.
 596
 597 You don't have to put all the chained actions in one controller. The
 598 specification of the parent through C<:Chained> also takes an absolute
 599 action path as its argument. Just specify it with a leading C</>.
 600
 601 If you want, for example, to have actions for the public paths
 602 C</foo/12/edit> and C</foo/12>, just specify two actions with
 603 C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
 604 path needs a C<:CaptureArgs(1)> attribute and a endpoint with
 605 C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
 606 the action just a C<:Args(1)> to mark it as endpoint. This sums up to
 607 this debugging output:
 608
 609   ...
 610   [debug] Loaded Path Part actions:
 611   .-----------------------+------------------------------.
 612   | Path Spec             | Private                      |
 613   +-----------------------+------------------------------+
 614   | /foo/*                | /controller/foo_view         |
 615   | /foo/*/edit           | /controller/foo_load (1)     |
 616   |                       | => /controller/edit          |
 617   '-----------------------+------------------------------'
 618   ...
 619
 620 Here's a more detailed specification of the attributes belonging to
 621 C<:Chained>:
 622
 623 =head2 Attributes
 624
 625 =over 8
 626
 627 =item PathPart
 628
 629 Sets the name of this part of the chain. If it is specified without
 630 arguments, it takes the name of the action as default. So basically
 631 C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
 632 This can also contain slashes to bind to a deeper level. An action
 633 with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
 634 C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
 635 effect as using C<:PathPart>, it would default to the action name.
 636
 637 =item PathPrefix
 638
 639 Sets PathPart to the path_prefix of the current controller.
 640
 641 =item Chained
 642
 643 Has to be specified for every child in the chain. Possible values are
 644 absolute and relative private action paths or a single slash C</> to
 645 tell Catalyst that this is the root of a chain. The attribute
 646 C<:Chained> without arguments also defaults to the C</> behavior.
 647 Relative action paths may use C<../> to refer to actions in parent
 648 controllers.
 649
 650 Because you can specify an absolute path to the parent action, it
 651 doesn't matter to Catalyst where that parent is located. So, if your
 652 design requests it, you can redispatch a chain through any controller or
 653 namespace you want.
 654
 655 Another interesting possibility gives C<:Chained('.')>, which chains
 656 itself to an action with the path of the current controller's namespace.
 657 For example:
 658
 659   #   in MyApp::Controller::Foo
 660   sub bar : Chained CaptureArgs(1) { ... }
 661
 662   #   in MyApp::Controller::Foo::Bar
 663   sub baz : Chained('.') Args(1) { ... }
 664
 665 This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
 666 as the argument to Chained here chains the C<baz> action to an action
 667 with the path of the current controller namespace, namely
 668 C</foo/bar>. That action chains directly to C</>, so the C</bar/*/baz/*>
 669 chain comes out as the end product.
 670
 671 =item ChainedParent
 672
 673 Chains an action to another action with the same name in the parent
 674 controller. For Example:
 675
 676   # in MyApp::Controller::Foo
 677   sub bar : Chained CaptureArgs(1) { ... }
 678
 679   # in MyApp::Controller::Foo::Moo
 680   sub bar : ChainedParent Args(1) { ... }
 681
 682 This builds a chain like C</bar/*/bar/*>.
 683
 684 =item CaptureArgs
 685
 686 Must be specified for every part of the chain that is not an
 687 endpoint. With this attribute Catalyst knows how many of the following
 688 parts of the path (separated by C</>) this action wants to capture as
 689 its arguments. If it doesn't expect any, just specify
 690 C<:CaptureArgs(0)>.  The captures get passed to the action's C<@_> right
 691 after the context, but you can also find them as array references in
 692 C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
 693 level of the action in the chain that captured the parts of the path.
 694
 695 An action that is part of a chain (that is, one that has a C<:Chained>
 696 attribute) but has no C<:CaptureArgs> attribute is treated by Catalyst
 697 as a chain end.
 698
 699 =item Args
 700
 701 By default, endpoints receive the rest of the arguments in the path. You
 702 can tell Catalyst through C<:Args> explicitly how many arguments your
 703 endpoint expects, just like you can with C<:CaptureArgs>. Note that this
 704 also affects whether this chain is invoked on a request. A chain with an
 705 endpoint specifying one argument will only match if exactly one argument
 706 exists in the path.
 707
 708 You can specify an exact number of arguments like C<:Args(3)>, including
 709 C<0>. If you just say C<:Args> without any arguments, it is the same as
 710 leaving it out altogether: The chain is matched regardless of the number
 711 of path parts after the endpoint.
 712
 713 Just as with C<:CaptureArgs>, the arguments get passed to the action in
 714 C<@_> after the context object. They can also be reached through
 715 C<$c-E<gt>request-E<gt>arguments>.
 716
 717 =back
 718
 719 =head2 Auto actions, dispatching and forwarding
 720
 721 Note that the list of C<auto> actions called depends on the private path
 722 of the endpoint of the chain, not on the chained actions way. The
 723 C<auto> actions will be run before the chain dispatching begins. In
 724 every other aspect, C<auto> actions behave as documented.
 725
 726 The C<forward>ing to other actions does just what you would expect. i.e.
 727 only the target action is run. The actions that that action is chained
 728 to are not run.
 729 If you C<detach> out of a chain, the rest of the chain will not get
 730 called after the C<detach>.
 731
 732 =head2 match_captures
 733
 734 A method which can optionally be implemented by actions to
 735 stop chain matching.
 736
 737 See L<Catalyst::Action> for further details.
 738
 739 =head1 AUTHORS
 740
 741 Catalyst Contributors, see Catalyst.pm
 742
 743 =head1 COPYRIGHT
 744
 745 This library is free software. You can redistribute it and/or modify it under
 746 the same terms as Perl itself.
 747
 748 =cut
 749
 750 1;