1Variable::Magic(3)    User Contributed Perl Documentation   Variable::Magic(3)
2
3
4

NAME

6       Variable::Magic - Associate user-defined magic to variables from Perl.
7

VERSION

9       Version 0.62
10

SYNOPSIS

12           use Variable::Magic qw<wizard cast VMG_OP_INFO_NAME>;
13
14           { # A variable tracer
15            my $wiz = wizard(
16             set  => sub { print "now set to ${$_[0]}!\n" },
17             free => sub { print "destroyed!\n" },
18            );
19
20            my $a = 1;
21            cast $a, $wiz;
22            $a = 2;        # "now set to 2!"
23           }               # "destroyed!"
24
25           { # A hash with a default value
26            my $wiz = wizard(
27             data     => sub { $_[1] },
28             fetch    => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () },
29             store    => sub { print "key $_[2] stored in $_[-1]\n" },
30             copy_key => 1,
31             op_info  => VMG_OP_INFO_NAME,
32            );
33
34            my %h = (_default => 0, apple => 2);
35            cast %h, $wiz, '_default';
36            print $h{banana}, "\n"; # "0" (there is no 'banana' key in %h)
37            $h{pear} = 1;           # "key pear stored in helem"
38           }
39

DESCRIPTION

41       Magic is Perl's way of enhancing variables.  This mechanism lets the
42       user add extra data to any variable and hook syntactical operations
43       (such as access, assignment or destruction) that can be applied to it.
44       With this module, you can add your own magic to any variable without
45       having to write a single line of XS.
46
47       You'll realize that these magic variables look a lot like tied
48       variables.  It is not surprising, as tied variables are implemented as
49       a special kind of magic, just like any 'irregular' Perl variable :
50       scalars like $!, $( or $^W, the %ENV and %SIG hashes, the @ISA array,
51       "vec()" and "substr()" lvalues, threads::shared variables...  They all
52       share the same underlying C API, and this module gives you direct
53       access to it.
54
55       Still, the magic made available by this module differs from tieing and
56       overloading in several ways :
57
58       ·   Magic is not copied on assignment.
59
60           You attach it to variables, not values (as for blessed references).
61
62       ·   Magic does not replace the original semantics.
63
64           Magic callbacks usually get triggered before the original action
65           takes place, and cannot prevent it from happening.  This also makes
66           catching individual events easier than with "tie", where you have
67           to provide fallbacks methods for all actions by usually inheriting
68           from the correct "Tie::Std*" class and overriding individual
69           methods in your own class.
70
71       ·   Magic is multivalued.
72
73           You can safely apply different kinds of magics to the same
74           variable, and each of them will be invoked successively.
75
76       ·   Magic is type-agnostic.
77
78           The same magic can be applied on scalars, arrays, hashes, subs or
79           globs.  But the same hook (see below for a list) may trigger
80           differently depending on the type of the variable.
81
82       ·   Magic is invisible at Perl level.
83
84           Magical and non-magical variables cannot be distinguished with
85           "ref", "tied" or another trick.
86
87       ·   Magic is notably faster.
88
89           Mainly because perl's way of handling magic is lighter by nature,
90           and because there is no need for any method resolution.  Also,
91           since you don't have to reimplement all the variable semantics, you
92           only pay for what you actually use.
93
94       The operations that can be overloaded are :
95
96       ·   get
97
98           This magic is invoked when the variable is evaluated.  It is never
99           called for arrays and hashes.
100
101       ·   set
102
103           This magic is called each time the value of the variable changes.
104           It is called for array subscripts and slices, but never for hashes.
105
106       ·   len
107
108           This magic only applies to arrays (though it used to also apply to
109           scalars), and is triggered when the 'size' or the 'length' of the
110           variable has to be known by Perl.  This is typically the magic
111           involved when an array is evaluated in scalar context, but also on
112           array assignment and loops ("for", "map" or "grep").  The length is
113           returned from the callback as an integer.
114
115           Starting from perl 5.12, this magic is no longer called by the
116           "length" keyword, and starting from perl 5.17.4 it is also no
117           longer called for scalars in any situation, making this magic only
118           meaningful on arrays.  You can use the constants
119           "VMG_COMPAT_SCALAR_LENGTH_NOLEN" and "VMG_COMPAT_SCALAR_NOLEN" to
120           see if this magic is available for scalars or not.
121
122       ·   clear
123
124           This magic is invoked when the variable is reset, such as when an
125           array is emptied.  Please note that this is different from
126           undefining the variable, even though the magic is called when the
127           clearing is a result of the undefine (e.g. for an array, but
128           actually a bug prevent it to work before perl 5.9.5 - see the
129           history).
130
131       ·   free
132
133           This magic is called when a variable is destroyed as the result of
134           going out of scope (but not when it is undefined).  It behaves
135           roughly like Perl object destructors (i.e. "DESTROY" methods),
136           except that exceptions thrown from inside a free callback will
137           always be propagated to the surrounding code.
138
139       ·   copy
140
141           When applied to tied arrays and hashes, this magic fires when you
142           try to access or change their elements.
143
144           Starting from perl 5.17.0, it can also be applied to closure
145           prototypes, in which case the magic will be called when the
146           prototype is cloned.  The "VMG_COMPAT_CODE_COPY_CLONE" constant is
147           true when your perl support this feature.
148
149       ·   dup
150
151           This magic is invoked when the variable is cloned across threads.
152           It is currently not available.
153
154       ·   local
155
156           When this magic is set on a variable, all subsequent localizations
157           of the variable will trigger the callback.  It is available on your
158           perl if and only if "MGf_LOCAL" is true.
159
160       The following actions only apply to hashes and are available if and
161       only if "VMG_UVAR" is true.  They are referred to as uvar magics.
162
163       ·   fetch
164
165           This magic is invoked each time an element is fetched from the
166           hash.
167
168       ·   store
169
170           This one is called when an element is stored into the hash.
171
172       ·   exists
173
174           This magic fires when a key is tested for existence in the hash.
175
176       ·   delete
177
178           This magic is triggered when a key is deleted in the hash,
179           regardless of whether the key actually exists in it.
180
181       You can refer to the tests to have more insight of where the different
182       magics are invoked.
183

FUNCTIONS

185   "wizard"
186           wizard(
187            data     => sub { ... },
188            get      => sub { my ($ref, $data [, $op]) = @_; ... },
189            set      => sub { my ($ref, $data [, $op]) = @_; ... },
190            len      => sub {
191             my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen
192            },
193            clear    => sub { my ($ref, $data [, $op]) = @_; ... },
194            free     => sub { my ($ref, $data [, $op]) = @_, ... },
195            copy     => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... },
196            local    => sub { my ($ref, $data [, $op]) = @_; ... },
197            fetch    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
198            store    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
199            exists   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
200            delete   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
201            copy_key => $bool,
202            op_info  => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ],
203           )
204
205       This function creates a 'wizard', an opaque object that holds the magic
206       information.  It takes a list of keys / values as argument, whose keys
207       can be :
208
209       ·   "data"
210
211           A code (or string) reference to a private data constructor.  It is
212           called in scalar context each time the magic is cast onto a
213           variable, with $_[0] being a reference to this variable and @_[1 ..
214           @_-1] being all extra arguments that were passed to "cast".  The
215           scalar returned from this call is then attached to the variable and
216           can be retrieved later with "getdata".
217
218       ·   "get", "set", "len", "clear", "free", "copy", "local", "fetch",
219           "store", "exists" and "delete"
220
221           Code (or string) references to the respective magic callbacks.  You
222           don't have to specify all of them : the magic corresponding to
223           undefined entries will simply not be hooked.
224
225           When those callbacks are executed, $_[0] is a reference to the
226           magic variable and $_[1] is the associated private data (or "undef"
227           when no private data constructor is supplied with the wizard).
228           Other arguments depend on which kind of magic is involved :
229
230           ·       len
231
232                   $_[2] contains the natural, non-magical length of the
233                   variable (which can only be a scalar or an array as len
234                   magic is only relevant for these types).  The callback is
235                   expected to return the new scalar or array length to use,
236                   or "undef" to default to the normal length.
237
238           ·       copy
239
240                   When the variable for which the magic is invoked is an
241                   array or an hash, $_[2] is a either an alias or a copy of
242                   the current key, and $_[3] is an alias to the current
243                   element (i.e. the value).  Since $_[2] might be a copy, it
244                   is useless to try to change it or cast magic on it.
245
246                   Starting from perl 5.17.0, this magic can also be called
247                   for code references.  In this case, $_[2] is always "undef"
248                   and $_[3] is a reference to the cloned anonymous
249                   subroutine.
250
251           ·       fetch, store, exists and delete
252
253                   $_[2] is an alias to the current key.  Note that $_[2] may
254                   rightfully be readonly if the key comes from a bareword,
255                   and as such it is unsafe to assign to it.  You can ask for
256                   a copy instead by passing "copy_key => 1" to "wizard"
257                   which, at the price of a small performance hit, allows you
258                   to safely assign to $_[2] in order to e.g. redirect the
259                   action to another key.
260
261           Finally, if "op_info => $num" is also passed to "wizard", then one
262           extra element is appended to @_.  Its nature depends on the value
263           of $num :
264
265           ·       "VMG_OP_INFO_NAME"
266
267                   $_[-1] is the current op name.
268
269           ·       "VMG_OP_INFO_OBJECT"
270
271                   $_[-1] is the "B::OP" object for the current op.
272
273           Both result in a small performance hit, but just getting the name
274           is lighter than getting the op object.
275
276           These callbacks are always executed in scalar context.  The
277           returned value is coerced into a signed integer, which is then
278           passed straight to the perl magic API.  However, note that perl
279           currently only cares about the return value of the len magic
280           callback and ignores all the others.  Starting with Variable::Magic
281           0.58, a reference returned from a non-len magic callback will not
282           be destroyed immediately but will be allowed to survive until the
283           end of the statement that triggered the magic.  This lets you use
284           this return value as a token for triggering a destructor after the
285           original magic action takes place.  You can see an example of this
286           technique in the cookbook.
287
288       Each callback can be specified as :
289
290       ·   a code reference, which will be called as a subroutine.
291
292       ·   a string reference, where the string denotes which subroutine is to
293           be called when magic is triggered.  If the subroutine name is not
294           fully qualified, then the current package at the time the magic is
295           invoked will be used instead.
296
297       ·   a reference to "undef", in which case a no-op magic callback is
298           installed instead of the default one.  This may especially be
299           helpful for local magic, where an empty callback prevents magic
300           from being copied during localization.
301
302       Note that free magic is never called during global destruction, as
303       there is no way to ensure that the wizard object and the callback were
304       not destroyed before the variable.
305
306       Here is a simple usage example :
307
308           # A simple scalar tracer
309           my $wiz = wizard(
310            get  => sub { print STDERR "got ${$_[0]}\n" },
311            set  => sub { print STDERR "set to ${$_[0]}\n" },
312            free => sub { print STDERR "${$_[0]} was deleted\n" },
313           );
314
315   "cast"
316           cast [$@%&*]var, $wiz, @args
317
318       This function associates $wiz magic to the supplied variable, without
319       overwriting any other kind of magic.  It returns true on success or
320       when $wiz magic is already attached, and croaks on error.  When $wiz
321       provides a data constructor, it is called just before magic is cast
322       onto the variable, and it receives a reference to the target variable
323       in $_[0] and the content of @args in @_[1 .. @args].  Otherwise, @args
324       is ignored.
325
326           # Casts $wiz onto $x, passing (\$x, '1') to the data constructor.
327           my $x;
328           cast $x, $wiz, 1;
329
330       The "var" argument can be an array or hash value.  Magic for these
331       scalars behaves like for any other, except that it is dispelled when
332       the entry is deleted from the container.  For example, if you want to
333       call "POSIX::tzset" each time the 'TZ' environment variable is changed
334       in %ENV, you can use :
335
336           use POSIX;
337           cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
338
339       If you want to handle the possible deletion of the 'TZ' entry, you must
340       also specify store magic.
341
342   "getdata"
343           getdata [$@%&*]var, $wiz
344
345       This accessor fetches the private data associated with the magic $wiz
346       in the variable.  It croaks when $wiz does not represent a valid magic
347       object, and returns an empty list if no such magic is attached to the
348       variable or when the wizard has no data constructor.
349
350           # Get the data attached to $wiz in $x, or undef if $wiz
351           # did not attach any.
352           my $data = getdata $x, $wiz;
353
354   "dispell"
355           dispell [$@%&*]variable, $wiz
356
357       The exact opposite of "cast" : it dissociates $wiz magic from the
358       variable.  This function returns true on success, 0 when no magic
359       represented by $wiz could be found in the variable, and croaks if the
360       supplied wizard is invalid.
361
362           # Dispell now.
363           die 'no such magic in $x' unless dispell $x, $wiz;
364

