=head1 VERSION
-Version 0.08
+Version 0.19
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.08';
+ $VERSION = '0.19';
}
=head1 SYNOPSIS
=back
-The following actions only applies to hashes and are available iff C<VMG_UVAR> is true. They are referred to as C<uvar> magics.
+The following actions only apply to hashes and are available iff C<VMG_UVAR> is true. They are referred to as C<uvar> magics.
=over 4
=over 4
-=item 'len' magic is no longer called when pushing an element into a magic array.
+=item I<p25854> : 'len' magic is no longer called when pushing an element into a magic array.
=item I<p26569> : 'local' magic.
=back
+=head2 B<5.10.0>
+
+=over 4
+
+=item Since C<PERL_MAGIC_uvar> is uppercased, C<hv_magic_check()> triggers 'copy' magic on hash stores for (non-tied) hashes that also have 'uvar' magic.
+
+=back
+
+=head2 B<5.11.x>
+
+=over 4
+
+=item I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar.
+
+=back
+
=head1 CONSTANTS
=head2 C<SIG_MIN>
When this constant is true, you can use the C<fetch,store,exists,delete> callbacks on hashes.
+=head2 C<VMG_COMPAT_ARRAY_PUSH_NOLEN>
+
+True for perls that don't call 'len' magic when you push an element in a magical array.
+
+=head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR>
+
+True for perls that call 'clear' magic when undefining magical arrays.
+
+=head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN>
+
+True for perls that don't call 'len' magic when taking the C<length> of a magical scalar.
+
+=head2 C<VMG_PERL_PATCHLEVEL>
+
+The perl patchlevel this module was built with, or C<0> for non-debugging perls.
+
=head1 FUNCTIONS
=cut
len => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
clear => sub { my ($ref, $data) = @_; ... },
free => sub { my ($ref, $data) = @_, ... },
- copy => sub { my ($ref, $data, $elt) = @_; ... },
+ copy => sub { my ($ref, $data, $key, $elt) = @_; ... },
local => sub { my ($ref, $data) = @_; ... },
fetch => sub { my ($ref, $data, $key) = @_; ... },
store => sub { my ($ref, $data, $key) = @_; ... },
=item C<get>, C<set>, C<len>, C<clear>, C<free>, C<copy>, C<local>, C<fetch>, C<store>, C<exists> and C<delete>
-Code references to corresponding magic callbacks. You don't have to specify all of them : the magic associated with undefined entries simply won't be hooked. In those callbacks, C<$_[0]> is always a reference to the magic object and C<$_[1]> is always the private data (or C<undef> when no private data constructor was supplied). In the special case of C<len> magic and when the variable is an array, C<$_[2]> contains its normal length. C<copy> magic receives the current element (i.e. the value) in C<$_[2]>. C<$_[2]> is also the current key in C<fetch>, C<store>, C<exists> and C<delete> callbacks.
+Code references to corresponding magic callbacks. You don't have to specify all of them : the magic associated with undefined entries simply won't be hooked. In those callbacks, C<$_[0]> is always a reference to the magic object and C<$_[1]> is always the private data (or C<undef> when no private data constructor was supplied). In the special case of C<len> magic and when the variable is an array, C<$_[2]> contains its normal length. C<$_[2]> is the current key in C<copy>, C<fetch>, C<store>, C<exists> and C<delete> callbacks, although for C<copy> it may just be a copy of the actual key so it's useless to (for example) cast magic on it. C<copy> magic also receives the current element (i.e. the value) in C<$_[3]>.
=back
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.
+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;
our @EXPORT = ();
our %EXPORT_TAGS = (
'funcs' => [ qw/wizard gensig getsig cast getdata dispell/ ],
- 'consts' => [ qw/SIG_MIN SIG_MAX SIG_NBR MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR/ ]
+ 'consts' => [ qw/SIG_MIN SIG_MAX SIG_NBR MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR/,
+ qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNDEF_CLEAR/,
+ qw/VMG_COMPAT_SCALAR_LENGTH_NOLEN/,
+ qw/VMG_PERL_PATCHLEVEL/ ]
);
our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
$EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
+=head1 CAVEATS
+
+If you store a magic object in the private data slot, the magic won't be accessible by L</getdata> since it's not copied by assignation. The only way to address this would be to return a reference.
+
+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.
+
=head1 DEPENDENCIES
L<perl> 5.7.3.
=head1 AUTHOR
-Vincent Pit, C<< <perl at profvince.com> >>
+Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
-You can contact me by mail or on #perl @ FreeNode (Prof_Vince).
+You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).
=head1 BUGS
-Please report any bugs or feature requests to
-C<bug-variable-magic at rt.cpan.org>, or through the web interface at
-L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>.
-I will be notified, and then you'll automatically be notified of progress on
-your bug as I make changes.
+Please report any bugs or feature requests to C<bug-variable-magic at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
=head1 SUPPORT
perldoc Variable::Magic
+Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Variable-Magic>.
+
=head1 COPYRIGHT & LICENSE
Copyright 2007-2008 Vincent Pit, all rights reserved.
projects / perl / modules / Variable-Magic.git / blobdiff