1NAME
2 Lexical::Alias - makes a lexical an alias for another variable
3
4SYNOPSIS
5 use 5.008;
6 use Lexical::Alias;
7
8 my ($src, $dst);
9 alias $src, $dst;
10
11 my (@src, @dst);
12 alias @src, @dst;
13
14 my (%src, %dst);
15 alias %src, %dst;
16
17 # modifying $src/@src/%src
18 # modifies $dst/@dst/%dst,
19 # and vice-versa
20
21 # or, if supporting Perls prior to v5.8:
22
23 use Lexical::Alias qw( alias_r alias_s alias_a alias_h );
24
25 my ($src, $dst);
26 alias_s $src, $dst;
27
28 my (@src, @dst);
29 alias_a @src, @dst;
30
31 my (%src, %dst);
32 alias_h %src, %dst;
33
34 alias_r \$src, \$dst;
35 alias_r \@src, \@dst;
36 alias_r \%src, \%dst;
37
38 # if you prefer the alias come first...
39 $Lexical::Alias::SWAP = 1;
40 alias $dst, $src; # $dst is an alias for $src
41
42DESCRIPTION
43 This module allows you to alias a lexical (declared with "my") variable
44 to another variable (package or lexical). You will receive a fatal error
45 if you try aliasing a scalar to something that is not a scalar (etc.).
46
47 Parameter Swaping (new!)
48 Version 0.04 introduced the $Lexical::Alias::SWAP variable. When it is
49 true, the arguments to the aliasing functions are expected in reverse
50 order; that is, the alias comes *first*, and the source variable second.
51
52 (Thanks to Jenda from perlmonks.org for requesting this.)
53
54 Exported Functions
55 * "alias(src, dst)"
56 Makes *dst* (which must be lexical) an alias to *src* (which can be
57 either lexical or a package variable). *src* and *dst* must be the
58 same data type (scalar and scalar, array and array, hash and hash).
59
60 This is only available in Perl v5.8 and later, where it is exported
61 automatically.
62
63 * "alias_s($src, $dst)"
64 Makes *dst* (which must be lexical) an alias to *src* (which can be
65 either lexical or a package variable). This is not exported by
66 default.
67
68 * "alias_a(@src, @dst)"
69 Makes *dst* (which must be lexical) an alias to *src* (which can be
70 either lexical or a package variable). This is not exported by
71 default.
72
73 * "alias_h(%src, %dst)"
74 Makes *dst* (which must be lexical) an alias to *src* (which can be
75 either lexical or a package variable). This is not exported by
76 default.
77
78 * "alias_r(\src, \dst)"
79 Makes *dst* (which must be lexical) an alias to *src* (which can be
80 either lexical or a package variable). *src* and *dst* must be the
81 same data type (scalar and scalar, array and array, hash and hash).
82 This is not exported by default.
83
84 Caveats
85 If you alias one lexical to another lexical, then making another alias
86 to either lexical makes *all three lexicals* point to the same data.
87
88 use Lexical::Alias;
89
90 my ($x, $y, $z);
91 alias $x => $y; # $y is an alias for $x
92 alias $z => $y; # $y (and thus $x) is an alias for $z
93 $z = 10;
94 print $x; # 10
95
96 This is not a bug.
97
98 However, there *does* appear to be a bug in Perl 5.8.0 (which has been
99 fixed in the development version 5.9.0); when these functions are used
100 in a subroutine, they appear to not work fully:
101
102 my $orig = 1;
103 my $alias = 99;
104 alias $orig => $alias;
105 print "$orig = $alias\n";
106
107 sub foo {
108 my $orig = 1;
109 my $alias = 99;
110 alias $orig => $alias;
111 print "foo(): $orig = $alias\n";
112 }
113
114 foo();
115
116 The expected output is "1 = 1" and "foo(): 1 = 1". It is not so. The
117 second output is "foo(): 1 = 99". Jenda pointed this out to me, and I do
118 not know where in the source the bug is, but it will be fixed for the
119 next release of Perl (5.8.1).
120
121AUTHOR
122 Jeff "japhy" Pinyan, japhy@pobox.com
123
124 Thanks to Tye McQueen for a bug fix -- this module should work from
125 5.005 on.
126
127 http://www.pobox.com/~japhy/
128
129SEE ALSO
130 Devel::LexAlias, by Richard Clamp, from which I got (and modified) the
131 code necessary for this module. I've wanted this feature for some time,
132 and Richard opened the door with this module.
133
134 Variable::Alias, by Brent Dax, which is a tie() interface to aliasing
135 all sorts of variables.
136
137