GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PATH::DISPATCHER (3)

.ds Aq ’

NAME

Path::Dispatcher - flexible and extensible dispatch

CONTENTS

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>

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

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 PATH::DISPATCHER (3) 2015-02-18

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.