1Sentinel(3) User Contributed Perl Documentation Sentinel(3)
2
6 "Sentinel" - create lightweight SCALARs with get/set callbacks
7
9 package Some::Class;
10 use Sentinel;
12 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 sub bar :lvalue
21 {
22 my $self = shift;
23 sentinel value => $self->get_bar,
24 set => sub { $self->set_bar( $_[0] ) };
25 }
26 sub splot :lvalue
28 {
29 sentinel obj => shift, get => \&get_splot, set => \&set_splot;
30 }
31 sub wibble :lvalue
33 {
34 sentinel obj => shift, get => "get_wibble", set => "set_wibble";
35 }
36
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
45 $scalar = sentinel %args
46 Returns (as an lvalue) a scalar with magic attached to it. This magic
47 is used to get the value of the scalar, or to inform of a new value
48 being set, by invoking callback functions supplied to the sentinel.
49 Takes the following named arguments:
50 get => CODE
52 A "CODE" reference or "obj" method name to invoke when the
53 value of the scalar is read, to obtain its value. The value
54 returned from this code will appear as the value of the scalar.
55 set => CODE
57 A "CODE" reference or "obj" method name to invoke when a new
58 value for the scalar is written. The code will be passed the
59 new value as its only argument.
60 value => SCALAR
62 If no "get" callback is provided, this value is given as the
63 initial value of the scalar. If the scalar manages to survive
64 longer than a single assignment, its value on read will retain
65 the last value set to it.
66 obj => SCALAR
68 Optional value to pass as the first argument into the "get" and
69 "set" callbacks. If this value is provided, then the "get" and
70 "set" callbacks may be given as direct sub references to object
71 methods, or simply method names, rather than closures that
72 capture the referent object. This avoids the runtime overhead
73 of creating lots of small one-use closures around the object.
74
76 A useful behaviour of this module is generation of mutation accessor
77 methods that automatically wrap "get_"/"set_" accessor/mutator pairs:
78 foreach (qw( name address age height )) {
80 my $name = $_;
81 no strict 'refs';
83 *$name = sub :lvalue {
84 sentinel obj => shift, get => "get_$name", set => "set_$name";
85 };
86 }
87 This is especially useful for methods whose values are simple strings
89 or numbers, because they allow Perl's rich set of mutation operators to
90 be applied to the object's values.
91 $obj->name =~ s/-/_/g;
93 substr( $obj->address, 100 ) = "";
95 $obj->age++;
97 $obj->height /= 100;
99
101 If an XS compiler is available at build time, this module is
102 implemented using XS. If not, it falls back on an implementation using
103 a "tie"d scalar. A pureperl installation can also be requested at build
104 time by passing the "--pp" argument to Build.PL:
105 $ perl Build.PL --pp
107 $ ./Build
108
110 With thanks to "leont", "Zefram", and others from "irc.perl.org/#p5p"
111 for assisting with trickier bits of XS logic. Thanks to "mst" for
112 suggesting a pureperl implementation for XS-challenged systems.
113
115 Paul Evans <leonerd@leonerd.org.uk>
116perl v5.28.0 2018-07-15 Sentinel(3)