File | /usr/local/lib/perl/5.10.0/Variable/Magic.pm |
Statements Executed | 37 |
Total Time | 0.001071 seconds |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
9 | 1 | 2 | 77µs | 77µs | cast(xsub) | Variable::Magic::
9 | 1 | 2 | 59µs | 59µs | getdata(xsub) | Variable::Magic::
2 | 1 | 2 | 31µs | 31µs | _wizard(xsub) | Variable::Magic::
1 | 1 | 1 | 28µs | 59µs | wizard | Variable::Magic::
0 | 0 | 0 | 0s | 0s | BEGIN | Variable::Magic::
Line | Stmts. | Exclusive Time | Avg. | Code |
---|---|---|---|---|
1 | package Variable::Magic; | |||
2 | ||||
3 | 3 | 31µs | 10µs | use 5.008; |
4 | ||||
5 | 3 | 25µs | 8µs | use strict; # spent 11µs making 1 call to strict::import |
6 | 3 | 36µs | 12µs | use warnings; # spent 24µs making 1 call to warnings::import |
7 | ||||
8 | 3 | 59µs | 20µs | use Carp qw/croak/; # spent 48µs making 1 call to Exporter::import |
9 | ||||
10 | =head1 NAME | |||
11 | ||||
12 | Variable::Magic - Associate user-defined magic to variables from Perl. | |||
13 | ||||
14 | =head1 VERSION | |||
15 | ||||
16 | Version 0.35 | |||
17 | ||||
18 | =cut | |||
19 | ||||
20 | 1 | 200ns | 200ns | our $VERSION; |
21 | BEGIN { | |||
22 | 1 | 1µs | 1µs | $VERSION = '0.35'; |
23 | 1 | 77µs | 77µs | } |
24 | ||||
25 | =head1 SYNOPSIS | |||
26 | ||||
27 | use Variable::Magic qw/wizard cast VMG_OP_INFO_NAME/; | |||
28 | ||||
29 | { # A variable tracer | |||
30 | my $wiz = wizard set => sub { print "now set to ${$_[0]}!\n" }, | |||
31 | free => sub { print "destroyed!\n" }; | |||
32 | ||||
33 | my $a = 1; | |||
34 | cast $a, $wiz; | |||
35 | $a = 2; # "now set to 2!" | |||
36 | } # "destroyed!" | |||
37 | ||||
38 | { # A hash with a default value | |||
39 | my $wiz = wizard data => sub { $_[1] }, | |||
40 | fetch => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () }, | |||
41 | store => sub { print "key $_[2] stored in $_[-1]\n" }, | |||
42 | copy_key => 1, | |||
43 | op_info => VMG_OP_INFO_NAME; | |||
44 | ||||
45 | my %h = (_default => 0, apple => 2); | |||
46 | cast %h, $wiz, '_default'; | |||
47 | print $h{banana}, "\n"; # "0", because the 'banana' key doesn't exist in %h | |||
48 | $h{pear} = 1; # "key pear stored in helem" | |||
49 | } | |||
50 | ||||
51 | =head1 DESCRIPTION | |||
52 | ||||
53 | Magic is Perl way of enhancing objects. | |||
54 | This mechanism lets the user add extra data to any variable and hook syntaxical operations (such as access, assignment or destruction) that can be applied to it. | |||
55 | With this module, you can add your own magic to any variable without having to write a single line of XS. | |||
56 | ||||
57 | You'll realize that these magic variables look a lot like tied variables. | |||
58 | 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... | |||
59 | They all share the same underlying C API, and this module gives you direct access to it. | |||
60 | ||||
61 | Still, the magic made available by this module differs from tieing and overloading in several ways : | |||
62 | ||||
63 | =over 4 | |||
64 | ||||
65 | =item * | |||
66 | ||||
67 | It isn't copied on assignment. | |||
68 | ||||
69 | You attach it to variables, not values (as for blessed references). | |||
70 | ||||
71 | =item * | |||
72 | ||||
73 | It doesn't replace the original semantics. | |||
74 | ||||
75 | Magic callbacks usually trigger before the original action take place, and can't prevent it to happen. | |||
76 | 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. | |||
77 | ||||
78 | =item * | |||
79 | ||||
80 | It's type-agnostic. | |||
81 | ||||
82 | The same magic can be applied on scalars, arrays, hashes, subs or globs. | |||
83 | But the same hook (see below for a list) may trigger differently depending on the the type of the variable. | |||
84 | ||||
85 | =item * | |||
86 | ||||
87 | It's mostly invisible at the Perl level. | |||
88 | ||||
89 | Magical and non-magical variables cannot be distinguished with C<ref>, C<tied> or another trick. | |||
90 | ||||
91 | =item * | |||
92 | ||||
93 | It's notably faster. | |||
94 | ||||
95 | Mainly because perl's way of handling magic is lighter by nature, and because there's no need for any method resolution. | |||
96 | Also, since you don't have to reimplement all the variable semantics, you only pay for what you actually use. | |||
97 | ||||
98 | =back | |||
99 | ||||
100 | The operations that can be overloaded are : | |||
101 | ||||
102 | =over 4 | |||
103 | ||||
104 | =item * | |||
105 | ||||
106 | C<get> | |||
107 | ||||
108 | This magic is invoked when the variable is evaluated (does not include array/hash subscripts and slices). | |||
109 | ||||
110 | =item * | |||
111 | ||||
112 | C<set> | |||
113 | ||||
114 | This one is triggered each time the value of the variable changes (includes array/hash subscripts and slices). | |||
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 | BEGIN { | |||
203 | 2 | 306µs | 153µs | require XSLoader; |
204 | XSLoader::load(__PACKAGE__, $VERSION); # spent 297µs making 1 call to XSLoader::load | |||
205 | 1 | 287µs | 287µs | } |
206 | ||||
207 | =head2 C<wizard> | |||
208 | ||||
209 | wizard sig => ..., | |||
210 | data => sub { ... }, | |||
211 | get => sub { my ($ref, $data [, $op]) = @_; ... }, | |||
212 | set => sub { my ($ref, $data [, $op]) = @_; ... }, | |||
213 | len => sub { my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen; }, | |||
214 | clear => sub { my ($ref, $data [, $op]) = @_; ... }, | |||
215 | free => sub { my ($ref, $data [, $op]) = @_, ... }, | |||
216 | copy => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... }, | |||
217 | local => sub { my ($ref, $data [, $op]) = @_; ... }, | |||
218 | fetch => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | |||
219 | store => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | |||
220 | exists => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | |||
221 | delete => sub { my ($ref, $data, $key [, $op]) = @_; ... }, | |||
222 | copy_key => $bool, | |||
223 | op_info => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ] | |||
224 | ||||
225 | This function creates a 'wizard', an opaque type that holds the magic information. | |||
226 | It takes a list of keys / values as argument, whose keys can be : | |||
227 | ||||
228 | =over 4 | |||
229 | ||||
230 | =item * | |||
231 | ||||
232 | C<sig> | |||
233 | ||||
234 | The numerical signature. | |||
235 | If not specified or undefined, a random signature is generated. | |||
236 | If the signature matches an already defined magic, then the existant magic object is returned. | |||
237 | ||||
238 | =item * | |||
239 | ||||
240 | C<data> | |||
241 | ||||
242 | A code reference to a private data constructor. | |||
243 | It is called each time this magic is cast on a variable, and the scalar returned is used as private data storage for it. | |||
244 | C<$_[0]> is a reference to the magic object and C<@_[1 .. @_-1]> are all extra arguments that were passed to L</cast>. | |||
245 | ||||
246 | =item * | |||
247 | ||||
248 | C<get>, C<set>, C<len>, C<clear>, C<free>, C<copy>, C<local>, C<fetch>, C<store>, C<exists> and C<delete> | |||
249 | ||||
250 | Code references to the corresponding magic callbacks. | |||
251 | You don't have to specify all of them : the magic associated with undefined entries simply won't be hooked. | |||
252 | 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). | |||
253 | ||||
254 | 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>. | |||
255 | Both have a performance hit, but just getting the name is lighter than getting the op object. | |||
256 | ||||
257 | Other arguments are specific to the magic hooked : | |||
258 | ||||
259 | =over 8 | |||
260 | ||||
261 | =item * | |||
262 | ||||
263 | C<len> | |||
264 | ||||
265 | When the variable is an array or a scalar, C<$_[2]> contains the non-magical length. | |||
266 | The callback can return the new scalar or array length to use, or C<undef> to default to the normal length. | |||
267 | ||||
268 | =item * | |||
269 | ||||
270 | C<copy> | |||
271 | ||||
272 | 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. | |||
273 | C<$_[3]> is an alias to the current element (i.e. the value). | |||
274 | ||||
275 | =item * | |||
276 | ||||
277 | C<fetch>, C<store>, C<exists> and C<delete> | |||
278 | ||||
279 | C<$_[2]> is an alias to the current key. | |||
280 | Nothing prevents you from changing it, but be aware that there lurk dangerous side effects. | |||
281 | For example, it may righteously be readonly if the key was a bareword. | |||
282 | 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. | |||
283 | This however has a little performance drawback because of the copy. | |||
284 | ||||
285 | =back | |||
286 | ||||
287 | All the callbacks are expected to return an integer, which is passed straight to the perl magic API. | |||
288 | However, only the return value of the C<len> callback currently holds a meaning. | |||
289 | ||||
290 | =back | |||
291 | ||||
292 | # A simple scalar tracer | |||
293 | my $wiz = wizard get => sub { print STDERR "got ${$_[0]}\n" }, | |||
294 | set => sub { print STDERR "set to ${$_[0]}\n" }, | |||
295 | free => sub { print STDERR "${$_[0]} was deleted\n" } | |||
296 | ||||
297 | 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. | |||
298 | ||||
299 | =cut | |||
300 | ||||
301 | # spent 59µs (28+31) within Variable::Magic::wizard which was called
# once (28µs+31µs) by B::Hooks::EndOfScope::__ANON__[/usr/local/share/perl/5.10.0/B/Hooks/EndOfScope.pm:47] at line 47 of /usr/local/share/perl/5.10.0/B/Hooks/EndOfScope.pm | |||
302 | 10 | 17µs | 2µs | croak 'Wrong number of arguments for wizard()' if @_ % 2; |
303 | my %opts = @_; | |||
304 | my @keys = qw/sig 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 | 1 | 37µs | 37µs | my $ret = eval { _wizard(map $opts{$_}, @keys) }; # spent 31µs making 1 call to Variable::Magic::_wizard |
310 | if (my $err = $@) { | |||
311 | $err =~ s/\sat\s+.*?\n//; | |||
312 | croak $err; | |||
313 | } | |||
314 | return $ret; | |||
315 | } | |||
316 | ||||
317 | =head2 C<gensig> | |||
318 | ||||
319 | With this tool, you can manually generate random magic signature between SIG_MIN and SIG_MAX inclusive. | |||
320 | That's the way L</wizard> creates them when no signature is supplied. | |||
321 | ||||
322 | # Generate a signature | |||
323 | my $sig = gensig; | |||
324 | ||||
325 | =head2 C<getsig> | |||
326 | ||||
327 | getsig $wiz | |||
328 | ||||
329 | This accessor returns the magic signature of this wizard. | |||
330 | ||||
331 | # Get $wiz signature | |||
332 | my $sig = getsig $wiz; | |||
333 | ||||
334 | =head2 C<cast> | |||
335 | ||||
336 | cast [$@%&*]var, [$wiz|$sig], ... | |||
337 | ||||
338 | This function associates C<$wiz> magic to the variable supplied, without overwriting any other kind of magic. | |||
339 | You can also supply the numeric signature C<$sig> instead of C<$wiz>. | |||
340 | It returns true on success or when C<$wiz> magic is already present, and croaks on error or when no magic corresponds to the given signature (in case a C<$sig> was supplied). | |||
341 | All extra arguments specified after C<$wiz> are passed to the private data constructor in C<@_[1 .. @_-1]>. | |||
342 | If the variable isn't a hash, any C<uvar> callback of the wizard is safely ignored. | |||
343 | ||||
344 | # Casts $wiz onto $x, and pass '1' to the data constructor. | |||
345 | my $x; | |||
346 | cast $x, $wiz, 1; | |||
347 | ||||
348 | The C<var> argument can be an array or hash value. | |||
349 | Magic for those behaves like for any other scalar, except that it is dispelled when the entry is deleted from the container. | |||
350 | 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 : | |||
351 | ||||
352 | use POSIX; | |||
353 | cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () }; | |||
354 | ||||
355 | 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. | |||
356 | ||||
357 | C<cast> can be called from any magical callback, and in particular from C<data>. | |||
358 | This allows you to recursively cast magic on datastructures : | |||
359 | ||||
360 | my $wiz; | |||
361 | $wiz = wizard | |||
362 | data => sub { | |||
363 | my ($var, $depth) = @_; | |||
364 | $depth ||= 0; | |||
365 | my $r = ref $var; | |||
366 | if ($r eq 'ARRAY') { | |||
367 | &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var; | |||
368 | } elsif ($r eq 'HASH') { | |||
369 | &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var; | |||
370 | } | |||
371 | return $depth; | |||
372 | }, | |||
373 | free => sub { | |||
374 | my ($var, $depth) = @_; | |||
375 | my $r = ref $var; | |||
376 | print "free $r at depth $depth\n"; | |||
377 | (); | |||
378 | }; | |||
379 | ||||
380 | { | |||
381 | my %h = ( | |||
382 | a => [ 1, 2 ], | |||
383 | b => { c => 3 } | |||
384 | ); | |||
385 | cast %h, $wiz; | |||
386 | } | |||
387 | ||||
388 | When C<%h> goes out of scope, this will print something among the lines of : | |||
389 | ||||
390 | free HASH at depth 0 | |||
391 | free HASH at depth 1 | |||
392 | free SCALAR at depth 2 | |||
393 | free ARRAY at depth 1 | |||
394 | free SCALAR at depth 3 | |||
395 | free SCALAR at depth 3 | |||
396 | ||||
397 | Of course, this example does nothing with the values that are added after the C<cast>. | |||
398 | ||||
399 | =head2 C<getdata> | |||
400 | ||||
401 | getdata [$@%&*]var, [$wiz|$sig] | |||
402 | ||||
403 | This accessor fetches the private data associated with the magic C<$wiz> (or the signature C<$sig>) in the variable. | |||
404 | It croaks when C<$wiz> or C<$sig> do not represent a current valid magic object attached to the variable, and returns C<undef> when the wizard has no data constructor or when the data is actually C<undef>. | |||
405 | ||||
406 | # Get the attached data, or undef if the wizard does not attach any. | |||
407 | my $data = getdata $x, $wiz; | |||
408 | ||||
409 | =head2 C<dispell> | |||
410 | ||||
411 | dispell [$@%&*]variable, [$wiz|$sig] | |||
412 | ||||
413 | The exact opposite of L</cast> : it dissociates C<$wiz> magic from the variable. | |||
414 | You can also pass the magic signature C<$sig> as the second argument. | |||
415 | This function returns true on success, C<0> when no magic represented by C<$wiz> or C<$sig> could be found in the variable, and croaks if the supplied wizard or signature is invalid. | |||
416 | ||||
417 | # Dispell now. | |||
418 | die 'no such magic in $x' unless dispell $x, $wiz; | |||
419 | ||||
420 | =head1 CONSTANTS | |||
421 | ||||
422 | =head2 C<SIG_MIN> | |||
423 | ||||
424 | The minimum integer used as a signature for user-defined magic. | |||
425 | ||||
426 | =head2 C<SIG_MAX> | |||
427 | ||||
428 | The maximum integer used as a signature for user-defined magic. | |||
429 | ||||
430 | =head2 C<SIG_NBR> | |||
431 | ||||
432 | SIG_NBR = SIG_MAX - SIG_MIN + 1 | |||
433 | ||||
434 | =head2 C<MGf_COPY> | |||
435 | ||||
436 | Evaluates to true iff the 'copy' magic is available. | |||
437 | ||||
438 | =head2 C<MGf_DUP> | |||
439 | ||||
440 | Evaluates to true iff the 'dup' magic is available. | |||
441 | ||||
442 | =head2 C<MGf_LOCAL> | |||
443 | ||||
444 | Evaluates to true iff the 'local' magic is available. | |||
445 | ||||
446 | =head2 C<VMG_UVAR> | |||
447 | ||||
448 | When this constant is true, you can use the C<fetch,store,exists,delete> callbacks on hashes. | |||
449 | ||||
450 | =head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN> | |||
451 | ||||
452 | True for perls that don't call 'len' magic when you push an element in a magical array. | |||
453 | ||||
454 | =head2 C<VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID> | |||
455 | ||||
456 | True for perls that don't call 'len' magic when you unshift in void context an element in a magical array. | |||
457 | ||||
458 | =head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR> | |||
459 | ||||
460 | True for perls that call 'clear' magic when undefining magical arrays. | |||
461 | ||||
462 | =head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN> | |||
463 | ||||
464 | True for perls that don't call 'len' magic when taking the C<length> of a magical scalar. | |||
465 | ||||
466 | =head2 C<VMG_PERL_PATCHLEVEL> | |||
467 | ||||
468 | The perl patchlevel this module was built with, or C<0> for non-debugging perls. | |||
469 | ||||
470 | =head2 C<VMG_THREADSAFE> | |||
471 | ||||
472 | True iff this module could have been built with thread-safety features enabled. | |||
473 | ||||
474 | =head2 C<VMG_OP_INFO_NAME> | |||
475 | ||||
476 | Value to pass with C<op_info> to get the current op name in the magic callbacks. | |||
477 | ||||
478 | =head2 C<VMG_OP_INFO_OBJECT> | |||
479 | ||||
480 | Value to pass with C<op_info> to get a C<B::OP> object representing the current op in the magic callbacks. | |||
481 | ||||
482 | =head1 PERL MAGIC HISTORY | |||
483 | ||||
484 | The places where magic is invoked have changed a bit through perl history. | |||
485 | Here's a little list of the most recent ones. | |||
486 | ||||
487 | =over 4 | |||
488 | ||||
489 | =item * | |||
490 | ||||
491 | B<5.6.x> | |||
492 | ||||
493 | I<p14416> : 'copy' and 'dup' magic. | |||
494 | ||||
495 | =item * | |||
496 | ||||
497 | B<5.8.9> | |||
498 | ||||
499 | I<p28160> : Integration of I<p25854> (see below). | |||
500 | ||||
501 | I<p32542> : Integration of I<p31473> (see below). | |||
502 | ||||
503 | =item * | |||
504 | ||||
505 | B<5.9.3> | |||
506 | ||||
507 | I<p25854> : 'len' magic is no longer called when pushing an element into a magic array. | |||
508 | ||||
509 | I<p26569> : 'local' magic. | |||
510 | ||||
511 | =item * | |||
512 | ||||
513 | B<5.9.5> | |||
514 | ||||
515 | I<p31064> : Meaningful 'uvar' magic. | |||
516 | ||||
517 | I<p31473> : 'clear' magic wasn't invoked when undefining an array. | |||
518 | The bug is fixed as of this version. | |||
519 | ||||
520 | =item * | |||
521 | ||||
522 | B<5.10.0> | |||
523 | ||||
524 | 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. | |||
525 | ||||
526 | =item * | |||
527 | ||||
528 | B<5.11.x> | |||
529 | ||||
530 | I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar. | |||
531 | ||||
532 | I<p34908> : 'len' magic is no longer called when pushing / unshifting an element into a magical array in void context. | |||
533 | The C<push> part was already covered by I<p25854>. | |||
534 | ||||
535 | =back | |||
536 | ||||
537 | =head1 EXPORT | |||
538 | ||||
539 | The functions L</wizard>, L</gensig>, L</getsig>, L</cast>, L</getdata> and L</dispell> are only exported on request. | |||
540 | All of them are exported by the tags C<':funcs'> and C<':all'>. | |||
541 | ||||
542 | All the constants are also only exported on request, either individually or by the tags C<':consts'> and C<':all'>. | |||
543 | ||||
544 | =cut | |||
545 | ||||
546 | 3 | 145µs | 48µs | use base qw/Exporter/; # spent 82µs making 1 call to base::import |
547 | ||||
548 | 1 | 700ns | 700ns | our @EXPORT = (); |
549 | 1 | 8µs | 8µs | our %EXPORT_TAGS = ( |
550 | 'funcs' => [ qw/wizard gensig getsig cast getdata dispell/ ], | |||
551 | 'consts' => [ | |||
552 | qw/SIG_MIN SIG_MAX SIG_NBR MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR/, | |||
553 | qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID VMG_COMPAT_ARRAY_UNDEF_CLEAR VMG_COMPAT_SCALAR_LENGTH_NOLEN/, | |||
554 | qw/VMG_PERL_PATCHLEVEL/, | |||
555 | qw/VMG_THREADSAFE/, | |||
556 | qw/VMG_OP_INFO_NAME VMG_OP_INFO_OBJECT/ | |||
557 | ] | |||
558 | ); | |||
559 | 1 | 27µs | 27µs | our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS; |
560 | 1 | 4µs | 4µs | $EXPORT_TAGS{'all'} = [ @EXPORT_OK ]; |
561 | ||||
562 | =head1 CAVEATS | |||
563 | ||||
564 | 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. | |||
565 | The only way to address this would be to return a reference. | |||
566 | ||||
567 | 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. | |||
568 | ||||
569 | =head1 DEPENDENCIES | |||
570 | ||||
571 | L<perl> 5.8. | |||
572 | ||||
573 | L<Carp> (standard since perl 5), L<XSLoader> (standard since perl 5.006). | |||
574 | ||||
575 | Copy tests need L<Tie::Array> (standard since perl 5.005) and L<Tie::Hash> (since 5.002). | |||
576 | ||||
577 | Some uvar tests need L<Hash::Util::FieldHash> (standard since perl 5.009004). | |||
578 | ||||
579 | Glob tests need L<Symbol> (standard since perl 5.002). | |||
580 | ||||
581 | Threads tests need L<threads> and L<threads::shared>. | |||
582 | ||||
583 | =head1 SEE ALSO | |||
584 | ||||
585 | L<perlguts> and L<perlapi> for internal information about magic. | |||
586 | ||||
587 | L<perltie> and L<overload> for other ways of enhancing objects. | |||
588 | ||||
589 | =head1 AUTHOR | |||
590 | ||||
591 | Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>. | |||
592 | ||||
593 | You can contact me by mail or on C<irc.perl.org> (vincent). | |||
594 | ||||
595 | =head1 BUGS | |||
596 | ||||
597 | 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. | |||
598 | ||||
599 | =head1 SUPPORT | |||
600 | ||||
601 | You can find documentation for this module with the perldoc command. | |||
602 | ||||
603 | perldoc Variable::Magic | |||
604 | ||||
605 | Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Variable-Magic>. | |||
606 | ||||
607 | =head1 COPYRIGHT & LICENSE | |||
608 | ||||
609 | Copyright 2007-2009 Vincent Pit, all rights reserved. | |||
610 | ||||
611 | This program is free software; you can redistribute it and/or modify it | |||
612 | under the same terms as Perl itself. | |||
613 | ||||
614 | =cut | |||
615 | ||||
616 | 1 | 12µs | 12µs | 1; # End of Variable::Magic |
# spent 31µs within Variable::Magic::_wizard which was called
# once (31µs+0s) by Variable::Magic::wizard at line 309 of /usr/local/lib/perl/5.10.0/Variable/Magic.pm | ||||
# spent 77µs within Variable::Magic::cast which was called 8 times, avg 10µs/call:
# 8 times (77µs+0s) by B::Hooks::EndOfScope::on_scope_end at line 58 of /usr/local/share/perl/5.10.0/B/Hooks/EndOfScope.pm, avg 10µs/call | ||||
# spent 59µs within Variable::Magic::getdata which was called 8 times, avg 7µs/call:
# 8 times (59µs+0s) by B::Hooks::EndOfScope::on_scope_end at line 54 of /usr/local/share/perl/5.10.0/B/Hooks/EndOfScope.pm, avg 7µs/call |