Router::Simple(3pm)

1Router::Simple(3)     User Contributed Perl Documentation    Router::Simple(3)
2
3
4

NAME

6       Router::Simple - simple HTTP router
7

SYNOPSIS

9           use Router::Simple;
10
11           my $router = Router::Simple->new();
12           $router->connect('/', {controller => 'Root', action => 'show'});
13           $router->connect('/blog/{year}/{month}', {controller => 'Blog', action => 'monthly'});
14
15           my $app = sub {
16               my $env = shift;
17               if (my $p = $router->match($env)) {
18                   # $p = { controller => 'Blog', action => 'monthly', ... }
19               } else {
20                   [404, [], ['not found']];
21               }
22           };
23

DESCRIPTION

25       Router::Simple is a simple router class.
26
27       Its main purpose is to serve as a dispatcher for web applications.
28
29       Router::Simple can match against PSGI $env directly, which means it's
30       easy to use with PSGI supporting web frameworks.
31

HOW TO WRITE A ROUTING RULE

33   plain string
34           $router->connect( '/foo', { controller => 'Root', action => 'foo' } );
35
36   :name notation
37           $router->connect( '/wiki/:page', { controller => 'WikiPage', action => 'show' } );
38           ...
39           $router->match('/wiki/john');
40           # => {controller => 'WikiPage', action => 'show', page => 'john' }
41
42       ':name' notation matches "qr{([^/]+)}".
43
44   '*' notation
45           $router->connect( '/download/*.*', { controller => 'Download', action => 'file' } );
46           ...
47           $router->match('/download/path/to/file.xml');
48           # => {controller => 'Download', action => 'file', splat => ['path/to/file', 'xml'] }
49
50       '*' notation matches "qr{(.+)}". You will get the captured argument as
51       an array ref for the special key "splat".
52
53   '{year}' notation
54           $router->connect( '/blog/{year}', { controller => 'Blog', action => 'yearly' } );
55           ...
56           $router->match('/blog/2010');
57           # => {controller => 'Blog', action => 'yearly', year => 2010 }
58
59       '{year}' notation matches "qr{([^/]+)}", and it will be captured.
60
61   '{year:[0-9]+}' notation
62           $router->connect( '/blog/{year:[0-9]+}/{month:[0-9]{2}}', { controller => 'Blog', action => 'monthly' } );
63           ...
64           $router->match('/blog/2010/04');
65           # => {controller => 'Blog', action => 'monthly', year => 2010, month => '04' }
66
67       You can specify regular expressions in named captures.
68
69   regexp
70           $router->connect( qr{/blog/(\d+)/([0-9]{2})', { controller => 'Blog', action => 'monthly' } );
71           ...
72           $router->match('/blog/2010/04');
73           # => {controller => 'Blog', action => 'monthly', splat => [2010, '04'] }
74
75       You can use Perl5's powerful regexp directly, and the captured values
76       are stored in the special key "splat".
77

METHODS

79       my $router = Router::Simple->new();
80           Creates a new instance of Router::Simple.
81
82       $router->method_not_allowed() : Boolean
83           This method returns last "$router->match()" call is rejected by
84           HTTP method or not.
85
86       $router->connect([$name, ] $pattern, \%destination[, \%options])
87           Adds a new rule to $router.
88
89               $router->connect( '/', { controller => 'Root', action => 'index' } );
90               $router->connect( 'show_entry', '/blog/:id',
91                   { controller => 'Blog', action => 'show' } );
92               $router->connect( '/blog/:id', { controller => 'Blog', action => 'show' } );
93               $router->connect( '/comment', { controller => 'Comment', action => 'new_comment' }, {method => 'POST'} );
94
95           "\%destination" will be used by match method.
96
97           You can specify some optional things to "\%options". The current
98           version supports 'method', 'host', and 'on_match'.
99
100           method
101               'method' is an ArrayRef[String] or String that matches
102               REQUEST_METHOD in $req.
103
104           host
105               'host' is a String or Regexp that matches HTTP_HOST in $req.
106
107           on_match
108                   $r->connect(
109                       '/{controller}/{action}/{id}',
110                       {},
111                       {
112                           on_match => sub {
113                               my($env, $match) = @_;
114                               $match->{referer} = $env->{HTTP_REFERER};
115                               return 1;
116                           }
117                       }
118                   );
119
120               A function that evaluates the request. Its signature must be
121               "($environ, $match) => bool". It should return true if the
122               match is successful or false otherwise. The first argument is
123               $env which is either a PSGI environment or a request path,
124               depending on what you pass to "match" method; the second is the
125               routing variables that would be returned if the match succeeds.
126
127               The function can modify $env (in case it's a reference) and
128               $match in place to affect which variables are returned. This
129               allows a wide range of transformations.
130
131       "$router->submapper($path, [\%dest, [\%opt]])"
132               $router->submapper('/entry/', {controller => 'Entry'})
133
134           This method is shorthand for creating new instance of
135           Router::Simple::Submapper.
136
137           The arguments will be passed to
138           "Router::Simple::SubMapper->new(%args)".
139
140       "$match = $router->match($env|$path)"
141           Matches a URL against one of the contained routes.
142
143           The parameter is either a PSGI $env or a plain string that
144           represents a path.
145
146           This method returns a plain hashref that would look like:
147
148               {
149                   controller => 'Blog',
150                   action     => 'daily',
151                   year => 2010, month => '03', day => '04',
152               }
153
154           It returns undef if no valid match is found.
155
156       "my ($match, $route) = $router->routematch($env|$path);"
157           Match a URL against one of the routes contained.
158
159           Will return undef if no valid match is found, otherwise a result
160           hashref and a Router::Simple::Route object is returned.
161
162       "$router->as_string()"
163           Dumps $router as string.
164
165           Example output:
166
167               home         GET  /
168               blog_monthly GET  /blog/{year}/{month}
169                            GET  /blog/{year:\d{1,4}}/{month:\d{2}}/{day:\d\d}
170                            POST /comment
171                            GET  /
172

AUTHOR

174       Tokuhiro Matsuno <tokuhirom AAJKLFJEF@ GMAIL COM>
175

THANKS TO

177       Tatsuhiko Miyagawa
178
179       Shawn M Moore
180
181       routes.py <http://routes.groovie.org/>.
182

THANKS TO

196       DeNA
197

LICENSE

199       Copyright (C) Tokuhiro Matsuno
200
201       This library is free software; you can redistribute it and/or modify it
202       under the same terms as Perl itself.
203
204
205
206perl v5.36.0                      2023-01-20                 Router::Simple(3)