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

   rules
       A list of Path::Dispatcher::Rule objects.

METHODS

   add_rule
       Adds a Path::Dispatcher::Rule to the end of this dispatcher's rule set.

   dispatch path -> dispatch
       Takes  a string (the path) and returns a Path::Dispatcher::Dispatch object representing a list of matches
       (Path::Dispatcher::Match objects).

   run path, args
       Dispatches on the path and then invokes the "run" method on the  Path::Dispatcher::Dispatch  object,  for
       when you don't need to inspect the dispatch.

       The args are passed down directly into each rule codeblock. No other args are given to the codeblock.

   complete path -> strings
       Given  a  path,  consult  each  rule  for  possible  completions  for  the path. This is intended for tab
       completion. You can use it with Term::ReadLine like so:

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

       This API is experimental and subject to change. In particular I think I want to  return  an  object  that
       resembles Path::Dispatcher::Dispatch.

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.

perl v5.30.3                                       2020-07-13                              Path::Dispatcher(3pm)