.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Path::Dispatcher 3pm"
.TH Path::Dispatcher 3pm "2020-07-13" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Path::Dispatcher \- Flexible and extensible dispatch
.SH "VERSION"
.IX Header "VERSION"
version 1.08
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    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    => [\*(Aqticket\*(Aq, \*(Aqdelete\*(Aq, qr/^\ed+$/],
\&            delimiter => \*(Aq/\*(Aq,
\&            block     => sub { delete_ticket(shift\->pos(3)) },
\&        )
\&    );
\&
\&    my $dispatch = $dispatcher\->dispatch("/foo/bar");
\&    die "404" unless $dispatch\->has_matches;
\&    $dispatch\->run;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
We really like Jifty::Dispatcher and wanted to use it for Prophet's
command line.
.PP
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 \*(L"run\*(R" 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.
.PP
Tab completion support is also available (see in particular
\&\*(L"How can I configure tab completion for shells?\*(R" in Path::Dispatcher::Cookbook)
for the dispatchers you write.
.PP
Each rule may take a variety of different forms (which I think justifies the
\&\*(L"flexible\*(R" adjective in the module's description). Some of the rule types are:
.IP "Path::Dispatcher::Rule::Regex" 4
.IX Item "Path::Dispatcher::Rule::Regex"
Matches the path against a regular expression.
.IP "Path::Dispatcher::Rule::Enum" 4
.IX Item "Path::Dispatcher::Rule::Enum"
Match one of a set of strings.
.IP "Path::Dispatcher::Rule::CodeRef" 4
.IX Item "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.
.IP "Path::Dispatcher::Rule::Dispatch" 4
.IX Item "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.
.PP
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 \*(L"extensible\*(R" adjective). For example, in Prophet, we have a
custom rule for matching, and tab completing, record IDs.
.PP
You may want to use Path::Dispatcher::Declarative which gives you some sugar
inspired by Jifty::Dispatcher.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "rules"
.IX Subsection "rules"
A list of Path::Dispatcher::Rule objects.
.SH "METHODS"
.IX Header "METHODS"
.SS "add_rule"
.IX Subsection "add_rule"
Adds a Path::Dispatcher::Rule to the end of this dispatcher's rule set.
.SS "dispatch path \-> dispatch"
.IX Subsection "dispatch path -> dispatch"
Takes a string (the path) and returns a Path::Dispatcher::Dispatch object
representing a list of matches (Path::Dispatcher::Match objects).
.SS "run path, args"
.IX Subsection "run path, args"
Dispatches on the path and then invokes the \f(CW\*(C`run\*(C'\fR method on the
Path::Dispatcher::Dispatch object, for when you don't need to inspect the
dispatch.
.PP
The args are passed down directly into each rule codeblock. No other args are
given to the codeblock.
.SS "complete path \-> strings"
.IX Subsection "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:
.PP
.Vb 5
\&    $term\->Attribs\->{completion_function} = sub {
\&        my ($last_word, $line, $start) = @_;
\&        my @matches = map { s/^.* //; $_ } $dispatcher\->complete($line);
\&        return @matches;
\&    };
.Ve
.PP
This \s-1API\s0 is experimental and subject to change. In particular I think I want to
return an object that resembles Path::Dispatcher::Dispatch.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "<http://sartak.org/talks/yapc\-na\-2010/path\-dispatcher/>" 4
.IX Item "<http://sartak.org/talks/yapc-na-2010/path-dispatcher/>"
.PD 0
.IP "<http://sartak.org/talks/yapc\-asia\-2010/evolution\-of\-path\-dispatcher/>" 4
.IX Item "<http://sartak.org/talks/yapc-asia-2010/evolution-of-path-dispatcher/>"
.IP "<http://github.com/miyagawa/plack\-dispatching\-samples>" 4
.IX Item "<http://github.com/miyagawa/plack-dispatching-samples>"
.IP "Jifty::Dispatcher" 4
.IX Item "Jifty::Dispatcher"
.IP "Catalyst::Dispatcher" 4
.IX Item "Catalyst::Dispatcher"
.IP "Mojolicious::Dispatcher" 4
.IX Item "Mojolicious::Dispatcher"
.IP "Path::Router" 4
.IX Item "Path::Router"
.IP "Router::Simple" 4
.IX Item "Router::Simple"
.IP "<http://github.com/bestpractical/path\-dispatcher\-debugger> \- Not quite ready for release" 4
.IX Item "<http://github.com/bestpractical/path-dispatcher-debugger> - Not quite ready for release"
.PD
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted through the \s-1RT\s0 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>).
.SH "AUTHOR"
.IX Header "AUTHOR"
Shawn M Moore, \f(CW\*(C`<sartak at bestpractical.com>\*(C'\fR
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
sartak <sartak@e417ac7c\-1bcc\-0310\-8ffa\-8f5827389a85>
.IP "\(bu" 4
Shawn M Moore <sartak@bestpractical.com>
.IP "\(bu" 4
Shawn M Moore <sartak@gmail.com>
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
robertkrimen <robertkrimen@gmail.com>
.IP "\(bu" 4
Aaron Trevena <aaron@aarontrevena.co.uk>
.IP "\(bu" 4
David Pottage <david@chrestomanci.org>
.IP "\(bu" 4
Shawn M Moore <code@sartak.org>
.IP "\(bu" 4
Shawn M Moore <shawn.moore@iinteractive.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.IP "\(bu" 4
Shawn M Moore <shawn@bestpractical.com>
.IP "\(bu" 4
clkao <clkao@e417ac7c\-1bcc\-0310\-8ffa\-8f5827389a85>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020 by Shawn M Moore.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.