X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=b9efea7b1d142a58bbcfafdf5b6cabea5daefe94;hb=6a204757f3b9c5d10bc57e21cbb65c0e29688066;hp=541b09da0daa68af9a14683aa6da0137ba1b4c0f;hpb=77a84f75f33e3ee44e61182dec76699e23025375;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index 541b09d..b9efea7 100644 --- a/README +++ b/README @@ -2,97 +2,251 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.01 + Version 0.37 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/wizard cast VMG_OP_INFO_NAME/; + + { # 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", because the 'banana' key doesn't exist 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 overload 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 way of enhancing objects. This mechanism lets the user add + extra data to any variable and hook syntaxical 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's 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 : + + * It isn't copied on assignment. + + You attach it to variables, not values (as for blessed references). + + * It doesn't replace the original semantics. + + Magic callbacks usually trigger before the original action take + place, and can't prevent it to happen. 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. + + * It's type-agnostic. + + 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 the type of the variable. + + * It's mostly invisible at the Perl level. + + Magical and non-magical variables cannot be distinguished with + "ref", "tied" or another trick. + + * It's notably faster. + + Mainly because perl's way of handling magic is lighter by nature, + and because there's 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" - This magic is invoked when the variable is evaluated (does not - include array/hash subscripts and slices). + * "get" + + This magic is invoked when the variable is evaluated. It is never + called for arrays and hashes. - "set" - This one is triggered each time the value of the variable changes - (includes array/hash subscripts and slices). + * "set" + + This one is triggered 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 + also on array assignment and loops ("for", "map" or "grep"). The callback has then to return the length as an integer. - "clear" + * "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 - the variable, even though the magic is called when the reset is a - result of the undefine (e.g. for an array). + the variable, even though the magic is called when the clearing is a + 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" - This last 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. + * "free" - 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). + This one can be considered as an object destructor. It happens when + the variable goes out of scope, but not when it is undefined. -CONSTANTS - "SIG_MIN" - The minimum integer used as a signature for user-defined magic. + * "copy" - "SIG_MAX" - The maximum integer used as a signature for user-defined magic. + 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. - "SIG_NBR" - SIG_NBR = SIG_MAX - SIG_MIN + 1 + * "dup" + + Invoked when the variable is cloned across threads. Currently not + available. + + * "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. + + The following actions only apply to hashes and are available iff + "VMG_UVAR" is true. They are referred to as "uvar" magics. + + * "fetch" + + This magic happens each time an element is fetched from the hash. + + * "store" + + This one is called when an element is stored into the hash. + + * "exists" + + This magic fires when a key is tested for existence in the hash. + + * "delete" + + This last one triggers 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). At the C level, magic + tokens owned by magic created by this module have their "mg->mg_private" + field set to 0x3891 or 0x3892, so please don't use these magic (sic) + numbers in other extensions. FUNCTIONS "wizard" - wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => .. + wizard sig => ..., + 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 type that holds the magic information. It takes a list of keys / values as argument, whose keys can be : - 'sig' + * "sig" + The numerical signature. If not specified or undefined, a random - signature is generated. - - 'data' - A code reference to a private data constructor. It will be called - each time this magic is cast on a variable, and the scalar returned - will be used as private data storage for it. - - '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. When the magic variable is an array or a - hash, $_[0] is a reference to it, but directly references it - otherwise. $_[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. + signature is generated. If the signature matches an already defined + magic, then the existant magic object is returned. + + * "data" + + 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". + + * "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 rightfully 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. # 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" } + 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 "free" callbacks are *never* called during global destruction, + as there's no way to ensure that the wizard and the "free" callback + weren't destroyed before the variable. "gensig" With this tool, you can manually generate random magic signature between @@ -111,52 +265,244 @@ FUNCTIONS my $sig = getsig $wiz; "cast" - cast [$@%&*]var, $wiz + cast [$@%&*]var, [$wiz|$sig], ... This function associates $wiz magic to the variable supplied, without - overwriting any other kind of magic. It returns true on success or when - $wiz magic is already present, and false on error. - - # Casts $wiz to $x + 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, and croaks on error or when no magic + corresponds to the given signature (in case a $sig was supplied). All + extra arguments specified after $wiz are passed to the private data + constructor in @_[1 .. @_-1]. If the variable isn't a hash, any "uvar" + callback of the wizard is safely ignored. + + # Casts $wiz onto $x, and pass '1' to the data constructor. my $x; - die 'error' unless cast $x, $wiz; + cast $x, $wiz, 1; + + The "var" argument can be an array or hash value. Magic for those + behaves like for any other scalar, 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(); () }; + + If you want to overcome the possible deletion of the 'TZ' entry, you + have no choice but to rely on "store" uvar magic. + + "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 will print 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". "getdata" - getdata [$@%&*]var, $wiz + getdata [$@%&*]var, [$wiz|$sig] - This accessor fetches the private data associated with the magic $wiz in - the variable. "undef" is returned when no such magic or data is found. + This accessor fetches the private data associated with the magic $wiz + (or the signature $sig) in the variable. It croaks when $wiz or $sig do + 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 attached data, or undef if the wizard does not attach any. + my $data = getdata $x, $wiz; "dispell" - dispell [$@%&*]variable, $wiz - dispell [$@%&*]variable, $sig + dispell [$@%&*]variable, [$wiz|$sig] The exact opposite of "cast" : it dissociates $wiz magic from the - variable. You can also pass the magic signature as the second argument. - True is returned on success, and false on error or when no magic - represented by $wiz could be found in the variable. + variable. You can also pass the magic signature $sig as the second + argument. This function returns true on success, 0 when no magic + represented by $wiz or $sig could be found in the variable, and croaks + if the supplied wizard or signature is invalid. + + # Dispell now. + die 'no such magic in $x' unless dispell $x, $wiz; + +CONSTANTS + "SIG_MIN" + The minimum integer used as a signature for user-defined magic. + + "SIG_MAX" + The maximum integer used as a signature for user-defined magic. + + "SIG_NBR" + SIG_NBR = SIG_MAX - SIG_MIN + 1 + + "MGf_COPY" + Evaluates to true iff the 'copy' magic is available. + + "MGf_DUP" + Evaluates to true iff the 'dup' magic is available. + + "MGf_LOCAL" + Evaluates to true iff the 'local' magic is available. + + "VMG_UVAR" + When this constant is true, you can use the "fetch,store,exists,delete" + callbacks on hashes. + + "VMG_COMPAT_ARRAY_PUSH_NOLEN" + True for perls that don't call 'len' magic when you push 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 + context an element in a magical array. + + "VMG_COMPAT_ARRAY_UNDEF_CLEAR" + 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_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. + + "VMG_FORKSAFE" + True iff this module could have been built with fork-safety features + enabled. This will always be true except on Windows where it's false for + perl 5.10.0 and below . - # Dispell now - die 'no such magic or error' unless dispell $x, $wiz; + "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. + +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. + + * 5.6.x + + *p14416* : 'copy' and 'dup' magic. + + * 5.8.9 + + *p28160* : Integration of *p25854* (see below). + + *p32542* : Integration of *p31473* (see below). + + * 5.9.3 + + *p25854* : 'len' magic is no longer called when pushing an element + into a magic array. + + *p26569* : 'local' magic. + + * 5.9.5 + + *p31064* : Meaningful 'uvar' magic. + + *p31473* : 'clear' magic wasn't invoked when undefining an array. + The bug is fixed as of this version. + + * 5.10.0 + + Since "PERL_MAGIC_uvar" is uppercased, "hv_magic_check()" triggers + 'copy' magic on hash stores for (non-tied) hashes that also have + 'uvar' magic. + + * 5.11.x + + *p32969* : 'len' magic is no longer invoked when calling "length" + with a magical scalar. + + *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*. 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 constants "SIG_MIN", "SIG_MAX" and "SIG_NBR" 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 assignment. The only + way to address this would be to return a reference. + + 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. DEPENDENCIES + perl 5.8. + Carp (standard since perl 5), XSLoader (standard since perl 5.006). - Tests use Symbol (standard since perl 5.002). + Copy tests need Tie::Array (standard since perl 5.005) and Tie::Hash + (since 5.002). + + Some uvar tests need Hash::Util::FieldHash (standard since perl + 5.009004). + + Glob tests need Symbol (standard since perl 5.002). + + Threads tests need threads and threads::shared. SEE ALSO perlguts and perlapi for internal information about magic. + perltie and overload for other ways of enhancing objects. + AUTHOR - Vincent Pit, "" + Vincent Pit, "", . + + You can contact me by mail or on "irc.perl.org" (vincent). BUGS Please report any bugs or feature requests to "bug-variable-magic at @@ -170,8 +516,11 @@ SUPPORT perldoc Variable::Magic + Tests code coverage report is available at + . + COPYRIGHT & LICENSE - Copyright 2007 Vincent Pit, all rights reserved. + Copyright 2007-2009 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.