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