Path::Dispatcher(3pm)

1Path::Dispatcher(3pm) User Contributed Perl DocumentationPath::Dispatcher(3pm)
2
3
4

NAME

6       Path::Dispatcher - Flexible and extensible dispatch
7

VERSION

9       version 1.08
10

SYNOPSIS

12           use Path::Dispatcher;
13           my $dispatcher = Path::Dispatcher->new;
14
15           $dispatcher->add_rule(
16               Path::Dispatcher::Rule::Regex->new(
17                   regex => qr{^/(foo)/},
18                   block => sub { warn shift->pos(1); },
19               )
20           );
21
22           $dispatcher->add_rule(
23               Path::Dispatcher::Rule::Tokens->new(
24                   tokens    => ['ticket', 'delete', qr/^\d+$/],
25                   delimiter => '/',
26                   block     => sub { delete_ticket(shift->pos(3)) },
27               )
28           );
29
30           my $dispatch = $dispatcher->dispatch("/foo/bar");
31           die "404" unless $dispatch->has_matches;
32           $dispatch->run;
33

DESCRIPTION

35       We really like Jifty::Dispatcher and wanted to use it for Prophet's
36       command line.
37
38       The basic operation is that of dispatch. Dispatch takes a path and a
39       list of rules, and it returns a list of matches. From there you can
40       "run" the rules that matched. These phases are distinct so that, if you
41       need to, you can inspect which rules were matched without ever running
42       their codeblocks.
43
44       Tab completion support is also available (see in particular "How can I
45       configure tab completion for shells?" in Path::Dispatcher::Cookbook)
46       for the dispatchers you write.
47
48       Each rule may take a variety of different forms (which I think
49       justifies the "flexible" adjective in the module's description). Some
50       of the rule types are:
51
52       Path::Dispatcher::Rule::Regex
53           Matches the path against a regular expression.
54
55       Path::Dispatcher::Rule::Enum
56           Match one of a set of strings.
57
58       Path::Dispatcher::Rule::CodeRef
59           Execute a coderef to determine whether the path matches the rule.
60           So you can do anything you like. Though writing a domain-specific
61           rule (see below) will enable better introspection and encoding
62           intent.
63
64       Path::Dispatcher::Rule::Dispatch
65           Use another Path::Dispatcher to match the path. This facilitates
66           both extending dispatchers (a bit like subclassing) and delegating
67           to plugins.
68
69       Since Path::Dispatcher is designed with good object-oriented
70       programming practices, you can also write your own domain-specific rule
71       classes (which earns it the "extensible" adjective). For example, in
72       Prophet, we have a custom rule for matching, and tab completing, record
73       IDs.
74
75       You may want to use Path::Dispatcher::Declarative which gives you some
76       sugar inspired by Jifty::Dispatcher.
77

ATTRIBUTES

79   rules
80       A list of Path::Dispatcher::Rule objects.
81

METHODS

83   add_rule
84       Adds a Path::Dispatcher::Rule to the end of this dispatcher's rule set.
85
86   dispatch path -> dispatch
87       Takes a string (the path) and returns a Path::Dispatcher::Dispatch
88       object representing a list of matches (Path::Dispatcher::Match
89       objects).
90
91   run path, args
92       Dispatches on the path and then invokes the "run" method on the
93       Path::Dispatcher::Dispatch object, for when you don't need to inspect
94       the dispatch.
95
96       The args are passed down directly into each rule codeblock. No other
97       args are given to the codeblock.
98
99   complete path -> strings
100       Given a path, consult each rule for possible completions for the path.
101       This is intended for tab completion. You can use it with Term::ReadLine
102       like so:
103
104           $term->Attribs->{completion_function} = sub {
105               my ($last_word, $line, $start) = @_;
106               my @matches = map { s/^.* //; $_ } $dispatcher->complete($line);
107               return @matches;
108           };
109
110       This API is experimental and subject to change. In particular I think I
111       want to return an object that resembles Path::Dispatcher::Dispatch.
112

SUPPORT

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

AUTHOR

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

CONTRIBUTORS

135       •   sartak <sartak@e417ac7c-1bcc-0310-8ffa-8f5827389a85>
136
137       •   Shawn M Moore <sartak@bestpractical.com>
138
139       •   Shawn M Moore <sartak@gmail.com>
140
141       •   Karen Etheridge <ether@cpan.org>
142
143       •   robertkrimen <robertkrimen@gmail.com>
144
145       •   Aaron Trevena <aaron@aarontrevena.co.uk>
146
147       •   David Pottage <david@chrestomanci.org>
148
149       •   Shawn M Moore <code@sartak.org>
150
151       •   Shawn M Moore <shawn.moore@iinteractive.com>
152
153       •   Florian Ragwitz <rafl@debian.org>
154
155       •   Shawn M Moore <shawn@bestpractical.com>
156
157       •   clkao <clkao@e417ac7c-1bcc-0310-8ffa-8f5827389a85>
158

COPYRIGHT AND LICENSE

160       This software is copyright (c) 2020 by Shawn M Moore.
161
162       This is free software; you can redistribute it and/or modify it under
163       the same terms as the Perl 5 programming language system itself.
164
165
166
167perl v5.34.0                      2022-01-21             Path::Dispatcher(3pm)