CONSTANTS

366   "MGf_COPY"
367       Evaluates to true if and only if the copy magic is available.  This is
368       the case for perl 5.7.3 and greater, which is ensured by the
369       requirements of this module.
370
371   "MGf_DUP"
372       Evaluates to true if and only if the dup magic is available.  This is
373       the case for perl 5.7.3 and greater, which is ensured by the
374       requirements of this module.
375
376   "MGf_LOCAL"
377       Evaluates to true if and only if the local magic is available.  This is
378       the case for perl 5.9.3 and greater.
379
380   "VMG_UVAR"
381       When this constant is true, you can use the fetch, store, exists and
382       delete magics on hashes.  Initial "VMG_UVAR" capability was introduced
383       in perl 5.9.5, with a fully functional implementation shipped with perl
384       5.10.0.
385
386   "VMG_COMPAT_SCALAR_LENGTH_NOLEN"
387       True for perls that don't call len magic when taking the "length" of a
388       magical scalar.
389
390   "VMG_COMPAT_SCALAR_NOLEN"
391       True for perls that don't call len magic on scalars.  Implies
392       "VMG_COMPAT_SCALAR_LENGTH_NOLEN".
393
394   "VMG_COMPAT_ARRAY_PUSH_NOLEN"
395       True for perls that don't call len magic when you push an element in a
396       magical array.  Starting from perl 5.11.0, this only refers to pushes
397       in non-void context and hence is false.
398
399   "VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID"
400       True for perls that don't call len magic when you push in void context
401       an element in a magical array.
402
403   "VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID"
404       True for perls that don't call len magic when you unshift in void
405       context an element in a magical array.
406
407   "VMG_COMPAT_ARRAY_UNDEF_CLEAR"
408       True for perls that call clear magic when undefining magical arrays.
409
410   "VMG_COMPAT_HASH_DELETE_NOUVAR_VOID"
411       True for perls that don't call delete magic when you delete an element
412       from a hash in void context.
413
414   "VMG_COMPAT_CODE_COPY_CLONE"
415       True for perls that call copy magic when a magical closure prototype is
416       cloned.
417
418   "VMG_COMPAT_GLOB_GET"
419       True for perls that call get magic for operations on globs.
420
421   "VMG_PERL_PATCHLEVEL"
422       The perl patchlevel this module was built with, or 0 for non-debugging
423       perls.
424
425   "VMG_THREADSAFE"
426       True if and only if this module could have been built with thread-
427       safety features enabled.
428
429   "VMG_FORKSAFE"
430       True if and only if this module could have been built with fork-safety
431       features enabled.  This is always true except on Windows where it is
432       false for perl 5.10.0 and below.
433
434   "VMG_OP_INFO_NAME"
435       Value to pass with "op_info" to get the current op name in the magic
436       callbacks.
437
438   "VMG_OP_INFO_OBJECT"
439       Value to pass with "op_info" to get a "B::OP" object representing the
440       current op in the magic callbacks.
441

