1Sentinel(3pm) User Contributed Perl Documentation Sentinel(3pm)
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 sentinel
46 $scalar = sentinel %args
47 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 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 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 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 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
78 A useful behaviour of this module is generation of mutation accessor
79 methods that automatically wrap "get_"/"set_" accessor/mutator pairs:
80 foreach (qw( name address age height )) {
82 my $name = $_;
83 no strict 'refs';
85 *$name = sub :lvalue {
86 sentinel obj => shift, get => "get_$name", set => "set_$name";
87 };
88 }
89 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 $obj->name =~ s/-/_/g;
95 substr( $obj->address, 100 ) = "";
97 $obj->age++;
99 $obj->height /= 100;
101
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 $ perl Build.PL --pp
109 $ ./Build
110
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
117 Paul Evans <leonerd@leonerd.org.uk>
118perl v5.38.0 2023-07-24 Sentinel(3pm)