NAME `Sentinel' - create lightweight SCALARs with get/set callbacks SYNOPSIS package Some::Class; use Sentinel; sub foo :lvalue { my $self = shift; sentinel get => sub { return $self->get_foo }, set => sub { $self->set_foo( $_[0] ) }; } sub bar :lvalue { my $self = shift; sentinel value => $self->get_bar, set => sub { $self->set_bar( $_[0] ) }; } sub splot :lvalue { sentinel obj => shift, get => \&get_splot, set => \&set_splot; } DESCRIPTION This module provides a single lvalue function, `sentinel', which yields a scalar that invoke callbacks to get or set its value. Primarily this is useful to create lvalue object accessors or other functions, to invoke actual code when a new value is set, rather than simply updating a scalar variable. If an XS compiler is available at build time, this module is implemented using XS. If not, it falls back on an implementation using a `tie'd scalar. FUNCTIONS $scalar = sentinel %args Returns (as an lvalue) a scalar with magic attached to it. This magic is used to get the value of the scalar, or to inform of a new value being set, by invoking callback functions supplied to the sentinel. Takes the following named arguments: get => CODE A `CODE' reference to invoke when the value of the scalar is read, to obtain its value. The value returned from this code will appear as the value of the scalar. set => CODE A `CODE' reference to invoke when a new value for the scalar is written. The code will be passed the new value as its only argument. value => SCALAR If no `get' callback is provided, this value is given as the initial value of the scalar. If the scalar manages to survive longer than a single assignment, its value on read will retain the last value set to it. obj => SCALAR Optional value to pass as the first argument into the `get' and `set' callbacks. If this value is provided, then the `get' and `set' callbacks may be given as direct sub references to object methods, rather than closures that capture the referent object. This avoids the runtime overhead of creating lots of small one-use closures around the object. ACKNOWLEDGEMENTS With thanks to `leont', `Zefram', and others from `irc.perl.org/#p5p' for assisting with trickier bits of XS logic. Thanks to `mst' for suggesting a pureperl implementation for XS-challenged systems. AUTHOR Paul Evans