COOKBOOK

443   Associate an object to any perl variable
444       This technique can be useful for passing user data through limited
445       APIs.  It is similar to using inside-out objects, but without the
446       drawback of having to implement a complex destructor.
447
448           {
449            package Magical::UserData;
450
451            use Variable::Magic qw<wizard cast getdata>;
452
453            my $wiz = wizard data => sub { \$_[1] };
454
455            sub ud (\[$@%*&]) : lvalue {
456             my ($var) = @_;
457             my $data = &getdata($var, $wiz);
458             unless (defined $data) {
459              $data = \(my $slot);
460              &cast($var, $wiz, $slot)
461                        or die "Couldn't cast UserData magic onto the variable";
462             }
463             $$data;
464            }
465           }
466
467           {
468            BEGIN { *ud = \&Magical::UserData::ud }
469
470            my $cb;
471            $cb = sub { print 'Hello, ', ud(&$cb), "!\n" };
472
473            ud(&$cb) = 'world';
474            $cb->(); # Hello, world!
475           }
476
477   Recursively cast magic on datastructures
478       "cast" can be called from any magical callback, and in particular from
479       "data".  This allows you to recursively cast magic on datastructures :
480
481           my $wiz;
482           $wiz = wizard data => sub {
483            my ($var, $depth) = @_;
484            $depth ||= 0;
485            my $r = ref $var;
486            if ($r eq 'ARRAY') {
487             &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var;
488            } elsif ($r eq 'HASH') {
489             &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var;
490            }
491            return $depth;
492           },
493           free => sub {
494            my ($var, $depth) = @_;
495            my $r = ref $var;
496            print "free $r at depth $depth\n";
497            ();
498           };
499
500           {
501            my %h = (
502             a => [ 1, 2 ],
503             b => { c => 3 }
504            );
505            cast %h, $wiz;
506           }
507
508       When %h goes out of scope, this prints something among the lines of :
509
510           free HASH at depth 0
511           free HASH at depth 1
512           free SCALAR at depth 2
513           free ARRAY at depth 1
514           free SCALAR at depth 3
515           free SCALAR at depth 3
516
517       Of course, this example does nothing with the values that are added
518       after the "cast".
519
520   Delayed magic actions
521       Starting with Variable::Magic 0.58, the return value of the magic
522       callbacks can be used to delay the action until after the original
523       action takes place :
524
525           my $delayed;
526           my $delayed_aux = wizard(
527            data => sub { $_[1] },
528            free => sub {
529             my ($target) = $_[1];
530             my $target_data = &getdata($target, $delayed);
531             local $target_data->{guard} = 1;
532             if (ref $target eq 'SCALAR') {
533              my $orig = $$target;
534              $$target = $target_data->{mangler}->($orig);
535             }
536             return;
537            },
538           );
539           $delayed = wizard(
540            data => sub {
541             return +{ guard => 0, mangler => $_[1] };
542            },
543            set  => sub {
544             return if $_[1]->{guard};
545             my $token;
546             cast $token, $delayed_aux, $_[0];
547             return \$token;
548            },
549           );
550           my $x = 1;
551           cast $x, $delayed => sub { $_[0] * 2 };
552           $x = 2;
553           # $x is now 4
554           # But note that the delayed action only takes place at the end of the
555           # current statement :
556           my @y = ($x = 5, $x);
557           # $x is now 10, but @y is (5, 5)
558

