.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::Info 3pm"
.TH Module::Info 3pm "2022-06-15" "perl v5.34.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::Info \- Information about Perl modules
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Module::Info;
\&
\&  my $mod = Module::Info\->new_from_file(\*(AqSome/Module.pm\*(Aq);
\&  my $mod = Module::Info\->new_from_module(\*(AqSome::Module\*(Aq);
\&  my $mod = Module::Info\->new_from_loaded(\*(AqSome::Module\*(Aq);
\&
\&  my @mods = Module::Info\->all_installed(\*(AqSome::Module\*(Aq);
\&
\&  my $name    = $mod\->name;
\&  my $version = $mod\->version;
\&  my $dir     = $mod\->inc_dir;
\&  my $file    = $mod\->file;
\&  my $is_core = $mod\->is_core;
\&
\&  # Only available in perl 5.6.1 and up.
\&  # These do compile the module.
\&  my @packages = $mod\->packages_inside;
\&  my @used     = $mod\->modules_used;
\&  my @subs     = $mod\->subroutines;
\&  my @isa      = $mod\->superclasses;
\&  my @calls    = $mod\->subroutines_called;
\&
\&  # Check for constructs which make perl hard to predict.
\&  my @methods   = $mod\->dynamic_method_calls;
\&  my @lines     = $mod\->eval_string;    *UNIMPLEMENTED*
\&  my @lines     = $mod\->gotos;          *UNIMPLEMENTED*
\&  my @controls  = $mod\->exit_via_loop_control;      *UNIMPLEMENTED*
\&  my @unpredictables = $mod\->has_unpredictables;    *UNIMPLEMENTED*
\&
\&  # set/get Module::Info options
\&  $self\->die_on_compilation_error(1);
\&  my $die_on_error = $mod\->die_on_compilation_error;
\&  $self\->safe(1);
\&  my $safe = $mod\->safe;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Module::Info gives you information about Perl modules \fBwithout
actually loading the module\fR.  It actually isn't specific to modules
and should work on any perl code.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
There are a few ways to specify which module you want information for.
They all return Module::Info objects.
.IP "new_from_file" 4
.IX Item "new_from_file"
.Vb 1
\&  my $module = Module::Info\->new_from_file(\*(Aqpath/to/Some/Module.pm\*(Aq);
.Ve
.Sp
Given a file, it will interpret this as the module you want
information about.  You can also hand it a perl script.
.Sp
If the file doesn't exist or isn't readable it will return false.
.IP "new_from_module" 4
.IX Item "new_from_module"
.Vb 2
\&  my $module = Module::Info\->new_from_module(\*(AqSome::Module\*(Aq);
\&  my $module = Module::Info\->new_from_module(\*(AqSome::Module\*(Aq, @INC);
.Ve
.Sp
Given a module name, \f(CW@INC\fR will be searched and the first module found
used.  This is the same module that would be loaded if you just say
\&\f(CW\*(C`use Some::Module\*(C'\fR.
.Sp
If you give your own \f(CW@INC\fR, that will be used to search instead.
.IP "new_from_loaded" 4
.IX Item "new_from_loaded"
.Vb 1
\&  my $module = Module::Info\->new_from_loaded(\*(AqSome::Module\*(Aq);
.Ve
.Sp
Gets information about the currently loaded version of Some::Module.
If it isn't loaded, returns false.
.IP "all_installed" 4
.IX Item "all_installed"
.Vb 2
\&  my @modules = Module::Info\->all_installed(\*(AqSome::Module\*(Aq);
\&  my @modules = Module::Info\->all_installed(\*(AqSome::Module\*(Aq, @INC);
.Ve
.Sp
Like \fBnew_from_module()\fR, except \fIall\fR modules in \f(CW@INC\fR will be
returned, in the order they are found.  Thus \f(CW$modules\fR[0] is the one
that would be loaded by \f(CW\*(C`use Some::Module\*(C'\fR.
.SS "Information without loading"
.IX Subsection "Information without loading"
The following methods get their information without actually compiling
the module.
.IP "\fBname\fR" 4
.IX Item "name"
.Vb 2
\&  my $name = $module\->name;
\&  $module\->name($name);
.Ve
.Sp
Name of the module (ie. Some::Module).
.Sp
Module loaded using \fBnew_from_file()\fR won't have this information in
which case you can set it yourself.
.IP "\fBversion\fR" 4
.IX Item "version"
.Vb 1
\&  my $version = $module\->version;
.Ve
.Sp
Divines the value of \f(CW$VERSION\fR.  This uses the same method as
ExtUtils::MakeMaker and all caveats therein apply.
.IP "\fBinc_dir\fR" 4
.IX Item "inc_dir"
.Vb 1
\&  my $dir = $module\->inc_dir;
.Ve
.Sp
Include directory in which this module was found.  Module::Info
objects created with \fBnew_from_file()\fR won't have this info.
.IP "\fBfile\fR" 4
.IX Item "file"
.Vb 1
\&  my $file = $module\->file;
.Ve
.Sp
The absolute path to this module.
.IP "\fBis_core\fR" 4
.IX Item "is_core"
.Vb 1
\&  my $is_core = $module\->is_core;
.Ve
.Sp
Checks if this module is the one distributed with Perl.
.Sp
\&\fB\s-1NOTE\s0\fR This goes by what directory it's in.  It's possible that the
module has been altered or upgraded from \s-1CPAN\s0 since the original Perl
installation.
.IP "\fBhas_pod\fR" 4
.IX Item "has_pod"
.Vb 1
\&    my $has_pod = $module\->has_pod;
.Ve
.Sp
Returns the location of the module's pod, which can be the module file itself, 
if the \s-1POD\s0 is inlined, the associated \s-1POD\s0 file, or nothing if there is no \s-1POD\s0 
at all.
.SS "Information that requires loading."
.IX Subsection "Information that requires loading."
\&\fB\s-1WARNING\s0!\fR  From here down reliability drops rapidly!
.PP
The following methods get their information by compiling the module
and examining the opcode tree.  The module will be compiled in a
separate process so as not to disturb the current program.
.PP
They will only work on 5.6.1 and up and requires the B::Utils module.
.IP "\fBpackages_inside\fR" 4
.IX Item "packages_inside"
.Vb 1
\&  my @packages = $module\->packages_inside;
.Ve
.Sp
Looks for any explicit \f(CW\*(C`package\*(C'\fR declarations inside the module and
returns a list.  Useful for finding hidden classes and functionality
(like Tie::StdHandle inside Tie::Handle).
.Sp
\&\fB\s-1KNOWN BUG\s0\fR Currently doesn't spot package changes inside subroutines.
.IP "\fBpackage_versions\fR" 4
.IX Item "package_versions"
.Vb 1
\&  my %versions = $module\->package_versions;
.Ve
.Sp
Returns a hash whose keys are the packages contained in the module
(these are the same as what's returned by \f(CW\*(C`packages_inside()\*(C'\fR), and
whose values are the versions of those packages.
.IP "\fBmodules_used\fR" 4
.IX Item "modules_used"
.Vb 1
\&  my @used = $module\->modules_used;
.Ve
.Sp
Returns a list of all modules and files which may be \f(CW\*(C`use\*(C'\fR'd or
\&\f(CW\*(C`require\*(C'\fR'd by this module.
.Sp
\&\fB\s-1NOTE\s0\fR These modules may be conditionally loaded, can't tell.  Also
can't find modules which might be used inside an \f(CW\*(C`eval\*(C'\fR.
.IP "\fBmodules_required\fR" 4
.IX Item "modules_required"
.Vb 1
\&  my %required = $module\->modules_required;
.Ve
.Sp
Returns a list of all modules and files which may be \f(CW\*(C`use\*(C'\fR'd or
\&\f(CW\*(C`require\*(C'\fR'd by this module, together with the minimum required version.
.Sp
The hash is keyed on the module/file name, the corrisponding value is
an array reference containing the requied versions, or an empty array
if no specific version was required.
.Sp
\&\fB\s-1NOTE\s0\fR These modules may be conditionally loaded, can't tell.  Also
can't find modules which might be used inside an \f(CW\*(C`eval\*(C'\fR.
.IP "\fBsubroutines\fR" 4
.IX Item "subroutines"
.Vb 1
\&  my %subs = $module\->subroutines;
.Ve
.Sp
Returns a hash of all subroutines defined inside this module and some
info about it.  The key is the *full* name of the subroutine
(ie. \f(CW$subs\fR{'Some::Module::foo'} rather than just \f(CW$subs\fR{'foo'}), value
is a hash ref with information about the subroutine like so:
.Sp
.Vb 2
\&    start   => line number of the first statement in the subroutine
\&    end     => line number of the last statement in the subroutine
.Ve
.Sp
Note that the line numbers may not be entirely accurate and will
change as perl's backend compiler improves.  They typically correspond
to the first and last \fIrun-time\fR statements in a subroutine.  For
example:
.Sp
.Vb 5
\&    sub foo {
\&        package Wibble;
\&        $foo = "bar";
\&        return $foo;
\&    }
.Ve
.Sp
Taking \f(CW\*(C`sub foo {\*(C'\fR as line 1, Module::Info will report line 3 as the
start and line 4 as the end.  \f(CW\*(C`package Wibble;\*(C'\fR is a compile-time
statement.  Again, this will change as perl changes.
.Sp
Note this only catches simple \f(CW\*(C`sub foo {...}\*(C'\fR subroutine
declarations.  Anonymous, autoloaded or eval'd subroutines are not
listed.
.IP "\fBsuperclasses\fR" 4
.IX Item "superclasses"
.Vb 1
\&  my @isa = $module\->superclasses;
.Ve
.Sp
Returns the value of \f(CW@ISA\fR for this \f(CW$module\fR.  Requires that
\&\f(CW$module\fR\->name be set to work.
.Sp
\&\fB\s-1NOTE\s0\fR \fBsuperclasses()\fR is currently cheating.  See \s-1CAVEATS\s0 below.
.IP "\fBsubroutines_called\fR" 4
.IX Item "subroutines_called"
.Vb 1
\&  my @calls = $module\->subroutines_called;
.Ve
.Sp
Finds all the methods and functions which are called inside the
\&\f(CW$module\fR.
.Sp
Returns a list of hashes.  Each hash represents a single function or
method call and has the keys:
.Sp
.Vb 7
\&    line        line number where this call originated
\&    class       class called on if its a class method
\&    type        function, symbolic function, object method, 
\&                class method, dynamic object method or 
\&                dynamic class method.
\&                (NOTE  This format will probably change)
\&    name        name of the function/method called if not dynamic
.Ve
.SS "Information about Unpredictable Constructs"
.IX Subsection "Information about Unpredictable Constructs"
Unpredictable constructs are things that make a Perl program hard to
predict what its going to do without actually running it.  There's
nothing wrong with these constructs, but its nice to know where they
are when maintaining a piece of code.
.IP "\fBdynamic_method_calls\fR" 4
.IX Item "dynamic_method_calls"
.Vb 1
\&  my @methods = $module\->dynamic_method_calls;
.Ve
.Sp
Returns a list of dynamic method calls (ie. \f(CW\*(C`$obj\-\*(C'\fR$\fBmethod()\fR>) used
by the \f(CW$module\fR.  \f(CW@methods\fR has the same format as the return value of
\&\fBsubroutines_called()\fR.
.SS "Options"
.IX Subsection "Options"
The following methods get/set specific option values for the
Module::Info object.
.IP "\fBdie_on_compilation_error\fR" 4
.IX Item "die_on_compilation_error"
.Vb 3
\&  $module\->die_on_compilation_error(0); # default
\&  $module\->die_on_compilation_error(1);
\&  my $flag = $module\->die_on_compilation_error;
.Ve
.Sp
Sets/gets the \*(L"die on compilation error\*(R" flag. When the flag is off
(default), and a module fails to compile, Module::Info simply emits a
watning and continues. When the flag is on and a module fails to
compile, Module::Info \f(CW\*(C`die()\*(C'\fRs with the same error message it would use
in the warning.
.IP "\fBsafe\fR" 4
.IX Item "safe"
.Vb 3
\&  $module\->safe(0); # default
\&  $module\->safe(1); # be safer
\&  my $flag = $module\->safe;
.Ve
.Sp
Sets/gets the \*(L"safe\*(R" flag. When the flag is enabled all operations
requiring module compilation are forbidden and the \f(CW\*(C`version()\*(C'\fR method
executes its code in a \f(CW\*(C`Safe\*(C'\fR compartment.
.IP "\fBuse_version\fR" 4
.IX Item "use_version"
.Vb 3
\&  $module\->use_version(0); # do not use version.pm (default)
\&  $module\->use_version(1); # use version.pm, die if not present
\&  my $flag = $module\->use_version;
.Ve
.Sp
Sets/gets the \*(L"use_version\*(R" flag. When the flag is enabled the 'version'
method always returns a version object.
.SH "REPOSITORY"
.IX Header "REPOSITORY"
<https://github.com/neilb/Module\-Info>
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael G Schwern <schwern@pobox.com> with code from ExtUtils::MM_Unix,
Module::InstalledVersion and lots of cargo-culting from B::Deparse.
.PP
Mattia Barbon <mbarbon@cpan.org> maintained
the module from 2002 to 2013.
.PP
Neil Bowers <neilb@cpan.org> is the current maintainer.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "THANKS"
.IX Header "THANKS"
Many thanks to Simon Cozens and Robin Houston for letting me chew
their ears about B.
.SH "CAVEATS"
.IX Header "CAVEATS"
Code refs in \f(CW@INC\fR are currently ignored.  If this bothers you submit a
patch.
.PP
\&\fBsuperclasses()\fR is cheating and just loading the module in a separate
process and looking at \f(CW@ISA\fR.  I don't think its worth the trouble to
go through and parse the opcode tree as it still requires loading the
module and running all the \s-1BEGIN\s0 blocks.  Patches welcome.
.PP
I originally was going to call \fBsuperclasses()\fR \fBisa()\fR but then I
remembered that would be bad.
.PP
All the methods that require loading are really inefficient as they're
not caching anything.  I'll worry about efficiency later.