| 1 | package Router::XS; | ||
| 2 | 1 | ▶ | use Exporter 'import'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 3 | |||
| 4 | 1 | my @STD = qw(check_route add_route); | |
| 5 | 1 | my @REST = qw(get post put patch del head conn options any); | |
| 6 | 1 | our @EXPORT_OK = (@STD, @REST); | |
| 7 | 1 | our %EXPORT_TAGS = (std => \@STD, rest => \@REST, all => [@STD, @REST]); | |
| 8 | |||
| 9 | 1 | our $VERSION = 0.02; | |
| 10 | |||
| 11 | 1 | require XSLoader; | |
| 12 | 1 | XSLoader::load(); | |
| 13 | |||
| 14 | 1 | ▶ | sub get ($&) { |
|
Subroutine
get: called CC=1 SCAR=0.0
Pod
documented
| |||
| 15 | 1 | add_route("GET/$_[0]", $_[1]); | |
| 16 | } | ||
| 17 | |||
| 18 | 1 | ▶ | sub post ($&) { |
|
Subroutine
post: called CC=1 SCAR=0.0
Pod
documented
| |||
| 19 | 1 | add_route("POST/$_[0]", $_[1]); | |
| 20 | } | ||
| 21 | |||
| 22 | 1 | ▶ | sub put ($&) { |
|
Subroutine
put: called CC=1 SCAR=0.0
Pod
documented
| |||
| 23 | 1 | add_route("PUT/$_[0]", $_[1]); | |
| 24 | } | ||
| 25 | |||
| 26 | 1 | ▶ | sub patch ($&) { |
|
Subroutine
patch: called CC=1 SCAR=0.0
Pod
documented
| |||
| 27 | 1 | add_route("PATCH/$_[0]", $_[1]); | |
| 28 | } | ||
| 29 | |||
| 30 | 1 | ▶ | sub del ($&) { |
|
Subroutine
del: called CC=1 SCAR=0.0
Pod
documented
| |||
| 31 | 1 | add_route("DELETE/$_[0]", $_[1]); | |
| 32 | } | ||
| 33 | |||
| 34 | 1 | ▶ | sub head ($&) { |
|
Subroutine
head: called CC=1 SCAR=0.0
Pod
documented
| |||
| 35 | 1 | add_route("HEAD/$_[0]", $_[1]); | |
| 36 | } | ||
| 37 | |||
| 38 | 1 | ▶ | sub conn ($&) { |
|
Subroutine
conn: called CC=1 SCAR=0.0
Pod
documented
| |||
| 39 | 1 | add_route("CONNECT/$_[0]", $_[1]); | |
| 40 | } | ||
| 41 | |||
| 42 | 1 | ▶ | sub options ($&) { |
|
Subroutine
options: called CC=1 SCAR=0.0
Pod
documented
| |||
| 43 | 1 | add_route("OPTIONS/$_[0]", $_[1]); | |
| 44 | } | ||
| 45 | |||
| 46 | 1 | ▶ | sub any ($&) { |
|
Subroutine
any: called CC=1 SCAR=0.0
Pod
documented
| |||
| 47 | 1 | add_route("*/$_[0]", $_[1]); | |
| 48 | } | ||
| 49 | |||
| 50 | 1 | 1; | |
| 51 | |||
| 52 | =encoding utf8 | ||
| 53 | |||
| 54 | =head1 NAME | ||
| 55 | |||
| 56 | Router::XS - Fast URI path to value lookup | ||
| 57 | |||
| 58 | =head1 SYNOPSIS | ||
| 59 | |||
| 60 | use Router::XS ':all'; | ||
| 61 | |||
| 62 | my $user_home_page = sub { ... }; | ||
| 63 | |||
| 64 | add_route('/user/*', $user_home_page); | ||
| 65 | my ($sub, @captures) = check_route('/user/foobar'); | ||
| 66 | |||
| 67 | # or use HTTP method verbs to add routes | ||
| 68 | get '/user/*' => sub { ... }; | ||
| 69 | |||
| 70 | my ($sub, @captures) = check_route('GET/user/foobar'); | ||
| 71 | |||
| 72 | =head1 FUNCTIONS | ||
| 73 | |||
| 74 | =head2 add_route ($path, $sub) | ||
| 75 | |||
| 76 | Adds a new route associated with a subroutine to the router. Will C<die> if a | ||
| 77 | matching route has already been added. Accepts asterisks (C<*>) as wildcards | ||
| 78 | for captures. C<$path> may be prepended with an HTTP method: | ||
| 79 | |||
| 80 | add_route('POST/some/path', $sub); | ||
| 81 | |||
| 82 | =head2 check_route ($path) | ||
| 83 | |||
| 84 | Checks a URI path against the added routes and returns C<undef> if no match is | ||
| 85 | found, otherwise returning the associated subroutine reference and any captures | ||
| 86 | from wildcards: | ||
| 87 | |||
| 88 | my ($sub, @captures) = check_route('POST/some/path'); | ||
| 89 | |||
| 90 | =head2 get/post/put/patch/del/head/conn/options/any | ||
| 91 | |||
| 92 | Sugar for C<add_route>: adds a route using C<$path> for the associated HTTP | ||
| 93 | method: | ||
| 94 | |||
| 95 | put '/product/*' => sub { ... }; | ||
| 96 | |||
| 97 | The C<any> function accepts any HTTP method. When an incoming request is | ||
| 98 | received, C<check_route> must still be called. | ||
| 99 | |||
| 100 | See the test file included in this distribution for further examples. | ||
| 101 | |||
| 102 | =head1 THREAD SAFETY | ||
| 103 | |||
| 104 | Router::XS is not thread safe: however if you add all routes at the startup of | ||
| 105 | an application under a single thread, and do not call C<add_route> thereafter, | ||
| 106 | it should be thread safe. | ||
| 107 | |||
| 108 | =head1 BENCHMARKS | ||
| 109 | |||
| 110 | On my machine Router::XS performs well against other fast Routers. The test | ||
| 111 | conditions add 200 routes, and then check how fast the router can match the | ||
| 112 | path '/interstitial/track': | ||
| 113 | |||
| 114 | Rate Router::Boom Router::R3 Router::XS | ||
| 115 | Router::Boom 344536/s -- -85% -93% | ||
| 116 | Router::R3 2235343/s 549% -- -54% | ||
| 117 | Router::XS 4860641/s 1311% 117% -- | ||
| 118 | |||
| 119 | =head2 DEPENDENCIES | ||
| 120 | |||
| 121 | This module uses L<uthash|http://troydhanson.github.com/uthash/> to build a | ||
| 122 | n-ary tree of paths. C<uthash> is a single C header file, included in this | ||
| 123 | distribution. uthash is copyright (c) 2003-2017, Troy D. Hanson. | ||
| 124 | |||
| 125 | =head1 INSTALLATION | ||
| 126 | |||
| 127 | perl Makefile.PL | ||
| 128 | make | ||
| 129 | make test | ||
| 130 | make install | ||
| 131 | |||
| 132 | =head1 AUTHOR | ||
| 133 | |||
| 134 | E<copy> 2017 David Farrell | ||
| 135 | |||
| 136 | =head1 LICENSE | ||
| 137 | |||
| 138 | The (two-clause) FreeBSD License | ||
| 139 | |||
| 140 | =head1 ACKNOWLEDGEMENTS | ||
| 141 | |||
| 142 | Thanks to L<ZipRecruiter|https://www.ziprecruiter.com> for letting their employees contribute to Open Source. | ||
| 143 | |||
| 144 | =head1 SEE ALSO | ||
| 145 | |||
| 146 | There are many routers on L<CPAN|https://metacpan.org/search?size=20&q=Router> including: | ||
| 147 | |||
| 148 | =over 4 | ||
| 149 | |||
| 150 | =item * L<HTTP::Router> | ||
| 151 | |||
| 152 | =item * L<Path::Router> | ||
| 153 | |||
| 154 | =item * L<Router::Boom> | ||
| 155 | |||
| 156 | =item * L<Router::R3> | ||
| 157 | |||
| 158 | =back | ||
| 159 | |||
| 160 | =cut | ||