From: Vincent Pit <vince@profvince.com>
Date: Mon, 30 Nov 2009 23:59:21 +0000 (+0100)
Subject: Document passing a string reference as the callback
X-Git-Tag: v0.39~1
X-Git-Url: http://git.vpit.fr/?a=commitdiff_plain;h=0e5ba8fa888250d493359ef1988234021bac0530;p=perl%2Fmodules%2FVariable-Magic.git

Document passing a string reference as the callback
---

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index c600a15..05fb364 100644
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -232,7 +232,7 @@ It takes a list of keys / values as argument, whose keys can be :
 
 C<data>
 
-A code reference to a private data constructor.
+A code (or string) reference to a private data constructor.
 It is called each time this magic is cast on a variable, and the scalar returned is used as private data storage for it.
 C<$_[0]> is a reference to the magic object and C<@_[1 .. @_-1]> are all extra arguments that were passed to L</cast>.
 
@@ -240,7 +240,7 @@ C<$_[0]> is a reference to the magic object and C<@_[1 .. @_-1]> are all extra a
 
 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 the corresponding magic callbacks.
+Code (or string) references to the 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).
 
@@ -282,13 +282,17 @@ 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.
+
+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.
+
+Here's a simple usage example :
+
     # A simple scalar tracer
     my $wiz = wizard get  => sub { print STDERR "got ${$_[0]}\n" },
                      set  => sub { print STDERR "set to ${$_[0]}\n" },
                      free => sub { print STDERR "${$_[0]} was deleted\n" }
 
-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.
-
 =cut
 
 sub wizard {