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.