- 'get', 'set', 'len', 'clear' and 'free'
- Code references to 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 a reference to
- the magic object and $_[1] is the private data (or "undef" when no
- private data constructor was supplied). In the special case of "len"
- magic and when the variable is an array, $_[2] contains its normal
- length.
+ * "get", "set", "len", "clear", "free", "copy", "local", "fetch",
+ "store", "exists" and "delete"
+
+ 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, $_[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).
+
+ Moreover, when you pass "op_info => $num" to "wizard", the last
+ element of @_ will be the current op name if "$num ==
+ VMG_OP_INFO_NAME" and a "B::OP" object representing the current op
+ if "$num == VMG_OP_INFO_OBJECT". Both have a performance hit, but
+ just getting the name is lighter than getting the op object.
+
+ Other arguments are specific to the magic hooked :
+
+ * "len"
+
+ When the variable is an array or a scalar, $_[2] contains
+ the non-magical length. The callback can return the new
+ scalar or array length to use, or "undef" to default to the
+ normal length.
+
+ * "copy"
+
+ $_[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. $_[3] is an alias to the current element (i.e.
+ the value).
+
+ * "fetch", "store", "exists" and "delete"
+
+ $_[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 "copy_key => 1" to "wizard", which allows you to
+ safely assign to $_[2] in order to e.g. redirect the action
+ to another key. This however has a little performance
+ drawback because of the copy.
+
+ 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 "len" callback currently holds a meaning.