X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FVariable-Magic.git;a=blobdiff_plain;f=README;h=b77b8453ef9536f4c6eec27afcb6de4103bd444f;hp=d5004fc0fd7ac68598b453f4a6961dca6b4b84dd;hb=ae89b589d2187cf0ed57bbb6132b9d4a8da29abb;hpb=da9c1cac7534f75645bb34430d38ec2d912eb9f4 diff --git a/README b/README index d5004fc..b77b845 100644 --- a/README +++ b/README @@ -2,62 +2,119 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.27 + Version 0.53 SYNOPSIS - use Variable::Magic qw/wizard cast dispell/; - - my $wiz = wizard set => sub { print STDERR "now set to ${$_[0]}!\n" }; - my $a = 1; - cast $a, $wiz; - $a = 2; # "now set to 2!" - dispell $a, $wiz; - $a = 3 # (nothing) + use Variable::Magic qw; + + { # A variable tracer + my $wiz = wizard( + set => sub { print "now set to ${$_[0]}!\n" }, + free => sub { print "destroyed!\n" }, + ); + + my $a = 1; + cast $a, $wiz; + $a = 2; # "now set to 2!" + } # "destroyed!" + + { # A hash with a default value + my $wiz = wizard( + data => sub { $_[1] }, + fetch => sub { $_[2] = $_[1] unless exists $_[0]->{$_[2]}; () }, + store => sub { print "key $_[2] stored in $_[-1]\n" }, + copy_key => 1, + op_info => VMG_OP_INFO_NAME, + ); + + my %h = (_default => 0, apple => 2); + cast %h, $wiz, '_default'; + print $h{banana}, "\n"; # "0" (there is no 'banana' key in %h) + $h{pear} = 1; # "key pear stored in helem" + } DESCRIPTION - Magic is Perl way of enhancing objects. This mechanism let the user add - extra data to any variable and hook syntaxical operations (such as - access, assignation or destruction) that can be applied to it. With this - module, you can add your own magic to any variable without the pain of - the C API. + Magic is Perl's way of enhancing variables. This mechanism lets the user + add extra data to any variable and hook syntactical operations (such as + access, assignment or destruction) that can be applied to it. With this + module, you can add your own magic to any variable without having to + write a single line of XS. + + You'll realize that these magic variables look a lot like tied + variables. It is not surprising, as tied variables are implemented as a + special kind of magic, just like any 'irregular' Perl variable : scalars + like $!, $( or $^W, the %ENV and %SIG hashes, the @ISA array, "vec()" + and "substr()" lvalues, threads::shared variables... They all share the + same underlying C API, and this module gives you direct access to it. + + Still, the magic made available by this module differs from tieing and + overloading in several ways : + + * Magic is not copied on assignment. + + You attach it to variables, not values (as for blessed references). + + * Magic does not replace the original semantics. + + Magic callbacks usually get triggered before the original action + takes place, and cannot prevent it from happening. This also makes + catching individual events easier than with "tie", where you have to + provide fallbacks methods for all actions by usually inheriting from + the correct "Tie::Std*" class and overriding individual methods in + your own class. - Magic differs from tieing and overloading in several ways : + * Magic is multivalued. - * Magic isn't copied on assignation (as for blessed references) : you - attach it to variables, not values. + You can safely apply different kinds of magics to the same variable, + and each of them will be invoked successively. - * It doesn't replace the original semantics : magic callbacks trigger - before the original action take place, and can't prevent it to - happen. + * Magic is type-agnostic. - * It's mostly invisible at the Perl level : magical and non-magical - variables cannot be distinguished with "ref", "reftype" or another - trick. + The same magic can be applied on scalars, arrays, hashes, subs or + globs. But the same hook (see below for a list) may trigger + differently depending on the type of the variable. - * It's notably faster, since perl's way of handling magic is lighter - by nature, and there's no need for any method resolution. + * Magic is invisible at Perl level. + + Magical and non-magical variables cannot be distinguished with + "ref", "tied" or another trick. + + * Magic is notably faster. + + Mainly because perl's way of handling magic is lighter by nature, + and because there is no need for any method resolution. Also, since + you don't have to reimplement all the variable semantics, you only + pay for what you actually use. The operations that can be overloaded are : - * "get" + * *get* - This magic is invoked when the variable is evaluated (does not - include array/hash subscripts and slices). + This magic is invoked when the variable is evaluated. It is never + called for arrays and hashes. - * "set" + * *set* - This one is triggered each time the value of the variable changes - (includes array/hash subscripts and slices). + This magic is called each time the value of the variable changes. It + is called for array subscripts and slices, but never for hashes. - * "len" + * *len* - This magic is a little special : it is called when the 'size' or the - 'length' of the variable has to be known by Perl. Typically, it's - the magic involved when an array is evaluated in scalar context, but - also on array assignation and loops ("for", "map" or "grep"). The - callback has then to return the length as an integer. + This magic only applies to arrays (though it used to also apply to + scalars), and is triggered when the 'size' or the 'length' of the + variable has to be known by Perl. This is typically the magic + involved when an array is evaluated in scalar context, but also on + array assignment and loops ("for", "map" or "grep"). The length is + returned from the callback as an integer. - * "clear" + Starting from perl 5.12, this magic is no longer called by the + "length" keyword, and starting from perl 5.17.4 it is also no longer + called for scalars in any situation, making this magic only + meaningful on arrays. You can use the constants + "VMG_COMPAT_SCALAR_LENGTH_NOLEN" and "VMG_COMPAT_SCALAR_NOLEN" to + see if this magic is available for scalars or not. + + * *clear* This magic is invoked when the variable is reset, such as when an array is emptied. Please note that this is different from undefining @@ -65,292 +122,450 @@ DESCRIPTION result of the undefine (e.g. for an array, but actually a bug prevent it to work before perl 5.9.5 - see the history). - * "free" + * *free* - This one can be considered as an object destructor. It happens when - the variable goes out of scope (with the exception of global scope), - but not when it is undefined. + This magic is called when a variable is destroyed as the result of + going out of scope (but not when it is undefined). It behaves + roughly like Perl object destructors (i.e. "DESTROY" methods), + except that exceptions thrown from inside a *free* callback will + always be propagated to the surrounding code. - * "copy" + * *copy* - This magic only applies to tied arrays and hashes. It fires when you - try to access or change their elements. It is available on your perl - iff "MGf_COPY" is true. + This magic only applies to tied arrays and hashes, and fires when + you try to access or change their elements. - * "dup" + * *dup* - Invoked when the variable is cloned across threads. Currently not - available. + This magic is invoked when the variable is cloned across threads. It + is currently not available. - * "local" + * *local* When this magic is set on a variable, all subsequent localizations of the variable will trigger the callback. It is available on your - perl iff "MGf_LOCAL" is true. + perl if and only if "MGf_LOCAL" is true. - The following actions only apply to hashes and are available iff - "VMG_UVAR" is true. They are referred to as "uvar" magics. + The following actions only apply to hashes and are available if and only + if "VMG_UVAR" is true. They are referred to as *uvar* magics. - * "fetch" + * *fetch* - This magic happens each time an element is fetched from the hash. + This magic is invoked each time an element is fetched from the hash. - * "store" + * *store* This one is called when an element is stored into the hash. - * "exists" + * *exists* This magic fires when a key is tested for existence in the hash. - * "delete" + * *delete* - This last one triggers when a key is deleted in the hash, regardless - of whether the key actually exists in it. + This magic is triggered when a key is deleted in the hash, + regardless of whether the key actually exists in it. 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). +FUNCTIONS + "wizard" + wizard( + data => sub { ... }, + get => sub { my ($ref, $data [, $op]) = @_; ... }, + set => sub { my ($ref, $data [, $op]) = @_; ... }, + len => sub { + my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen + }, + clear => sub { my ($ref, $data [, $op]) = @_; ... }, + free => sub { my ($ref, $data [, $op]) = @_, ... }, + copy => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... }, + local => sub { my ($ref, $data [, $op]) = @_; ... }, + fetch => sub { my ($ref, $data, $key [, $op]) = @_; ... }, + store => sub { my ($ref, $data, $key [, $op]) = @_; ... }, + exists => sub { my ($ref, $data, $key [, $op]) = @_; ... }, + delete => sub { my ($ref, $data, $key [, $op]) = @_; ... }, + copy_key => $bool, + op_info => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ], + ) + + This function creates a 'wizard', an opaque object that holds the magic + information. It takes a list of keys / values as argument, whose keys + can be : -PERL MAGIC HISTORY - The places where magic is invoked have changed a bit through perl - history. Here's a little list of the most recent ones. + * "data" - * 5.6.x + A code (or string) reference to a private data constructor. It is + called in scalar context each time the magic is cast onto a + variable, with $_[0] being a reference to this variable and @_[1 .. + @_-1] being all extra arguments that were passed to "cast". The + scalar returned from this call is then attached to the variable and + can be retrieved later with "getdata". - *p14416* : 'copy' and 'dup' magic. + * "get", "set", "len", "clear", "free", "copy", "local", "fetch", + "store", "exists" and "delete" - * 5.8.9 + 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. - *p28160* : Integration of *p25854* (see below). + 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 : - *p32542* : Integration of *p31473* (see below). + * *len* - * 5.9.3 + $_[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. - *p25854* : 'len' magic is no longer called when pushing an element - into a magic array. + * *copy* - *p26569* : 'local' magic. + $_[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). + Because $_[2] might be a copy, it is useless to try to + change it or cast magic on it. - * 5.9.5 + * *fetch*, *store*, *exists* and *delete* - *p31064* : Meaningful 'uvar' magic. + $_[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. - *p31473* : 'clear' magic wasn't invoked when undefining an array. - The bug is fixed as of this version. + Finally, if "op_info => $num" is also passed to "wizard", then one + extra element is appended to @_. Its nature depends on the value of + $num : - * 5.10.0 + * "VMG_OP_INFO_NAME" - Since "PERL_MAGIC_uvar" is uppercased, "hv_magic_check()" triggers - 'copy' magic on hash stores for (non-tied) hashes that also have - 'uvar' magic. + $_[-1] is the current op name. - * 5.11.x + * "VMG_OP_INFO_OBJECT" - *p32969* : 'len' magic is no longer invoked when calling "length" - with a magical scalar. + $_[-1] is the "B::OP" object for the current op. - *p34908* : 'len' magic is no longer called when pushing / unshifting - an element into a magical array in void context. The "push" part was - already covered by *p25854*. + Both result in a small performance hit, but just getting the name is + lighter than getting the op object. -CONSTANTS - "SIG_MIN" - The minimum integer used as a signature for user-defined magic. + These callbacks are executed in scalar context and are expected to + return an integer, which is then passed straight to the perl magic + API. However, only the return value of the *len* magic callback + currently holds a meaning. + + Each callback can be specified as : + + * a code reference, which will be called as a subroutine. + + * 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. + + * a reference to "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. + + Note that *free* magic is never called during global destruction, as + there is no way to ensure that the wizard object and the callback were + not destroyed before the variable. + + Here is 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" }, + ); + + "cast" + cast [$@%&*]var, $wiz, @args + + This function associates $wiz magic to the supplied variable, without + overwriting any other kind of magic. It returns true on success or when + $wiz magic is already attached, and croaks on error. When $wiz provides + a data constructor, it is called just before magic is cast onto the + variable, and it receives a reference to the target variable in $_[0] + and the content of @args in @_[1 .. @args]. Otherwise, @args is ignored. + + # Casts $wiz onto $x, passing (\$x, '1') to the data constructor. + my $x; + cast $x, $wiz, 1; + + The "var" argument can be an array or hash value. Magic for these + scalars behaves like for any other, except that it is dispelled when the + entry is deleted from the container. For example, if you want to call + "POSIX::tzset" each time the 'TZ' environment variable is changed in + %ENV, you can use : + + use POSIX; + cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () }; - "SIG_MAX" - The maximum integer used as a signature for user-defined magic. + If you want to handle the possible deletion of the 'TZ' entry, you must + also specify *store* magic. - "SIG_NBR" - SIG_NBR = SIG_MAX - SIG_MIN + 1 + "getdata" + getdata [$@%&*]var, $wiz + + This accessor fetches the private data associated with the magic $wiz in + the variable. It croaks when $wiz does not represent a valid magic + object, and returns an empty list if no such magic is attached to the + variable or when the wizard has no data constructor. + + # Get the data attached to $wiz in $x, or undef if $wiz + # did not attach any. + my $data = getdata $x, $wiz; + + "dispell" + dispell [$@%&*]variable, $wiz + + The exact opposite of "cast" : it dissociates $wiz magic from the + variable. This function returns true on success, 0 when no magic + represented by $wiz could be found in the variable, and croaks if the + supplied wizard is invalid. + # Dispell now. + die 'no such magic in $x' unless dispell $x, $wiz; + +CONSTANTS "MGf_COPY" - Evaluates to true iff the 'copy' magic is available. + Evaluates to true if and only if the *copy* magic is available. This is + the case for perl 5.7.3 and greater, which is ensured by the + requirements of this module. "MGf_DUP" - Evaluates to true iff the 'dup' magic is available. + Evaluates to true if and only if the *dup* magic is available. This is + the case for perl 5.7.3 and greater, which is ensured by the + requirements of this module. "MGf_LOCAL" - Evaluates to true iff the 'local' magic is available. + Evaluates to true if and only if the *local* magic is available. This is + the case for perl 5.9.3 and greater. "VMG_UVAR" - When this constant is true, you can use the "fetch,store,exists,delete" - callbacks on hashes. + When this constant is true, you can use the *fetch*, *store*, *exists* + and *delete* magics on hashes. Initial "VMG_UVAR" capability was + introduced in perl 5.9.5, with a fully functional implementation shipped + with perl 5.10.0. + + "VMG_COMPAT_SCALAR_LENGTH_NOLEN" + True for perls that don't call *len* magic when taking the "length" of a + magical scalar. + + "VMG_COMPAT_SCALAR_NOLEN" + True for perls that don't call *len* magic on scalars. Implies + "VMG_COMPAT_SCALAR_LENGTH_NOLEN". "VMG_COMPAT_ARRAY_PUSH_NOLEN" - True for perls that don't call 'len' magic when you push an element in a - magical array. + True for perls that don't call *len* magic when you push an element in a + magical array. Starting from perl 5.11.0, this only refers to pushes in + non-void context and hence is false. + + "VMG_COMPAT_ARRAY_PUSH_NOLEN_VOID" + True for perls that don't call *len* magic when you push in void context + an element in a magical array. "VMG_COMPAT_ARRAY_UNSHIFT_NOLEN_VOID" - True for perls that don't call 'len' magic when you unshift in void + True for perls that don't call *len* magic when you unshift in void context an element in a magical array. "VMG_COMPAT_ARRAY_UNDEF_CLEAR" - True for perls that call 'clear' magic when undefining magical arrays. + True for perls that call *clear* magic when undefining magical arrays. - "VMG_COMPAT_SCALAR_LENGTH_NOLEN" - True for perls that don't call 'len' magic when taking the "length" of a - magical scalar. + "VMG_COMPAT_HASH_DELETE_NOUVAR_VOID" + True for perls that don't call *delete* magic when you delete an element + from a hash in void context. + + "VMG_COMPAT_GLOB_GET" + True for perls that call *get* magic for operations on globs. "VMG_PERL_PATCHLEVEL" The perl patchlevel this module was built with, or 0 for non-debugging perls. "VMG_THREADSAFE" - True iff this module could have been built with thread-safety features - enabled. - -FUNCTIONS - "wizard" - wizard sig => ..., - data => sub { ... }, - get => sub { my ($ref, $data) = @_; ... }, - set => sub { my ($ref, $data) = @_; ... }, - len => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; }, - clear => sub { my ($ref, $data) = @_; ... }, - free => sub { my ($ref, $data) = @_, ... }, - copy => sub { my ($ref, $data, $key, $elt) = @_; ... }, - local => sub { my ($ref, $data) = @_; ... }, - fetch => sub { my ($ref, $data, $key) = @_; ... }, - store => sub { my ($ref, $data, $key) = @_; ... }, - exists => sub { my ($ref, $data, $key) = @_; ... }, - delete => sub { my ($ref, $data, $key) = @_; ... } - - This function creates a 'wizard', an opaque type that holds the magic - information. It takes a list of keys / values as argument, whose keys - can be : + True if and only if this module could have been built with thread-safety + features enabled. + + "VMG_FORKSAFE" + True if and only if this module could have been built with fork-safety + features enabled. This is always true except on Windows where it is + false for perl 5.10.0 and below. + + "VMG_OP_INFO_NAME" + Value to pass with "op_info" to get the current op name in the magic + callbacks. + + "VMG_OP_INFO_OBJECT" + Value to pass with "op_info" to get a "B::OP" object representing the + current op in the magic callbacks. + +COOKBOOK + Associate an object to any perl variable + This technique can be useful for passing user data through limited APIs. + It is similar to using inside-out objects, but without the drawback of + having to implement a complex destructor. + + { + package Magical::UserData; + + use Variable::Magic qw; + + my $wiz = wizard data => sub { \$_[1] }; + + sub ud (\[$@%*&]) : lvalue { + my ($var) = @_; + my $data = &getdata($var, $wiz); + unless (defined $data) { + $data = \(my $slot); + &cast($var, $wiz, $slot) + or die "Couldn't cast UserData magic onto the variable"; + } + $$data; + } + } + + { + BEGIN { *ud = \&Magical::UserData::ud } + + my $cb; + $cb = sub { print 'Hello, ', ud(&$cb), "!\n" }; + + ud(&$cb) = 'world'; + $cb->(); # Hello, world! + } + + Recursively cast magic on datastructures + "cast" can be called from any magical callback, and in particular from + "data". This allows you to recursively cast magic on datastructures : + + my $wiz; + $wiz = wizard data => sub { + my ($var, $depth) = @_; + $depth ||= 0; + my $r = ref $var; + if ($r eq 'ARRAY') { + &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for @$var; + } elsif ($r eq 'HASH') { + &cast((ref() ? $_ : \$_), $wiz, $depth + 1) for values %$var; + } + return $depth; + }, + free => sub { + my ($var, $depth) = @_; + my $r = ref $var; + print "free $r at depth $depth\n"; + (); + }; + + { + my %h = ( + a => [ 1, 2 ], + b => { c => 3 } + ); + cast %h, $wiz; + } + + When %h goes out of scope, this prints something among the lines of : + + free HASH at depth 0 + free HASH at depth 1 + free SCALAR at depth 2 + free ARRAY at depth 1 + free SCALAR at depth 3 + free SCALAR at depth 3 + + Of course, this example does nothing with the values that are added + after the "cast". - * "sig" - - The numerical signature. If not specified or undefined, a random - signature is generated. If the signature matches an already defined - magic, then the existant magic object is returned. +PERL MAGIC HISTORY + The places where magic is invoked have changed a bit through perl + history. Here is a little list of the most recent ones. - * "data" + * 5.6.x - A code 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. $_[0] is a reference to the - magic object and @_[1 .. @_-1] are all extra arguments that were - passed to "cast". + *p14416* : *copy* and *dup* magic. - * "get", "set", "len", "clear", "free", "copy", "local", "fetch", - "store", "exists" and "delete" + * 5.8.9 - 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 always a - reference to the magic object and $_[1] is always 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. $_[2] is the current key in "copy", - "fetch", "store", "exists" and "delete" callbacks, although for - "copy" it may just be a copy of the actual key so it's useless to - (for example) cast magic on it. "copy" magic also receives the - current element (i.e. the value) in $_[3]. - - 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. + *p28160* : Integration of *p25854* (see below). - # 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" } + *p32542* : Integration of *p31473* (see below). - "gensig" - With this tool, you can manually generate random magic signature between - SIG_MIN and SIG_MAX inclusive. That's the way "wizard" creates them when - no signature is supplied. + * 5.9.3 - # Generate a signature - my $sig = gensig; + *p25854* : *len* magic is no longer called when pushing an element + into a magic array. - "getsig" - getsig $wiz + *p26569* : *local* magic. - This accessor returns the magic signature of this wizard. + * 5.9.5 - # Get $wiz signature - my $sig = getsig $wiz; + *p31064* : Meaningful *uvar* magic. - "cast" - cast [$@%&*]var, [$wiz|$sig], ... - - This function associates $wiz magic to the variable supplied, without - overwriting any other kind of magic. You can also supply the numeric - signature $sig instead of $wiz. It returns true on success or when $wiz - magic is already present, 0 on error, and "undef" when no magic - corresponds to the given signature (in case $sig was supplied). All - extra arguments specified after $wiz are passed to the private data - constructor. If the variable isn't a hash, any "uvar" callback of the - wizard is safely ignored. - - # Casts $wiz onto $x. If $wiz isn't a signature, undef can't be returned. - my $x; - die 'error' unless cast $x, $wiz; + *p31473* : *clear* magic was not invoked when undefining an array. + The bug is fixed as of this version. - "getdata" - getdata [$@%&*]var, [$wiz|$sig] + * 5.10.0 - This accessor fetches the private data associated with the magic $wiz - (or the signature $sig) in the variable. "undef" is returned when no - such magic or data is found, or when $sig does not represent a current - valid magic object. + Since "PERL_MAGIC_uvar" is uppercased, "hv_magic_check()" triggers + *copy* magic on hash stores for (non-tied) hashes that also have + *uvar* magic. - # Get the attached data. - my $data = getdata $x, $wiz or die 'no such magic or magic has no data'; + * 5.11.x - "dispell" - dispell [$@%&*]variable, [$wiz|$sig] + *p32969* : *len* magic is no longer invoked when calling "length" + with a magical scalar. - The exact opposite of "cast" : it dissociates $wiz magic from the - variable. You can also pass the magic signature $sig as the second - argument. True is returned on success, 0 on error or when no magic - represented by $wiz could be found in the variable, and "undef" when no - magic corresponds to the given signature (in case $sig was supplied). + *p34908* : *len* magic is no longer called when pushing / unshifting + an element into a magical array in void context. The "push" part was + already covered by *p25854*. - # Dispell now. If $wiz isn't a signature, undef can't be returned. - die 'no such magic or error' unless dispell $x, $wiz; + *g9cdcb38b* : *len* magic is called again when pushing into a + magical array in non-void context. EXPORT - The functions "wizard", "gensig", "getsig", "cast", "getdata" and - "dispell" are only exported on request. All of them are exported by the - tags ':funcs' and ':all'. + The functions "wizard", "cast", "getdata" and "dispell" are only + exported on request. All of them are exported by the tags ':funcs' and + ':all'. - The constants "SIG_MIN", "SIG_MAX", "SIG_NBR", "MGf_COPY", "MGf_DUP", - "MGf_LOCAL" and "VMG_UVAR" are also only exported on request. They are - all exported by the tags ':consts' and ':all'. + All the constants are also only exported on request, either individually + or by the tags ':consts' and ':all'. CAVEATS - If you store a magic object in the private data slot, the magic won't be - accessible by "getdata" since it's not copied by assignation. The only - way to address this would be to return a reference. + In order to hook hash operations with magic, you need at least perl + 5.10.0 (see "VMG_UVAR"). - If you define a wizard with a "free" callback and cast it on itself, - this destructor won't be called because the wizard will be destroyed - first. + If you want to store a magic object in the private data slot, you will + not be able to recover the magic with "getdata", since magic is not + copied by assignment. You can work around this gotcha by storing a + reference to the magic object instead. - Using "get" and "clear" magics on hashes may cause segfaults. + If you define a wizard with *free* magic and cast it on itself, it + results in a memory cycle, so this destructor will not be called when + the wizard is freed. DEPENDENCIES - perl 5.7.3. - - Carp (standard since perl 5), XSLoader (standard since perl 5.006). - - Copy tests need Tie::Array (standard since perl 5.005) and Tie::Hash - (since 5.002). + perl 5.8. - Some uvar tests need Hash::Util::FieldHash (standard since perl - 5.009004). + A C compiler. This module may happen to build with a C++ compiler as + well, but don't rely on it, as no guarantee is made in this regard. - Glob tests need Symbol (standard since perl 5.002). + Carp (core since perl 5), XSLoader (since 5.6.0). - Threads tests need threads and threads::shared. + Copy tests need Tie::Array (core since perl 5.005) and Tie::Hash (since + 5.002). Some uvar tests need Hash::Util::FieldHash (since 5.9.4). Glob + tests need Symbol (since 5.002). Threads tests need threads and + threads::shared (both since 5.7.3). SEE ALSO perlguts and perlapi for internal information about magic. @@ -378,7 +593,8 @@ SUPPORT . COPYRIGHT & LICENSE - Copyright 2007-2009 Vincent Pit, all rights reserved. + Copyright 2007,2008,2009,2010,2011,2012,2013 Vincent Pit, all rights + reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.