README
1NAME
2 Class::Forward - Namespace Dispatch and Resolution
3
4VERSION
5 version 0.100006
6
7SYNOPSIS
8 use Class::Forward;
9
10 # create a resolution object
11 my $res = Class::Forward->new(namespace => 'MyApp');
12
13 # returns MyApp::Data
14 say $res->forward('data');
15
16 # returns a MyApp::Data instance
17 my $data = $res->forward('data.new');
18
19 # returns the string /my_app/data
20 my $string = $res->reverse('data.new');
21
22 # returns MyApp::Data
23 say $res->forward($string);
24
25DESCRIPTION
26 Class::Forward is designed to resolve Perl namespaces from shorthand
27 (which is simply a file-path-like specification). Class::Forward can
28 also be used to dispatch method calls using said shorthand. See the
29 following exported functions for examples on how this can be used.
30
31EXPORTS
32 clsf
33 The exported function clsf is responsible for resolving your shorthand.
34 The following is an example of how it functions:
35
36 package App::Store;
37
38 use CGI;
39 use Class::Forward;
40
41 clsf; # returns App::Store
42 clsf './user'; # returns App::Store::User
43 clsf './user.new', name => 'N30'; # return a new App::Store::User object
44 clsf './user_profile.new'; # ... App::Store::UserProfile object
45 clsf '../user'; # returns App::User
46 clsf '//'; # returns App; (top of the calling class)
47 clsf '//.new'; # returns a new App object
48 clsf '//view'; # ... returns App::View
49 clsf '//view.new'; # ... returns a new App::View object
50 clsf '//view.new.render'; # ... dispatches methods in succession
51 clsf 'cgi'; # returns App::Store::Cgi
52 clsf '/cgi'; # returns Cgi (or CGI if already loaded)
53
54 1;
55
56 The clsf function takes two arguments, the shorthand to be translated,
57 and an optional list of arguments to be passed to the last method
58 appended to the shorthand.
59
60 clsr
61 The exported function clsr is responsible for resolving your shorthand.
62 The following is an example of how it functions:
63
64 package App::Store;
65
66 use CGI;
67 use Class::Forward;
68
69 clsr; # returns /app/store
70 clsr './user'; # returns /app/store/user
71 clsr './user.new', name => 'N30'; # returns /app/store/user
72 clsr './user_profile'; # returns /app/store/user_profile
73 clsr '../user'; # returns /app/user
74 clsr '//'; # returns /app
75 clsr '//.new'; # returns /app
76 clsr '//view'; # returns /app/view
77 clsr '//view.new'; # returns /app/view
78 clsr '//view.new.render'; # returns /app/view
79 clsr 'cgi'; # returns /app/store/cgi
80 clsr '/cgi'; # returns /cgi
81
82 1;
83
84 The clsr function takes three arguments, the shorthand to be translated
85 (required), the offset (optional level of namespace nodes to omit
86 left-to-right), and the delimiter to be used to generate the resulting
87 path (defaults to forward-slash).
88
89METHODS
90 new
91 The new method is used to instantiate a new instance.
92
93 namespace
94 The namespace method is used to get/set the root namespace used as an
95 anchor for all resolution requests.
96
97 my $namespace = $self->namespace('MyApp');
98
99 forward
100 The forward (or forward_lookup) method is used to resolve Perl
101 namespaces from path-like shorthand.
102
103 say $self->forward('example');
104 # given a default namespace of MyApp
105 # prints MyApp::Example
106
107 reverse
108 The reverse method (or reverse_lookup) is used to generate path-like
109 shorthand from Perl namespaces.
110
111 say $self->reverse('Simple::Example');
112 # given a default namespace of MyApp
113 # prints /my_app/simple/example
114
115 say $self->reverse('Simple::Example', 1);
116 # given a default namespace of MyApp
117 # prints simple/example
118
119 say $self->reverse('Simple::Example', 1, '_');
120 # given a default namespace of MyApp
121 # prints simple_example
122
123SEE ALSO
124 Class::Forward was designed to provide shorthand and easy access to
125 class namespaces in an environment where you're dealing with a multitude
126 of long well-named classes. In that vein, it provides an alternative to
127 modules like aliased, aliased::factory, as, and the like, and also
128 modules like Namespace::Dispatch which are similar enough to be
129 mentioned but really address a completely different issue.
130
131AUTHOR
132 Al Newkirk <anewkirk@ana.io>
133
134COPYRIGHT AND LICENSE
135 This software is copyright (c) 2012 by Al Newkirk.
136
137 This is free software; you can redistribute it and/or modify it under
138 the same terms as the Perl 5 programming language system itself.
139
140
README.mkdn
1# NAME
2
3Class::Forward - Namespace Dispatch and Resolution
4
5# VERSION
6
7version 0.100006
8
9# SYNOPSIS
10
11 use Class::Forward;
12
13 # create a resolution object
14 my $res = Class::Forward->new(namespace => 'MyApp');
15
16 # returns MyApp::Data
17 say $res->forward('data');
18
19 # returns a MyApp::Data instance
20 my $data = $res->forward('data.new');
21
22 # returns the string /my_app/data
23 my $string = $res->reverse('data.new');
24
25 # returns MyApp::Data
26 say $res->forward($string);
27
28# DESCRIPTION
29
30Class::Forward is designed to resolve Perl namespaces from shorthand (which is
31simply a file-path-like specification). Class::Forward can also be used to
32dispatch method calls using said shorthand. See the following exported
33functions for examples on how this can be used.
34
35# EXPORTS
36
37## clsf
38
39The exported function clsf is responsible for resolving your shorthand. The
40following is an example of how it functions:
41
42 package App::Store;
43
44 use CGI;
45 use Class::Forward;
46
47 clsf; # returns App::Store
48 clsf './user'; # returns App::Store::User
49 clsf './user.new', name => 'N30'; # return a new App::Store::User object
50 clsf './user_profile.new'; # ... App::Store::UserProfile object
51 clsf '../user'; # returns App::User
52 clsf '//'; # returns App; (top of the calling class)
53 clsf '//.new'; # returns a new App object
54 clsf '//view'; # ... returns App::View
55 clsf '//view.new'; # ... returns a new App::View object
56 clsf '//view.new.render'; # ... dispatches methods in succession
57 clsf 'cgi'; # returns App::Store::Cgi
58 clsf '/cgi'; # returns Cgi (or CGI if already loaded)
59
60 1;
61
62The clsf function takes two arguments, the shorthand to be translated, and an
63optional list of arguments to be passed to the last method appended to the
64shorthand.
65
66## clsr
67
68The exported function clsr is responsible for resolving your shorthand. The
69following is an example of how it functions:
70
71 package App::Store;
72
73 use CGI;
74 use Class::Forward;
75
76 clsr; # returns /app/store
77 clsr './user'; # returns /app/store/user
78 clsr './user.new', name => 'N30'; # returns /app/store/user
79 clsr './user_profile'; # returns /app/store/user_profile
80 clsr '../user'; # returns /app/user
81 clsr '//'; # returns /app
82 clsr '//.new'; # returns /app
83 clsr '//view'; # returns /app/view
84 clsr '//view.new'; # returns /app/view
85 clsr '//view.new.render'; # returns /app/view
86 clsr 'cgi'; # returns /app/store/cgi
87 clsr '/cgi'; # returns /cgi
88
89 1;
90
91The clsr function takes three arguments, the shorthand to be translated
92(required), the offset (optional level of namespace nodes to omit
93left-to-right), and the delimiter to be used to generate the resulting path
94(defaults to forward-slash).
95
96# METHODS
97
98## new
99
100The new method is used to instantiate a new instance.
101
102## namespace
103
104The namespace method is used to get/set the root namespace used as an anchor for
105all resolution requests.
106
107 my $namespace = $self->namespace('MyApp');
108
109## forward
110
111The forward (or forward\_lookup) method is used to resolve Perl namespaces from
112path-like shorthand.
113
114 say $self->forward('example');
115 # given a default namespace of MyApp
116 # prints MyApp::Example
117
118## reverse
119
120The reverse method (or reverse\_lookup) is used to generate path-like shorthand
121from Perl namespaces.
122
123 say $self->reverse('Simple::Example');
124 # given a default namespace of MyApp
125 # prints /my_app/simple/example
126
127 say $self->reverse('Simple::Example', 1);
128 # given a default namespace of MyApp
129 # prints simple/example
130
131 say $self->reverse('Simple::Example', 1, '_');
132 # given a default namespace of MyApp
133 # prints simple_example
134
135# SEE ALSO
136
137Class::Forward was designed to provide shorthand and easy access to class
138namespaces in an environment where you're dealing with a multitude of long
139well-named classes. In that vein, it provides an alternative to modules like
140[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
141[Namespace::Dispatch](http://search.cpan.org/perldoc?Namespace::Dispatch) which are similar enough to be mentioned but really
142address a completely different issue.
143
144# AUTHOR
145
146Al Newkirk <anewkirk@ana.io>
147
148# COPYRIGHT AND LICENSE
149
150This software is copyright (c) 2012 by Al Newkirk.
151
152This is free software; you can redistribute it and/or modify it under
153the same terms as the Perl 5 programming language system itself.
154