Filename | /home/hinrik/perl5/perlbrew/perls/perl-5.13.5/lib/site_perl/5.13.5/x86_64-linux/Variable/Magic.pm |
Statements | Executed 32 statements in 906µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
9 | 1 | 1 | 97µs | 132µs | cast (xsub) | Variable::Magic::
1 | 1 | 1 | 42µs | 51µs | wizard | Variable::Magic::
1 | 1 | 1 | 31µs | 31µs | BEGIN@3 | Variable::Magic::
9 | 1 | 1 | 21µs | 21µs | getdata (xsub) | Variable::Magic::
1 | 1 | 1 | 15µs | 24µs | BEGIN@6 | Variable::Magic::
1 | 1 | 1 | 12µs | 89µs | BEGIN@576 | Variable::Magic::
1 | 1 | 1 | 11µs | 233µs | BEGIN@202 | Variable::Magic::
1 | 1 | 1 | 11µs | 16µs | BEGIN@5 | Variable::Magic::
1 | 1 | 1 | 9µs | 9µs | _wizard (xsub) | Variable::Magic::
1 | 1 | 1 | 5µs | 5µs | BEGIN@19 | Variable::Magic::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package Variable::Magic; | ||||
2 | |||||
3 | 2 | 36µs | 1 | 31µs | # spent 31µs within Variable::Magic::BEGIN@3 which was called:
# once (31µs+0s) by B::Hooks::EndOfScope::BEGIN@14 at line 3 # spent 31µs making 1 call to Variable::Magic::BEGIN@3 |
4 | |||||
5 | 2 | 28µs | 2 | 21µs | # spent 16µs (11+5) within Variable::Magic::BEGIN@5 which was called:
# once (11µs+5µs) by B::Hooks::EndOfScope::BEGIN@14 at line 5 # spent 16µs making 1 call to Variable::Magic::BEGIN@5
# spent 5µs making 1 call to strict::import |
6 | 2 | 39µs | 2 | 33µs | # spent 24µs (15+9) within Variable::Magic::BEGIN@6 which was called:
# once (15µs+9µs) by B::Hooks::EndOfScope::BEGIN@14 at line 6 # spent 24µs making 1 call to Variable::Magic::BEGIN@6
# spent 9µs making 1 call to warnings::import |
7 | |||||
8 | =head1 NAME | ||||
9 | |||||
10 | Variable::Magic - Associate user-defined magic to variables from Perl. | ||||
11 | |||||
12 | =head1 VERSION | ||||
13 | |||||
14 | Version 0.44 | ||||
15 | |||||
16 | =cut | ||||
17 | |||||
18 | 1 | 700ns | our $VERSION; | ||
19 | # spent 5µs within Variable::Magic::BEGIN@19 which was called:
# once (5µs+0s) by B::Hooks::EndOfScope::BEGIN@14 at line 21 | ||||
20 | 1 | 5µs | $VERSION = '0.44'; | ||
21 | 1 | 96µs | 1 | 5µs | } # spent 5µs making 1 call to Variable::Magic::BEGIN@19 |
22 | |||||
23 | =head1 SYNOPSIS | ||||
24 | |||||
25 | use Variable::Magic qw/wizard cast VMG_OP_INFO_NAME/; | ||||
26 | |||||
27 | { # A variable tracer | ||||
28 | my $wiz = wizard set => sub { print "now set to ${$_[0]}!\n" }, | ||||
29 | free => sub { print "destroyed!\n" }; | ||||
30 | |||||
31 | my $a = 1; | ||||
32 | cast $a, $wiz; | ||||
33 | $a = 2; # "now set to 2!" | ||||
34 | } # "destroyed!" | ||||
35 | |||||
36 | { # A hash with a default value | ||||
37 | my $wiz = wizard data => sub { $_[1] }, | ||||
38 | fetch => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () }, | ||||
39 | store => sub { print "key $_[2] stored in $_[-1]\n" }, | ||||
40 | copy_key => 1, | ||||
41 | op_info => VMG_OP_INFO_NAME; | ||||
42 | |||||
43 | my %h = (_default => 0, apple => 2); | ||||
44 | cast %h, $wiz, '_default'; | ||||
45 | print $h{banana}, "\n"; # "0", because the 'banana' key doesn't exist in %h | ||||
46 | $h{pear} = 1; # "key pear stored in helem" | ||||
47 | } | ||||
48 | |||||
49 | =head1 DESCRIPTION | ||||
50 | |||||
51 | Magic is Perl's way of enhancing variables. | ||||
52 | This mechanism lets the user add extra data to any variable and hook syntactical operations (such as access, assignment or destruction) that can be applied to it. | ||||
53 | With this module, you can add your own magic to any variable without having to write a single line of XS. | ||||
54 | |||||
55 | You'll realize that these magic variables look a lot like tied variables. | ||||
56 | It's not surprising, as tied variables are implemented as a special kind of magic, just like any 'irregular' Perl variable : scalars like C<$!>, C<$(> or C<$^W>, the C<%ENV> and C<%SIG> hashes, the C<@ISA> array, C<vec()> and C<substr()> lvalues, L<threads::shared> variables... | ||||
57 | They all share the same underlying C API, and this module gives you direct access to it. | ||||
58 | |||||
59 | Still, the magic made available by this module differs from tieing and overloading in several ways : | ||||
60 | |||||
61 | =over 4 | ||||
62 | |||||
63 | =item * | ||||
64 | |||||
65 | It isn't copied on assignment. | ||||
66 | |||||
67 | You attach it to variables, not values (as for blessed references). | ||||
68 | |||||
69 | =item * | ||||
70 | |||||
71 | It doesn't replace the original semantics. | ||||
72 | |||||
73 | Magic callbacks usually get triggered before the original action takes place, and can't prevent it from happening. | ||||
74 | This also makes catching individual events easier than with C<tie>, where you have to provide fallbacks methods for all actions by usually inheriting from the correct C<Tie::Std*> class and overriding individual methods in your own class. | ||||
75 | |||||
76 | =item * | ||||
77 | |||||
78 | It's type-agnostic. | ||||
79 | |||||
80 | The same magic can be applied on scalars, arrays, hashes, subs or globs. | ||||
81 | But the same hook (see below for a list) may trigger differently depending on the the type of the variable. | ||||
82 | |||||
83 | =item * | ||||
84 | |||||
85 | It's mostly invisible at the Perl level. | ||||
86 | |||||
87 | Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> or another trick. | ||||
88 | |||||
89 | =item * | ||||
90 | |||||
91 | It's notably faster. | ||||
92 | |||||
93 | Mainly because perl's way of handling magic is lighter by nature, and because there's no need for any method resolution. | ||||
94 | Also, since you don't have to reimplement all the variable semantics, you only pay for what you actually use. | ||||
95 | |||||
96 | =back | ||||
97 | |||||
98 | The operations that can be overloaded are : | ||||
99 | |||||
100 | =over 4 | ||||
101 | |||||
102 | =item * | ||||
103 | |||||
104 | C<get> | ||||
105 | |||||
106 | This magic is invoked when the variable is evaluated. | ||||
107 | It is never called for arrays and hashes. | ||||
108 | |||||
109 | =item * | ||||
110 | |||||
111 | C<set> | ||||
112 | |||||
113 | This one is triggered each time the value of the variable changes. | ||||
114 | It is called for array subscripts and slices, but never for hashes. | ||||
115 | |||||
116 | =item * | ||||
117 | |||||
118 | C<len> | ||||
119 | |||||
120 | This magic is a little special : it is called when the 'size' or the 'length' of the variable has to be known by Perl. | ||||
121 | Typically, it's the magic involved when an array is evaluated in scalar context, but also on array assignment and loops (C<for>, C<map> or C<grep>). | ||||
122 | The callback has then to return the length as an integer. | ||||
123 | |||||
124 | =item * | ||||
125 | |||||
126 | C<clear> | ||||
127 | |||||
128 | This magic is invoked when the variable is reset, such as when an array is emptied. | ||||
129 | Please note that this is different from undefining the variable, even though the magic is called when the clearing is a result of the undefine (e.g. for an array, but actually a bug prevent it to work before perl 5.9.5 - see the L<history|/PERL MAGIC HISTORY>). | ||||
130 | |||||
131 | =item * | ||||
132 | |||||
133 | C<free> | ||||
134 | |||||
135 | This one can be considered as an object destructor. | ||||
136 | It happens when the variable goes out of scope, but not when it is undefined. | ||||
137 | |||||
138 | =item * | ||||
139 | |||||
140 | C<copy> | ||||
141 | |||||
142 | This magic only applies to tied arrays and hashes. | ||||
143 | It fires when you try to access or change their elements. | ||||
144 | It is available on your perl iff C<MGf_COPY> is true. | ||||
145 | |||||
146 | =item * | ||||
147 | |||||
148 | C<dup> | ||||
149 | |||||
150 | Invoked when the variable is cloned across threads. | ||||
151 | Currently not available. | ||||
152 | |||||
153 | =item * | ||||
154 | |||||
155 | C<local> | ||||
156 | |||||
157 | When this magic is set on a variable, all subsequent localizations of the variable will trigger the callback. | ||||
158 | It is available on your perl iff C<MGf_LOCAL> is true. | ||||
159 | |||||
160 | =back | ||||
161 | |||||
162 | The following actions only apply to hashes and are available iff C<VMG_UVAR> is true. | ||||
163 | They are referred to as C<uvar> magics. | ||||
164 | |||||
165 | =over 4 | ||||
166 | |||||
167 | =item * | ||||
168 | |||||
169 | C<fetch> | ||||
170 | |||||
171 | This magic happens each time an element is fetched from the hash. | ||||
172 | |||||
173 | =item * | ||||
174 | |||||
175 | C<store> | ||||
176 | |||||
177 | This one is called when an element is stored into the hash. | ||||
178 | |||||
179 | =item * | ||||
180 | |||||
181 | C<exists> | ||||
182 | |||||
183 | This magic fires when a key is tested for existence in the hash. | ||||
184 | |||||
185 | =item * | ||||
186 | |||||
187 | C<delete> | ||||
188 | |||||
189 | This last one triggers when a key is deleted in the hash, regardless of whether the key actually exists in it. | ||||
190 | |||||
191 | =back | ||||
192 | |||||
193 | You can refer to the tests to have more insight of where the different magics are invoked. | ||||
194 | |||||
195 | To prevent any clash between different magics defined with this module, an unique numerical signature is attached to each kind of magic (i.e. each set of callbacks for magic operations). | ||||
196 | At the C level, magic tokens owned by magic created by this module have their C<< mg->mg_private >> field set to C<0x3891> or C<0x3892>, so please don't use these magic (sic) numbers in other extensions. | ||||
197 | |||||
198 | =head1 FUNCTIONS | ||||
199 | |||||
200 | =cut | ||||
201 | |||||
202 | # spent 233µs (11+222) within Variable::Magic::BEGIN@202 which was called:
# once (11µs+222µs) by B::Hooks::EndOfScope::BEGIN@14 at line 205 | ||||
203 | 2 | 235µs | require XSLoader; | ||
204 | 1 | 222µs | XSLoader::load(__PACKAGE__, $VERSION); # spent 222µs making 1 call to XSLoader::load | ||
205 | 1 | 272µs | 1 | 233µs | } # spent 233µs making 1 call to Variable::Magic::BEGIN@202 |
206 | |||||
207 | =head2 C<wizard> | ||||
208 | |||||
209 | wizard data => sub { ... }, | ||||
210 | get => sub { my ($ref, $data [, $op]) = @_; ... }, | ||||
211 | set => sub { my ($ref, $data [, $op]) = @_; ... }, | ||||
212 | len => sub { my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen; }, | ||||
213 | clear => sub { my ($ref, $data [, $op]) = @_; ... }, | ||||
214 | free => sub { my ($ref, $data [, $op]) = @_, ... }, | ||||
215 | copy => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... }, | ||||
216 | local => sub { my ($ref, $data [, $op]) = @_; ... }, | ||||
217 | fetch => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | ||||
218 | store => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | ||||
219 | exists => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | ||||
220 | delete => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | ||||
221 | copy_key => $bool, | ||||
222 | op_info => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ] | ||||
223 | |||||
224 | This function creates a 'wizard', an opaque type that holds the magic information. | ||||
225 | It takes a list of keys / values as argument, whose keys can be : | ||||
226 | |||||
227 | =over 4 | ||||
228 | |||||
229 | =item * | ||||
230 | |||||
231 | C<data> | ||||
232 | |||||
233 | A code (or string) reference to a private data constructor. | ||||
234 | It is called each time this magic is cast on a variable, and the scalar returned is used as private data storage for it. | ||||
235 | C<$_[0]> is a reference to the magic object and C<@_[1 .. @_-1]> are all extra arguments that were passed to L</cast>. | ||||
236 | |||||
237 | =item * | ||||
238 | |||||
239 | C<get>, C<set>, C<len>, C<clear>, C<free>, C<copy>, C<local>, C<fetch>, C<store>, C<exists> and C<delete> | ||||
240 | |||||
241 | Code (or string) references to the corresponding magic callbacks. | ||||
242 | You don't have to specify all of them : the magic associated with undefined entries simply won't be hooked. | ||||
243 | In those callbacks, C<$_[0]> is always a reference to the magic object and C<$_[1]> is always the private data (or C<undef> when no private data constructor was supplied). | ||||
244 | |||||
245 | Moreover, when you pass C<< op_info => $num >> to C<wizard>, the last element of C<@_> will be the current op name if C<$num == VMG_OP_INFO_NAME> and a C<B::OP> object representing the current op if C<$num == VMG_OP_INFO_OBJECT>. | ||||
246 | Both have a performance hit, but just getting the name is lighter than getting the op object. | ||||
247 | |||||
248 | Other arguments are specific to the magic hooked : | ||||
249 | |||||
250 | =over 8 | ||||
251 | |||||
252 | =item * | ||||
253 | |||||
254 | C<len> | ||||
255 | |||||
256 | When the variable is an array or a scalar, C<$_[2]> contains the non-magical length. | ||||
257 | The callback can return the new scalar or array length to use, or C<undef> to default to the normal length. | ||||
258 | |||||
259 | =item * | ||||
260 | |||||
261 | C<copy> | ||||
262 | |||||
263 | C<$_[2]> is a either a copy or an alias of the current key, which means that it is useless to try to change or cast magic on it. | ||||
264 | C<$_[3]> is an alias to the current element (i.e. the value). | ||||
265 | |||||
266 | =item * | ||||
267 | |||||
268 | C<fetch>, C<store>, C<exists> and C<delete> | ||||
269 | |||||
270 | C<$_[2]> is an alias to the current key. | ||||
271 | Nothing prevents you from changing it, but be aware that there lurk dangerous side effects. | ||||
272 | For example, it may rightfully be readonly if the key was a bareword. | ||||
273 | You can get a copy instead by passing C<< copy_key => 1 >> to L</wizard>, which allows you to safely assign to C<$_[2]> in order to e.g. redirect the action to another key. | ||||
274 | This however has a little performance drawback because of the copy. | ||||
275 | |||||
276 | =back | ||||
277 | |||||
278 | All the callbacks are expected to return an integer, which is passed straight to the perl magic API. | ||||
279 | However, only the return value of the C<len> callback currently holds a meaning. | ||||
280 | |||||
281 | =back | ||||
282 | |||||
283 | Each callback can be specified as a code or a string reference, in which case the function denoted by the string will be used as the callback. | ||||
284 | |||||
285 | Note that C<free> callbacks are I<never> called during global destruction, as there's no way to ensure that the wizard and the C<free> callback weren't destroyed before the variable. | ||||
286 | |||||
287 | Here's a simple usage example : | ||||
288 | |||||
289 | # A simple scalar tracer | ||||
290 | my $wiz = wizard get => sub { print STDERR "got ${$_[0]}\n" }, | ||||
291 | set => sub { print STDERR "set to ${$_[0]}\n" }, | ||||
292 | free => sub { print STDERR "${$_[0]} was deleted\n" } | ||||
293 | |||||
294 | =cut | ||||
295 | |||||
296 | # spent 51µs (42+9) within Variable::Magic::wizard which was called:
# once (42µs+9µs) by namespace::clean::BEGIN@17 at line 26 of B/Hooks/EndOfScope.pm | ||||
297 | 15 | 53µs | if (@_ % 2) { | ||
298 | require Carp; | ||||
299 | Carp::croak('Wrong number of arguments for wizard()'); | ||||
300 | } | ||||
301 | |||||
302 | my %opts = @_; | ||||
303 | |||||
304 | my @keys = qw/data op_info get set len clear free/; | ||||
305 | push @keys, 'copy' if MGf_COPY; | ||||
306 | push @keys, 'dup' if MGf_DUP; | ||||
307 | push @keys, 'local' if MGf_LOCAL; | ||||
308 | push @keys, qw/fetch store exists delete copy_key/ if VMG_UVAR; | ||||
309 | |||||
310 | my ($wiz, $err); | ||||
311 | { | ||||
312 | local $@; | ||||
313 | 1 | 9µs | $wiz = eval { _wizard(map $opts{$_}, @keys) }; # spent 9µs making 1 call to Variable::Magic::_wizard | ||
314 | $err = $@; | ||||
315 | } | ||||
316 | if ($err) { | ||||
317 | $err =~ s/\sat\s+.*?\n//; | ||||
318 | require Carp; | ||||
319 | Carp::croak($err); | ||||
320 | } | ||||
321 | |||||
322 | return $wiz; | ||||
323 | } | ||||
324 | |||||
325 | =head2 C<cast> | ||||
326 | |||||
327 | cast [$@%&*]var, $wiz, ... | ||||
328 | |||||
329 | This function associates C<$wiz> magic to the variable supplied, without overwriting any other kind of magic. | ||||
330 | It returns true on success or when C<$wiz> magic is already present, and croaks on error. | ||||
331 | All extra arguments specified after C<$wiz> are passed to the private data constructor in C<@_[1 .. @_-1]>. | ||||
332 | If the variable isn't a hash, any C<uvar> callback of the wizard is safely ignored. | ||||
333 | |||||
334 | # Casts $wiz onto $x, and pass '1' to the data constructor. | ||||
335 | my $x; | ||||
336 | cast $x, $wiz, 1; | ||||
337 | |||||
338 | The C<var> argument can be an array or hash value. | ||||
339 | Magic for those behaves like for any other scalar, except that it is dispelled when the entry is deleted from the container. | ||||
340 | For example, if you want to call C<POSIX::tzset> each time the C<'TZ'> environment variable is changed in C<%ENV>, you can use : | ||||
341 | |||||
342 | use POSIX; | ||||
343 | cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () }; | ||||
344 | |||||
345 | If you want to overcome the possible deletion of the C<'TZ'> entry, you have no choice but to rely on C<store> uvar magic. | ||||
346 | |||||
347 | =head2 C<getdata> | ||||
348 | |||||
349 | getdata [$@%&*]var, $wiz | ||||
350 | |||||
351 | This accessor fetches the private data associated with the magic C<$wiz> in the variable. | ||||
352 | It croaks when C<$wiz> do not represent a valid magic object, and returns an empty list if no such magic is attached to the variable or when the wizard has no data constructor. | ||||
353 | |||||
354 | # Get the attached data, or undef if the wizard does not attach any. | ||||
355 | my $data = getdata $x, $wiz; | ||||
356 | |||||
357 | =head2 C<dispell> | ||||
358 | |||||
359 | dispell [$@%&*]variable, $wiz | ||||
360 | |||||
361 | The exact opposite of L</cast> : it dissociates C<$wiz> magic from the variable. | ||||
362 | This function returns true on success, C<0> when no magic represented by C<$wiz> could be found in the variable, and croaks if the supplied wizard is invalid. | ||||
363 | |||||
364 | # Dispell now. | ||||
365 | die 'no such magic in $x' unless dispell $x, $wiz; | ||||
366 | |||||
367 | =head1 CONSTANTS | ||||
368 | |||||
369 | =head2 C<MGf_COPY> | ||||
370 | |||||
371 | Evaluates to true iff the 'copy' magic is available. | ||||
372 | |||||
373 | =head2 C<MGf_DUP> | ||||
374 | |||||
375 | Evaluates to true iff the 'dup' magic is available. | ||||
376 | |||||
377 | =head2 C<MGf_LOCAL> | ||||
378 | |||||
379 | Evaluates to true iff the 'local' magic is available. | ||||
380 | |||||
381 | =head2 C<VMG_UVAR> | ||||
382 | |||||
383 | When this constant is true, you can use the C<fetch,store,exists,delete> callbacks on hashes. | ||||
384 | |||||
385 | =head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN> | ||||
386 | |||||
387 | True for perls that don't call 'len' magic when you push an element in a magical array. | ||||
388 | Starting from perl 5.11.0, this only refers to pushes in non-void context and hence is false. | ||||
389 | |||||
390 | =head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID> | ||||
391 | |||||
392 | True for perls that don't call 'len' magic when you push in void context an element in a magical array. | ||||
393 | |||||
394 | =head2 C<VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID> | ||||
395 | |||||
396 | True for perls that don't call 'len' magic when you unshift in void context an element in a magical array. | ||||
397 | |||||
398 | =head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR> | ||||
399 | |||||
400 | True for perls that call 'clear' magic when undefining magical arrays. | ||||
401 | |||||
402 | =head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN> | ||||
403 | |||||
404 | True for perls that don't call 'len' magic when taking the C<length> of a magical scalar. | ||||
405 | |||||
406 | =head2 C<VMG_COMPAT_GLOB_GET> | ||||
407 | |||||
408 | True for perls that call 'get' magic for operations on globs. | ||||
409 | |||||
410 | =head2 C<VMG_PERL_PATCHLEVEL> | ||||
411 | |||||
412 | The perl patchlevel this module was built with, or C<0> for non-debugging perls. | ||||
413 | |||||
414 | =head2 C<VMG_THREADSAFE> | ||||
415 | |||||
416 | True iff this module could have been built with thread-safety features enabled. | ||||
417 | |||||
418 | =head2 C<VMG_FORKSAFE> | ||||
419 | |||||
420 | True iff this module could have been built with fork-safety features enabled. | ||||
421 | This will always be true except on Windows where it's false for perl 5.10.0 and below . | ||||
422 | |||||
423 | =head2 C<VMG_OP_INFO_NAME> | ||||
424 | |||||
425 | Value to pass with C<op_info> to get the current op name in the magic callbacks. | ||||
426 | |||||
427 | =head2 C<VMG_OP_INFO_OBJECT> | ||||
428 | |||||
429 | Value to pass with C<op_info> to get a C<B::OP> object representing the current op in the magic callbacks. | ||||
430 | |||||
431 | =head1 COOKBOOK | ||||
432 | |||||
433 | =head2 Associate an object to any perl variable | ||||
434 | |||||
435 | This technique can be useful for passing user data through limited APIs. | ||||
436 | It is similar to using inside-out objects, but without the drawback of having to implement a complex destructor. | ||||
437 | |||||
438 | { | ||||
439 | package Magical::UserData; | ||||
440 | |||||
441 | use Variable::Magic qw/wizard cast getdata/; | ||||
442 | |||||
443 | my $wiz = wizard data => sub { \$_[1] }; | ||||
444 | |||||
445 | sub ud (\[$@%*&]) : lvalue { | ||||
446 | my ($var) = @_; | ||||
447 | my $data = &getdata($var, $wiz); | ||||
448 | unless (defined $data) { | ||||
449 | $data = \(my $slot); | ||||
450 | &cast($var, $wiz, $slot) | ||||
451 | or die "Couldn't cast UserData magic onto the variable"; | ||||
452 | } | ||||
453 | $$data; | ||||
454 | } | ||||
455 | } | ||||
456 | |||||
457 | { | ||||
458 | BEGIN { *ud = \&Magical::UserData::ud } | ||||
459 | |||||
460 | my $cb; | ||||
461 | $cb = sub { print 'Hello, ', ud(&$cb), "!\n" }; | ||||
462 | |||||
463 | ud(&$cb) = 'world'; | ||||
464 | $cb->(); # Hello, world! | ||||
465 | } | ||||
466 | |||||
467 | =head2 Recursively cast magic on datastructures | ||||
468 | |||||
469 | C<cast> can be called from any magical callback, and in particular from C<data>. | ||||
470 | This allows you to recursively cast magic on datastructures : | ||||
471 | |||||
472 | my $wiz; | ||||
473 | $wiz = wizard data => sub { | ||||
474 | my ($var, $depth) = @_; | ||||
475 | $depth ||= 0; | ||||
476 | my $r = ref $var; | ||||
477 | if ($r eq 'ARRAY') { | ||||
478 | &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var; | ||||
479 | } elsif ($r eq 'HASH') { | ||||
480 | &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var; | ||||
481 | } | ||||
482 | return $depth; | ||||
483 | }, | ||||
484 | free => sub { | ||||
485 | my ($var, $depth) = @_; | ||||
486 | my $r = ref $var; | ||||
487 | print "free $r at depth $depth\n"; | ||||
488 | (); | ||||
489 | }; | ||||
490 | |||||
491 | { | ||||
492 | my %h = ( | ||||
493 | a => [ 1, 2 ], | ||||
494 | b => { c => 3 } | ||||
495 | ); | ||||
496 | cast %h, $wiz; | ||||
497 | } | ||||
498 | |||||
499 | When C<%h> goes out of scope, this will print something among the lines of : | ||||
500 | |||||
501 | free HASH at depth 0 | ||||
502 | free HASH at depth 1 | ||||
503 | free SCALAR at depth 2 | ||||
504 | free ARRAY at depth 1 | ||||
505 | free SCALAR at depth 3 | ||||
506 | free SCALAR at depth 3 | ||||
507 | |||||
508 | Of course, this example does nothing with the values that are added after the C<cast>. | ||||
509 | |||||
510 | =head1 PERL MAGIC HISTORY | ||||
511 | |||||
512 | The places where magic is invoked have changed a bit through perl history. | ||||
513 | Here's a little list of the most recent ones. | ||||
514 | |||||
515 | =over 4 | ||||
516 | |||||
517 | =item * | ||||
518 | |||||
519 | B<5.6.x> | ||||
520 | |||||
521 | I<p14416> : 'copy' and 'dup' magic. | ||||
522 | |||||
523 | =item * | ||||
524 | |||||
525 | B<5.8.9> | ||||
526 | |||||
527 | I<p28160> : Integration of I<p25854> (see below). | ||||
528 | |||||
529 | I<p32542> : Integration of I<p31473> (see below). | ||||
530 | |||||
531 | =item * | ||||
532 | |||||
533 | B<5.9.3> | ||||
534 | |||||
535 | I<p25854> : 'len' magic is no longer called when pushing an element into a magic array. | ||||
536 | |||||
537 | I<p26569> : 'local' magic. | ||||
538 | |||||
539 | =item * | ||||
540 | |||||
541 | B<5.9.5> | ||||
542 | |||||
543 | I<p31064> : Meaningful 'uvar' magic. | ||||
544 | |||||
545 | I<p31473> : 'clear' magic wasn't invoked when undefining an array. | ||||
546 | The bug is fixed as of this version. | ||||
547 | |||||
548 | =item * | ||||
549 | |||||
550 | B<5.10.0> | ||||
551 | |||||
552 | Since C<PERL_MAGIC_uvar> is uppercased, C<hv_magic_check()> triggers 'copy' magic on hash stores for (non-tied) hashes that also have 'uvar' magic. | ||||
553 | |||||
554 | =item * | ||||
555 | |||||
556 | B<5.11.x> | ||||
557 | |||||
558 | I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar. | ||||
559 | |||||
560 | I<p34908> : 'len' magic is no longer called when pushing / unshifting an element into a magical array in void context. | ||||
561 | The C<push> part was already covered by I<p25854>. | ||||
562 | |||||
563 | I<g9cdcb38b> : 'len' magic is called again when pushing into a magical array in non-void context. | ||||
564 | |||||
565 | =back | ||||
566 | |||||
567 | =head1 EXPORT | ||||
568 | |||||
569 | The functions L</wizard>, L</cast>, L</getdata> and L</dispell> are only exported on request. | ||||
570 | All of them are exported by the tags C<':funcs'> and C<':all'>. | ||||
571 | |||||
572 | All the constants are also only exported on request, either individually or by the tags C<':consts'> and C<':all'>. | ||||
573 | |||||
574 | =cut | ||||
575 | |||||
576 | 2 | 112µs | 2 | 166µs | # spent 89µs (12+77) within Variable::Magic::BEGIN@576 which was called:
# once (12µs+77µs) by B::Hooks::EndOfScope::BEGIN@14 at line 576 # spent 89µs making 1 call to Variable::Magic::BEGIN@576
# spent 77µs making 1 call to base::import |
577 | |||||
578 | 1 | 1µs | our @EXPORT = (); | ||
579 | 1 | 6µs | our %EXPORT_TAGS = ( | ||
580 | 'funcs' => [ qw/wizard cast getdata dispell/ ], | ||||
581 | 'consts' => [ qw/ | ||||
582 | MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR | ||||
583 | VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID | ||||
584 | VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID | ||||
585 | VMG_COMPAT_ARRAY_UNDEF_CLEAR | ||||
586 | VMG_COMPAT_SCALAR_LENGTH_NOLEN | ||||
587 | VMG_COMPAT_GLOB_GET | ||||
588 | VMG_PERL_PATCHLEVEL | ||||
589 | VMG_THREADSAFE VMG_FORKSAFE | ||||
590 | VMG_OP_INFO_NAME VMG_OP_INFO_OBJECT | ||||
591 | / ], | ||||
592 | ); | ||||
593 | 1 | 10µs | our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS; | ||
594 | 1 | 4µs | $EXPORT_TAGS{'all'} = [ @EXPORT_OK ]; | ||
595 | |||||
596 | =head1 CAVEATS | ||||
597 | |||||
598 | If you store a magic object in the private data slot, the magic won't be accessible by L</getdata> since it's not copied by assignment. | ||||
599 | The only way to address this would be to return a reference. | ||||
600 | |||||
601 | If you define a wizard with a C<free> callback and cast it on itself, this destructor won't be called because the wizard will be destroyed first. | ||||
602 | |||||
603 | =head1 DEPENDENCIES | ||||
604 | |||||
605 | L<perl> 5.8. | ||||
606 | |||||
607 | L<Carp> (standard since perl 5), L<XSLoader> (standard since perl 5.006). | ||||
608 | |||||
609 | Copy tests need L<Tie::Array> (standard since perl 5.005) and L<Tie::Hash> (since 5.002). | ||||
610 | |||||
611 | Some uvar tests need L<Hash::Util::FieldHash> (standard since perl 5.009004). | ||||
612 | |||||
613 | Glob tests need L<Symbol> (standard since perl 5.002). | ||||
614 | |||||
615 | Threads tests need L<threads> and L<threads::shared>. | ||||
616 | |||||
617 | =head1 SEE ALSO | ||||
618 | |||||
619 | L<perlguts> and L<perlapi> for internal information about magic. | ||||
620 | |||||
621 | L<perltie> and L<overload> for other ways of enhancing objects. | ||||
622 | |||||
623 | =head1 AUTHOR | ||||
624 | |||||
625 | Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>. | ||||
626 | |||||
627 | You can contact me by mail or on C<irc.perl.org> (vincent). | ||||
628 | |||||
629 | =head1 BUGS | ||||
630 | |||||
631 | Please report any bugs or feature requests to C<bug-variable-magic at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. | ||||
632 | |||||
633 | =head1 SUPPORT | ||||
634 | |||||
635 | You can find documentation for this module with the perldoc command. | ||||
636 | |||||
637 | perldoc Variable::Magic | ||||
638 | |||||
639 | Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Variable-Magic>. | ||||
640 | |||||
641 | =head1 COPYRIGHT & LICENSE | ||||
642 | |||||
643 | Copyright 2007,2008,2009,2010 Vincent Pit, all rights reserved. | ||||
644 | |||||
645 | This program is free software; you can redistribute it and/or modify it | ||||
646 | under the same terms as Perl itself. | ||||
647 | |||||
648 | =cut | ||||
649 | |||||
650 | 1 | 7µs | 1; # End of Variable::Magic | ||
# spent 9µs within Variable::Magic::_wizard which was called:
# once (9µs+0s) by Variable::Magic::wizard at line 313 | |||||
# spent 132µs (97+36) within Variable::Magic::cast which was called 9 times, avg 15µs/call:
# 9 times (97µs+36µs) by B::Hooks::EndOfScope::on_scope_end at line 37 of B/Hooks/EndOfScope.pm, avg 15µs/call | |||||
# spent 21µs within Variable::Magic::getdata which was called 9 times, avg 2µs/call:
# 9 times (21µs+0s) by B::Hooks::EndOfScope::on_scope_end at line 33 of B/Hooks/EndOfScope.pm, avg 2µs/call |