README

   1 NAME
   2     Variable::Magic - Associate user-defined magic to variables from Perl.
   3
   4 VERSION
   5     Version 0.01
   6
   7 SYNOPSIS
   8         use Variable::Magic qw/wizard cast dispell/;
   9
  10         my $wiz = wizard set => sub { print STDERR "now set to $_[0]!\n" };
  11         my $a = 1;
  12         cast $a, $wiz;
  13         $a = 2;          # "now set to 2!"
  14         dispell $a, $wiz;
  15         $a = 3           # (nothing)
  16
  17 DESCRIPTION
  18     Magic is Perl way of enhancing objects. This mechanism let the user add
  19     extra data to any variable and overload syntaxical operations (such as
  20     access, assignation or destruction) that can be applied to it. With this
  21     module, you can add your own magic to any variable without the pain of
  22     the C API.
  23
  24     The operations that can be overloaded are :
  25
  26     "get"
  27         This magic is invoked when the variable is evaluated (does not
  28         include array/hash subscripts and slices).
  29
  30     "set"
  31         This one is triggered each time the value of the variable changes
  32         (includes array/hash subscripts and slices).
  33
  34     "len"
  35         This magic is a little special : it is called when the 'size' or the
  36         'length' of the variable has to be known by Perl. Typically, it's
  37         the magic involved when an array is evaluated in scalar context, but
  38         also on array assignation and loops ("for", "map" or "grep"). The
  39         callback has then to return the length as an integer.
  40
  41     "clear"
  42         This magic is invoked when the variable is reset, such as when an
  43         array is emptied. Please note that this is different from undefining
  44         the variable, even though the magic is called when the reset is a
  45         result of the undefine (e.g. for an array).
  46
  47     "free"
  48         This last one can be considered as an object destructor. It happens
  49         when the variable goes out of scope (with the exception of global
  50         scope), but not when it is undefined.
  51
  52     To prevent any clash between different magics defined with this module,
  53     an unique numerical signature is attached to each kind of magic (i.e.
  54     each set of callbacks for magic operations).
  55
  56 CONSTANTS
  57   "SIG_MIN"
  58     The minimum integer used as a signature for user-defined magic.
  59
  60   "SIG_MAX"
  61     The maximum integer used as a signature for user-defined magic.
  62
  63   "SIG_NBR"
  64         SIG_NBR = SIG_MAX - SIG_MIN + 1
  65
  66 FUNCTIONS
  67   "wizard"
  68         wizard sig => .., data => ..., get => .., set => .., len => .., clear => .., free => ..
  69
  70     This function creates a 'wizard', an opaque type that holds the magic
  71     information. It takes a list of keys / values as argument, whose keys
  72     can be :
  73
  74     'sig'
  75         The numerical signature. If not specified or undefined, a random
  76         signature is generated.
  77
  78     'data'
  79         A code reference to a private data constructor. It will be called
  80         each time this magic is cast on a variable, and the scalar returned
  81         will be used as private data storage for it.
  82
  83     'get', 'set', 'len', 'clear' and 'free'
  84         Code references to corresponding magic callbacks. You don't have to
  85         specify all of them : the magic associated with undefined entries
  86         simply won't be hooked. When the magic variable is an array or a
  87         hash, $_[0] is a reference to it, but directly references it
  88         otherwise. $_[1] is the private data (or "undef" when no private
  89         data constructor was supplied). In the special case of "len" magic
  90         and when the variable is an array, $_[2] contains its normal length.
  91
  92         # A simple scalar tracer
  93         my $wiz = wizard get  => sub { print STDERR "got $_[0]\n" },
  94                          set  => sub { print STDERR "set to $_[0]\n" },
  95                          free => sub { print STDERR "$_[0] was deleted\n" }
  96
  97   "gensig"
  98     With this tool, you can manually generate random magic signature between
  99     SIG_MIN and SIG_MAX inclusive. That's the way "wizard" creates them when
 100     no signature is supplied.
 101
 102         # Generate a signature
 103         my $sig = gensig;
 104
 105   "getsig"
 106         getsig $wiz
 107
 108     This accessor returns the magic signature of this wizard.
 109
 110         # Get $wiz signature
 111         my $sig = getsig $wiz;
 112
 113   "cast"
 114         cast [$@%&*]var, $wiz
 115
 116     This function associates $wiz magic to the variable supplied, without
 117     overwriting any other kind of magic. It returns true on success or when
 118     $wiz magic is already present, and false on error.
 119
 120         # Casts $wiz to $x
 121         my $x;
 122         die 'error' unless cast $x, $wiz;
 123
 124   "getdata"
 125         getdata [$@%&*]var, $wiz
 126
 127     This accessor fetches the private data associated with the magic $wiz in
 128     the variable. "undef" is returned when no such magic or data is found.
 129
 130   "dispell"
 131         dispell [$@%&*]variable, $wiz
 132         dispell [$@%&*]variable, $sig
 133
 134     The exact opposite of "cast" : it dissociates $wiz magic from the
 135     variable. You can also pass the magic signature as the second argument.
 136     True is returned on success, and false on error or when no magic
 137     represented by $wiz could be found in the variable.
 138
 139         # Dispell now
 140         die 'no such magic or error' unless dispell $x, $wiz;
 141
 142 EXPORT
 143     The functions "wizard", "gensig", "getsig", "cast", "getdata" and
 144     "dispell" are only exported on request. All of them are exported by the
 145     tags ':funcs' and ':all'.
 146
 147     The constants "SIG_MIN", "SIG_MAX" and "SIG_NBR" are also only exported
 148     on request. They are all exported by the tags ':consts' and ':all'.
 149
 150 DEPENDENCIES
 151     Carp (standard since perl 5), XSLoader (standard since perl 5.006).
 152
 153     Tests use Symbol (standard since perl 5.002).
 154
 155 SEE ALSO
 156     perlguts and perlapi for internal information about magic.
 157
 158 AUTHOR
 159     Vincent Pit, "<perl at profvince.com>"
 160
 161 BUGS
 162     Please report any bugs or feature requests to "bug-variable-magic at
 163     rt.cpan.org", or through the web interface at
 164     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Variable-Magic>. I will
 165     be notified, and then you'll automatically be notified of progress on
 166     your bug as I make changes.
 167
 168 SUPPORT
 169     You can find documentation for this module with the perldoc command.
 170
 171         perldoc Variable::Magic
 172
 173 COPYRIGHT & LICENSE
 174     Copyright 2007 Vincent Pit, all rights reserved.
 175
 176     This program is free software; you can redistribute it and/or modify it
 177     under the same terms as Perl itself.
 178