Sentinel(3pm)

💖 Sentinel — the manual, but make it cute 💖

okay so bestie, this is Sentinel, and it lives in the User Contributed Perl Documentation section of the manual (you know, the 3pm girlies). sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

"Sentinel" — create lightweight SCALARs with get/set callbacks. no cap, that's the whole vibe. 🎀

---

✨ SYNOPSIS ✨

okay here's the tea, look at how pretty this is:

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;
}

sub wibble :lvalue
{
   sentinel obj => shift, get => "get_wibble", set => "set_wibble";
}

look at that. :lvalue everywhere. it's giving main character energy 💅

---

✨ DESCRIPTION ✨

so this module hands you exactly one lvalue function, "sentinel", and it yields a scalar that invokes callbacks whenever you get or set its value. 🦋

and like… why would you even want that? bestie. it's for making lvalue object accessors (and other functions) that actually run code when a new value gets set, instead of just quietly updating some boring scalar variable. the way that it just works. iconic. ⭐

---

✨ FUNCTIONS ✨

💜 sentinel

$scalar = sentinel %args

returns (as an lvalue, obviously) a scalar with ✨magic✨ attached to it. this magic is what gets the value of the scalar, or tells you a new value is being set, by invoking the callback functions you supplied to the sentinel. 🌈

it takes these named arguments, and yes we're going through all of them:

• get => CODE — a "CODE" reference, or an "obj" method name, to invoke when the value of the scalar is read, so it can obtain its value. whatever that code returns is what shows up as the value of the scalar. 💖
• set => CODE — a "CODE" reference, or an "obj" method name, to invoke when a new value for the scalar is written. the code gets passed the new value as its only argument. one arg, that's it, don't be weird about it. 🫶
• value => SCALAR — if you didn't give a "get" callback, this value becomes the initial value of the scalar. and if the scalar manages to survive longer than a single assignment, then when you read it, its value will retain the last value set to it. periodt. 💅
• obj => SCALAR — an optional value to pass as the first argument into the "get" and "set" callbacks. if you provide this, then "get" and "set" can be given as direct sub references to object methods, or just plain method names, instead of closures that capture the referent object. this dodges the runtime overhead of creating a ton of tiny one-use closures around the object. efficiency queen 👑

---

✨ MUTATION ACCESSORS ✨

okay this part is lowkey the best part. a really useful behaviour of this module is that it generates mutation accessor methods that automatically wrap your "get_"/"set_" accessor/mutator pairs:

foreach (qw( name address age height )) {
   my $name = $_;

   no strict 'refs';
   *$name = sub :lvalue {
      sentinel obj => shift, get => "get_$name", set => "set_$name";
   };
}

this is especially useful for methods whose values are simple strings or numbers, because it lets Perl's rich set of mutation operators be applied directly to the object's values. 🔥 watch:

$obj->name =~ s/-/_/g;

substr( $obj->address, 100 ) = "";

$obj->age++;

$obj->height /= 100;

not me actually screaming. the mutation operators just go there. 🧚

---

✨ XS vs PUREPERL ✨

here's the technical bit, bestie, pay attention:

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. 🍓

you can also request a pureperl installation at build time by passing the --pp argument to Build.PL:

$ perl Build.PL --pp
$ ./Build

choose your fighter. both slay. 💜

---

✨ ACKNOWLEDGEMENTS ✨

with thanks to "leont", "Zefram", and others from "irc.perl.org/#p5p" for assisting with trickier bits of XS logic. 🙈

and thanks to "mst" for suggesting a pureperl implementation for XS-challenged systems. we love an inclusive king. 👑

---

✨ AUTHOR ✨

Paul Evans <leonerd@leonerd.org.uk> — absolute legend, no notes. 💖

---

and that's the whole page, bestie!! this was written for perl v5.42.0, dated 2025-07-25, and yeah it's still Sentinel(3pm) if you need to look it up again. now go make some lvalue accessors, you've got this. mwah. 💋✨