# NAME Router::Simple - simple HTTP router # SYNOPSIS use Router::Simple; my $router = Router::Simple->new(); $router->connect('/', {controller => 'Root', action => 'show'}); $router->connect('/blog/{year}/{month}', {controller => 'Blog', action => 'monthly'}); my $app = sub { my $env = shift; if (my $p = $router->match($env)) { return "MyApp::C::$p->{controller}"->can($p->{action})->($env, $p->{args}); } else { [404, [], ['not found']]; } }; # DESCRIPTION Router::Simple is simple router class. The main purpose is dispatcher for web application. Router::Simple is [PSGI](http://search.cpan.org/search?mode=module&query=PSGI) friendly. # HOW TO WRITE ROUTING RULE ## plain string $router->connect( '/foo', { controller => 'Root', action => 'foo' } ); ## :name notation $router->connect( '/wiki/:page', { controller => 'WikiPage', action => 'show' } ); ... $router->match('/wiki/john'); # => {controller => 'WikiPage', action => 'show', args => { page => 'john' } } ':name' notation matches qr{([^/]+)}. ## '*' notation $router->connect( '/download/*.*', { controller => 'Download', action => 'file' } ); ... $router->match('/download/path/to/file.xml'); # => {controller => 'Download', action => 'file', splat => ['path/to/file', 'xml'] } '*' notation matches qr{(.+)}.You will got captured arguments as 'splat'. ## '{year}' notation $router->connect( '/blog/{year}', { controller => 'Blog', action => 'yearly' } ); ... $router->match('/blog/2010'); # => {controller => 'Blog', action => 'yearly', args => { year => 2010 } } '{year}' notation matches qr{([^/]+)}, and it will capture to 'args'. ## '{year:[0-9]+}' notation $router->connect( '/blog/{year:[0-9]+}/{month:[0-9]{2}}', { controller => 'Blog', action => 'monthly' } ); ... $router->match('/blog/2010/04'); # => {controller => 'Blog', action => 'monthly', args => { year => 2010, month => '04' } } You can specify the regexp for named capture. ## regexp $router->connect( qr{/blog/(\d+)/([0-9]{2})', { controller => 'Blog', action => 'monthly' } ); ... $router->match('/blog/2010/04'); # => {controller => 'Blog', action => 'monthly', splat => [2010, '04'] } You can use Perl5's powerful regexp directly. # METHODS - my $router = Router::Simple->new(); create new instance of Router::Simple. - $router->connect([$name, ] $pattern, $destination[, \%options]) Add new rule for $router. $router->connect( '/', { controller => 'Root', action => 'index' } ); $router->connect( 'show_entry', '/blog/:id', { controller => 'Blog', action => 'show' } ); $router->connect( '/blog/:id', { controller => 'Blog', action => 'show' } ); $router->connect( '/comment', { controller => 'Comment', action => 'new_comment' }, {method => 'POST'} ); define the new route to $router. You can specify the $destination as \%hashref or \&coderef.The coderef should have keys named __controller__ and __action__. You can specify some optional things to \%options.Current version supports 'method' and 'host'. 'method' is ArrayRef[String] or String, that matches __REQUEST_METHOD__ in $req. 'host' is String or Regexp, that matches __HTTP_HOST__ in $req. - $router->submapper([$pathprefix, ] %args) $router->submapper('/entry/, controller => 'Entry') $router->submapper(path_prefix => '/entry/, controller => 'Entry') This method is shorthand for creating new instance of [Router::Simple::Submapper](http://search.cpan.org/search?mode=module&query=Router::Simple::Submapper). The arguments will pass to Router::Simple::SubMapper->new(%args). - $router->match($req|$path) Match a URL against against one of the routes contained. $req is a [PSGI](http://search.cpan.org/search?mode=module&query=PSGI)'s $env or plain string. This method returns a plain hashref. If you are using +{ controller => 'Blog', action => 'daily' } style, then you got return value as following: { controller => 'Blog', action => 'daily', args => { year => 2010, month => '03', day => '04' }, } If you are using sub { ... } as action, you will get the following: { code => sub { 'DUMMY' }, args => { year => 2010, month => '03', day => '04' }, } Will return undef if no valid match is found. - $router->url_for($anchor, \%opts) generate path string from rule named $anchor. You must pass the each parameters to \%opts. my $router = Router::Simple->new(); $router->connect('articles', '/article', {controller => 'Article', action => 'index'}); $router->connect('edit_articles', '/article/{id}', {controller => 'Article', action => 'edit'}); $router->url_for('articles'); # => /articles $router->url_for('edit_articles', {id => 3}); # => /articles/3/edit - $router->as_string() Dump $router as string. The example output is following: home GET / blog_monthly GET /blog/{year}/{month} GET /blog/{year:\d{1,4}}/{month:\d{2}}/{day:\d\d} POST /comment GET / # AUTHOR Tokuhiro Matsuno # THANKS TO Tatsuhiko Miyagawa L. # SEE ALSO Router::Simple is inspired by L. [Path::Dispatcher](http://search.cpan.org/search?mode=module&query=Path::Dispatcher) is similar, but so complex. [Path::Router](http://search.cpan.org/search?mode=module&query=Path::Router) is heavy.It depend to [Moose](http://search.cpan.org/search?mode=module&query=Moose). [HTTP::Router](http://search.cpan.org/search?mode=module&query=HTTP::Router) has many deps.It doesn't well documented. [HTTPx::Dispatcher](http://search.cpan.org/search?mode=module&query=HTTPx::Dispatcher) is my old one.It does not provides OOish interface. # THANKS TO DeNA # LICENSE Copyright (C) Tokuhiro Matsuno This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.