NAME

Router::Pygmy - ultrasimple path router matching paths to names and args

VERSION

version 0.05

SYNOPSIS

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'"

DESCRIPTION

Router::Pygmy is a very simple straightforward router which maps paths to (name, args) and vice versa.

METHODS

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.

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.

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 ]

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)

Simplicity

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.

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.

DEPENDENCIES

None so far.

AUTHOR

Roman Daniel <roman.daniel@davosro.cz>

COPYRIGHT AND LICENSE

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.