.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Module::Reader 3pm"
.TH Module::Reader 3pm "2023-08-08" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Reader \- Find and read perl modules like perl does
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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 => { \*(AqMy/Module.pm\*(Aq => \*(Aq/a_location.pm\*(Aq });
\&
\&  # Functional Interface
\&  use Module::Reader qw(module_handle module_content);
\&  my $io = module_handle(\*(AqMy::Module\*(Aq);
\&  my $content = module_content(\*(AqMy::Module\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module finds modules in \f(CW@INC\fR 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 \fIrequire|perlfunc/require\fR and
\&\fIdo|perlfunc/do\fR.
.SH "EXPORTS"
.IX Header "EXPORTS"
.ie n .SS "module_handle ( $module_name, @search_directories )"
.el .SS "module_handle ( \f(CW$module_name\fP, \f(CW@search_directories\fP )"
.IX Subsection "module_handle ( $module_name, @search_directories )"
Returns an \s-1IO\s0 handle for the given module.
.ie n .SS "module_content ( $module_name, @search_directories )"
.el .SS "module_content ( \f(CW$module_name\fP, \f(CW@search_directories\fP )"
.IX Subsection "module_content ( $module_name, @search_directories )"
Returns the content of a given module.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "inc" 4
.IX Item "inc"
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 \f(CW@INC\fR.  If not provided,
\&\f(CW@INC\fR itself will be used.
.IP "found" 4
.IX Item "found"
A hash reference of module filenames (of \f(CW\*(C`My/Module.pm\*(C'\fR format>) to files that
exist on disk, working the same as \f(CW%INC\fR.  The values can
optionally be an \f(CW@INC\fR hook.  This option can also be
1, in which case \f(CW%INC\fR will be used instead.
.IP "pmc" 4
.IX Item "pmc"
A boolean controlling if \f(CW\*(C`.pmc\*(C'\fR files should be found in preference to \f(CW\*(C`.pm\*(C'\fR
files.  If not specified, the same behavior perl was compiled with will be used.
.IP "open" 4
.IX Item "open"
A boolean controlling if the files found will be opened immediately when found.
Defaults to true.
.IP "abort_on_eacces" 4
.IX Item "abort_on_eacces"
A boolean controlling if an error should be thrown or if the path should be
skipped when encountering \f(CW\*(C`EACCES\*(C'\fR (access denied) errors.  Defaults to true
on perl 5.18 and above, matching the behavior of require.
.IP "check_hooks_for_nonsearchable" 4
.IX Item "check_hooks_for_nonsearchable"
For non-searchable paths (absolute paths and those starting with \f(CW\*(C`./\*(C'\fR or
\&\f(CW\*(C`../\*(C'\fR) attempt to check the hook items (and not the directories) in \f(CW@INC\fR if
the file cannot be found directly.  This matches the behavior of perl.  Defaults
to true.
.SH "METHODS"
.IX Header "METHODS"
.SS "module"
.IX Subsection "module"
Returns a file object for the given module name.  If the module
can't be found, an exception will be raised.
.SS "file"
.IX Subsection "file"
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 \f(CW\*(C`./\*(C'\fR or \f(CW\*(C`../\*(C'\fR (and \f(CW\*(C`.\e\*(C'\fR or \f(CW\*(C`..\e\*(C'\fR on Windows), no directory
search will be performed.
.SS "modules"
.IX Subsection "modules"
Returns an array of file objects for a given module name.  This
will give every file that could be loaded based on the \*(L"inc\*(R" options.
.SS "files"
.IX Subsection "files"
Returns an array of file objects for a given file name.  This
will give every file that could be loaded based on the \*(L"inc\*(R" options.
.SH "FILE OBJECTS"
.IX Header "FILE OBJECTS"
The file objects returned represent an entry that could be found in
\&\f(CW@INC\fR.  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.
.SS "\s-1FILE METHODS\s0"
.IX Subsection "FILE METHODS"
\fIfilename\fR
.IX Subsection "filename"
.PP
The filename that was searched for.
.PP
\fImodule\fR
.IX Subsection "module"
.PP
If a module was searched for, or a file of the matching form (\f(CW\*(C`My/Module.pm\*(C'\fR),
this will be the module searched for.
.PP
\fIfound_file\fR
.IX Subsection "found_file"
.PP
The path to the file found by require.
.PP
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_\|_.
.PP
For \f(CW\*(C`.pmc\*(C'\fR files, this will be the \f(CW\*(C`.pm\*(C'\fR form of the file.
.PP
For \f(CW@INC\fR hooks this will be a file name of the form
\&\f(CW\*(C`/loader/0x123456abcdef/My/Module.pm\*(C'\fR, matching how perl treats them internally.
.PP
\fIdisk_file\fR
.IX Subsection "disk_file"
.PP
The path to the file that exists on disk.  When the file is found via an
\&\f(CW@INC\fR hook, this will be undef.
.PP
\fIcontent\fR
.IX Subsection "content"
.PP
The content of the found file.
.PP
\fIhandle\fR
.IX Subsection "handle"
.PP
A file handle to the found file's content.
.PP
\fIis_pmc\fR
.IX Subsection "is_pmc"
.PP
A boolean value representing if the file found was \f(CW\*(C`.pmc\*(C'\fR variant of the file
requested.
.PP
\fIinc_entry\fR
.IX Subsection "inc_entry"
.PP
The directory or hook that was used to find the given file
or module.  If \*(L"found\*(R" is used, this may be undef.
.SS "\s-1RAW HOOK DATA\s0"
.IX Subsection "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 \*(L"content\*(R" and \*(L"handle\*(R", and vice versa.  It should generally be
avoided unless you are introspecting the \fI\f(CI@INC\fI hooks|perlfunc/require\fR.
.PP
\fIraw_filehandle\fR
.IX Subsection "raw_filehandle"
.PP
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
\&\fI\f(CI@INC\fI hook|perlfunc/require\fR.  The hook callback, if it exists, will not
be taken into account by this method.
.PP
\fIread_callback\fR
.IX Subsection "read_callback"
.PP
A callback used to read content, or modify a file handle from an \f(CW@INC\fR hook.
.PP
\fIread_callback_options\fR
.IX Subsection "read_callback_options"
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Numerous other modules attempt to do \f(CW@INC\fR searches similar to this module,
but no other module accurately represents how perl itself uses
\&\f(CW@INC\fR.  Most don't match perl's behavior regarding
character and block devices, directories, or permissions.  Often, \f(CW\*(C`.pmc\*(C'\fR files
are not taken into account.
.PP
Some of these modules have other use cases.  The following comments are
primarily related to their ability to search \f(CW@INC\fR.
.IP "App::moduleswhere" 4
.IX Item "App::moduleswhere"
Only available as a command line utility.  Inaccurately gives the first file
found on disk in \f(CW@INC\fR.
.IP "App::whichpm" 4
.IX Item "App::whichpm"
Inaccurately gives the first file found on disk in \f(CW@INC\fR.
.IP "Class::Inspector" 4
.IX Item "Class::Inspector"
For unloaded modules, inaccurately checks if a module exists.
.IP "Module::Data" 4
.IX Item "Module::Data"
Same caveats as \*(L"Path::ScanINC\*(R".
.IP "Module::Filename" 4
.IX Item "Module::Filename"
Inaccurately gives the first file found on disk in \f(CW@INC\fR.
.IP "Module::Finder" 4
.IX Item "Module::Finder"
Inaccurately searches for \f(CW\*(C`.pm\*(C'\fR and \f(CW\*(C`.pmc\*(C'\fR files in subdirectories of \f(CW@INC\fR.
.IP "Module::Info" 4
.IX Item "Module::Info"
Inaccurately searches \f(CW@INC\fR for files and gives inaccurate information for the
files that it finds.
.IP "Module::Locate" 4
.IX Item "Module::Locate"
Inaccurately searches \f(CW@INC\fR for matching files.  Attempts to handle hooks, but
handles most cases wrong.
.IP "Module::Mapper" 4
.IX Item "Module::Mapper"
Searches for \f(CW\*(C`.pm\*(C'\fR and \f(CW\*(C`.pod\*(C'\fR files in relatively unpredictable fashion,
based usually on the current directory.  Optionally, can inaccurately scan
\&\f(CW@INC\fR.
.IP "Module::Metadata" 4
.IX Item "Module::Metadata"
Primarily designed as a version number extractor.  Meant to find files on disk,
avoiding the nuance involved in perl's file loading.
.IP "Module::Path" 4
.IX Item "Module::Path"
Inaccurately gives the first file found on disk in \f(CW@INC\fR.
.IP "Module::Util" 4
.IX Item "Module::Util"
Inaccurately searches for modules, ignoring \f(CW@INC\fR hooks.
.IP "Path::ScanINC" 4
.IX Item "Path::ScanINC"
Inaccurately searches for files, with confusing output for \f(CW@INC\fR hooks.
.IP "Pod::Perldoc" 4
.IX Item "Pod::Perldoc"
Primarily meant for searching for related documentation.  Finds related module
files, or sometimes \f(CW\*(C`.pod\*(C'\fR files.  Unpredictable search path.
.SH "AUTHOR"
.IX Header "AUTHOR"
haarg \- Graham Knop (cpan:HAARG) <haarg@haarg.org>
.SS "\s-1CONTRIBUTORS\s0"
.IX Subsection "CONTRIBUTORS"
None yet.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2013 the Module::Reader \*(L"\s-1AUTHOR\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0
as listed above.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software and may be distributed under the same terms
as perl itself.