2 Variable::Magic - Associate user-defined magic to variables from Perl.
8 use Variable::Magic qw/wizard cast dispell/;
10 my $wiz = wizard set => sub { print STDERR "now set to $_[0]!\n" };
13 $a = 2; # "now set to 2!"
18 Magic is Perl way of enhancing objects. This mechanism let the user add
19 extra data to any variable and overload syntaxical operations (such as
20 access, assignation or destruction) that can be applied to it. With this
21 module, you can add your own magic to any variable without the pain of
24 The operations that can be overloaded are :
27 This magic is invoked when the variable is evaluated (does not
28 include array/hash subscripts and slices).
31 This one is triggered each time the value of the variable changes
32 (includes array/hash subscripts and slices).
35 This magic is a little special : it is called when the 'size' or the
36 'length' of the variable has to be known by Perl. Typically, it's
37 the magic involved when an array is evaluated in scalar context, but
38 also on array assignation and loops ("for", "map" or "grep"). The
39 callback has then to return the length as an integer.
42 This magic is invoked when the variable is reset, such as when an
43 array is emptied. Please note that this is different from undefining
44 the variable, even though the magic is called when the clearing is a
45 result of the undefine (e.g. for an array, but actually a bug
46 prevent it to work before perl 5.9.5 - see the history).
49 This last one can be considered as an object destructor. It happens
50 when the variable goes out of scope (with the exception of global
51 scope), but not when it is undefined.
53 To prevent any clash between different magics defined with this module,
54 an unique numerical signature is attached to each kind of magic (i.e.
55 each set of callbacks for magic operations).
59 'len' magic is no longer called when pushing an element into a magic
63 'clear' magic wasn't invoked when undefining an array. The bug is fixed
68 The minimum integer used as a signature for user-defined magic.
71 The maximum integer used as a signature for user-defined magic.
74 SIG_NBR = SIG_MAX - SIG_MIN + 1
78 wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => ..
80 This function creates a 'wizard', an opaque type that holds the magic
81 information. It takes a list of keys / values as argument, whose keys
85 The numerical signature. If not specified or undefined, a random
86 signature is generated.
89 A code reference to a private data constructor. It will be called
90 each time this magic is cast on a variable, and the scalar returned
91 will be used as private data storage for it.
93 'get', 'set', 'len', 'clear' and 'free'
94 Code references to corresponding magic callbacks. You don't have to
95 specify all of them : the magic associated with undefined entries
96 simply won't be hooked. When the magic variable is an array or a
97 hash, $_[0] is a reference to it, but directly references it
98 otherwise. $_[1] is the private data (or "undef" when no private
99 data constructor was supplied). In the special case of "len" magic
100 and when the variable is an array, $_[2] contains its normal length.
102 # A simple scalar tracer
103 my $wiz = wizard get => sub { print STDERR "got $_[0]\n" },
104 set => sub { print STDERR "set to $_[0]\n" },
105 free => sub { print STDERR "$_[0] was deleted\n" }
108 With this tool, you can manually generate random magic signature between
109 SIG_MIN and SIG_MAX inclusive. That's the way "wizard" creates them when
110 no signature is supplied.
112 # Generate a signature
118 This accessor returns the magic signature of this wizard.
121 my $sig = getsig $wiz;
124 cast [$@%&*]var, $wiz
126 This function associates $wiz magic to the variable supplied, without
127 overwriting any other kind of magic. It returns true on success or when
128 $wiz magic is already present, and false on error.
132 die 'error' unless cast $x, $wiz;
135 getdata [$@%&*]var, $wiz
137 This accessor fetches the private data associated with the magic $wiz in
138 the variable. "undef" is returned when no such magic or data is found.
141 dispell [$@%&*]variable, $wiz
142 dispell [$@%&*]variable, $sig
144 The exact opposite of "cast" : it dissociates $wiz magic from the
145 variable. You can also pass the magic signature as the second argument.
146 True is returned on success, and false on error or when no magic
147 represented by $wiz could be found in the variable.
150 die 'no such magic or error' unless dispell $x, $wiz;
153 The functions "wizard", "gensig", "getsig", "cast", "getdata" and
154 "dispell" are only exported on request. All of them are exported by the
155 tags ':funcs' and ':all'.
157 The constants "SIG_MIN", "SIG_MAX" and "SIG_NBR" are also only exported
158 on request. They are all exported by the tags ':consts' and ':all'.
161 Carp (standard since perl 5), XSLoader (standard since perl 5.006).
163 Tests use Symbol (standard since perl 5.002).
166 perlguts and perlapi for internal information about magic.
169 Vincent Pit, "<perl at profvince.com>"
172 Please report any bugs or feature requests to "bug-variable-magic at
173 rt.cpan.org", or through the web interface at
174 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>. I will
175 be notified, and then you'll automatically be notified of progress on
176 your bug as I make changes.
179 You can find documentation for this module with the perldoc command.
181 perldoc Variable::Magic
184 Copyright 2007 Vincent Pit, all rights reserved.
186 This program is free software; you can redistribute it and/or modify it
187 under the same terms as Perl itself.