UNIVER...equire(3pm)

💖 UNIVERSAL::require — the 3pm manual, bestie edition 💖

okay so. you found the UNIVERSAL::require page. it's a Perl module, it's from the User Contributed Perl Documentation corner of the world, and it is deprecated — so like, read this for the lore, but maybe don't make it your whole personality. 🫶

---

✨ NAME ✨

UNIVERSAL::require — require() modules from a variable, and yes the [deprecated] tag is right there in the name, no cap. 💀

---

🌸 SYNOPSIS 🌸

# This only needs to be said once in your program.
require UNIVERSAL::require;

# Same as "require Some::Module"
my $module = 'Some::Module';
$module->require or die $@;

# Same as "use Some::Module"
BEGIN { $module->use or die $@ }

---

🦋 DESCRIPTION 🦋

okay before you even breathe in this module's direction: you should go look at the alternatives first. some of them are listed in SEE ALSO down below. this is the part where I'm holding your hand, fr fr. 🫶

So. What does this thing do? It gives you a safe mechanism for loading a module at runtime, for when the module's name is living in a variable and not just sitting there as a bareword. iconic behavior honestly.

If you've ever had to do this...

eval "require $module";

...just to get around the bareword caveats on require(), then bestie, this module was literally made for you. 💅 It creates a universal require() class method that works with every Perl module, and it's secure. So instead of doing that arcane eval() nonsense, you get to do this:

$module->require;

Does it save you a ton of typing? ngl, not really. But it'll make so much more sense to someone who isn't a ninth level Perl acolyte. main character clarity. ✨

🎀 Methods 🎀

⭐ require

my $return_val = $module->require           or die $@;
my $return_val = $module->require($version) or die $@;

This works exactly like Perl's require, except with no bareword restriction, and — this is the good part — it doesn't die. 😌 Since require() lives in the UNIVERSAL namespace, it'll work on any module. You just have to use UNIVERSAL::require somewhere in your code.

If the module's require fails, or it isn't a high enough $version, it will simply return false and not die. The error lands in $@ and also in $UNIVERSAL::require::ERROR. two places, double the receipts.

$module->require or die $@;

⭐ use

my $require_return = $module->use           or die $@;
my $require_return = $module->use(@imports) or die $@;

Like UNIVERSAL::require, this lets you use a $module without having to eval your way around the bareword requirement. It returns the same thing as require. consistent queen. 👑

Should either the require or the import fail, it returns false. The error will be in $@.

If you can, call this inside a BEGIN block so it emulates a normal use as closely as possible. do it for the bit. do it for the fidelity. 🧚

BEGIN { $module->use }

---

🔒 SECURITY NOTES 🔒

okay this is the serious section, put your phone down for a sec. 🙈

UNIVERSAL::require makes use of eval STRING. In previous versions of UNIVERSAL::require it was discovered that one could craft a class name which would result in code being executed. 😭 That hole has been closed. The only variables now exposed to eval STRING are the caller's package, filename and line — which are not tainted.

UNIVERSAL::require is taint clean. slay. 💚

---

©️ COPYRIGHT ©️

Copyright 2001, 2005 by Michael G Schwern <schwern@pobox.com>.

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

See http://www.perl.com/perl/misc/Artistic.html

---

👑 AUTHOR 👑

Michael G Schwern <schwern@pobox.com>

Now maintained by Neil Bowers (NEILB).

---

🌈 SEE ALSO 🌈

• Module::Load provides functions for loading code, and importing functions. It's actively maintained.
• Module::Runtime provides a number of usesful functions for require'ing and use'ing modules, and associated operations.
• Mojo::Loader is a class loader and plugin framework. Module::Loader is a stand-alone module that was inspired by Mojo::Loader.
• There are many other modules that may be of interest on CPAN. An old review of some of them can be read at <https://neilb.org/reviews/module-loading.html>.
• require in perlfunc.

---

and that's the whole page, bestie 🎀 this one came from perl v5.36.0, dated 2022-11-19, and it was filed under UNIVER...equire(3pm) in case you need to find it again. mwah 💋✨