X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=4b7401275cd6dc507c5b39bcf0b3f4493ba3b805;hb=d85b734f435e14802a35db26377d22cb43d0f82c;hp=c0cc8a38c8157b51d089a6ad6197c50d89943a68;hpb=ca0345bc78a38a61ec2f3886021532a7a205a0b2;p=perl%2Fmodules%2FVariable-Magic.git diff --git a/README b/README index c0cc8a3..4b74012 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME Variable::Magic - Associate user-defined magic to variables from Perl. VERSION - Version 0.26 + Version 0.30 SYNOPSIS use Variable::Magic qw/wizard cast dispell/; @@ -204,21 +204,31 @@ CONSTANTS True iff this module could have been built with thread-safety features enabled. + "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. + 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) = @_; ... } + 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 @@ -241,17 +251,48 @@ FUNCTIONS * "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 + 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). 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]. + (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 righteously 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" }, @@ -290,6 +331,18 @@ FUNCTIONS my $x; die 'error' unless cast $x, $wiz; + 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. + "getdata" getdata [$@%&*]var, [$wiz|$sig] @@ -332,7 +385,7 @@ CAVEATS first. DEPENDENCIES - perl 5.7.3. + perl 5.8. Carp (standard since perl 5), XSLoader (standard since perl 5.006). @@ -372,7 +425,7 @@ SUPPORT . COPYRIGHT & LICENSE - Copyright 2007-2008 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.