1aliased(3pm)          User Contributed Perl Documentation         aliased(3pm)
2
3
4

NAME

6       aliased - Use shorter versions of class names.
7

VERSION

9       version 0.34
10

SYNOPSIS

12         # Class name interface
13         use aliased 'My::Company::Namespace::Customer';
14         my $cust = Customer->new;
15
16         use aliased 'My::Company::Namespace::Preferred::Customer' => 'Preferred';
17         my $pref = Preferred->new;
18
19
20         # Variable interface
21         use aliased;
22         my $Customer  = alias "My::Other::Namespace::Customer";
23         my $cust      = $Customer->new;
24
25         my $Preferred = alias "My::Other::Namespace::Preferred::Customer";
26         my $pref      = $Preferred->new;
27

DESCRIPTION

29       "aliased" is simple in concept but is a rather handy module.  It loads
30       the class you specify and exports into your namespace a subroutine that
31       returns the class name.  You can explicitly alias the class to another
32       name or, if you prefer, you can do so implicitly.  In the latter case,
33       the name of the subroutine is the last part of the class name.  Thus,
34       it does something similar to the following:
35
36         #use aliased 'Some::Annoyingly::Long::Module::Name::Customer';
37
38         use Some::Annoyingly::Long::Module::Name::Customer;
39         sub Customer {
40           return 'Some::Annoyingly::Long::Module::Name::Customer';
41         }
42         my $cust = Customer->new;
43
44       This module is useful if you prefer a shorter name for a class.  It's
45       also handy if a class has been renamed.
46
47       (Some may object to the term "aliasing" because we're not aliasing one
48       namespace to another, but it's a handy term.  Just keep in mind that
49       this is done with a subroutine and not with typeglobs and weird
50       namespace munging.)
51
52       Note that this is only for "use"ing OO modules.  You cannot use this to
53       load procedural modules.  See the "Why OO Only?" section.  Also, don't
54       let the version number fool you.  This code is ridiculously simple and
55       is just fine for most use.
56
57   Implicit Aliasing
58       The most common use of this module is:
59
60         use aliased 'Some::Module::name';
61
62       "aliased" will  allow you to reference the class by the last part of
63       the class name.  Thus, "Really::Long::Name" becomes "Name".  It does
64       this by exporting a subroutine into your namespace with the same name
65       as the aliased name.  This subroutine returns the original class name.
66
67       For example:
68
69         use aliased "Acme::Company::Customer";
70         my $cust = Customer->find($id);
71
72       Note that any class method can be called on the shorter version of the
73       class name, not just the constructor.
74
75   Explicit Aliasing
76       Sometimes two class names can cause a conflict (they both end with
77       "Customer" for example), or you already have a subroutine with the same
78       name as the aliased name.  In that case, you can make an explicit alias
79       by stating the name you wish to alias to:
80
81         use aliased 'Original::Module::Name' => 'NewName';
82
83       Here's how we use "aliased" to avoid conflicts:
84
85         use aliased "Really::Long::Name";
86         use aliased "Another::Really::Long::Name" => "Aname";
87         my $name  = Name->new;
88         my $aname = Aname->new;
89
90       You can even alias to a different package:
91
92         use aliased "Another::Really::Long::Name" => "Another::Name";
93         my $aname = Another::Name->new;
94
95       Messing around with different namespaces is a really bad idea and you
96       probably don't want to do this.  However, it might prove handy if the
97       module you are using has been renamed.  If the interface has not
98       changed, this allows you to use the new module by only changing one
99       line of code.
100
101         use aliased "New::Module::Name" => "Old::Module::Name";
102         my $thing = Old::Module::Name->new;
103
104   Import Lists
105       Sometimes, even with an OO module, you need to specify extra arguments
106       when using the module.  When this happens, simply use "Explicit
107       Aliasing" followed by the import list:
108
109       Snippet 1:
110
111         use Some::Module::Name qw/foo bar/;
112         my $o = Some::Module::Name->some_class_method;
113
114       Snippet 2 (equivalent to snippet 1):
115
116         use aliased 'Some::Module::Name' => 'Name', qw/foo bar/;
117         my $o = Name->some_class_method;
118
119       Note:  remember, you cannot use import lists with "Implicit Aliasing".
120       As a result, you may simply prefer to only use "Explicit Aliasing" as a
121       matter of style.
122
123   alias()
124       This function is only exported if you specify "use aliased" with no
125       import list.
126
127           use aliased;
128           my $alias = alias($class);
129           my $alias = alias($class, @imports);
130
131       alias() is an alternative to "use aliased ..." which uses less magic
132       and avoids some of the ambiguities.
133
134       Like "use aliased" it "use"s the $class (pass in @imports, if given)
135       but instead of providing an "Alias" constant it simply returns a scalar
136       set to the $class name.
137
138           my $thing = alias("Some::Thing::With::A::Long::Name");
139
140           # Just like Some::Thing::With::A::Long::Name->method
141           $thing->method;
142
143       The use of a scalar instead of a constant avoids any possible ambiguity
144       when aliasing two similar names:
145
146           # No ambiguity despite the fact that they both end with "Name"
147           my $thing = alias("Some::Thing::With::A::Long::Name");
148           my $other = alias("Some::Other::Thing::With::A::Long::Name");
149
150       and there is no magic constant exported into your namespace.
151
152       The only caveat is loading of the $class happens at run time.  If
153       $class exports anything you might want to ensure it is loaded at
154       compile time with:
155
156           my $thing;
157           BEGIN { $thing = alias("Some::Thing"); }
158
159       However, since OO classes rarely export this should not be necessary.
160
161   prefix() (experimental)
162       This function is only exported if you specify "use aliased" with no
163       import list.
164
165           use aliased;
166
167       Sometimes you find you have a ton of packages in the same top-level
168       namespace and you want to alias them, but only use them on demand.  For
169       example:
170
171           # instead of:
172           MailVerwaltung::Client::Exception::REST::Response->throw()
173
174           my $error = prefix('MailVerwaltung::Client::Exception');
175           $error->('REST::Response')->throw();   # same as above
176           $error->()->throw; # same as MailVerwaltung::Client::Exception->throw
177
178   Why OO Only?
179       Some people have asked why this code only support object-oriented
180       modules (OO).  If I were to support normal subroutines, I would have to
181       allow the following syntax:
182
183         use aliased 'Some::Really::Long::Module::Name';
184         my $data = Name::data();
185
186       That causes a serious problem.  The only (reasonable) way it can be
187       done is to handle the aliasing via typeglobs.  Thus, instead of a
188       subroutine that provides the class name, we alias one package to
189       another (as the namespace module does.)  However, we really don't want
190       to simply alias one package to another and wipe out namespaces willy-
191       nilly.  By merely exporting a single subroutine to a namespace, we
192       minimize the issue.
193
194       Fortunately, this doesn't seem to be that much of a problem.  Non-OO
195       modules generally support exporting of the functions you need and this
196       eliminates the need for a module such as this.
197

EXPORT

199       This modules exports a subroutine with the same name as the "aliased"
200       name.
201

SEE ALSO

203       The namespace module.
204

THANKS

206       Many thanks to Rentrak, Inc. (http://www.rentrak.com/) for graciously
207       allowing me to replicate the functionality of some of their internal
208       code.
209

AUTHOR

211       Curtis "Ovid" Poe <ovid@cpan.org>
212
214       This software is copyright (c) 2005 by Curtis "Ovid" Poe.
215
216       This is free software; you can redistribute it and/or modify it under
217       the same terms as the Perl 5 programming language system itself.
218

CONTRIBUTORS

220       •   Karen Etheridge <ether@cpan.org>
221
222       •   Curtis Poe <ovid@cpan.org>
223
224       •   Ovid <curtis_ovid_poe@yahoo.com>
225
226       •   Florian Ragwitz <rafl@debian.org>
227
228       •   Grzegorz Rożniecki <xaerxess@gmail.com>
229
230       •   Father Chrysostomos <sprout@cpan.org>
231
232       •   Belden Lyman <belden@shutterstock.com>
233
234       •   Olivier Mengué <dolmen@cpan.org>
235
236
237
238perl v5.38.0                      2023-07-21                      aliased(3pm)
Impressum