Ubuntu Manpage: Path::Dispatcher - flexible and extensible dispatch

Provided by: libpath-dispatcher-perl_1.05-1_all

NAME

       Path::Dispatcher - flexible and extensible dispatch

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.

AUTHOR

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

COPYRIGHT & LICENSE

       Copyright 2008-2011 Best Practical Solutions.

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