- # 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" }
-
-=cut
-
-sub wizard {
- croak 'Wrong number of arguments for wizard()' if @_ % 2;
- my %opts = @_;
- my @keys = qw/sig data op_info get set len clear free/;
- push @keys, 'copy' if MGf_COPY;
- push @keys, 'dup' if MGf_DUP;
- push @keys, 'local' if MGf_LOCAL;
- push @keys, qw/fetch store exists delete copy_key/ if VMG_UVAR;
- my $ret = eval { _wizard(map $opts{$_}, @keys) };
- if (my $err = $@) {
- $err =~ s/\sat\s+.*?\n//;
- croak $err;
- }
- return $ret;
-}
-
-=head2 C<gensig>
-
-With this tool, you can manually generate random magic signature between SIG_MIN and SIG_MAX inclusive.
-That's the way L</wizard> creates them when no signature is supplied.
-
- # Generate a signature
- my $sig = gensig;
-
-=head2 C<getsig>
-
- getsig $wiz
-
-This accessor returns the magic signature of this wizard.
-
- # Get $wiz signature
- my $sig = getsig $wiz;
-
-=head2 C<cast>
-
- cast [$@%&*]var, [$wiz|$sig], ...
-
-This function associates C<$wiz> magic to the variable supplied, without overwriting any other kind of magic.
-You can also supply the numeric signature C<$sig> instead of C<$wiz>.
-It returns true on success or when C<$wiz> magic is already present, C<0> on error, and C<undef> when no magic corresponds to the given signature (in case C<$sig> was supplied).
-All extra arguments specified after C<$wiz> are passed to the private data constructor.
-If the variable isn't a hash, any C<uvar> callback of the wizard is safely ignored.
-
- # Casts $wiz onto $x. If $wiz isn't a signature, undef can't be returned.
- my $x;
- die 'error' unless cast $x, $wiz;
-
-The C<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 C<POSIX::tzset> each time the C<'TZ'> environment variable is changed in C<%ENV>, you can use :
-
- use POSIX;
- cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
-
-If you want to overcome the possible deletion of the C<'TZ'> entry, you have no choice but to rely on C<store> uvar magic.
-
-=head2 C<getdata>
-
- getdata [$@%&*]var, [$wiz|$sig]
-
-This accessor fetches the private data associated with the magic C<$wiz> (or the signature C<$sig>) in the variable.
-C<undef> is returned when no such magic or data is found, or when C<$sig> does not represent a current valid magic object.
-
- # Get the attached data.
- my $data = getdata $x, $wiz or die 'no such magic or magic has no data';
-
-=head2 C<dispell>
-
- dispell [$@%&*]variable, [$wiz|$sig]
-
-The exact opposite of L</cast> : it dissociates C<$wiz> magic from the variable.
-You can also pass the magic signature C<$sig> as the second argument.
-True is returned on success, C<0> on error or when no magic represented by C<$wiz> could be found in the variable, and C<undef> when no magic corresponds to the given signature (in case C<$sig> was supplied).
-
- # Dispell now. If $wiz isn't a signature, undef can't be returned.
- die 'no such magic or error' unless dispell $x, $wiz;
-