Allow passing ref-to-undef as callbacks to install a noop callback

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

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index fd2c0ef6b3b73e7b3f3e186626a9b1fe9c0f211a..73402ac0262b328ff8002695d01150c49b6cdeaa 100644 (file)
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -11,13 +11,13 @@ Variable::Magic - Associate user-defined magic to variables from Perl.
 
 =head1 VERSION
 
-Version 0.46
+Version 0.47
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.46';
+ $VERSION = '0.47';
 }
 
 =head1 SYNOPSIS
@@ -196,9 +196,6 @@ This last one triggers when a key is deleted in the hash, regardless of whether
 
 You can refer to the tests to have more insight of where the different magics are invoked.
 
-To prevent any clash between different magics defined with this module, an unique numerical signature is attached to each kind of magic (i.e. each set of callbacks for magic operations).
-At the C level, magic tokens owned by magic created by this module have their C<< mg->mg_private >> field set to C<0x3891> or C<0x3892>, so please don't use these magic (sic) numbers in other extensions.
-
 =head1 FUNCTIONS
 
 =cut
@@ -288,7 +285,25 @@ However, only the return value of the C<len> callback currently holds a meaning.
 
 =back
 
-Each callback can be specified as a code or a string reference, in which case the function denoted by the string will be used as the callback.
+Each callback can be specified as :
+
+=over 4
+
+=item *
+
+a code reference, which will be called as a subroutine.
+
+=item *
+
+a string reference, where the string denotes which subroutine is to be called when magic is triggered.
+If the subroutine name is not fully qualified, then the current package at the time the magic is invoked will be used instead.
+
+=item *
+
+a reference to C<undef>, in which case a no-op magic callback is installed instead of the default one.
+This may especially be helpful for 'local' magic, where an empty callback prevents magic from being copied during localization.
+
+=back
 
 Note that C<free> callbacks are I<never> called during global destruction, as there's no way to ensure that the wizard and the C<free> callback weren't destroyed before the variable.
 
@@ -311,9 +326,7 @@ sub wizard {
 
  my %opts = @_;
 
- my @keys = qw<op_info data get set len clear free>;
- push @keys, 'copy'  if MGf_COPY;
- push @keys, 'dup'   if MGf_DUP;
+ my @keys = qw<op_info data get set len clear free copy dup>;
  push @keys, 'local' if MGf_LOCAL;
  push @keys, qw<fetch store exists delete copy_key> if VMG_UVAR;
 
@@ -394,6 +407,10 @@ When this constant is true, you can use the C<fetch,store,exists,delete> callbac
 Initial VMG_UVAR capability was introduced in perl 5.9.5, with a fully functional implementation
 shipped with perl 5.10.0.
 
+=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_COMPAT_ARRAY_PUSH_NOLEN>
 
 True for perls that don't call 'len' magic when you push an element in a magical array.
@@ -411,9 +428,9 @@ True for perls that don't call 'len' magic when you unshift in void context an e
 
 True for perls that call 'clear' magic when undefining magical arrays.
 
-=head2 C<VMG_COMPAT_SCALAR_LENGTH_NOLEN>
+=head2 C<VMG_COMPAT_HASH_DELETE_NOUVAR_VOID>
 
-True for perls that don't call 'len' magic when taking the C<length> of a magical scalar.
+True for perls that don't call 'delete' uvar magic when you delete an element from a hash in void context.
 
 =head2 C<VMG_COMPAT_GLOB_GET>
 
@@ -592,10 +609,11 @@ our %EXPORT_TAGS    = (
  'funcs' =>  [ qw<wizard cast getdata dispell> ],
  'consts' => [ qw<
    MGf_COPY MGf_DUP MGf_LOCAL VMG_UVAR
+   VMG_COMPAT_SCALAR_LENGTH_NOLEN
    VMG_COMPAT_ARRAY_PUSH_NOLEN VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID
    VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID
    VMG_COMPAT_ARRAY_UNDEF_CLEAR
-   VMG_COMPAT_SCALAR_LENGTH_NOLEN
+   VMG_COMPAT_HASH_DELETE_NOUVAR_VOID
    VMG_COMPAT_GLOB_GET
    VMG_PERL_PATCHLEVEL
    VMG_THREADSAFE VMG_FORKSAFE