/ 
Kelp-2.17
River stage two • 19 direct dependents • 20 total dependents
/ Kelp::Routes::Pattern

NAME

Kelp::Routes::Pattern - Route patterns for Kelp routes

SYNOPSIS

my $p = Kelp::Routes::Pattern->new( pattern => '/:name/:place' );
if ( $p->match('/james/london') ) {
    %named = %{ $p->named };    # ( name => 'james', place => 'london' )
    @param = @{ $p->param };    # ( 'james', 'london' )
}

DESCRIPTION

This module is needed by Kelp::Routes. It provides matching for individual route patterns, returning the named placeholders in a hash and an array.

ATTRIBUTES

pattern

The pattern to match against. Each pattern is a string, which may contain named placeholders. For more information on the types and use of placeholders, look at "PLACEHOLDERS" in Kelp::Routes.

my $p = Kelp::Routes::Patters->new( pattern => '/:id/*other' );
...
$p->match('/4/something-else');    # True

method

Specifies an HTTP method to be matched by the route.

my $p = Kelp::Routes::Patters->new(
    pattern => '/:id/*other',
    method  => 'PUT'
);

$p->match('/4/something-else', 'GET');    # False. Only PUT allowed.

name

You are encouraged to give each route a name, so you can look it up later when you build a URL for it.

my $p = Kelp::Routes::Patters->new(
    pattern => '/:id/*other',
    name    => 'other_id'
);
...

say $p->build( 'other_id', id => '100', other => 'something-else' );
# Prints '/100/something-else'

If no name is provided for the route, the pattern is used.

has_name

A boolean signifying whether this route was originally given a specific name. It will be false if the name was taken from pattern.

check

A hashref with placeholder names as keys and regular expressions as values. It is used to match the values of the placeholders against the provided regular expressions.

my $p = Kelp::Routes::Patters->new(
    pattern => '/:id/*other',
    check   => { id => qr/\d+/ }    # id may only be a didgit
);

$p->match('/4/other');    # True
$p->match('/q/other');    # False

Note: Do not add ^ at the beginning or $ at the end of the regular expressions, because they are merged into a bigger regex.

defaults

A hashref with placeholder defaults. This only applies to optional placeholders, or those prefixed with a question mark. If a default value is provided for any of them, it will be used in case the placeholder value is missing.

my $p = Kelp::Routes::Patters->new(
    pattern  => '/:id/?other',
    defaults => { other => 'info' }
);

$p->match('/100');
# $p->named will contain { id => 100, other => 'info' }

$p->match('/100/delete');
# $p->named will contain { id => 100, other => 'delete' }

bridge

A True/False value. Specifies if the route is a bridge. For more information about bridges, please see "BRIDGES" in Kelp::Routes

regex

We recommend that you stick to using patterns, because they are simpler and easier to read, but if you need to match a really complicated route, then you can use a regular expression.

my $p = Kelp::Routes::Patters->new( regex => qr{^(\d+)/(\d+)$} );
$p->match('/100/200');  # True. $p->param will be [ 100, 200 ]

After matching, the "param" array will be initialized with the values of the captures in the order they appear in the regex. If you used a regex with named captures, then a hashref "named" will also be initialized with the names and values of the named placeholders. In other words, this hash will be a permanent copy of the %+ built-in hash.

my $p = Kelp::Routes::Patters->new( regex => qr{^(?<id>\d+)/(?<line>\d+)$} );
$p->match('/100/200');  # True.
                        # $p->param will be [ 100, 200 ]
                        # $p->named will be { id => 100, line => 200 }

If regex is not explicitly given a value it will be built from the pattern.

named

A hashref which will be initialized by the "match" function. After matching, it will contain placeholder names and values for the matched route.

param

An arrayref, which will be initialized by the "match" function. After matching, it will contain all placeholder values in the order they were specified in the pattern.

to

Specifies the route destination. See examples in Kelp::Routes.

dest

The loaded destination. An array reference with two values, a controller name (or undef if not a controller) and the code reference to the method. It will be automatically generated by the router based on the contents of "to".

METHODS

match

match( $path, $method )

Matches an already initialized route against a path and http method. If the match was successful, this sub will return a true value and the "named" and "param" attributes will be initialized with the names and values of the matched placeholders.

build

build( %args )

Builds a URL from a pattern.

my $p = Kelp::Routes::Patters->new( pattern  => '/:id/:line/:row' );
$p->build( id => 100, line => 5, row => 8 ); # Returns '/100/5/8'

If the pattern contains an unnamed wildcard * or slurpy >, then it should be built like this:

my $p = Kelp::Routes::Patters->new( pattern  => '/hello/*/>' );
$p->build( '*' => 'kelp', '>' => 'world' ); # Returns '/hello/kelp/world'

If the pattern contains more than one unnamed items, then you should probably give them some names.

ACKNOWLEDGEMENTS

This module was inspired by Routes::Tiny.

The concept of bridges was borrowed from Mojolicious