X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=494ef72d2cdcbff8a48185672fe5b70107b38dcc;hb=02e503ed53ca6660ac886020f3aaa12776cb60f5;hp=f6f4362944106f006d7fe75b6f7559bf37d56492;hpb=6c7c2526186bcb3bb40a9a337d77af313f5b2a4e;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index f6f4362..494ef72 100644 --- a/README +++ b/README @@ -2,14 +2,16 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.41 + Version 0.49 SYNOPSIS - use Variable::Magic qw/wizard cast VMG_OP_INFO_NAME/; + use Variable::Magic qw; { # A variable tracer - my $wiz = wizard set => sub { print "now set to ${$_[0]}!\n" }, - free => sub { print "destroyed!\n" }; + my $wiz = wizard( + set => sub { print "now set to ${$_[0]}!\n" }, + free => sub { print "destroyed!\n" }, + ); my $a = 1; cast $a, $wiz; @@ -17,15 +19,17 @@ SYNOPSIS } # "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 $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 + print $h{banana}, "\n"; # "0" (there is no 'banana' key in %h) $h{pear} = 1; # "key pear stored in helem" } @@ -150,29 +154,26 @@ DESCRIPTION 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 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 ] + 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 type that holds the magic information. It takes a list of keys / values as argument, whose keys @@ -233,8 +234,19 @@ FUNCTIONS straight to the perl magic API. However, only the return value of the "len" callback currently holds a meaning. - Each callback can be specified as a code or a string reference, in which - case the function denoted by the string will be used as the callback. + 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" callbacks are *never* called during global destruction, as there's no way to ensure that the wizard and the "free" callback @@ -243,9 +255,11 @@ FUNCTIONS Here's 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" } + 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, ... @@ -307,7 +321,12 @@ CONSTANTS "VMG_UVAR" When this constant is true, you can use the "fetch,store,exists,delete" - callbacks on hashes. + callbacks 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_ARRAY_PUSH_NOLEN" True for perls that don't call 'len' magic when you push an element in a @@ -325,9 +344,12 @@ CONSTANTS "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_COMPAT_HASH_DELETE_NOUVAR_VOID" + True for perls that don't call 'delete' uvar 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 @@ -359,7 +381,7 @@ COOKBOOK { package Magical::UserData; - use Variable::Magic qw/wizard cast getdata/; + use Variable::Magic qw; my $wiz = wizard data => sub { \$_[1] }; @@ -369,7 +391,7 @@ COOKBOOK unless (defined $data) { $data = \(my $slot); &cast($var, $wiz, $slot) - or die "Couldn't cast UserData magic onto the variable"; + or die "Couldn't cast UserData magic onto the variable"; } $$data; } @@ -492,9 +514,15 @@ CAVEATS this destructor won't be called because the wizard will be destroyed first. + In order to define magic on hash members, you need at least perl 5.10.0 + (see "VMG_UVAR") + DEPENDENCIES perl 5.8. + 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. + Carp (standard since perl 5), XSLoader (standard since perl 5.006). Copy tests need Tie::Array (standard since perl 5.005) and Tie::Hash @@ -533,7 +561,8 @@ SUPPORT . COPYRIGHT & LICENSE - Copyright 2007,2008,2009,2010 Vincent Pit, all rights reserved. + Copyright 2007,2008,2009,2010,2011,2012 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.