+ * "copy"
+
+ $_[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. $_[3] is an alias to the current element (i.e.
+ the value).
+
+ * "fetch", "store", "exists" and "delete"
+
+ $_[2] is an alias to the current key. Nothing prevents you
+ from changing it, but be aware that there lurk dangerous
+ side effects. For example, it may rightfully be readonly if
+ the key was a bareword. You can get a copy instead by
+ passing "copy_key => 1" to "wizard", which allows you to
+ safely assign to $_[2] in order to e.g. redirect the action
+ to another key. This however has a little performance
+ drawback because of the copy.
+
+ All the callbacks are expected to return an integer, which is passed
+ straight to the perl magic API. However, only the return value of
+ the "len" callback currently holds a meaning.
+
+ # A simple scalar tracer
+ my $wiz = wizard get => sub { print STDERR "got ${$_[0]}\n" },
+ set => sub { print STDERR "set to ${$_[0]}\n" },
+ free => sub { print STDERR "${$_[0]} was deleted\n" }
+
+ Note that "free" callbacks are *never* called during global destruction,
+ as there's no way to ensure that the wizard and the "free" callback
+ weren't destroyed before the variable.
+
+ "gensig"
+ With this tool, you can manually generate random magic signature between
+ SIG_MIN and SIG_MAX inclusive. That's the way "wizard" creates them when
+ no signature is supplied.
+
+ # Generate a signature
+ my $sig = gensig;
+
+ "getsig"
+ getsig $wiz
+
+ This accessor returns the magic signature of this wizard.
+
+ # Get $wiz signature
+ my $sig = getsig $wiz;
+
+ "cast"
+ cast [$@%&*]var, [$wiz|$sig], ...
+
+ This function associates $wiz magic to the variable supplied, without
+ overwriting any other kind of magic. You can also supply the numeric
+ signature $sig instead of $wiz. It returns true on success or when $wiz
+ magic is already present, and croaks on error or when no magic
+ corresponds to the given signature (in case a $sig was supplied). All
+ extra arguments specified after $wiz are passed to the private data
+ constructor in @_[1 .. @_-1]. If the variable isn't a hash, any "uvar"
+ callback of the wizard is safely ignored.
+
+ # Casts $wiz onto $x, and pass '1' to the data constructor.
+ my $x;
+ cast $x, $wiz, 1;
+
+ The "var" argument can be an array or hash value. Magic for those
+ behaves like for any other scalar, except that it is dispelled when the
+ entry is deleted from the container. For example, if you want to call
+ "POSIX::tzset" each time the 'TZ' environment variable is changed in
+ %ENV, you can use :
+
+ use POSIX;
+ cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
+
+ If you want to overcome the possible deletion of the 'TZ' entry, you
+ have no choice but to rely on "store" uvar magic.
+
+ "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 will print 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".
+
+ "getdata"
+ getdata [$@%&*]var, [$wiz|$sig]
+
+ This accessor fetches the private data associated with the magic $wiz
+ (or the signature $sig) in the variable. It croaks when $wiz or $sig 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.
+
+ # Get the attached data, or undef if the wizard does not attach any.
+ my $data = getdata $x, $wiz;
+
+ "dispell"
+ dispell [$@%&*]variable, [$wiz|$sig]
+
+ The exact opposite of "cast" : it dissociates $wiz magic from the
+ variable. You can also pass the magic signature $sig as the second
+ argument. This function returns true on success, 0 when no magic
+ represented by $wiz or $sig could be found in the variable, and croaks
+ if the supplied wizard or signature is invalid.
+
+ # Dispell now.
+ die 'no such magic in $x' unless dispell $x, $wiz;