1Module::Reader(3)     User Contributed Perl Documentation    Module::Reader(3)
2
3
4

NAME

6       Module::Reader - Find and read perl modules like perl does
7

SYNOPSIS

9         use Module::Reader;
10
11         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
17         # 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
21         # 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

DESCRIPTION

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

EXPORTS

34   module_handle ( $module_name, @search_directories )
35       Returns an IO handle for the given module.
36
37   module_content ( $module_name, @search_directories )
38       Returns the content of a given module.
39

ATTRIBUTES

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
45       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
51       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
55       open
56           A boolean controlling if the files found will be opened immediately
57           when found.  Defaults to true.
58
59       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
65       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

METHODS

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
76   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
82   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
86   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

FILE OBJECTS

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
96   FILE METHODS
97       filename
98
99       The filename that was searched for.
100
101       module
102
103       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
106       found_file
107
108       The path to the file found by require.
109
110       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
113       For ".pmc" files, this will be the ".pm" form of the file.
114
115       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
119       disk_file
120
121       The path to the file that exists on disk.  When the file is found via
122       an @INC hook, this will be undef.
123
124       content
125
126       The content of the found file.
127
128       handle
129
130       A file handle to the found file's content.
131
132       is_pmc
133
134       A boolean value representing if the file found was ".pmc" variant of
135       the file requested.
136
137       inc_entry
138
139       The directory or hook that was used to find the given file or module.
140       If "found" is used, this may be undef.
141
142   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
149       raw_filehandle
150
151       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
156       read_callback
157
158       A callback used to read content, or modify a file handle from an @INC
159       hook.
160
161       read_callback_options
162
163       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

SEE ALSO

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
174       Some of these modules have other use cases.  The following comments are
175       primarily related to their ability to search @INC.
176
177       App::moduleswhere
178           Only available as a command line utility.  Inaccurately gives the
179           first file found on disk in @INC.
180
181       App::whichpm
182           Inaccurately gives the first file found on disk in @INC.
183
184       Class::Inspector
185           For unloaded modules, inaccurately checks if a module exists.
186
187       Module::Data
188           Same caveats as "Path::ScanINC".
189
190       Module::Filename
191           Inaccurately gives the first file found on disk in @INC.
192
193       Module::Finder
194           Inaccurately searches for ".pm" and ".pmc" files in subdirectories
195           of @INC.
196
197       Module::Info
198           Inaccurately searches @INC for files and gives inaccurate
199           information for the files that it finds.
200
201       Module::Locate
202           Inaccurately searches @INC for matching files.  Attempts to handle
203           hooks, but handles most cases wrong.
204
205       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
210       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
214       Module::Path
215           Inaccurately gives the first file found on disk in @INC.
216
217       Module::Util
218           Inaccurately searches for modules, ignoring @INC hooks.
219
220       Path::ScanINC
221           Inaccurately searches for files, with confusing output for @INC
222           hooks.
223
224       Pod::Perldoc
225           Primarily meant for searching for related documentation.  Finds
226           related module files, or sometimes ".pod" files.  Unpredictable
227           search path.
228

AUTHOR

230       haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
231
232   CONTRIBUTORS
233       None yet.
234
236       Copyright (c) 2013 the Module::Reader "AUTHOR" and "CONTRIBUTORS" as
237       listed above.
238

LICENSE

240       This library is free software and may be distributed under the same
241       terms as perl itself.
242
243
244
245perl v5.34.0                      2022-01-21                 Module::Reader(3)
Impressum