NAME
    Path::Mapper - map paths to handlers

VERSION
    0.01

SYNOPSIS
        my $mapper = Path::Mapper->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::Mapper 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::Mapper is lookup speed. Path::Router uses
        regexes to do lookups, but Path::Mapper uses hash lookups.
        Path::Mapper 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::Mapper 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::Mapper.

    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::Mapper does
        not currently have this ability, patches welcome!

    Validation
        Path::Mapper 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::Mapper 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::Mapper 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::Mapper::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.

