Introduce VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID to cover unshift no longer calling...

[perl/modules/Variable-Magic.git] / lib / Variable / Magic.pm

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index ea1836e181eda823b0c13046e3f57125e2737434..59cf2995d4fc63470ed205b665a4ff4500ce1c47 100644 (file)
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -13,13 +13,13 @@ Variable::Magic - Associate user-defined magic to variables from Perl.
 
 =head1 VERSION
 
-Version 0.19
+Version 0.25
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.19';
+ $VERSION = '0.25';
 }
 
 =head1 SYNOPSIS
@@ -35,7 +35,29 @@ BEGIN {
 
 =head1 DESCRIPTION
 
-Magic is Perl way of enhancing objects. This mechanism let the user add extra data to any variable and overload syntaxical operations (such as access, assignation or destruction) that can be applied to it. With this module, you can add your own magic to any variable without the pain of the C API.
+Magic is Perl way of enhancing objects. This mechanism let the user add extra data to any variable and hook syntaxical operations (such as access, assignation or destruction) that can be applied to it. With this module, you can add your own magic to any variable without the pain of the C API.
+
+Magic differs from tieing and overloading in several ways :
+
+=over 4
+
+=item *
+
+Magic isn't copied on assignation (as for blessed references) : you attach it to variables, not values.
+
+=item *
+
+It doesn't replace the original semantics : magic callbacks trigger before the original action take place, and can't prevent it to happen.
+
+=item *
+
+It's mostly invisible at the Perl level : magical and non-magical variables cannot be distinguished with C<ref>, C<reftype> or another trick.
+
+=item *
+
+It's notably faster, since perl's way of handling magic is lighter by nature, and there's no need for any method resolution.
+
+=back
 
 The operations that can be overloaded are :
 
@@ -139,6 +161,14 @@ I<p14416> : 'copy' and 'dup' magic.
 
 =item *
 
+B<5.8.9>
+
+I<p28160> : Integration of I<p25854> (see below).
+
+I<p32542> : Integration of I<p31473> (see below).
+
+=item *
+
 B<5.9.3>
 
 I<p25854> : 'len' magic is no longer called when pushing an element into a magic array.
@@ -165,6 +195,8 @@ B<5.11.x>
 
 I<p32969> : 'len' magic is no longer invoked when calling C<length> with a magical scalar.
 
+I<p34908> : 'len' magic is no longer called when pushing / unshifting an element into a magical array in void context. The C<push> part was already covered by I<p25854>.
+
 =back
 
 =head1 CONSTANTS
@@ -201,6 +233,10 @@ When this constant is true, you can use the C<fetch,store,exists,delete> callbac
 
 True for perls that don't call 'len' magic when you push an element in a magical array.
 
+=head2 C<VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID>
+
+True for perls that don't call 'len' magic when you unshift in void context an element in a magical array.
+
 =head2 C<VMG_COMPAT_ARRAY_UNDEF_CLEAR>
 
 True for perls that call 'clear' magic when undefining magical arrays.
@@ -213,6 +249,10 @@ True for perls that don't call 'len' magic when taking the C<length> of a magica
 
 The perl patchlevel this module was built with, or C<0> for non-debugging perls.
 
+=head2 C<VMG_THREADSAFE>
+
+True iff this module could have been built with thread-safety features enabled.
+
 =head1 FUNCTIONS
 
 =cut
@@ -343,9 +383,10 @@ 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/,
-               qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNDEF_CLEAR/,
+               qw/VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID VMG_COMPAT_ARRAY_UNDEF_CLEAR/,
                qw/VMG_COMPAT_SCALAR_LENGTH_NOLEN/,
-               qw/VMG_PERL_PATCHLEVEL/ ]
+               qw/VMG_PERL_PATCHLEVEL/,
+               qw/VMG_THREADSAFE/ ]
 );
 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
@@ -368,6 +409,8 @@ Some uvar tests need L<Hash::Util::FieldHash> (standard since perl 5.009004).
 
 Glob tests need L<Symbol> (standard since perl 5.002).
 
+Threads tests need L<threads> and L<threads::shared>.
+
 =head1 SEE ALSO
 
 L<perlguts> and L<perlapi> for internal information about magic.
@@ -378,7 +421,7 @@ L<perltie> and L<overload> for other ways of enhancing objects.
 
 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 
-You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).
+You can contact me by mail or on C<irc.perl.org> (vincent).
 
 =head1 BUGS