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

via

Specifies an HTTP method to be matched by the route.

    my $p = Kelp::Routes::Patters->new(
        pattern => '/:id/*other',
        via     => '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.

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.

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'

ACKNOWLEDGEMENTS

This module was inspired by Routes::Tiny.

The concept of bridges was borrowed from Mojolicious

cpanm Kelp

perl -MCPAN -e shell
install Kelp