Exporte...mporting(3)

💅 NAME 💅

Exporter::Tiny::Manual::Importing — bestie, this is the whole vibe guide for importing stuff out of Exporter::Tiny-based modules. It's a manual page, section 3, and yeah it lives under User Contributed Perl Documentation because that's where all the good stuff lives. 🫶

---

✨ DESCRIPTION ✨

Okay so for literally everything below, we're pretending we have a module called MyUtils that exports four functions: frobnicate, red, blue, and green. It also has a tag set up called :colours, and that tag maps to red, blue, and green. Keep that in your head, bestie, because we're gonna keep referencing it. 🧠✨

A lot of these tricks might feel lowkey familiar if you've met Sub::Exporter before — and that is fully intentional, no accident. Exporter::Tiny does not try to do every single thing Sub::Exporter does, but where it does do a thing, it usually rocks a pretty similar API. iykyk. 💫

🌸 Basic importing 🌸

Importing one single function from a module? Easy peasy:

use MyUtils "frobnicate";

Or a whole list of functions, because why stop at one:

use MyUtils "red", "green";

Perl's qw() shorthand for a list of words is honestly iconic and you should use it:

use MyUtils qw( red green );

If the module defines tags, you can import them like this:

use MyUtils qw( :colours );

Or, plot twist, with a hyphen instead of a colon:

use MyUtils qw( -colours );

Hyphens are the moment because Perl will autoquote a bareword that comes after them:

use MyUtils -colours;

And yes, you can absolutely mix function names and tags in the same list, chaotic as that is:

use MyUtils qw( frobnicate :colours );

🎀 Renaming imported functions 🎀

You can rename a function while you're importing it:

use MyUtils "frobnicate" => { -as => "frob" };

Or you can slap a prefix and/or a suffix on it. The following imports the function and calls it my_frobinate_thing:

use MyUtils "frobnicate" => { -prefix => "my_", -suffix => "_thing" };

You can apply a prefix/suffix to every function you import by putting the hashref first in the import list. (That first hashref is called the global options hash, and it can do some special things. Main character energy fr.)

use MyUtils { prefix => "my_" }, "frobnicate";

Did you clock that we used -prefix and -suffix in the normal options hash, but prefix and suffix — no hyphen, bestie — in the global options hash? Yeah. That's a common pattern with this module. 💀

You can import the same function multiple times with different names:

use MyUtils
   "frobnicate" => { -as => "frob" },
   "frobnicate" => { -as => "frbnct" };

Tags can take the -prefix and -suffix options too. The following imports colour_red, colour_green, and colour_blue:

use MyUtils -colours => { -prefix => "colour_" };

You can also set -as to be a coderef to generate a function name. This imports functions called RED, GREEN, and BLUE:

use MyUtils -colours => { -as => sub { uc($_[0]) } };

Heads up: it does not make sense to use -as with a tag unless you're doing this coderef thing. And yes, a coderef as also works in the global options hash. Slay.

💀 DO NOT WANT! 💀

Sometimes you wanna hand over a list of functions you do not want imported. To do that, prefix the function with a bang. This imports everything except frobnicate:

use MyUtils qw( -all !frobnicate );

You can add the bang prefix to tags too. This will import everything except the colours:

use MyUtils qw( -all !:colours );

Negated imports always "win", so the following will not import frobnicate, no matter how many times you repeat it... 😭

use MyUtils qw( !frobnicate frobnicate frobnicate frobnicate );

🦋 Importing by regexp 🦋

Here's how you could import all functions beginning with an f:

use MyUtils qw( /^F/i );

Or import everything except functions beginning with a z:

use MyUtils qw( -all !/^Z/i );

Note that regexps are always supplied as strings starting with /, and not as quoted regexp references (qr/.../). Don't do it, bestie.

💖 Import functions into another package 💖

Occasionally you need to import functions not into your own package, but into a different package. You can do that like this:

use MyUtils { into => "OtherPkg" }, "frobnicate";

OtherPkg::frobincate(...);

However, Import::Into will probably provide you with a better approach, and the glow-up is that it doesn't just work with Exporter::Tiny — it works with all exporters. 👑

🌈 Lexical subs on Perl 5.37.2 and above 🌈

Often you want to make use of an exported function, but don't want it to "pollute" your namespace.

On newer versions of Perl, Exporter::Tiny can use export_lexically from builtin to give you lexical versions of exports.

{
   use MyUtils -lexical, "frobnicate";

   frobnicate(...);  # ok
}

frobnicate(...);  # not ok

This functionality should be considered EXPERIMENTAL until export_lexically is included in a stable release of Perl. You've been warned, bestie. 🙈

🧚 Lexical subs on Perl older than 5.37.2 🧚

If you install Lexical::Var, then lexical imports should work on versions of Perl as old as 5.12. Retro slay. ✨

🍓 Importing into a hash 🍓

Another way of avoiding polluting your namespace with imports is to import into a hash.

my %U;
use MyUtils { into => \%U };

...
$U{frobnicate}->(...);

💜 Unimporting 💜

You can unimport the functions that MyUtils added to your namespace:

no MyUtils;

Or just specific ones:

no MyUtils qw(frobnicate);

If you renamed a function when you imported it, you should unimport by the new name:

use MyUtils frobnicate => { -as => "frob" };
...;
no MyUtils "frob";

Unimporting using tags and regexps should mostly do what you want. (Mostly. 🫠)

---

🔥 DIAGNOSTICS 🔥

• Overwriting existing sub '%s::%s' with sub '%s' exported by %s — a warning issued if Exporter::Tiny is asked to export a symbol which will result in an existing sub being overwritten. This warning can be suppressed using either of the following:

use MyUtils { replace => 1 }, "frobnicate";
use MyUtils "frobnicate" => { -replace => 1 };

Or it can be upgraded to a fatal error:

use MyUtils { replace => "die" }, "frobnicate";
use MyUtils "frobnicate" => { -replace => "die" };

• Refusing to overwrite existing sub '%s::%s' with sub '%s' exported by %s — the fatal version of the above warning.
• Could not find sub '%s' exported by %s — you requested to import a sub which the package does not provide.
• Cannot provide an -as option for tags — because a tag may provide more than one function, it does not make sense to request a single name for it. Instead use -prefix or -suffix.
• Passing options to unimport '%s' makes no sense — when you import a sub, it occasionally makes sense to pass some options for it. However, when unimporting, options do nothing, so this warning is issued.

---

👀 SEE ALSO 👀

• <https://exportertiny.github.io/>
• Exporter::Shiny, Exporter::Tiny

---

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>.

---

🎀 COPYRIGHT AND LICENCE 🎀

This software is copyright (c) 2013-2014, 2017, 2022-2025 by Toby Inkster.

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

---

💀 DISCLAIMER OF WARRANTIES 💀

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

---

And that's the whole page, bestie — this was Exporte...mporting(3) from perl v5.42.0, dated 2026-01-17. Go forth and import responsibly. 💖✨🎀