NAME

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

SYNOPSIS

         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 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.

EXPORTS

   module_handle ( $module_name, @search_directories )
       Returns an IO handle for the given module.

   module_content ( $module_name, @search_directories )
       Returns the content of a given module.

ATTRIBUTES

       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 @INC.  If not provided,
           @INC itself will be used.

       found
           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.

       pmc 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.

       open
           A boolean controlling if the files found will be opened immediately when found.
           Defaults to true.

       abort_on_eacces
           A boolean controlling if an error should be thrown or if the path should be skipped
           when encountering "EACCES" (access denied) errors.  Defaults to true on perl 5.18 and
           above, matching the behavior of require.

       check_hooks_for_nonsearchable
           For non-searchable paths (absolute paths and those starting with "./" or "../")
           attempt to check the hook items (and not the directories) in @INC if the file cannot
           be found directly.  This matches the behavior of perl.  Defaults to true.

METHODS

   module
       Returns a file object for the given module name.  If the module can't be found, an
       exception will be raised.

   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 "./" or "../" (and ".\" or
       "..\" on Windows), no directory search will be performed.

   modules
       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.

   files
       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.

FILE OBJECTS

       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.

   FILE METHODS
       filename

       The filename that was searched for.

       module

       If a module was searched for, or a file of the matching form ("My/Module.pm"), this will
       be the module searched for.

       found_file

       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.

       disk_file

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

       content

       The content of the found file.

       handle

       A file handle to the found file's content.

       is_pmc

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

       inc_entry

       The directory or hook that was used to find the given file or module.  If "found" is used,
       this may 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 are introspecting
       the @INC hooks|perlfunc/require.

       raw_filehandle

       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.

       read_callback

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

       read_callback_options

       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.

SEE ALSO

       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.

       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>

   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.