1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
# 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.
|
