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.