NAME¶

Path::Dispatcher - Flexible and extensible dispatch

VERSION¶

version 1.08

SYNOPSIS¶

    use Path::Dispatcher;
    my $dispatcher = Path::Dispatcher->new;
    $dispatcher->add_rule(
        Path::Dispatcher::Rule::Regex->new(
            regex => qr{^/(foo)/},
            block => sub { warn shift->pos(1); },
        )
    );
    $dispatcher->add_rule(
        Path::Dispatcher::Rule::Tokens->new(
            tokens    => ['ticket', 'delete', qr/^\d+$/],
            delimiter => '/',
            block     => sub { delete_ticket(shift->pos(3)) },
        )
    );
    my $dispatch = $dispatcher->dispatch("/foo/bar");
    die "404" unless $dispatch->has_matches;
    $dispatch->run;

DESCRIPTION¶

We really like Jifty::Dispatcher and wanted to use it for Prophet's command line.

The basic operation is that of dispatch. Dispatch takes a path and a list of rules, and it returns a list of matches. From there you can "run" the rules that matched. These phases are distinct so that, if you need to, you can inspect which rules were matched without ever running their codeblocks.

Tab completion support is also available (see in particular "How can I configure tab completion for shells?" in Path::Dispatcher::Cookbook) for the dispatchers you write.

Each rule may take a variety of different forms (which I think justifies the "flexible" adjective in the module's description). Some of the rule types are:

Path::Dispatcher::Rule::Regex

Matches the path against a regular expression.

Path::Dispatcher::Rule::Enum

Match one of a set of strings.

Path::Dispatcher::Rule::CodeRef

Execute a coderef to determine whether the path matches the rule. So you can do anything you like. Though writing a domain-specific rule (see below) will enable better introspection and encoding intent.

Path::Dispatcher::Rule::Dispatch

Use another Path::Dispatcher to match the path. This facilitates both extending dispatchers (a bit like subclassing) and delegating to plugins.

Since Path::Dispatcher is designed with good object-oriented programming practices, you can also write your own domain-specific rule classes (which earns it the "extensible" adjective). For example, in Prophet, we have a custom rule for matching, and tab completing, record IDs.

You may want to use Path::Dispatcher::Declarative which gives you some sugar inspired by Jifty::Dispatcher.

ATTRIBUTES¶

METHODS¶

    $term->Attribs->{completion_function} = sub {
        my ($last_word, $line, $start) = @_;
        my @matches = map { s/^.* //; $_ } $dispatcher->complete($line);
        return @matches;
    };

SEE ALSO¶

<http://sartak.org/talks/yapc-na-2010/path-dispatcher/>

<http://sartak.org/talks/yapc-asia-2010/evolution-of-path-dispatcher/>

<http://github.com/miyagawa/plack-dispatching-samples>

Jifty::Dispatcher

Catalyst::Dispatcher

Mojolicious::Dispatcher

Path::Router

Router::Simple

<http://github.com/bestpractical/path-dispatcher-debugger> - Not quite ready for release

SUPPORT¶

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Path-Dispatcher> (or bug-Path-Dispatcher@rt.cpan.org <mailto:bug-Path-Dispatcher@rt.cpan.org>).

AUTHOR¶

Shawn M Moore, "<sartak at bestpractical.com>"

CONTRIBUTORS¶

• sartak <sartak@e417ac7c-1bcc-0310-8ffa-8f5827389a85>
• Shawn M Moore <sartak@bestpractical.com>
• Shawn M Moore <sartak@gmail.com>
• Karen Etheridge <ether@cpan.org>
• robertkrimen <robertkrimen@gmail.com>
• Aaron Trevena <aaron@aarontrevena.co.uk>
• David Pottage <david@chrestomanci.org>
• Shawn M Moore <code@sartak.org>
• Shawn M Moore <shawn.moore@iinteractive.com>
• Florian Ragwitz <rafl@debian.org>
• Shawn M Moore <shawn@bestpractical.com>
• clkao <clkao@e417ac7c-1bcc-0310-8ffa-8f5827389a85>

COPYRIGHT AND LICENSE¶

This software is copyright (c) 2020 by Shawn M Moore.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.