+ * "len"
+
+ When the variable is an array or a scalar, $_[2] contains
+ the non-magical length. The callback can return the new
+ scalar or array length to use, or "undef" to default to the
+ normal length.
+
+ * "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.
+
+ Each callback can be specified as a code or a string reference, in which
+ case the function denoted by the string will be used as the callback.
+
+ 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.
+
+ Here's a simple usage example :
+
+ # 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" },
+ );
+
+ "cast"
+ cast [$@%&*]var, $wiz, ...
+
+ This function associates $wiz magic to the variable supplied, without
+ overwriting any other kind of magic. It returns true on success or when
+ $wiz magic is already present, and croaks on error. 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.
+
+ "getdata"
+ getdata [$@%&*]var, $wiz
+
+ This accessor fetches the private data associated with the magic $wiz in
+ the variable. It croaks when $wiz 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
+
+ The exact opposite of "cast" : it dissociates $wiz magic from the
+ 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