# NAME Router::XS - Fast URI path to value lookup # SYNOPSIS use Router::XS ':all'; my $user_home_page = sub { ... }; add_route('/user/*', $user_home_page); my ($sub, @captures) = check_route('/user/foobar'); # or use HTTP method verbs to add routes get '/user/*' => sub { ... }; my ($sub, @captures) = check_route('GET/user/foobar'); # FUNCTIONS ## add\_route ($path, $sub) Adds a new route associated with a subroutine to the router. Will `die` if a matching route has already been added. Accepts asterisks (`*`) as wildcards for captures. `$path` may be prepended with an HTTP method: add_route('POST/some/path', $sub); ## check\_route ($path) Checks a URI path against the added routes and returns `undef` if no match is found, otherwise returning the associated subroutine reference and any captures from wildcards: ## get/post/put/patch/del/head/conn/options/any Sugar for `add_route`: adds a route using `$path` for the associated HTTP method: put '/product/*' => sub { ... }; The `any` function accepts any HTTP method. When an incoming request is received, `check_route` must still be called. See the test file included in this distribution for further examples. # THREAD SAFETY Router::XS is not thread safe: however if you add all routes at the startup of an application under a single thread, and do not call `add_route` thereafter, it should be thread safe. # BENCHMARKS On my machine Router::XS performs well against other fast Routers. The test conditions add 200 routes, and then check how fast the router can match the path '/interstitial/track': Rate Router::Boom Router::R3 Router::XS Router::Boom 344536/s -- -85% -93% Router::R3 2235343/s 549% -- -54% Router::XS 4860641/s 1311% 117% -- ## DEPENDENCIES This module uses `uthash|http://troydhanson.github.com/uthash/` to build a n-ary tree of paths. `uthash` is a single C header file, included in this distribution. uthash is copyright (c) 2003-2017, Troy D. Hanson. # INSTALLATION perl Makefile.PL make make test make install # AUTHOR © 2017 David Farrell # LICENSE The (two-clause) FreeBSD License # ACKNOWLEDGEMENTS Thanks to [ZipRecruiter](https://www.ziprecruiter.com) for letting their employees contribute to Open Source. # SEE ALSO There are many routers on [CPAN](https://metacpan.org/search?size=20&q=Router) including: - [HTTP::Router](https://metacpan.org/pod/HTTP::Router) - [Path::Router](https://metacpan.org/pod/Path::Router) - [Router::Boom](https://metacpan.org/pod/Router::Boom) - [Router::R3](https://metacpan.org/pod/Router::R3)