Module::Reader(3)

🎀 NAME 🎀

Hii bestie!! 💖 Welcome to Module::Reader(3), from the User Contributed Perl Documentation corner of the universe. The official one-liner is: Module::Reader - Find and read perl modules like perl does. Lowkey that’s the whole mood: it finds and reads Perl modules the same way perl does. No cap. ✨

🌈 SYNOPSIS 🌈

Okay so here’s the demo code, and yes we’re keeping it exactly as it was. Group-chat screenshot energy:

use Module::Reader;

my $reader      = Module::Reader->new;
my $module      = $reader->module("My::Module");
my $filename    = $module->found_file;
my $content     = $module->content;
my $file_handle = $module->handle;

# search options
my $other_reader = Module::Reader->new(inc => ["/some/lib/dir", "/another/lib/dir"]);
my $other_reader2 = Module::Reader->new(found => { 'My/Module.pm' => '/a_location.pm' });

# Functional Interface
use Module::Reader qw(module_handle module_content);
my $io = module_handle('My::Module');
my $content = module_content('My::Module');

✨ DESCRIPTION ✨

This module finds modules in @INC using the same algorithm perl does. From that, it gives you the source content of a module, the file name (where available), and how it was found. Searches (and content) are based on the same internal rules that perl uses for require|perlfunc/require and do|perlfunc/do. Iconic behavior only. 💅

🎁 EXPORTS 🎁

✨ module_handle ( $module_name, @search_directories ) ✨

Returns an IO handle for the given module. Slay.

🦋 module_content ( $module_name, @search_directories ) 🦋

Returns the content of a given module. Obsessed.

💅 ATTRIBUTES 💅

• inc — An arrayref packed with directories or hooks to search for modules or files. It gets used exactly the way require uses @INC. If you don’t provide it, @INC itself is what gets used. No extra setup needed.
• found — A hashref mapping module filenames (of "My/Module.pm" format> — yep, the tiny > stays) to files that exist on disk, doing the same job as %INC. The values can optionally be an @INC hook. You can also set this option to 1, and then %INC will be used instead. Choose your fighter.
• pmc — A boolean that says whether .pmc files should be found in preference to .pm files. If you don’t specify it, you get the same behavior perl was compiled with. Compiled-in vibes.
• open — A boolean controlling whether the files found get opened immediately when they’re found. Defaults to true. Instant access, bestie.
• abort_on_eacces — A boolean that decides whether to throw an error or skip the path when it hits "EACCES" (access denied) errors. Defaults to true on perl 5.18 and above, matching what require does. Respect the permission wall.
• check_hooks_for_nonsearchable — For non-searchable paths (absolute paths and ones starting with "./" or "../"), this attempts to check the hook items (and not the directories) in @INC if the file can’t be found directly. It matches perl’s behavior. Defaults to true. Hook check, but make it searchable-adjacent.

🌸 METHODS 🌸

module

Hands you a file object for the module name you give it. If the module can’t be found, it raises an exception. No silent ghosting.

file

Hands you a file object for the file name you give it. If the file can’t be found, it raises an exception. For absolute paths, or files starting with "./" or "../" (and ".\" or "..\" on Windows), no directory search happens. Windows said not today.

modules

Returns an array of file objects for a module name. You get every file that could be loaded based on the inc options.

files

Returns an array of file objects for a file name. You get every file that could be loaded based on the inc options.

🧚 FILE OBJECTS 🧚

The file objects returned represent an entry that could be found in @INC. They’ll generally be files that exist on the file system somewhere, but they can also represent files that only exist only in memory or have arbitrary filters applied. (Yes, “only exist only” is the original phrasing — we keep the lore.) 💀

🎀 FILE METHODS 🎀

filename

The filename that was searched for. Simple.

module

If a module was searched for, or a file of the matching form ("My/Module.pm"), this is the module that was searched for. Module identity unlocked.

found_file

The path to the file found by require.

This might not be an actual file that exists; it’s the file name perl will use for the file for things like caller or __FILE__.

For .pmc files, this is the .pm form of the file.

For @INC hooks this is a file name of the form "/loader/0x123456abcdef/My/Module.pm", matching how perl treats them internally. Perl internals said what they said.

disk_file

The path to the file that exists on disk. When the file is found via an @INC hook, this is undef. Undef is undef.

content

The content of the found file. Snack time.

handle

A file handle to the found file’s content. Handle acquired.

is_pmc

A boolean value representing if the file found was .pmc variant of the file requested. PMC check.

inc_entry

The directory or hook that was used to find the given file or module. If "found" is used, this may be undef. Mystery entry can be undef.

🌀 RAW HOOK DATA 🌀

File objects also have methods for the raw file handle and read callbacks used to read a file. Interacting with the handle or callback can impact the return values of "content" and "handle", and vice versa. It should generally be avoided unless you’re introspecting the @INC hooks|perlfunc/require. Handle with care, bestie.

raw_filehandle

The raw file handle to the file found. This is either a file handle to a file found on disk, or something returned by an @INC hook|perlfunc/require. The hook callback, if it exists, will not be taken into account by this method. Raw mode.

read_callback

A callback used to read content, or modify a file handle from an @INC hook. Callback behavior.

read_callback_options

An array reference of arguments to send to the read callback whem reading or modifying content from a file handle. It’ll contain either zero or one entries. Yes, whem. The original spelling stays.

🔥 SEE ALSO 🔥

Okay so a bunch of other modules try to do @INC searches like this one, but no other module accurately represents how perl itself uses @INC. Most don’t match perl’s behavior around character and block devices, directories, or permissions. And often, .pmc files are just not taken into account. Accuracy tea.

Some of these modules have other use cases. The comments below are primarily about their ability to search @INC.

• App::moduleswhere — Only available as a command line utility. Inaccurately gives the first file found on disk in @INC.
• App::whichpm — Inaccurately gives the first file found on disk in @INC.
• Class::Inspector — For unloaded modules, inaccurately checks if a module exists.
• Module::Data — Same caveats as "Path::ScanINC".
• Module::Filename — Inaccurately gives the first file found on disk in @INC.
• Module::Finder — Inaccurately searches for ".pm" and ".pmc" files in subdirectories of @INC.
• Module::Info — Inaccurately searches @INC for files and gives inaccurate information for the files that it finds.
• Module::Locate — Inaccurately searches @INC for matching files. Attempts to handle hooks, but handles most cases wrong.
• Module::Mapper — Searches for ".pm" and ".pod" files in relatively unpredictable fashion, based usually on the current directory. Optionally, can inaccurately scan @INC.
• Module::Metadata — Primarily designed as a version number extractor. Meant to find files on disk, avoiding the nuance involved in perl’s file loading.
• Module::Path — Inaccurately gives the first file found on disk in @INC.
• Module::Util — Inaccurately searches for modules, ignoring @INC hooks.
• Path::ScanINC — Inaccurately searches for files, with confusing output for @INC hooks.
• Pod::Perldoc — Primarily meant for searching for related documentation. Finds related module files, or sometimes ".pod" files. Unpredictable search path.

👑 AUTHOR 👑

haarg — Graham Knop (cpan:HAARG) <haarg@haarg.org>. Legend behavior.

CONTRIBUTORS

None yet.

💖 COPYRIGHT 💖

Copyright (c) 2013 the Module::Reader "AUTHOR" and "CONTRIBUTORS" as listed above.

🌈 LICENSE 🌈

This library is free software and may be distributed under the same terms as perl itself.

Byeee bestie! 🫶 This page came from perl v5.42.0, dated 2023-08-08, and it’s the Module::Reader(3) manual. Mwah 💋✨