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