README
1NAME
2 Method::Alias - Create method aliases (and do it safely)
3
4SYNOPSIS
5 # My method
6 sub foo {
7 ...
8 }
9
10 # Alias the method
11 use Method::Alias 'bar' => 'foo',
12 'baz' => 'foo';
13
14DESCRIPTION
15 For a very long time, whenever I wanted to have a method alias (provide
16 an alternate name for a method) I would simple do a GLOB alias. That is,
17
18 # My method
19 sub foo {
20 ...
21 }
22
23 # Alias the method
24 *bar = *foo;
25
26 While this works fine for functions, it does not work for methods.
27
28 If your class has a subclass that redefines "foo", any call to "bar"
29 will result in the overloaded method being ignored and the wrong "foo"
30 method being called.
31
32 These are basically bugs waiting to happen, and having completed a
33 number of very large APIs with lots of depth myself, I've been bitten
34 several times.
35
36 In this situation, the canonical and fasest way to handle an alias looks
37 something like this.
38
39 # My method
40 sub foo {
41 ...
42 }
43
44 # Alias the method
45 sub bar { shift->foo(@_) }
46
47 Note that this adds an extra entry to the caller array, but this isn't
48 really all that important unless you are paranoid about these things.
49
50 The alternative would be to try to find the method using UNIVERSAL::can,
51 and then goto it. I might add this later if someone really wants it, but
52 until then the basic method will suffice.
53
54 That doing this right is even worthy of a module is debatable, but I
55 would rather have something that looks like a method alias definition,
56 than have to document additional methods all the time.
57
58 Using Method::Alias
59 Method::Alias is designed to be used as a pragma, to which you provide a
60 set of pairs of method names. Only very minimal checking is done, if you
61 wish to create infinite loops or what have you, you are more than
62 welcome to shoot yourself in the foot.
63
64 # Add a single method alias
65 use Method::Alias 'foo' => 'bar';
66
67 # Add several method aliases
68 use Method::Alias 'a' => 'b',
69 'c' => 'd',
70 'e' => 'f';
71
72 And for now, that's all there is to it.
73
74METHODS
75 import from => to, ...
76 Although primarily used as a pragma, you may call import directly if you
77 wish.
78
79 Taking a set of pairs of normal strings, the import method creates a
80 number of methods in the caller's package to call the real method.
81
82 Returns true, or dies on error.
83
84SUPPORT
85 Bugs should always be submitted via the CPAN bug tracker
86
87 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Method-Alias>
88
89 For other issues, contact the maintainer
90
91AUTHORS
92 Adam Kennedy <cpan@ali.as>
93
94SEE ALSO
95 <http://ali.as/>
96
97COPYRIGHT
98 Copyright 2004, 2006 Adam Kennedy. All rights reserved.
99
100 This program is free software; you can redistribute it and/or modify it
101 under the same terms as Perl itself.
102
103 The full text of the license can be found in the LICENSE file included
104 with this module.
105
106