Question

I can usually get the behavior I desire by just randomly trying different permutations of these two options, but I still can’t say I know precisely what they do. Is there a concrete example that demonstrates the difference?

Answer 1

:CaptureArgs(N) matches if there are at least N args left. It is used for non-terminal Chained handlers.

:Args(N) only matches if there are exactly N args left.

For example,

sub catalog : Chained : CaptureArgs(1) {
    my ( $self, $c, $arg ) = @_;
    ...
}

sub item : Chained('catalog') : Args(2) {
    my ( $self, $c, $arg1, $arg2 ) = @_;
    ...
}

matches

/catalog/*/item/*/*