Path::Dispatcher(3pm)

💅 Path::Dispatcher — the manual page, bestie edition

okay so you're reading Path::Dispatcher(3pm) and honestly? you're about to have a great time. this thing is flexible and extensible dispatch and i'm obsessed with it. it's giving routing but make it fashion. let's go 🦋

---

✨ VERSION ✨

version 1.08 — yes queen, current, we love to see it 👑

---

🌸 SYNOPSIS 🌸

here's the vibe, bestie, copy-paste ready:

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;

no cap, that's the whole thing. you make a dispatcher, you feed it rules, you dispatch a path, you check has_matches, you run it. periodt 💖

---

🌈 DESCRIPTION 🌈

so the origin story: we really liked Jifty::Dispatcher and wanted to use it for Prophet's command line. that's it, that's the lore 🫶

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. the way that these phases are distinct is honestly iconic — it means that, if you need to, you can inspect which rules were matched without ever running their codeblocks. like, peek at the matches, no commitment, no side effects. main character energy ✨

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. yes bestie, autocomplete, we love her 🌸

each rule may take a variety of different forms (which i think justifies the "flexible" adjective in the module's description — lowkey it earned it). 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 — two adjectives, two slays 💅). 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. sugar = cute syntax, not literal sugar, don't eat it 🙈

---

🎀 ATTRIBUTES 🎀

rules

a list of Path::Dispatcher::Rule objects. just a list. a lil lineup of rules. adorable, honestly 💜

---

⭐ METHODS ⭐

add_rule

adds a Path::Dispatcher::Rule to the end of this dispatcher's rule set. back of the line, babe, but make it slay.

dispatch path -> dispatch

takes a string (the path) and returns a Path::Dispatcher::Dispatch object representing a list of matches (Path::Dispatcher::Match objects). you get a whole object back, not just a yes/no. we're thorough like that 🔥

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. shortcut era, we love a shortcut.

the args are passed down directly into each rule codeblock. no other args are given to the codeblock. that's it, that's the whole args situation, don't go looking for extras 💀

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;
};

⚠️ okay heads up bestie: this API is experimental and subject to change. in particular i think i want to return an object that resembles Path::Dispatcher::Dispatch. so like, don't build your whole personality on it yet 😭

---

🔍 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>).

found a bug? tell the RT bug tracker. she's listening. she cares. don't suffer in silence ngl 💌

---

👑 AUTHOR 👑

Shawn M Moore, "<sartak at bestpractical.com>" — the icon, the legend, the one who did all of this 💖

---

🧚 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>

a whole squad, a whole committee, a whole friend group. we stan every single one 🌈

---

💜 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. free as in go ahead bestie, it's yours 🎀

---

and that's the page! this was documented with perl v5.30.3 on 2020-07-13, and if you made it all the way to the bottom of a manual page you are genuinely iconic, no cap. go write some rules, go run some dispatches, go take a nap 💅✨💖