PERL MAGIC HISTORY

560       The places where magic is invoked have changed a bit through perl
561       history.  Here is a little list of the most recent ones.
562
563       ·   5.6.x
564
565           p14416 : copy and dup magic.
566
567       ·   5.8.9
568
569           p28160 : Integration of p25854 (see below).
570
571           p32542 : Integration of p31473 (see below).
572
573       ·   5.9.3
574
575           p25854 : len magic is no longer called when pushing an element into
576           a magic array.
577
578           p26569 : local magic.
579
580       ·   5.9.5
581
582           p31064 : Meaningful uvar magic.
583
584           p31473 : clear magic was not invoked when undefining an array.  The
585           bug is fixed as of this version.
586
587       ·   5.10.0
588
589           Since "PERL_MAGIC_uvar" is uppercased, "hv_magic_check()" triggers
590           copy magic on hash stores for (non-tied) hashes that also have uvar
591           magic.
592
593       ·   5.11.x
594
595           p32969 : len magic is no longer invoked when calling "length" with
596           a magical scalar.
597
598           p34908 : len magic is no longer called when pushing / unshifting an
599           element into a magical array in void context.  The "push" part was
600           already covered by p25854.
601
602           g9cdcb38b : len magic is called again when pushing into a magical
603           array in non-void context.
604

