NAME
    "Sentinel" - create lightweight SCALARs with get/set callbacks

SYNOPSIS
     package Some::Class;

     use Sentinel;

     sub attribute_name :lvalue
     {
        my $self = shift;
        ${ \sentinel get => sub { return $self->get_attribute_name },
                     set => sub { $self->set_attribute_name( $_[0] ) } };
     }

     sub another_attribute :lvalue
     {
        my $self = shift;
        ${ \sentinel value => $self->get_another_attribute,
                     set   => sub { $self->set_attribute_name( $_[0] ) } };
     }

     sub yet_another_attribute :lvalue
     {
        my $self = shift;
        ${ \sentinel obj => $self,
                     get => \&get_attr,
                     set => \&set_attr };
     }

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.

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.

    The slightly awkward reference/dereference syntax of "${ \sentinel ...
    }" works around an as-yet-unresolved issue that, without it, an error is
    raised at runtime. See the "TODO" section below.

TODO
    *   See if the awkward reference/dereference construct can be removed,
        yielding a neater syntax of

         sub foo :lvalue { sentinel get => ..., set => ...; }

        Currently this fails with the error

         Can't return a temporary from lvalue subroutine at ...

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>

