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 af2762db066577e372fc7b918b593c468a377490..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.
@@ -373,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.
@@ -383,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