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