blib/lib/Router/XS.pm

filter: Statementstmt 100% 20 / 20 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 10 / 10 Podpod 100% 9 / 9 totaltotal 100% 39 / 39 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
get
1.0
post
1.0
CRAP 1.0
« XS.xs ↑ Summary
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
« XS.xs ↑ Summary