Sub::Ex...Lexical(3)

💖 Sub::Ex...Lexical(3): the bestie edit 💖

okay so this is the Sub::Ex...Lexical(3) page for Sub::Exporter::Lexical, version 1.000 — it’s giving “lexical subs that clean themselves up,” and I’m obsessed. Let’s go. 💅

🌸 NAME 🌸

Sub::Exporter::Lexical — to export lexically-available subs with Sub::Exporter. That’s the whole NAME vibe, no cap. ✨

🦋 VERSION 🦋

version 1.000 — short, sweet, iconic. 🎀

✨ SYNOPSIS ✨

In an exporting library:

package Some::Toolkit;

use Sub::Exporter -setup => {
  exports   => [ qw(foo bar baz) ],
};

sub foo { ... }
sub bar { ... }
sub baz { ... }

In an importing library:

package Vehicle::Autobot;

use Sub::Exporter::Lexical lexical_installer => { -as => 'lex' };

...;

{
  use Some:::Toolkit { installer => lex }, qw(foo bar);

  foo(1,2,3);
  my $x = bar;

  ...
};

# ... and here, foo and bar are no longer available ...

💅 DESCRIPTION 💅

Sub::Exporter::Lexical provides an alternate installer for Sub::Exporter. Installers are documented in Sub::Exporter’s documentation; all you need to know is that by using Sub::Exporter::Lexical’s installer, you can import routines into a lexical scope that will be cleaned up when that scope ends. Literally so clean. 🧚

There are two places it makes sense to use the lexical installer: when configuring Sub::Exporter in your exporting package or when importing from a package that uses Sub::Exporter. For the first case, do something like this:

package Some::Toolkit;
use Sub::Exporter::Lexical ();
use Sub::Exporter -setup => {
  exports   => [ ... ],
  installer => Sub::Exporter::Lexical::lexical_installer,
};

For the second:

package My::Library;

use Sub::Exporter::Lexical ();
use Some::Toolkit
  { installer => Sub::Exporter::Lexical::lexical_installer },
  qw(foo bar baz);

🐚 PERL VERSION 🐚

This module is shipped with no promise about what version of perl it will require in the future. In practice, this tends to mean “you need a perl from the last three years,” but you can’t rely on that. If a new version of perl ship, this software may begin to require it for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. Read that twice, bestie. 😭

🎁 EXPORTS 🎁

Sub::Exporter::Lexical offers only one routine for export, and it may also be called by its full package name:

🔥 lexical_installer 🔥

This routine returns an installer suitable for use as the "installer" argument to Sub::Exporter. It installs all requested routines as usual, but marks them to be removed from the target package as soon as the block in which it was called is complete. Block ends, subs dip. 👑

It does not affect the behavior of routines exported into scalar references.

More importantly, it does not affect scopes in which it is invoked at runtime, rather than compile time.

⚠️ This is important! It means that this works:

{
  use Some::Toolkit { installer => lexical_installer }, qw(foo);
  foo(1,2,3);
}

foo(); # this dies

...but this does not...

{
  require Some::Toolkit;
  Some::Toolkit->import({ installer => lexical_installer }, qw(foo));
  foo(1,2,3);
}

foo(); # this does not die, even though you might expect it to

Finally, you can’t supply a -as => \$var install destination yet. Not yet, bestie. 🫶

👑 AUTHOR 👑

Ricardo Signes <cpan@semiotic.systems> — iconic. 💜

🌈 CONTRIBUTORS 🌈

• Hans Dieter Pearcey — hdp@weftsoar.net
• Ricardo Signes — rjbs@semiotic.systems

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2023 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, legally speaking 🌈💅

---

xoxo, your Perl bestie 💖 — this page came from perl v5.40.0, dated 2024-09-02, and its manpage name is Sub::Ex...Lexical(3). 🦋