1Sentinel(3)           User Contributed Perl Documentation          Sentinel(3)
2
3
4

NAME

6       "Sentinel" - create lightweight SCALARs with get/set callbacks
7

SYNOPSIS

9          package Some::Class;
10
11          use Sentinel;
12
13          sub foo :lvalue
14          {
15             my $self = shift;
16             sentinel get => sub { return $self->get_foo },
17                      set => sub { $self->set_foo( $_[0] ) };
18          }
19
20          sub bar :lvalue
21          {
22             my $self = shift;
23             sentinel value => $self->get_bar,
24                      set   => sub { $self->set_bar( $_[0] ) };
25          }
26
27          sub splot :lvalue
28          {
29             sentinel obj => shift, get => \&get_splot, set => \&set_splot;
30          }
31
32          sub wibble :lvalue
33          {
34             sentinel obj => shift, get => "get_wibble", set => "set_wibble";
35          }
36

DESCRIPTION

38       This module provides a single lvalue function, "sentinel", which yields
39       a scalar that invoke callbacks to get or set its value. Primarily this
40       is useful to create lvalue object accessors or other functions, to
41       invoke actual code when a new value is set, rather than simply updating
42       a scalar variable.
43

FUNCTIONS

45   sentinel
46          $scalar = sentinel %args
47
48       Returns (as an lvalue) a scalar with magic attached to it. This magic
49       is used to get the value of the scalar, or to inform of a new value
50       being set, by invoking callback functions supplied to the sentinel.
51       Takes the following named arguments:
52
53       get => CODE
54               A "CODE" reference or "obj" method name to invoke when the
55               value of the scalar is read, to obtain its value. The value
56               returned from this code will appear as the value of the scalar.
57
58       set => CODE
59               A "CODE" reference or "obj" method name to invoke when a new
60               value for the scalar is written. The code will be passed the
61               new value as its only argument.
62
63       value => SCALAR
64               If no "get" callback is provided, this value is given as the
65               initial value of the scalar. If the scalar manages to survive
66               longer than a single assignment, its value on read will retain
67               the last value set to it.
68
69       obj => SCALAR
70               Optional value to pass as the first argument into the "get" and
71               "set" callbacks. If this value is provided, then the "get" and
72               "set" callbacks may be given as direct sub references to object
73               methods, or simply method names, rather than closures that
74               capture the referent object. This avoids the runtime overhead
75               of creating lots of small one-use closures around the object.
76

MUTATION ACCESSORS

78       A useful behaviour of this module is generation of mutation accessor
79       methods that automatically wrap "get_"/"set_" accessor/mutator pairs:
80
81          foreach (qw( name address age height )) {
82             my $name = $_;
83
84             no strict 'refs';
85             *$name = sub :lvalue {
86                sentinel obj => shift, get => "get_$name", set => "set_$name";
87             };
88          }
89
90       This is especially useful for methods whose values are simple strings
91       or numbers, because they allow Perl's rich set of mutation operators to
92       be applied to the object's values.
93
94          $obj->name =~ s/-/_/g;
95
96          substr( $obj->address, 100 ) = "";
97
98          $obj->age++;
99
100          $obj->height /= 100;
101

XS vs PUREPERL

103       If an XS compiler is available at build time, this module is
104       implemented using XS. If not, it falls back on an implementation using
105       a "tie"d scalar. A pureperl installation can also be requested at build
106       time by passing the "--pp" argument to Build.PL:
107
108          $ perl Build.PL --pp
109          $ ./Build
110

ACKNOWLEDGEMENTS

112       With thanks to "leont", "Zefram", and others from "irc.perl.org/#p5p"
113       for assisting with trickier bits of XS logic. Thanks to "mst" for
114       suggesting a pureperl implementation for XS-challenged systems.
115

AUTHOR

117       Paul Evans <leonerd@leonerd.org.uk>
118
119
120
121perl v5.36.0                      2022-07-22                       Sentinel(3)
Impressum