NAME
    Path::Map - map paths to handlers

VERSION
    0.03

SYNOPSIS
        my $mapper = Path::Map->new(
            '/x/y/z' => 'XYZ',
            '/a/b/c' => 'ABC',
            '/a/b'   => 'AB',

            '/date/:year/:month/:day' => 'Date',
        );

        if (my $match = $mapper->lookup('/date/2013/12/25')) {
            # $match->handler is 'Date'
            # $match->variables is { year => 2012, month => 12, day => 25 }
        }

        # Add more mappings later
        $mapper->add_handler($path => $target)

DESCRIPTION
    This class maps paths to handlers. The paths can contain variable path
    segments, which match against any incoming path segment, where the
    matching segments are saved as named variables for later retrieval.

    Note that the handlers being mapped to can be any arbitrary data, not
    just strings as illustrated in the synopsis.

  Comparison with Path::Router
    This class fulfills some of the same jobs as Path::Router, with slightly
    different design goals. Broadly speaking, Path::Map is a lighter,
    faster, but less featureful version of Path::Router.

    I've listed a few points of difference here to help highlight the pros
    and cons of each class.

    Speed
        The main goal for Path::Map is lookup speed. Path::Router uses
        regexes to do lookups, but Path::Map uses hash lookups. Path::Map
        seems to be at least an order of magnitude faster based on my
        benchmarks, and performance doesn't degrade with the number of
        routes that are added. The main source of performance degradation
        for Path::Map is path *depth*, Path::Router degrades less with depth
        but more with width.

        This approach also means that the order in which routes are added
        makes no difference to Path::Map.

    Reversibility
        Path::Router has a specific aim of being reversible. That is to say
        you can construct a path from a set of parameters. Path::Map does
        not currently have this ability, patches welcome!

    Validation
        Path::Map has no built-in ability to validate path variables in any
        way. Obviously validation can be done externally after the fact, but
        that doesn't allow for the more complex routing rules possible in
        Path::Router.

        In other words, it's not possible for Path::Map to differentiate two
        path templates which differ only in the variable segments (e.g.
        "/blog/:name" vs "/blog/:id" where "id" matches "\d+" and "name"
        matches "\D+").

    Dependencies
        Path::Map has a very small dependency chain, whereas Path::Router is
        based on Moose, so has a relatively high dependency footprint. If
        you're already using Moose, there's obviously no additional cost in
        using Path::Router.

METHODS
  new
        $mapper = $class->new(@pairs)

    The constructor.

    Takes an even-sized list and passes each pair to "add_handler".

  add_handler
        $mapper->add_handler($path_template, $handler)

    Adds a single item to the mapping.

    The path template should be a string comprising slash-delimited path
    segments, where a path segment may contain any character other than the
    slash. Any segment beginning with a colon (":") denotes a mandatory
    named variable. Empty segments, including those implied by leading or
    trailing slashes are ignored.

    For example, these are all identical path templates:

        /a/:var/b
        a/:var/b/
        //a//:var//b//

    The order in which these templates are added has no bearing on the
    lookup, except that later additions with identical templates overwrite
    earlier ones.

  lookup
        $match = $mapper->lookup($path)

    Returns a Path::Map::Match object if the path matches a known path
    template, "undef" otherwise.

    The two main methods on the match object are:

    handler
        The handler that was matched, identical to whatever was originally
        passed to "add_handler".

    variables
        The named path variables as a hashref.

  handlers
        @handlers = $mapper->handlers()

    Returns all of the handlers in no particular order.

SEE ALSO
    Path::Router

AUTHOR
    Matt Lawrence <mattlaw@cpan.org>

COPYRIGHT
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

