- 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, $_[0]
- is always a reference to the magic object and $_[1] is always the
- private data (or "undef" when no private data constructor was
- supplied).
+ Code (or string) references to the respective magic callbacks. You
+ don't have to specify all of them : the magic corresponding to
+ undefined entries will simply not be hooked.
+
+ When those callbacks are executed, $_[0] is a reference to the magic
+ variable and $_[1] is the associated private data (or "undef" when
+ no private data constructor is supplied with the wizard). Other
+ arguments depend on which kind of magic is involved :
+
+ * *len*
+
+ $_[2] contains the natural, non-magical length of the
+ variable (which can only be a scalar or an array as *len*
+ magic is only relevant for these types). The callback is
+ expected to return the new scalar or array length to use, or
+ "undef" to default to the normal length.
+
+ * *copy*
+
+ When the variable for which the magic is invoked is an array
+ or an hash, $_[2] is a either an alias or a copy of the
+ current key, and $_[3] is an alias to the current element
+ (i.e. the value). Since $_[2] might be a copy, it is useless
+ to try to change it or cast magic on it.
+
+ Starting from perl 5.17.0, this magic can also be called for
+ code references. In this case, $_[2] is always "undef" and
+ $_[3] is a reference to the cloned anonymous subroutine.
+
+ * *fetch*, *store*, *exists* and *delete*
+
+ $_[2] is an alias to the current key. Note that $_[2] may
+ rightfully be readonly if the key comes from a bareword, and
+ as such it is unsafe to assign to it. You can ask for a copy
+ instead by passing "copy_key => 1" to "wizard" which, at the
+ price of a small performance hit, allows you to safely
+ assign to $_[2] in order to e.g. redirect the action to
+ another key.