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