X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=a626da01eb6c5a454204c4eb90abea31e75b80ca;hb=183e73e0590b46550dfa6fdd4b6cf3280c1a5877;hp=541b09da0daa68af9a14683aa6da0137ba1b4c0f;hpb=77a84f75f33e3ee44e61182dec76699e23025375;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index 541b09d..a626da0 100644 --- a/README +++ b/README @@ -2,12 +2,12 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.01 + Version 0.07_01 SYNOPSIS use Variable::Magic qw/wizard cast dispell/; - my $wiz = wizard set => sub { print STDERR "now set to $_[0]!\n" }; + my $wiz = wizard set => sub { print STDERR "now set to ${$_[0]}!\n" }; my $a = 1; cast $a, $wiz; $a = 2; # "now set to 2!" @@ -41,8 +41,9 @@ DESCRIPTION "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 @@ -53,6 +54,18 @@ DESCRIPTION an unique numerical signature is attached to each kind of magic (i.e. each set of callbacks for magic operations). +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.9.3 + 'len' magic is no longer called when pushing an element into a magic + array. + + 5.9.5 + 'clear' magic wasn't invoked when undefining an array. The bug is fixed + as of this version. + CONSTANTS "SIG_MIN" The minimum integer used as a signature for user-defined magic. @@ -63,6 +76,15 @@ CONSTANTS "SIG_NBR" SIG_NBR = SIG_MAX - SIG_MIN + 1 + "MGf_COPY" + True iff the 'copy' magic is available. + + "MGf_DUP" + True iff the 'dup' magic is available. + + "MGf_LOCAL" + True iff the 'local' magic is available. + FUNCTIONS "wizard" wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => .. @@ -73,26 +95,29 @@ FUNCTIONS 'sig' The numerical signature. If not specified or undefined, a random - signature is generated. + 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 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. + 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' 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. + 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. # 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" } "gensig" With this tool, you can manually generate random magic signature between @@ -111,32 +136,41 @@ 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, 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. + + # Casts $wiz onto $x. If $wiz isn't a signature, undef can't be returned. my $x; die 'error' unless cast $x, $wiz; "getdata" - getdata [$@%&*]var, $wiz + getdata [$@%&*]var, [$wiz|$sig] + + 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. - 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. + # Get the attached data. + my $data = getdata $x, $wiz or die 'no such magic or magic has no data'; "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. 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). - # Dispell now + # Dispell now. If $wiz isn't a signature, undef can't be returned. die 'no such magic or error' unless dispell $x, $wiz; EXPORT @@ -148,9 +182,11 @@ EXPORT on request. They are all exported by the tags ':consts' and ':all'. DEPENDENCIES + perl 5.7.3. + Carp (standard since perl 5), XSLoader (standard since perl 5.006). - Tests use Symbol (standard since perl 5.002). + Glob tests need Symbol (standard since perl 5.002). SEE ALSO perlguts and perlapi for internal information about magic. @@ -158,6 +194,8 @@ SEE ALSO AUTHOR Vincent Pit, "" + You can contact me by mail or on #perl @ FreeNode (Prof_Vince). + BUGS Please report any bugs or feature requests to "bug-variable-magic at rt.cpan.org", or through the web interface at