above(3pm)

💖 above — the manual page bestie 💖

okay so we're looking at above from the Perl user-contributed docs, third section, the 3pm girlies. it's a tiny little thing and it's lowkey iconic. let's get into it 🫶

---

✨ NAME ✨

above — auto use lib when a module is in the tree of the PWD. like, it finds your module by walking up from where you're standing. main character behaviour fr 💅

---

🌸 SYNOPSIS 🌸

use above "My::Module";

that's it. that's the whole vibe. one line and you're slaying ✨

---

🦋 DESCRIPTION 🦋

so above is used by the command-line wrappers for Command modules which are developer tools. that's its whole job, it's a supporting character, and it eats every time.

Do NOT use this in modules, or user applications. 🚨 bestie I am SO serious. this is not for your app, this is not for your library, this is for the dev-tool wrappers. periodt.

what it actually does: it uses a module as though the cwd and each of its parent directories were at the beginning of @INC. so it's checking you, then your parent, then their parent, all the way up. and if the module is found in that path, the parent directory is kept as though by use lib. 💖

also! set the ABOVE_DISCOVERY_ACROSS_FILESYSTEM shell variable to a true value if you want it to crawl past device boundaries. iykyk, sometimes the module lives on a different filesystem and you gotta let it wander 🧚

---

🎀 EXAMPLES 🎀

# given /home/me/perlsrc/My/Module.pm

# in /home/me/perlsrc/My/Module/Some/Path/

# in myapp.pl: use above "My::Module";

# does this ..if run anywhere under /home/me/perlsrc: use lib
'/home/me/perlsrc/' use My::Module;

see how it works?? you're deep down in some nested path and it still finds your module all the way up at /home/me/perlsrc/. it's giving search-party energy 🔥

---

👑 AUTHOR 👑

Scott Smith Nathaniel Nutter 🌈

---

and that's the whole page bestie!! this one's perl v5.32.1, dated 2022-01-17, and it lives at above(3pm) in the Perl user-contributed manual. mwah, go forth and use above responsibly 💅💖✨