Document magic changes in 5.8.9

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

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index ea1836e181eda823b0c13046e3f57125e2737434..46e7ac3093076d1675b85d0f26b05b8786246675 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.
@@ -213,6 +243,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
@@ -345,7 +379,8 @@ our %EXPORT_TAGS    = (
  '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/ ]
+               qw/VMG_PERL_PATCHLEVEL/,
+               qw/VMG_THREADSAFE/ ]
 );
 our @EXPORT_OK      = map { @$_ } values %EXPORT_TAGS;
 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
@@ -368,6 +403,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 +415,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