X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=944ed1936a9cce0c05590278aa8b6e9bc291d7b6;hb=91aec4cfae75e61ff8eeb79448501a8739b0d240;hp=281f3dca7838554375ef4149ead4dc35b84529c9;hpb=14f66d40970bef63105be046a109c1a32859a8a0;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index 281f3dc..944ed19 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.04 + Version 0.15 SYNOPSIS use Variable::Magic qw/wizard cast dispell/; @@ -46,9 +46,42 @@ DESCRIPTION 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. + 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. + + "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. + + "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. @@ -58,13 +91,27 @@ 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.9.3 - 'len' magic is no longer called when pushing an element into a magic - array. + *p25854* : 'len' magic is no longer called when pushing an element into + a magic array. + *p26569* : 'local' magic. 5.9.5 - 'clear' magic wasn't invoked when undefining an array. The bug is fixed - as of this version. + *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. CONSTANTS "SIG_MIN" @@ -76,34 +123,75 @@ CONSTANTS "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_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. + FUNCTIONS "wizard" - wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => .. + 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 : - 'sig' + "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. - 'data' + "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' and 'free' + "get", "set", "len", "clear", "free", "copy", "local", "fetch", "store", + "exists" and "delete" 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. + 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]. # A simple scalar tracer my $wiz = wizard get => sub { print STDERR "got ${$_[0]}\n" }, @@ -135,7 +223,8 @@ FUNCTIONS 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. + 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; @@ -169,21 +258,42 @@ EXPORT "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'. + 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'. + +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. + + 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.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). + + Some uvar tests need Hash::Util::FieldHash (standard since perl + 5.009004). + Glob tests need Symbol (standard since perl 5.002). 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 #perl @ FreeNode (Prof_Vince). + You can contact me by mail or on #perl @ FreeNode (vincent or + Prof_Vince). BUGS Please report any bugs or feature requests to "bug-variable-magic at @@ -197,8 +307,11 @@ SUPPORT perldoc Variable::Magic + Tests code coverage report is available at + . + COPYRIGHT & LICENSE - Copyright 2007 Vincent Pit, all rights reserved. + Copyright 2007-2008 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.