1Module::Reader(3) User Contributed Perl Documentation Module::Reader(3)
2
6 Module::Reader - Find and read perl modules like perl does
7
9 use Module::Reader;
10 my $reader = Module::Reader->new;
12 my $module = $reader->module("My::Module");
13 my $filename = $module->found_file;
14 my $content = $module->content;
15 my $file_handle = $module->handle;
16 # search options
18 my $other_reader = Module::Reader->new(inc => ["/some/lib/dir", "/another/lib/dir"]);
19 my $other_reader2 = Module::Reader->new(found => { 'My/Module.pm' => '/a_location.pm' });
20 # Functional Interface
22 use Module::Reader qw(module_handle module_content);
23 my $io = module_handle('My::Module');
24 my $content = module_content('My::Module');
25
27 This module finds modules in @INC using the same algorithm perl does.
28 From that, it will give you the source content of a module, the file
29 name (where available), and how it was found. Searches (and content)
30 are based on the same internal rules that perl uses for
31 require|perlfunc/require and do|perlfunc/do.
32
34 module_handle ( $module_name, @search_directories )
35 Returns an IO handle for the given module.
36 module_content ( $module_name, @search_directories )
38 Returns the content of a given module.
39
41 inc An array reference containing a list of directories or hooks to
42 search for modules or files. This will be used in the same manner
43 that require uses @INC. If not provided, @INC itself will be used.
44 found
46 A hash reference of module filenames (of "My/Module.pm" format>) to
47 files that exist on disk, working the same as %INC. The values can
48 optionally be an @INC hook. This option can also be 1, in which
49 case %INC will be used instead.
50 pmc A boolean controlling if ".pmc" files should be found in preference
52 to ".pm" files. If not specified, the same behavior perl was
53 compiled with will be used.
54 open
56 A boolean controlling if the files found will be opened immediately
57 when found. Defaults to true.
58 abort_on_eacces
60 A boolean controlling if an error should be thrown or if the path
61 should be skipped when encountering "EACCES" (access denied)
62 errors. Defaults to true on perl 5.18 and above, matching the
63 behavior of require.
64 check_hooks_for_nonsearchable
66 For non-searchable paths (absolute paths and those starting with
67 "./" or "../") attempt to check the hook items (and not the
68 directories) in @INC if the file cannot be found directly. This
69 matches the behavior of perl. Defaults to true.
70
72 module
73 Returns a file object for the given module name. If the module can't
74 be found, an exception will be raised.
75 file
77 Returns a file object for the given file name. If the file can't be
78 found, an exception will be raised. For absolute paths, or files
79 starting with "./" or "../" (and ".\" or "..\" on Windows), no
80 directory search will be performed.
81 modules
83 Returns an array of file objects for a given module name. This will
84 give every file that could be loaded based on the "inc" options.
85 files
87 Returns an array of file objects for a given file name. This will give
88 every file that could be loaded based on the "inc" options.
89
91 The file objects returned represent an entry that could be found in
92 @INC. While they will generally be files that exist on the file system
93 somewhere, they may also represent files that only exist only in memory
94 or have arbitrary filters applied.
95 FILE METHODS
97 filename
98 The filename that was searched for.
100 module
102 If a module was searched for, or a file of the matching form
104 ("My/Module.pm"), this will be the module searched for.
105 found_file
107 The path to the file found by require.
109 This may not represent an actual file that exists, but the file name
111 that perl will use for the file for things like caller or __FILE__.
112 For ".pmc" files, this will be the ".pm" form of the file.
114 For @INC hooks this will be a file name of the form
116 "/loader/0x123456abcdef/My/Module.pm", matching how perl treats them
117 internally.
118 disk_file
120 The path to the file that exists on disk. When the file is found via
122 an @INC hook, this will be undef.
123 content
125 The content of the found file.
127 handle
129 A file handle to the found file's content.
131 is_pmc
133 A boolean value representing if the file found was ".pmc" variant of
135 the file requested.
136 inc_entry
138 The directory or hook that was used to find the given file or module.
140 If "found" is used, this may be undef.
141 RAW HOOK DATA
143 File objects also have methods for the raw file handle and read
144 callbacks used to read a file. Interacting with the handle or callback
145 can impact the return values of "content" and "handle", and vice versa.
146 It should generally be avoided unless you are introspecting the @INC
147 hooks|perlfunc/require.
148 raw_filehandle
150 The raw file handle to the file found. This will be either a file
152 handle to a file found on disk, or something returned by an @INC
153 hook|perlfunc/require. The hook callback, if it exists, will not be
154 taken into account by this method.
155 read_callback
157 A callback used to read content, or modify a file handle from an @INC
159 hook.
160 read_callback_options
162 An array reference of arguments to send to the read callback whem
164 reading or modifying content from a file handle. Will contain either
165 zero or one entries.
166
168 Numerous other modules attempt to do @INC searches similar to this
169 module, but no other module accurately represents how perl itself uses
170 @INC. Most don't match perl's behavior regarding character and block
171 devices, directories, or permissions. Often, ".pmc" files are not
172 taken into account.
173 Some of these modules have other use cases. The following comments are
175 primarily related to their ability to search @INC.
176 App::moduleswhere
178 Only available as a command line utility. Inaccurately gives the
179 first file found on disk in @INC.
180 App::whichpm
182 Inaccurately gives the first file found on disk in @INC.
183 Class::Inspector
185 For unloaded modules, inaccurately checks if a module exists.
186 Module::Data
188 Same caveats as "Path::ScanINC".
189 Module::Filename
191 Inaccurately gives the first file found on disk in @INC.
192 Module::Finder
194 Inaccurately searches for ".pm" and ".pmc" files in subdirectories
195 of @INC.
196 Module::Info
198 Inaccurately searches @INC for files and gives inaccurate
199 information for the files that it finds.
200 Module::Locate
202 Inaccurately searches @INC for matching files. Attempts to handle
203 hooks, but handles most cases wrong.
204 Module::Mapper
206 Searches for ".pm" and ".pod" files in relatively unpredictable
207 fashion, based usually on the current directory. Optionally, can
208 inaccurately scan @INC.
209 Module::Metadata
211 Primarily designed as a version number extractor. Meant to find
212 files on disk, avoiding the nuance involved in perl's file loading.
213 Module::Path
215 Inaccurately gives the first file found on disk in @INC.
216 Module::Util
218 Inaccurately searches for modules, ignoring @INC hooks.
219 Path::ScanINC
221 Inaccurately searches for files, with confusing output for @INC
222 hooks.
223 Pod::Perldoc
225 Primarily meant for searching for related documentation. Finds
226 related module files, or sometimes ".pod" files. Unpredictable
227 search path.
228
230 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
231 CONTRIBUTORS
233 None yet.
234
236 Copyright (c) 2013 the Module::Reader "AUTHOR" and "CONTRIBUTORS" as
237 listed above.
238
240 This library is free software and may be distributed under the same
241 terms as perl itself.
242perl v5.36.0 2023-01-20 Module::Reader(3)