+ # 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