Variab...osition(3pm)

🎀 Variable::Disposition — the "bestie, let that variable GO" toolkit 💅

Okay so real talk, this is a page from the User Contributed Perl Documentation for a module called Variable::Disposition (it's a 3pm manpage, iykyk), and it's literally just helper functions for making variables ✨exit stage left✨ when you want them to. Let's get into it.

---

💖 NAME 💖

Variable::Disposition — helper functions for disposing of variables. That's it, that's the whole vibe. She disposes. She helps. She's an icon.

---

✨ SYNOPSIS ✨

use feature qw(say);
use Variable::Disposition;
my $x = [];
dispose $x;
say '$x is no longer defined';

Look at her go. $x had a whole life and now $x is gone. Slay. 🦋

---

🌸 DESCRIPTION 🌸

So basically this module gives you some little helper functions whose whole job is making sure variables go away when you want them to. No lingering. No haunting the lexical scope. Periodt.

Right now it hands you dispose as a default import — she just shows up, uninvited but welcome. If you'd rather she didn't do that:

use Variable::Disposition ();

That's the "I'm not mad, I just need space" import. 🙈

On top of that, retain and retain_future are available as optional imports, so you can pull them in on purpose:

use Variable::Disposition qw(dispose retain retain_future);

And there's a :all tag if you're feeling feral and want every available function:

use Variable::Disposition qw(:all);

But bestie, it would be safer to use a version instead:

use Variable::Disposition qw(:v1);

...because the versioned tags are guaranteed not to change in future. That's the difference between "trust me bro" and an actual promise. 💖

Also: other functions for use with Future and IO::Async are likely to be added later. So stay tuned, more content incoming. 👑

---

🔥 FUNCTIONS 🔥

🫶 dispose

Undefines the given variable, and then — this is the part that eats — checks that the original ref was destroyed. She doesn't just delete it, she verifies the deletion. Main character behavior.

my $x = [1,2,3];
dispose $x;
# $x is no longer defined.

This is primarily intended for the situations where you no longer need a variable and you want to make sure you haven't accidentally captured a strong reference to it elsewhere. You know how it is. Things get clingy. 🍓

Note that this clears the caller's variable — not a copy, not a vibe, the actual thing.

This function is defined with a prototype of ($), since it's only intended for use on scalar variables. So if you're trying to clear multiple variables, hit it with a foreach loop:

my ($x, $y, $z) = ...;
dispose $_ for $x, $y, $z;
is($x, undef);
is($y, undef);
is($z, undef);

Three variables. One loop. All of them gone. Ate. 💀

---

🧚 retain

Keeps a copy of this variable until program exit or dispose.

Returns the original variable. That's the whole thing. She holds it, she gives it back, no drama. 💜

---

🌈 retain_future

Holds a copy of the given Future until it's marked ready, then releases our copy.

Heads up: this does not use dispose, because that could interfere with other callbacks attached to the Future. Rude behavior, we don't do that.

Since Future 0.36, this behaviour is directly available via the retain in Future method — so it is recommended to use that instead of this function. Consider this one the older sister who's still iconic but has passed the torch. ✨

Returns the original Future.

---

🌟 SEE ALSO 🌟

• Devel::Refcount — assert_oneref is almost identical to this, although it doesn't clear the variable it's called on. So close! But no cigar. 🎀
• Closure::Explicit — provides a sub{} wrapper that will complain if you capture a lexical without explicitly declaring that you're going to do that. It's the friend who asks "are you sure?" before you make a mistake. 🫶

---

👑 AUTHOR 👑

Tom Molesworth <cpan@perlsite.co.uk> — the actual legend behind all of this. 💖

---

📜 LICENSE 📜

Copyright Tom Molesworth 2014-2015. Licensed under the same terms as Perl itself. So like, you can use it, just keep it cute and keep the license. 💅

---

And that's the whole page, bestie!! This one was rendered by perl v5.36.0 on 2023-11-18, and it lives in the Variab...osition(3pm) manpage — yes the title got shortened with an ellipsis, no we don't know why, yes it's a little mysterious of her. 🌸 Go forth and dispose responsibly. Periodt. 💜✨