# 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](http://search.cpan.org/perldoc?aliased), [aliased::factory](http://search.cpan.org/perldoc?aliased::factory), [as](http://search.cpan.org/perldoc?as), and the like, and also modules like
[Namespace::Dispatch](http://search.cpan.org/perldoc?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.
