NAME

Path::Dispatcher::Match - the result of a successful rule match

SYNOPSIS

    my $rule = Path::Dispatcher::Rule::Tokens->new(
        tokens => [ 'attack', qr/^\w+$/ ],
        block  => sub { attack($2) },
    );

    my $match = $rule->match("attack dragon");

    $match->path            # "attack dragon"
    $match->leftover        # empty string (populated with prefix rules)
    $match->rule            # $rule
    $match->result          # ["attack", "dragon"] (decided by the rule)
    $match->set_number_vars # 1 (boolean indicating whether to set $1, $2, etc)

    $match->run                         # causes the player to attack the dragon
    $match->run_with_number_vars($code) # runs $code with $1=attack $2=dragon

DESCRIPTION

If a Path::Dispatcher::Rule successfully matches a path, it creates one or more Path::Dispatcher::Match objects.

ATTRIBUTES

rule

The Path::Dispatcher::Rule that created this match.

path

The path that the rule matched.

leftover

The rest of the path. This is populated when the rule matches a prefix of the path.

result

Arbitrary results generated by the rule. For example, Path::Dispatcher::Rule::Regex rules' result is an array reference of capture variables.

set_number_vars

A boolean indicating whether invoking the rule should populate the number variables ($1, $2, etc) with the array reference of results.

Default is true if the result is an array reference; otherwise false.

METHODS

run

Executes the rule's codeblock with the same arguments. If "set_number_vars" is true, then "run_with_number_vars" is used, otherwise the rule's codeblock is invoked directly.

run_with_number_vars coderef, $1, $2, ...

Populates the number variables $1, $2, ... then executes the coderef.

Unfortunately, the only way to achieve this (pre-5.10 anyway) is to match a regular expression. Both a string and a regex are constructed such that matching will produce the correct capture variables.