focal (3) Class::Forward.3pm.gz

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.