NAME

Router::PathInfo::Controller provides a mapping PATH_INFO to controllers.

SYNOPSIS

    # create instance
    my $r = Router::PathInfo::Controller->new();
    
    # describe connect
    $r->add_rule(connect => '/foo/:enum(bar|baz)/:any', action => ['some','bar']);
    
    # prepare arguments (this action to prepare $env hidden from you in the module Router::PathInfo)
    my $env = {PATH_INFO => '/foo/baz/bar', REQUEST_METHOD => 'GET'};
    my @segment = split '/', $env->{PATH_INFO}, -1; 
    shift @segment;
    $env->{'psgix.tmp.RouterPathInfo'} = {
        segments => [@segment],
        depth => scalar @segment 
    };
    
    # match
    my $res = $r->match($env);  
        #  $res =  HASH(0x93d74d8)
        #   'action' => ARRAY(0x99294e8)
        #      0  'some'
        #      1  'bar'
        #   'segment' => ARRAY(0x93d8038)
        #      0  'baz'
        #      1  'bar'
        #   'type' => 'controller'

    # or $res may by undef

DESCRIPTION

Router::PathInfo::Controller is used for matching sets of trees. Therefore, search matching is faster and more efficient, than a simple enumeration of regular expressions to search for a suitable result.

In the descriptions of 'connect' by adding rules, you can use these tokens:

    :any                                 - match with any segment
    :re(...some regular expression...)   - match with the specified regular expression
    :enum(...|...)                       - match with a segment from the set

and sub-attribute for rules

    :name(...)

For example

    '/foo/:name(some_name)bar/:any'
    '/foo/:re(^\d{4}\w{4}$)/:name(my_token):any'
    '/:enum(foo|bar|baz)/:re(^\d{4}\w{4}$)/:any'
 

All descriptions of the segments have a certain weight. Thus, the description :enum has the greatest weight, a description of :re weighs even less. Weakest coincidence is :any.

For all descriptions 'connect' using these tokens in the match will be returned to a special key 'segment' in which stores a list of all segments PATH_INFO they are responsible.

An important point: description 'connect' dominates over http method. Example:

    $r->add_rule(connect => '/foo/:any/baz', action => 'one', methods => ['GET','DELETE']);
    $r->add_rule(connect => '/foo/bar/:any', action => 'two');
    
    for '/foo/bar/baz' with GET -> 'two'

In action you can pass any value: object, arrayref, hashref or a scalar.

METHODS

new()

Simple constructor

add_rule(connect => $describe_connect, action => $action_token[, methods => $arrayref, match_callback => $code_ref])

Add your description to match.

'methods' - arrayref of items GET, POST, PUT, OPTIONS, DELETE, HEAD

'match_callback' - coderef is called after match found. It takes two arguments: a match found and heshref passed parameters (see method match). Example:

    $r->add_rule(
        connect => '/foo/:enum(bar|baz)/:any', 
        action => ['any thing'], 
        methods => ['POST'], 
        match_callback => sub {
            my ($match, $env) = @_;
            
            if ($env->{...} == ..) {
                # $match->{action}->[0] eq 'any thing'
                return $match;
            } else {
                return {
                    type  => 'error',
                    code => 403,
                    desc  => 'blah-blah'   
                }; 
            }
        }
    );

match({REQUEST_METHOD => ..., 'psgix.tmp.RouterPathInfo' => ...})

Search match. See SYNOPSIS.

If a match is found, it returns hashref:

    {
        type => 'controller',
        action => $action,
        name_segments => $arrayref
    }

Otherwise, undef.

SEE ALSO

Router::PathInfo, Router::PathInfo::Static

AUTHOR

mr.Rico <catamoose at yandex.ru>

cpanm Router::PathInfo

perl -MCPAN -e shell
install Router::PathInfo