/ 
Router-Ragel-0.01
/ Router::Ragel

NAME

Router::Ragel - A high-performance URL router using the Ragel finite state machine

SYNOPSIS

use Router::Ragel;

# Create a new router
my $router = Router::Ragel->new;

# Add routes
$router->add('/users', { controller => 'users', action => 'index' });
$router->add('/users/:id', { controller => 'users', action => 'show' });
$router->add('/blog/:year/:month/:slug', { controller => 'blog', action => 'post' });

# Compile the routes (must be done before matching)
$router->compile;

# Match a path
my ($route_data, @captures) = $router->match('/users/42');
# $route_data = { controller => 'users', action => 'show' }
# @captures = ('42')

my ($blog_data, @blog_captures) = $router->match('/blog/2023/04/perl-routing');
# $blog_data = { controller => 'blog', action => 'post' }
# @blog_captures = ('2023', '04', 'perl-routing')

# Non-matching path returns empty list
my @no_match = $router->match('/nonexistent');
# @no_match = ()

DESCRIPTION

Router::Ragel is a fast URI path router for Perl applications that uses the Ragel state machine compiler to generate efficient C code for route matching. This approach offers significant performance advantages over regex-based routers, especially for applications with many routes or high request volumes.

The router supports:

  • Static routes (/users, /products)

  • Dynamic routes with named placeholders (/users/:id, /blog/:year/:month/:day)

  • Multiple independent router instances

METHODS

new

my $router = Router::Ragel->new;

Creates a new router instance.

add($pattern, $data)

$router->add('/users', { controller => 'users', action => 'index' });
$router->add('/users/:id', { controller => 'users', action => 'show' });
$router->add('/api', $whatever);

Adds a route to the router. The $pattern parameter defines the URL pattern to match, and $data is the data to be returned when the pattern matches.

Patterns can include named placeholders that start with a colon, like :id or :slug. These placeholders will capture the corresponding segments from the URL path.

compile

$router->compile;

Compiles the routes into a Ragel state machine. This method must be called after adding all routes and before attempting to match any paths.

match($path)

my ($route_data, @captures) = $router->match('/users/42');

Matches a path against the compiled routes. Returns the route data and any captured values from placeholders.

If the path doesn't match any route, an empty list is returned.

ROUTE PATTERNS

Route patterns are strings that define the URL paths to match. They can include:

  • Static segments: /users, /products

  • Named placeholders: :id, :slug, :year

Named placeholders start with a colon (:) and match any characters except for a forward slash (/). The values captured by these placeholders are returned as additional values from the match method.

Examples:

'/users'                  # Matches only '/users'
'/users/:id'              # Matches '/users/42', '/users/john', etc.
'/blog/:year/:month/:day' # Matches '/blog/2023/04/15', etc.

MULTIPLE ROUTERS

You can create multiple independent router instances:

my $api_router = Router::Ragel->new;
$api_router->add('/api/users', 'api_users_handler');

my $admin_router = Router::Ragel->new;
$admin_router->add('/admin/users', 'admin_users_handler');

$api_router->compile;
$admin_router->compile;

PERFORMANCE

Router::Ragel is designed for high performance. According to benchmarks, it outperforms other popular Perl routing libraries:

Benchmark comparing Router::XS (XS), Router::R3 (R3), URI::Router (UR), and Router::Ragel (Ragel):

                   Rate R3(method) R3(fun) XS(fun) UR(method) UR(fun) Ragel(method) Ragel(fun)
R3(method)     265481/s         --     -4%    -57%       -58%    -63%          -70%       -77%
R3(fun)        276801/s         4%      --    -55%       -56%    -61%          -68%       -76%
XS(fun)        613304/s       131%    122%      --        -2%    -14%          -30%       -47%
UR(method)     625570/s       136%    126%      2%         --    -12%          -29%       -45%
UR(fun)        710874/s       168%    157%     16%        14%      --          -19%       -38%
Ragel(method)  877196/s       230%    217%     43%        40%     23%            --       -24%
Ragel(fun)    1146879/s       332%    314%     87%        83%     61%           31%         --

ref: ex/bench.pl

HOW IT WORKS

Router::Ragel uses the Ragel state machine compiler to generate efficient C code for route matching. The workflow is:

1. Create a new router instance
2. Add routes with patterns and associated data
3. Compile the routes, which generates a Ragel state machine in C
4. Match incoming paths against the compiled state machine

The compiled state machine is highly optimized for path matching and can handle a large number of routes with minimal overhead.

LIMITATIONS

  • Router::Ragel assumes input as byte strings

  • The compile method must be called after adding all routes and before matching

SEE ALSO

AUTHOR

Yegor Korablev

LICENSE AND COPYRIGHT

This software is copyright (c) 2025 by Yegor Korablev.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.