/ 
Router-PathInfo-0.03
River stage zero No dependents
/ Router::PathInfo::Controller

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

For example

   '/foo/bar/:any'
   '/foo/:re(:re(^\d{4}\w{4}$))/:any'
   '/:enum(foo|bar|baz)/:re(: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,
    segment => $arrayref
}

Otherwise, undef.

SEE ALSO

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

AUTHOR

mr.Rico <catamoose at yandex.ru>