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