Router::Pygmy - ultrasimple path router matching paths to names and args
version 0.05
use Router::Pygmy; my $router = Router::Pygmy->new; $router->add_route( 'tree/:species/branches', 'tree.branches' ); $router->add_route( 'tree/:species/:branch', 'tree.branch' ); $router->add_route( 'tree/:species/:branch/nut', 'tree.nut' ); # mapping path to ($name, \@args) or ($name, \%params) my ($name, $args) = $router->match('tree/oak/branches'); # yields ('tree.branches', ['oak'] ) my ($name, $params) = $router->match_named('tree/oak/branches'); # yields ('tree.branches', [species=>'oak']) my ($name, $args) = $router->match('tree/oak/12'); # yields ('tree.branch', [ 'oak', 12 ] ) my ($name, $params) = $router->match_named('tree/oak/12'); # yields ('tree.branch', [ species=> 'oak', branch => 12 ] ) my ($name, $args) = $router->match('tree/oak/12/ut'); # yields () # branches cannot serve as a value for :branch parameter my ($name, $args) = $router->match('tree/oak/branches/nut'); # yields () not ('tree.branches', ['branches']) # reverse routing # # mapping ($name, \%args) or ($name, \@args) to $path # path arguments can be \@args (positional), \%params (named) or $arg (single positional) my $path = $router->path_for( 'tree.branches', ['ash'] ); # yields 'tree/ash/branches' my $path = $router->path_for( 'tree.branches', 'ash' ); # yields 'tree/ash/branches' my $path = $router->path_for( 'tree.branches', { species => 'ash' } ); # yields 'tree/ash/branches' # If you supply invalid number or invalid names of args an exception is thrown my $path = $router->path_for( 'tree.branches', { pecies => 'ash' } ); # throws "Invalid args for route 'tree/:species/branches', got ('pecies') expected ('species')" # If name cannot be found, also the error is thrown my $path = $router->path_for( 'tree.root', [ 'ash', 12, 3 ] ); # throws "No route 'tree.root'"
Router::Pygmy is a very simple straightforward router which maps paths to (name, args) and vice versa.
new
my $router = Router::Pygmy->new; my $router = Router::Pygmy->new(routes => \%hash );
a constructor
add_route($route, $name)
$router->add_route( 'tree/:species/branches', 'tree.branches' );
Adds mapping. Both $path and $name args must be strings. The $route can contain parameter names in form of :identifier. You cannot (intentionally) have two paths leading to the same name.
$path
$name
$route
:
match($path)
my ($name, $args) = $router->match("tree/walnut/branches");
Maps $path to list ($name, $args) where $args is the arrayref of values of path params. Returns an empty list if no route matches.
$args
match_named($path)
my ($name, $args) = $router->match_named("tree/walnut/branches");
Same as match only the second element of the list is an arrayref with key value pairs [ param_name => param_value, param_name => param_value ]
match
path_for($name, $args)
Constructs the path for a $name
my $path = $router->path_for("tree.branches", ["walnut"]);
The $args can be either positional, names single string or nothing (if path has no parameter)
Route::Pygmy is very simple and thuse maybe of limited use. There are no parameter validations, no default param values, "the target" is always a string.
Also it must be noted that fixed parts have an absolute precedence over parameters. If two routes shares the start and then one follows with a fixed part and the other one with a parameter, then the parameter can never have the value of fixed part even if it leads to no match. It is also the intention.
Having routes like this:
$router->add_route( 'tree/:species/branches', 'tree.branches' ); $router->add_route( 'tree/search', 'tree.search' );
the path tree/search/branches doesnot match.
tree/search/branches
At the other hand the mapping is fast. For the direct mapping path to ($name, $args) it is a simple DFA, the reverse mapping ($name, $args) is a simple hash lookup.
None so far.
Roman Daniel <roman.daniel@davosro.cz>
This software is copyright (c) 2014 by Roman Daniel.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Router::Pygmy, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Router::Pygmy
CPAN shell
perl -MCPAN -e shell install Router::Pygmy
For more information on module installation, please visit the detailed CPAN module installation guide.