From: Vincent Pit <vince@profvince.com>
Date: Fri, 23 Jan 2009 22:57:29 +0000 (+0100)
Subject: Better documentation for the values passed to the callbacks
X-Git-Tag: v0.28~6
X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FVariable-Magic.git;a=commitdiff_plain;h=c475e1988f3033a818329f04d2e86acbc3c53632

Better documentation for the values passed to the callbacks
---

diff --git a/lib/Variable/Magic.pm b/lib/Variable/Magic.pm
index 5f268a4..70dff80 100644
--- a/lib/Variable/Magic.pm
+++ b/lib/Variable/Magic.pm
@@ -317,12 +317,38 @@ 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 corresponding magic callbacks.
+Code 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).
-In the special case of C<len> magic and when the variable is an array, C<$_[2]> contains its normal length.
-C<$_[2]> is the current key in C<copy>, C<fetch>, C<store>, C<exists> and C<delete> callbacks, although for C<copy> it may just be a copy of the actual key so it's useless to (for example) cast magic on it.
-C<copy> magic also receives the current element (i.e. the value) in C<$_[3]>.
+Other arguments are specific to the magic hooked :
+
+=over 8
+
+=item -
+
+C<len>
+
+When the variable is an array, C<$_[2]> contains the normal length.
+The callback is also expected to return the new scalar or array length.
+
+=item -
+
+C<copy>
+
+C<$_[2]> is a either a copy or an alias of the current key, which means that it is useless to try to change or cast magic on it.
+C<$_[3]> is an alias to the current element (i.e. the value).
+
+=item -
+
+C<fetch>, C<store>, C<exists> and C<delete>
+
+C<$_[2]> is an alias to the current key.
+Nothing prevents you from changing it, but be aware that there lurk dangerous side effects.
+For example, it may righteously be readonly if the key was a bareword.
+You can get a copy instead by passing C<< copy_key => 1 >> to L</wizard>, which allows you to safely assign to C<$_[2]> in order to e.g. redirect the action to another key.
+This however has a little performance drawback because of the copy.
+
+=back
 
 All the callbacks are expected to return an integer, which is passed straight to the perl magic API.
 However, only the return value of the C<len> callback currently holds a meaning.