package Variable::Magic;
-use 5.007003;
+use 5.008;
use strict;
use warnings;
=head1 VERSION
-Version 0.27
+Version 0.29
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.27';
+ $VERSION = '0.29';
}
=head1 SYNOPSIS
=head2 C<wizard>
- wizard sig => ...,
- data => sub { ... },
- get => sub { my ($ref, $data) = @_; ... },
- set => sub { my ($ref, $data) = @_; ... },
- len => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
- clear => sub { my ($ref, $data) = @_; ... },
- free => sub { my ($ref, $data) = @_, ... },
- copy => sub { my ($ref, $data, $key, $elt) = @_; ... },
- local => sub { my ($ref, $data) = @_; ... },
- fetch => sub { my ($ref, $data, $key) = @_; ... },
- store => sub { my ($ref, $data, $key) = @_; ... },
- exists => sub { my ($ref, $data, $key) = @_; ... },
- delete => sub { my ($ref, $data, $key) = @_; ... }
+ wizard sig => ...,
+ data => sub { ... },
+ get => sub { my ($ref, $data) = @_; ... },
+ set => sub { my ($ref, $data) = @_; ... },
+ len => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
+ clear => sub { my ($ref, $data) = @_; ... },
+ free => sub { my ($ref, $data) = @_, ... },
+ copy => sub { my ($ref, $data, $key, $elt) = @_; ... },
+ local => sub { my ($ref, $data) = @_; ... },
+ fetch => sub { my ($ref, $data, $key) = @_; ... },
+ store => sub { my ($ref, $data, $key) = @_; ... },
+ exists => sub { my ($ref, $data, $key) = @_; ... },
+ delete => sub { my ($ref, $data, $key) = @_; ... },
+ copy_key => $bool
This function creates a 'wizard', an opaque type that holds the magic information.
It takes a list of keys / values as argument, whose keys can be :
=over 8
-=item -
+=item *
C<len>
-When the variable is an array, C<$_[2]> contains the normal length.
-The callback is also expected to return the new scalar or array length.
+When the variable is an array or a scalar, C<$_[2]> contains the non-magical length.
+The callback can return the new scalar or array length to use, or C<undef> to default to the normal length.
-=item -
+=item *
C<copy>
C<$_[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.
C<$_[3]> is an alias to the current element (i.e. the value).
-=item -
+=item *
C<fetch>, C<store>, C<exists> and C<delete>
If you define a wizard with a C<free> callback and cast it on itself, this destructor won't be called because the wizard will be destroyed first.
-Using simultaneously C<get> and C<clear> magics on hashes may cause segfaults.
-
=head1 DEPENDENCIES
-L<perl> 5.7.3.
+L<perl> 5.8.
L<Carp> (standard since perl 5), L<XSLoader> (standard since perl 5.006).