+ variable. This function returns true on success, 0 when no magic
+ represented by $wiz could be found in the variable, and croaks if the
+ supplied wizard is invalid.
+
+ # Dispell now.
+ die 'no such magic in $x' unless dispell $x, $wiz;
+
+CONSTANTS
+ "MGf_COPY"
+ Evaluates to true if and only if the *copy* magic is available. This is
+ the case for perl 5.7.3 and greater, which is ensured by the
+ requirements of this module.
+
+ "MGf_DUP"
+ Evaluates to true if and only if the *dup* magic is available. This is
+ the case for perl 5.7.3 and greater, which is ensured by the
+ requirements of this module.
+
+ "MGf_LOCAL"
+ Evaluates to true if and only if the *local* magic is available. This is
+ the case for perl 5.9.3 and greater.
+
+ "VMG_UVAR"
+ When this constant is true, you can use the *fetch*, *store*, *exists*
+ and *delete* magics on hashes. Initial "VMG_UVAR" capability was
+ introduced in perl 5.9.5, with a fully functional implementation shipped
+ with perl 5.10.0.
+
+ "VMG_COMPAT_SCALAR_LENGTH_NOLEN"
+ True for perls that don't call *len* magic when taking the "length" of a
+ magical scalar.
+
+ "VMG_COMPAT_SCALAR_NOLEN"
+ True for perls that don't call *len* magic on scalars. Implies
+ "VMG_COMPAT_SCALAR_LENGTH_NOLEN".
+
+ "VMG_COMPAT_ARRAY_PUSH_NOLEN"
+ True for perls that don't call *len* magic when you push an element in a
+ magical array. Starting from perl 5.11.0, this only refers to pushes in
+ non-void context and hence is false.
+
+ "VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID"
+ True for perls that don't call *len* magic when you push in void context
+ an element in a magical array.
+
+ "VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID"
+ True for perls that don't call *len* magic when you unshift in void
+ context an element in a magical array.
+
+ "VMG_COMPAT_ARRAY_UNDEF_CLEAR"
+ True for perls that call *clear* magic when undefining magical arrays.
+
+ "VMG_COMPAT_HASH_DELETE_NOUVAR_VOID"
+ True for perls that don't call *delete* magic when you delete an element
+ from a hash in void context.
+
+ "VMG_COMPAT_CODE_COPY_CLONE"
+ True for perls that call *copy* magic when a magical closure prototype
+ is cloned.
+
+ "VMG_COMPAT_GLOB_GET"
+ True for perls that call *get* magic for operations on globs.
+
+ "VMG_PERL_PATCHLEVEL"
+ The perl patchlevel this module was built with, or 0 for non-debugging
+ perls.
+
+ "VMG_THREADSAFE"
+ True if and only if this module could have been built with thread-safety
+ features enabled.
+
+ "VMG_FORKSAFE"
+ True if and only if this module could have been built with fork-safety
+ features enabled. This is always true except on Windows where it is
+ false for perl 5.10.0 and below.
+
+ "VMG_OP_INFO_NAME"
+ Value to pass with "op_info" to get the current op name in the magic
+ callbacks.
+
+ "VMG_OP_INFO_OBJECT"
+ Value to pass with "op_info" to get a "B::OP" object representing the
+ current op in the magic callbacks.
+
+COOKBOOK
+ Associate an object to any perl variable
+ This technique can be useful for passing user data through limited APIs.
+ It is similar to using inside-out objects, but without the drawback of
+ having to implement a complex destructor.
+
+ {
+ package Magical::UserData;
+
+ use Variable::Magic qw<wizard cast getdata>;
+
+ my $wiz = wizard data => sub { \$_[1] };
+
+ sub ud (\[$@%*&]) : lvalue {
+ my ($var) = @_;
+ my $data = &getdata($var, $wiz);
+ unless (defined $data) {
+ $data = \(my $slot);
+ &cast($var, $wiz, $slot)
+ or die "Couldn't cast UserData magic onto the variable";
+ }
+ $$data;
+ }
+ }
+
+ {
+ BEGIN { *ud = \&Magical::UserData::ud }
+
+ my $cb;
+ $cb = sub { print 'Hello, ', ud(&$cb), "!\n" };
+
+ ud(&$cb) = 'world';
+ $cb->(); # Hello, world!
+ }
+
+ Recursively cast magic on datastructures
+ "cast" can be called from any magical callback, and in particular from
+ "data". This allows you to recursively cast magic on datastructures :
+
+ my $wiz;
+ $wiz = wizard data => sub {
+ my ($var, $depth) = @_;
+ $depth ||= 0;
+ my $r = ref $var;
+ if ($r eq 'ARRAY') {
+ &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var;
+ } elsif ($r eq 'HASH') {
+ &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var;
+ }
+ return $depth;
+ },
+ free => sub {
+ my ($var, $depth) = @_;
+ my $r = ref $var;
+ print "free $r at depth $depth\n";
+ ();
+ };
+
+ {
+ my %h = (
+ a => [ 1, 2 ],
+ b => { c => 3 }
+ );
+ cast %h, $wiz;
+ }
+
+ When %h goes out of scope, this prints something among the lines of :
+
+ free HASH at depth 0
+ free HASH at depth 1
+ free SCALAR at depth 2
+ free ARRAY at depth 1
+ free SCALAR at depth 3
+ free SCALAR at depth 3
+
+ Of course, this example does nothing with the values that are added
+ after the "cast".
+
+PERL MAGIC HISTORY
+ The places where magic is invoked have changed a bit through perl
+ history. Here is a little list of the most recent ones.