Module::Util(3pm)

💖 Module::Util 💖

okay bestie, so you know how perl modules are all Foo::Bar::Baz with the double colons and the vibes, and sometimes you gotta turn that into a file path, or turn a file path back into a module name, and it's giving chaos every single time? yeah. this is the page for Module::Util (that's the 3pm manual, perl section 3, contributed docs section — iykyk). it's a little toolkit of module name tools and transformations, and it literally centralises all the stuff that modules-about-modules keep re-implementing. converting module names to relative paths? that's the whole moment. periodt.

---

✨ SYNOPSIS ✨

use Module::Util qw( :all );

$valid = is_valid_module_name $potential_module;

$relative_path = module_path $module_name;

$file_system_path = module_fs_path $module_name;

# load module at runtime
require module_path $module_name;

# (see perldoc -f require for limitations of this approach.)

---

🌸 DESCRIPTION 🌸

so basically Module::Util hands you a handful of genuinely useful functions for messing with module names. its main character energy is all about centralising the stuff that modules which manipulate other modules keep writing over and over — converting module names to relative paths, that kinda thing. no cap, it's a tiny little glue library and it ate. 💅

---

🎀 EXPORTS 🎀

• by default? literally nothing. zero. nada. 🙈
• want it all? use the tag :all to import every function. slay.

---

🌈 FUNCTIONS 🌈

is_valid_module_name 🔍

$bool = is_valid_module_name($module)

returns true if $module looks like a module name, and false otherwise. simple as that bestie.

---

module_is_loaded 👑

$abs_path_or_hook = module_is_loaded($module)

returns the %INC entry for the given module. usually that's the absolute path of the module... but sometimes it's the hook object that loaded it instead. sneaky.

see perldoc -f require for the ✨lore✨.

it's equivalent to:

$INC{module_path($module)};

with one tiny glow-up: invalid module names just quietly return false without generating warnings. not me being chill about it 💅.

---

find_installed 🕵️‍♀️

$path = find_installed($module, [@inc])

returns the first found installed location of the given module. it's always an absolute filesystem path, even when it's derived from a relative path in the include list. iconic.

by default @INC gets searched, but you can override that by passing extra arguments:

# look in @INC
$path = find_installed("Module::Util")

# look only in lib and blib/lib, not in @INC
$path = find_installed("Module::Util", 'lib', 'blib/lib')

⚠️ heads up bestie: this will ignore any references in the search path. so if this returns nothing, it does not necessarily mean the module can't be successfully required. don't come for me, it's just how it is 😭

---

all_installed 📚

@paths = all_installed($module, [@inc])

like find_installed, but it'll return multiple results if the module is installed in multiple locations. collector behavior fr fr 🌸

---

find_in_namespace 🦋

@modules = find_in_namespace($namespace, [ @inc ])

searches for modules under a given namespace in the search path (@INC by default).

find_in_namespace("My::Namespace");

returns unique installed module names under that namespace. important note: this does not include the passed-in name, even if it is the name of an installed module. the audacity? anyway.

using an empty string as the namespace returns all modules in @inc. everything. the whole closet. 👑

---

module_path 🛤️

$path = module_path($module)

returns a relative path in the form used in %INC. which, I am led to believe, is always a unix file path, no matter what platform you're on. periods staying unix-y.

if the argument isn't a valid module name, nothing is returned. 🤷‍♀️

---

module_fs_path 💻

$path = module_fs_path($module)

like module_path, but returns the path in the native filesystem format. on unix systems this should be identical to module_path, so enjoy the consistency bestie.

---

path_to_module 🔄

$module = path_to_module($path)

transforms a relative unix file path into a module name.

# Print loaded modules as module names instead of paths:
print join("\n", map { path_to_module($_) } keys %INC

returns undef if the resulting module name isn't valid. no notes.

---

fs_path_to_module 🪟

$module = fs_path_to_module($fs_path)

transforms relative filesystem paths into module names. yes, even with the backslashes.

# on windows:
fs_path_to_module("Module\\Util.pm")
# returns Module::Util

returns undef if the resulting module isn't valid.

---

module_path_parts 🧩

@parts = module_path_parts($module_name)

returns the module name split into parts suitable for feeding to File::Spec->catfile.

module_path_parts('Module::Util')
# returns ('Module', 'Util.pm')

if the module name is invalid, nothing is returned. 💀

---

canonical_module_name 🎀

$module = canonical_module_name($module);

returns the canonical module name for the given module. basically it eliminates any apostrophe symbols and replaces them with '::'. little glow-up, big impact.

canonical_module_name("Acme::Don't"); # Acme::Don::t

returns undef if the name isn't valid.

---

module_name_parts 🍓

@parts = module_name_parts($module);

returns a list of name parts for the given module. cute and simple.

module_name_parts('Acme::Example); # ('Acme', 'Example')

(that example line is exactly how it appears in the docs, bestie — yes, the quote is unbalanced, I'm just the messenger 🫶)

---

💀 BUGS 💀

None known. please report any found! if you find one you're literally doing the lord's work, drop it in the tracker 🌸

---

🌟 SEE ALSO 🌟

• pm_which — a command-line utility for finding installed perl modules that is bundled with this module. bestie it ships with us, that's so cute 🎀
• other, similar CPAN modules:
  • Class::Inspector, Module::Info,
  • Module::Require, UNIVERSAL::require, Module::Runtime
• perldoc -f require

---

👑 AUTHOR 👑

Matt Lawrence <mattlaw@cpan.org> — icon, legend, the moment.

---

💜 THANKS 💜

Alexander Kuehne, Adrian Lai and Daniel Lukasiak for submitting patches. we love a contributor era 🫶✨

---

📜 COPYRIGHT 📜

Copyright 2005 Matt Lawrence, All Rights Reserved.

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

---

that's the whole page. no cap, you're now a Module::Util girlie. go forth and convert some module names, bestie 💅🦋

perl v5.36.0 · 2022-10-13 — that's the version and date stamped on this page, mwah 💖