/ 
Gears-0.001
/ Gears::Router::Location

NAME

Gears::Router::Location - A routing location with a pattern

SYNOPSIS

my $location = Gears::Router::Location::Subclass->new(
	pattern => '/user/:id',
	router => $router,
);

# Add child locations
my $child = $location->add('/profile', { name => 'profile' });

# Check if this location has children
if ($location->is_bridge) {
	# ...
}

# Compare a path against this location's pattern
my $match_data = $location->compare('/user/123');

# Build a URL from this location's pattern
my $url = $location->build(id => 123);

DESCRIPTION

Gears::Router::Location represents a single routing location with a pattern. Locations can have child locations, forming a hierarchical routing tree. Both router and location share common interface thourgh a role, so they can be used interchangeably to build the tree of locations. A location with child locations is called a "bridge".

Each location holds a pattern string and creates a pattern object to handle matching and URL building operations.

This is a base, abstract class. It must be reimplemented to at least override the _build_pattern_obj method. Take a look at Gears::Router::Location::Match for the simplest example of a subclass.

INTERFACE

Attributes

pattern

The pattern string for this location, such as /path.

Required in constructor

pattern_obj

A Gears::Router::Pattern object that handles the actual pattern matching and building operations. This is lazily built from the pattern string.

Not available in constructor

router

A weak reference to the parent Gears::Router object.

Required in constructor

locations

An array reference of child Gears::Router::Location objects.

Not available in constructor

Methods

new

$object = $class->new(%args)

A standard Mooish constructor. Consult "Attributes" section to learn what keys can key passed in %args.

add

$child_location = $location->add($pattern, $data = {})

Adds a new child location with the specified pattern. The child's pattern is automatically prepended with the parent's pattern. Returns the newly created child location object.

is_bridge

$bool = $location->is_bridge()

Returns true if this location has child locations, false otherwise.

compare

$match_data = $location->compare($path)

Compares the given path string against this location's pattern. Returns an array reference with matched data if successful, or undef if the path doesn't match.

Note that a successful match may also return an empty array reference, but never undef.

build

$string = $location->build(@build_data)

Builds a URI string from this location's pattern. The exact behavior is implementation-specific.