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:

  my ($sub, @captures) = check_route('POST/some/path');

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 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 for letting their employees contribute to Open Source.

SEE ALSO

There are many routers on CPAN including:

• HTTP::Router

• Path::Router

• Router::Boom

• Router::R3

cpanm Router::XS

perl -MCPAN -e shell
install Router::XS