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 @pathparts = split /\//, $action->attributes->{PathPart}->[0];
 294                 #    No best action currently
 295                 # OR This one matches with fewer parts left than the current best action,
 296                 #    And therefore is a better match
 297                 # OR No parts and this expects 0
 298                 #    The current best action might also be Args(0),
 299                 #    but we couldn't chose between then anyway so we'll take the last seen
 300
 301                 if (
 302                     !$best_action                       ||
 303                     @parts < @{$best_action->{parts}}   ||
 304                     (
 305                         !@parts &&
 306                         defined($args_attr) &&
 307                         (
 308                             $args_attr eq "0" &&
 309                             (
 310                               ($c->config->{use_chained_args_0_special_case}||0) ||
 311                                 (
 312                                   exists($best_action->{args_attr}) && defined($best_action->{args_attr}) ?
 313                                   ($best_action->{args_attr} ne 0) : 1
 314                                 )
 315                             )
 316                         )
 317                     )
 318                 ){
 319                     $best_action = {
 320                         actions => [ $action ],
 321                         captures=> [],
 322                         parts   => \@parts,
 323                         args_attr => $args_attr,
 324                         n_pathparts => scalar(@pathparts),
 325                     };
 326                 }
 327             }
 328         }
 329     }
 330     return @$best_action{qw/actions captures parts n_pathparts/} if $best_action;
 331     return ();
 332 }
 333
 334 =head2 $self->register( $c, $action )
 335
 336 Calls register_path for every Path attribute for the given $action.
 337
 338 =cut
 339
 340 sub register {
 341     my ( $self, $c, $action ) = @_;
 342
 343     my @chained_attr = @{ $action->attributes->{Chained} || [] };
 344
 345     return 0 unless @chained_attr;
 346
 347     if (@chained_attr > 1) {
 348         Catalyst::Exception->throw(
 349           "Multiple Chained attributes not supported registering ${action}"
 350         );
 351     }
 352     my $chained_to = $chained_attr[0];
 353
 354     Catalyst::Exception->throw(
 355       "Actions cannot chain to themselves registering /${action}"
 356     ) if ($chained_to eq '/' . $action);
 357
 358     my $children = ($self->_children_of->{ $chained_to } ||= {});
 359
 360     my @path_part = @{ $action->attributes->{PathPart} || [] };
 361
 362     my $part = $action->name;
 363
 364     if (@path_part == 1 && defined $path_part[0]) {
 365         $part = $path_part[0];
 366     } elsif (@path_part > 1) {
 367         Catalyst::Exception->throw(
 368           "Multiple PathPart attributes not supported registering " . $action->reverse()
 369         );
 370     }
 371
 372     if ($part =~ m(^/)) {
 373         Catalyst::Exception->throw(
 374           "Absolute parameters to PathPart not allowed registering " . $action->reverse()
 375         );
 376     }
 377
 378     my $encoded_part = URI->new($part)->canonical;
 379     $encoded_part =~ s{(?<=[^/])/+\z}{};
 380
 381     $action->attributes->{PathPart} = [ $encoded_part ];
 382
 383     unshift(@{ $children->{$encoded_part} ||= [] }, $action);
 384
 385     $self->_actions->{'/'.$action->reverse} = $action;
 386
 387     if (exists $action->attributes->{Args} and exists $action->attributes->{CaptureArgs}) {
 388         Catalyst::Exception->throw(
 389           "Combining Args and CaptureArgs attributes not supported registering " .
 390           $action->reverse()
 391         );
 392     }
 393
 394     unless ($action->attributes->{CaptureArgs}) {
 395         unshift(@{ $self->_endpoints }, $action);
 396     }
 397
 398     return 1;
 399 }
 400
 401 =head2 $self->uri_for_action($action, $captures)
 402
 403 Get the URI part for the action, using C<$captures> to fill
 404 the capturing parts.
 405
 406 =cut
 407
 408 sub uri_for_action {
 409     my ( $self, $action, $captures ) = @_;
 410
 411     return undef unless ($action->attributes->{Chained}
 412                            && !$action->attributes->{CaptureArgs});
 413
 414     my @parts = ();
 415     my @captures = @$captures;
 416     my $parent = "DUMMY";
 417     my $curr = $action;
 418     # If this is an action chain get the last action in the chain
 419     if($curr->can('chain') ) {
 420       $curr = ${$curr->chain}[-1];
 421     }
 422     while ($curr) {
 423         if (my $cap = $curr->number_of_captures) {
 424             return undef unless @captures >= $cap; # not enough captures
 425             if ($cap) {
 426                 unshift(@parts, splice(@captures, -$cap));
 427             }
 428         }
 429         if (my $pp = $curr->attributes->{PathPart}) {
 430             unshift(@parts, $pp->[0])
 431                 if (defined($pp->[0]) && length($pp->[0]));
 432         }
 433         $parent = $curr->attributes->{Chained}->[0];
 434         $curr = $self->_actions->{$parent};
 435     }
 436
 437     return undef unless $parent eq '/'; # fail for dangling action
 438
 439     return undef if @captures; # fail for too many captures
 440
 441     return join('/', '', @parts);
 442
 443 }
 444
 445 =head2 $c->expand_action($action)
 446
 447 Return a list of actions that represents a chained action. See
 448 L<Catalyst::Dispatcher> for more info. You probably want to
 449 use the expand_action it provides rather than this directly.
 450
 451 =cut
 452
 453 sub expand_action {
 454     my ($self, $action) = @_;
 455
 456     return unless $action->attributes && $action->attributes->{Chained};
 457
 458     my @chain;
 459     my $curr = $action;
 460
 461     while ($curr) {
 462         push @chain, $curr;
 463         my $parent = $curr->attributes->{Chained}->[0];
 464         $curr = $self->_actions->{$parent};
 465     }
 466
 467     return Catalyst::ActionChain->from_chain([reverse @chain]);
 468 }
 469
 470 __PACKAGE__->meta->make_immutable;
 471 1;
 472
 473 =head1 USAGE
 474
 475 =head2 Introduction
 476
 477 The C<Chained> attribute allows you to chain public path parts together
 478 by their private names. A chain part's path can be specified with
 479 C<PathPart> and can be declared to expect an arbitrary number of
 480 arguments. The endpoint of the chain specifies how many arguments it
 481 gets through the C<Args> attribute. C<:Args(0)> would be none at all,
 482 C<:Args> without an integer would be unlimited. The path parts that
 483 aren't endpoints are using C<CaptureArgs> to specify how many parameters
 484 they expect to receive. As an example setup:
 485
 486   package MyApp::Controller::Greeting;
 487   use base qw/ Catalyst::Controller /;
 488
 489   #   this is the beginning of our chain
 490   sub hello : PathPart('hello') Chained('/') CaptureArgs(1) {
 491       my ( $self, $c, $integer ) = @_;
 492       $c->stash->{ message } = "Hello ";
 493       $c->stash->{ arg_sum } = $integer;
 494   }
 495
 496   #   this is our endpoint, because it has no :CaptureArgs
 497   sub world : PathPart('world') Chained('hello') Args(1) {
 498       my ( $self, $c, $integer ) = @_;
 499       $c->stash->{ message } .= "World!";
 500       $c->stash->{ arg_sum } += $integer;
 501
 502       $c->response->body( join "<br/>\n" =>
 503           $c->stash->{ message }, $c->stash->{ arg_sum } );
 504   }
 505
 506 The debug output provides a separate table for chained actions, showing
 507 the whole chain as it would match and the actions it contains. Here's an
 508 example of the startup output with our actions above:
 509
 510   ...
 511   [debug] Loaded Path Part actions:
 512   .-----------------------+------------------------------.
 513   | Path Spec             | Private                      |
 514   +-----------------------+------------------------------+
 515   | /hello/*/world/*      | /greeting/hello (1)          |
 516   |                       | => /greeting/world           |
 517   '-----------------------+------------------------------'
 518   ...
 519
 520 As you can see, Catalyst only deals with chains as whole paths and
 521 builds one for each endpoint, which are the actions with C<:Chained> but
 522 without C<:CaptureArgs>.
 523
 524 Let's assume this application gets a request at the path
 525 C</hello/23/world/12>. What happens then? First, Catalyst will dispatch
 526 to the C<hello> action and pass the value C<23> as an argument to it
 527 after the context. It does so because we have previously used
 528 C<:CaptureArgs(1)> to declare that it has one path part after itself as
 529 its argument. We told Catalyst that this is the beginning of the chain
 530 by specifying C<:Chained('/')>. Also note that instead of saying
 531 C<:PathPart('hello')> we could also just have said C<:PathPart>, as it
 532 defaults to the name of the action.
 533
 534 After C<hello> has run, Catalyst goes on to dispatch to the C<world>
 535 action. This is the last action to be called: Catalyst knows this is an
 536 endpoint because we did not specify a C<:CaptureArgs>
 537 attribute. Nevertheless we specify that this action expects an argument,
 538 but at this point we're using C<:Args(1)> to do that. We could also have
 539 said C<:Args> or left it out altogether, which would mean this action
 540 would get all arguments that are there. This action's C<:Chained>
 541 attribute says C<hello> and tells Catalyst that the C<hello> action in
 542 the current controller is its parent.
 543
 544 With this we have built a chain consisting of two public path parts.
 545 C<hello> captures one part of the path as its argument, and also
 546 specifies the path root as its parent. So this part is
 547 C</hello/$arg>. The next part is the endpoint C<world>, expecting one
 548 argument. It sums up to the path part C<world/$arg>. This leads to a
 549 complete chain of C</hello/$arg/world/$arg> which is matched against the
 550 requested paths.
 551
 552 This example application would, if run and called by e.g.
 553 C</hello/23/world/12>, set the stash value C<message> to "Hello" and the
 554 value C<arg_sum> to "23". The C<world> action would then append "World!"
 555 to C<message> and add C<12> to the stash's C<arg_sum> value.  For the
 556 sake of simplicity no view is shown. Instead we just put the values of
 557 the stash into our body. So the output would look like:
 558
 559   Hello World!
 560   35
 561
 562 And our test server would have given us this debugging output for the
 563 request:
 564
 565   ...
 566   [debug] "GET" request for "hello/23/world/12" from "127.0.0.1"
 567   [debug] Path is "/greeting/world"
 568   [debug] Arguments are "12"
 569   [info] Request took 0.164113s (6.093/s)
 570   .------------------------------------------+-----------.
 571   | Action                                   | Time      |
 572   +------------------------------------------+-----------+
 573   | /greeting/hello                          | 0.000029s |
 574   | /greeting/world                          | 0.000024s |
 575   '------------------------------------------+-----------'
 576   ...
 577
 578 What would be common uses of this dispatch technique? It gives the
 579 possibility to split up logic that contains steps that each depend on
 580 each other. An example would be, for example, a wiki path like
 581 C</wiki/FooBarPage/rev/23/view>. This chain can be easily built with
 582 these actions:
 583
 584   sub wiki : PathPart('wiki') Chained('/') CaptureArgs(1) {
 585       my ( $self, $c, $page_name ) = @_;
 586       #  load the page named $page_name and put the object
 587       #  into the stash
 588   }
 589
 590   sub rev : PathPart('rev') Chained('wiki') CaptureArgs(1) {
 591       my ( $self, $c, $revision_id ) = @_;
 592       #  use the page object in the stash to get at its
 593       #  revision with number $revision_id
 594   }
 595
 596   sub view : PathPart Chained('rev') Args(0) {
 597       my ( $self, $c ) = @_;
 598       #  display the revision in our stash. Another option
 599       #  would be to forward a compatible object to the action
 600       #  that displays the default wiki pages, unless we want
 601       #  a different interface here, for example restore
 602       #  functionality.
 603   }
 604
 605 It would now be possible to add other endpoints, for example C<restore>
 606 to restore this specific revision as the current state.
 607
 608 You don't have to put all the chained actions in one controller. The
 609 specification of the parent through C<:Chained> also takes an absolute
 610 action path as its argument. Just specify it with a leading C</>.
 611
 612 If you want, for example, to have actions for the public paths
 613 C</foo/12/edit> and C</foo/12>, just specify two actions with
 614 C<:PathPart('foo')> and C<:Chained('/')>. The handler for the former
 615 path needs a C<:CaptureArgs(1)> attribute and a endpoint with
 616 C<:PathPart('edit')> and C<:Chained('foo')>. For the latter path give
 617 the action just a C<:Args(1)> to mark it as endpoint. This sums up to
 618 this debugging output:
 619
 620   ...
 621   [debug] Loaded Path Part actions:
 622   .-----------------------+------------------------------.
 623   | Path Spec             | Private                      |
 624   +-----------------------+------------------------------+
 625   | /foo/*                | /controller/foo_view         |
 626   | /foo/*/edit           | /controller/foo_load (1)     |
 627   |                       | => /controller/edit          |
 628   '-----------------------+------------------------------'
 629   ...
 630
 631 Here's a more detailed specification of the attributes belonging to
 632 C<:Chained>:
 633
 634 =head2 Attributes
 635
 636 =over 8
 637
 638 =item PathPart
 639
 640 Sets the name of this part of the chain. If it is specified without
 641 arguments, it takes the name of the action as default. So basically
 642 C<sub foo :PathPart> and C<sub foo :PathPart('foo')> are identical.
 643 This can also contain slashes to bind to a deeper level. An action
 644 with C<sub bar :PathPart('foo/bar') :Chained('/')> would bind to
 645 C</foo/bar/...>. If you don't specify C<:PathPart> it has the same
 646 effect as using C<:PathPart>, it would default to the action name.
 647
 648 =item PathPrefix
 649
 650 Sets PathPart to the path_prefix of the current controller.
 651
 652 =item Chained
 653
 654 Has to be specified for every child in the chain. Possible values are
 655 absolute and relative private action paths or a single slash C</> to
 656 tell Catalyst that this is the root of a chain. The attribute
 657 C<:Chained> without arguments also defaults to the C</> behavior.
 658 Relative action paths may use C<../> to refer to actions in parent
 659 controllers.
 660
 661 Because you can specify an absolute path to the parent action, it
 662 doesn't matter to Catalyst where that parent is located. So, if your
 663 design requests it, you can redispatch a chain through any controller or
 664 namespace you want.
 665
 666 Another interesting possibility gives C<:Chained('.')>, which chains
 667 itself to an action with the path of the current controller's namespace.
 668 For example:
 669
 670   #   in MyApp::Controller::Foo
 671   sub bar : Chained CaptureArgs(1) { ... }
 672
 673   #   in MyApp::Controller::Foo::Bar
 674   sub baz : Chained('.') Args(1) { ... }
 675
 676 This builds up a chain like C</bar/*/baz/*>. The specification of C<.>
 677 as the argument to Chained here chains the C<baz> action to an action
 678 with the path of the current controller namespace, namely
 679 C</foo/bar>. That action chains directly to C</>, so the C</bar/*/baz/*>
 680 chain comes out as the end product.
 681
 682 =item ChainedParent
 683
 684 Chains an action to another action with the same name in the parent
 685 controller. For Example:
 686
 687   # in MyApp::Controller::Foo
 688   sub bar : Chained CaptureArgs(1) { ... }
 689
 690   # in MyApp::Controller::Foo::Moo
 691   sub bar : ChainedParent Args(1) { ... }
 692
 693 This builds a chain like C</bar/*/bar/*>.
 694
 695 =item CaptureArgs
 696
 697 Must be specified for every part of the chain that is not an
 698 endpoint. With this attribute Catalyst knows how many of the following
 699 parts of the path (separated by C</>) this action wants to capture as
 700 its arguments. If it doesn't expect any, just specify
 701 C<:CaptureArgs(0)>.  The captures get passed to the action's C<@_> right
 702 after the context, but you can also find them as array references in
 703 C<$c-E<gt>request-E<gt>captures-E<gt>[$level]>. The C<$level> is the
 704 level of the action in the chain that captured the parts of the path.
 705
 706 An action that is part of a chain (that is, one that has a C<:Chained>
 707 attribute) but has no C<:CaptureArgs> attribute is treated by Catalyst
 708 as a chain end.
 709
 710 Allowed values for CaptureArgs is a single integer (CaptureArgs(2), meaning two
 711 allowed) or you can declare a L<Moose>, L<MooseX::Types> or L<Type::Tiny>
 712 named constraint such as CaptureArgs(Int,Str) would require two args with
 713 the first being a Integer and the second a string.  You may declare your own
 714 custom type constraints and import them into the controller namespace:
 715
 716     package MyApp::Controller::Root;
 717
 718     use Moose;
 719     use MooseX::MethodAttributes;
 720     use MyApp::Types qw/Int/;
 721
 722     extends 'Catalyst::Controller';
 723
 724     sub chain_base :Chained(/) CaptureArgs(1) { }
 725
 726       sub any_priority_chain :Chained(chain_base) PathPart('') Args(1) { }
 727
 728       sub int_priority_chain :Chained(chain_base) PathPart('') Args(Int) { }
 729
 730 See L<Catalyst::RouteMatching> for more.
 731
 732 =item Args
 733
 734 By default, endpoints receive the rest of the arguments in the path. You
 735 can tell Catalyst through C<:Args> explicitly how many arguments your
 736 endpoint expects, just like you can with C<:CaptureArgs>. Note that this
 737 also affects whether this chain is invoked on a request. A chain with an
 738 endpoint specifying one argument will only match if exactly one argument
 739 exists in the path.
 740
 741 You can specify an exact number of arguments like C<:Args(3)>, including
 742 C<0>. If you just say C<:Args> without any arguments, it is the same as
 743 leaving it out altogether: The chain is matched regardless of the number
 744 of path parts after the endpoint.
 745
 746 Just as with C<:CaptureArgs>, the arguments get passed to the action in
 747 C<@_> after the context object. They can also be reached through
 748 C<$c-E<gt>request-E<gt>arguments>.
 749
 750 =back
 751
 752 =head2 Auto actions, dispatching and forwarding
 753
 754 Note that the list of C<auto> actions called depends on the private path
 755 of the endpoint of the chain, not on the chained actions way. The
 756 C<auto> actions will be run before the chain dispatching begins. In
 757 every other aspect, C<auto> actions behave as documented.
 758
 759 The C<forward>ing to other actions does just what you would expect. i.e.
 760 only the target action is run. The actions that that action is chained
 761 to are not run.
 762 If you C<detach> out of a chain, the rest of the chain will not get
 763 called after the C<detach>.
 764
 765 =head2 match_captures
 766
 767 A method which can optionally be implemented by actions to
 768 stop chain matching.
 769
 770 See L<Catalyst::Action> for further details.
 771
 772 =head1 AUTHORS
 773
 774 Catalyst Contributors, see Catalyst.pm
 775
 776 =head1 COPYRIGHT
 777
 778 This library is free software. You can redistribute it and/or modify it under
 779 the same terms as Perl itself.
 780
 781 =cut
 782
 783 1;