NAME
    Class::Forward - Namespace Dispatch and Resolution

VERSION
    version 0.100006

SYNOPSIS
        use Class::Forward;

        # create a resolution object
        my $res = Class::Forward->new(namespace => 'MyApp');

        # returns MyApp::Data
        say $res->forward('data');

        # returns a MyApp::Data instance
        my $data  = $res->forward('data.new');

        # returns the string /my_app/data
        my $string = $res->reverse('data.new');

        # returns MyApp::Data
        say $res->forward($string);

DESCRIPTION
    Class::Forward is designed to resolve Perl namespaces from shorthand
    (which is simply a file-path-like specification). Class::Forward can
    also be used to dispatch method calls using said shorthand. See the
    following exported functions for examples on how this can be used.

EXPORTS
  clsf
    The exported function clsf is responsible for resolving your shorthand.
    The following is an example of how it functions:

        package App::Store;

        use CGI;
        use Class::Forward;

        clsf;                             # returns App::Store
        clsf './user';                    # returns App::Store::User
        clsf './user.new', name => 'N30'; # return a new App::Store::User object
        clsf './user_profile.new';        # ... App::Store::UserProfile object
        clsf '../user';                   # returns App::User
        clsf '//';                        # returns App; (top of the calling class)
        clsf '//.new';                    # returns a new App object
        clsf '//view';                    # ... returns App::View
        clsf '//view.new';                # ... returns a new App::View object
        clsf '//view.new.render';         # ... dispatches methods in succession
        clsf 'cgi';                       # returns App::Store::Cgi
        clsf '/cgi';                      # returns Cgi (or CGI if already loaded)

        1;

    The clsf function takes two arguments, the shorthand to be translated,
    and an optional list of arguments to be passed to the last method
    appended to the shorthand.

  clsr
    The exported function clsr is responsible for resolving your shorthand.
    The following is an example of how it functions:

        package App::Store;

        use CGI;
        use Class::Forward;

        clsr;                             # returns /app/store
        clsr './user';                    # returns /app/store/user
        clsr './user.new', name => 'N30'; # returns /app/store/user
        clsr './user_profile';            # returns /app/store/user_profile
        clsr '../user';                   # returns /app/user
        clsr '//';                        # returns /app
        clsr '//.new';                    # returns /app
        clsr '//view';                    # returns /app/view
        clsr '//view.new';                # returns /app/view
        clsr '//view.new.render';         # returns /app/view
        clsr 'cgi';                       # returns /app/store/cgi
        clsr '/cgi';                      # returns /cgi

        1;

    The clsr function takes three arguments, the shorthand to be translated
    (required), the offset (optional level of namespace nodes to omit
    left-to-right), and the delimiter to be used to generate the resulting
    path (defaults to forward-slash).

METHODS
  new
    The new method is used to instantiate a new instance.

  namespace
    The namespace method is used to get/set the root namespace used as an
    anchor for all resolution requests.

        my $namespace = $self->namespace('MyApp');

  forward
    The forward (or forward_lookup) method is used to resolve Perl
    namespaces from path-like shorthand.

        say $self->forward('example');
        # given a default namespace of MyApp
        # prints MyApp::Example

  reverse
    The reverse method (or reverse_lookup) is used to generate path-like
    shorthand from Perl namespaces.

        say $self->reverse('Simple::Example');
        # given a default namespace of MyApp
        # prints /my_app/simple/example

        say $self->reverse('Simple::Example', 1);
        # given a default namespace of MyApp
        # prints simple/example

        say $self->reverse('Simple::Example', 1, '_');
        # given a default namespace of MyApp
        # prints simple_example

SEE ALSO
    Class::Forward was designed to provide shorthand and easy access to
    class namespaces in an environment where you're dealing with a multitude
    of long well-named classes. In that vein, it provides an alternative to
    modules like aliased, aliased::factory, as, and the like, and also
    modules like Namespace::Dispatch which are similar enough to be
    mentioned but really address a completely different issue.

AUTHOR
    Al Newkirk <anewkirk@ana.io>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 by Al Newkirk.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.