Module::Reader - Find and read perl modules like perl does
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');
This module finds modules in @INC using the same algorithm perl does. From that, it will give 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.
@INC
Returns an IO handle for the given module.
Returns the content of a given module.
An array reference containing a list of directories or hooks to search for modules or files. This will be used in the same manner that require uses @INC. If not provided, @INC itself will be used.
A hash reference of module filenames (of My/Module.pm format>) to files that exist on disk, working the same as %INC. The values can optionally be an @INC hook. This option can also be 1, in which case %INC will be used instead.
My/Module.pm
%INC
A boolean controlling if .pmc files should be found in preference to .pm files. If not specified, the same behavior perl was compiled with will be used.
.pmc
.pm
A boolean controlling if the files found will be opened immediately when found. Defaults to true.
Returns a file object for the given module name. If the module can't be found, an exception will be raised.
Returns a file object for the given file name. If the file can't be found, an exception will be raised. For absolute paths, or files starting with ./ or ../ (and .\ or ..\ on Windows), no directory search will be performed.
./
../
.\
..\
Returns an array of file objects for a given module name. This will give every file that could be loaded based on the "inc" options.
Returns an array of file objects for a given file name. This will give every file that could be loaded based on the "inc" options.
The file objects returned represent an entry that could be found in @INC. While they will generally be files that exist on the file system somewhere, they may also represent files that only exist only in memory or have arbitrary filters applied.
The filename that was seached for.
If a module was searched for, or a file of the matching form (My/Module.pm), this will be the module searched for.
The path to the file found by require.
This may not represent an actual file that exists, but the file name that perl will use for the file for things like caller or __FILE__.
For .pmc files, this will be the .pm form of the file.
For @INC hooks this will be a file name of the form /loader/0x123456abcdef/My/Module.pm, matching how perl treats them internally.
/loader/0x123456abcdef/My/Module.pm
The path to the file that exists on disk. When the file is found via an @INC hook, this will be undef.
The content of the found file.
A file handle to the found file's content.
A boolean value representing if the file found was .pmc variant of the file requested.
The directory or hook that was used to find the given file or module. If "found" is used, this may be undef.
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 are introspecting the @INC hooks|perlfunc/require.
The raw file handle to the file found. This will be 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.
A callback used to read content, or modify a file handle from an @INC hook.
An array reference of arguments to send to the read callback whem reading or modifying content from a file handle. Will contain either zero or one entries.
Numerous other modules attempt to do @INC searches similar to this module, but no other module accurately represents how perl itself uses @INC. Most don't match perl's behavior regarding character and block devices, directories, or permissions. Often, .pmc files are not taken into account.
Some of these modules have other use cases. The following comments are primarily related to their ability to search @INC.
Only available as a command line utility. Inaccurately gives the first file found on disk in @INC.
Inaccurately gives the first file found on disk in @INC.
For unloaded modules, inaccurately checks if a module exists.
Same caveats as "Path::ScanINC".
Inaccurately searches for .pm and .pmc files in subdirectories of @INC.
Inaccurately searches @INC for files and gives inaccurate information for the files that it finds.
Innacurately searches @INC for matching files. Attempts to handle hooks, but handles most cases wrong.
Searches for .pm and .pod files in relatively unpredictable fashion, based usually on the current directory. Optionally, can inaccurately scan @INC.
.pod
Primarily designed as a version number extractor. Meant to find files on disk, avoiding the nuance involved in perl's file loading.
Inaccurately searches for modules, ignoring @INC hooks.
Inaccurately searches for files, with confusing output for @INC hooks.
Primarily meant for searching for related documentation. Finds related module files, or sometimes .pod files. Unpredictable search path.
haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
None yet.
Copyright (c) 2013 the Module::Reader "AUTHOR" and "CONTRIBUTORS" as listed above.
This library is free software and may be distributed under the same terms as perl itself.
To install Module::Reader, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Reader
CPAN shell
perl -MCPAN -e shell install Module::Reader
For more information on module installation, please visit the detailed CPAN module installation guide.