EXPORT

606       The functions "wizard", "cast", "getdata" and "dispell" are only
607       exported on request.  All of them are exported by the tags ':funcs' and
608       ':all'.
609
610       All the constants are also only exported on request, either
611       individually or by the tags ':consts' and ':all'.
612

CAVEATS

614       In order to hook hash operations with magic, you need at least perl
615       5.10.0 (see "VMG_UVAR").
616
617       If you want to store a magic object in the private data slot, you will
618       not be able to recover the magic with "getdata", since magic is not
619       copied by assignment.  You can work around this gotcha by storing a
620       reference to the magic object instead.
621
622       If you define a wizard with free magic and cast it on itself, it
623       results in a memory cycle, so this destructor will not be called when
624       the wizard is freed.
625

DEPENDENCIES

627       perl 5.8.
628
629       A C compiler.  This module may happen to build with a C++ compiler as
630       well, but don't rely on it, as no guarantee is made in this regard.
631
632       Carp (core since perl 5), XSLoader (since 5.6.0).
633

SEE ALSO

635       perlguts and perlapi for internal information about magic.
636
637       perltie and overload for other ways of enhancing objects.
638

AUTHOR

640       Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
641
642       You can contact me by mail or on "irc.perl.org" (vincent).
643

BUGS

645       Please report any bugs or feature requests to "bug-variable-magic at
646       rt.cpan.org", or through the web interface at
647       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>.  I
648       will be notified, and then you'll automatically be notified of progress
649       on your bug as I make changes.
650

SUPPORT

652       You can find documentation for this module with the perldoc command.
653
654           perldoc Variable::Magic
655
657       Copyright 2007,2008,2009,2010,2011,2012,2013,2014,2015,2016,2017
658       Vincent Pit, all rights reserved.
659
660       This program is free software; you can redistribute it and/or modify it
661       under the same terms as Perl itself.
662
663
664
665perl v5.32.0                      2020-07-28                Variable::Magic(3)
Impressum