.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Extract::Use 3pm"
.TH Module::Extract::Use 3pm 2024-02-09 "perl v5.38.2" "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::Extract::Use \- Discover the modules a module explicitly uses
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&        use Module::Extract::Use;
\&
\&        my $extor = Module::Extract::Use\->new;
\&
\&        my @modules = $extor\->get_modules( $file );
\&        if( $extor\->error ) { ... }
\&
\&        my $details = $extor\->get_modules_with_details( $file );
\&        foreach my $detail ( @$details ) {
\&                printf "%s %s imports %s\en",
\&                        $detail\->module, $detail\->version,
\&                        join \*(Aq \*(Aq, @{ $detail\->imports }
\&                }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Extract the names of the modules used in a file using a static
analysis. Since this module does not run code, it cannot find dynamic
uses of modules, such as \f(CW\*(C`eval "require $class"\*(C'\fR. It only reports modules
that the file loads directly or are in the import lists for parent
or base.
.PP
The module can handle the conventional inclusion of modules with either
\&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR as the statement:
.PP
.Vb 2
\&        use Foo;
\&        require Foo;
\&
\&        use Foo 1.23;
\&        use Foo qw(this that);
.Ve
.PP
It now finds \f(CW\*(C`require\*(C'\fR as an expression, which is useful to lazily
load a module once (and may be faster):
.PP
.Vb 4
\&        sub do_something {
\&                state $rc = require Foo;
\&                ...
\&                }
.Ve
.PP
Additionally, it finds module names used with \f(CW\*(C`parent\*(C'\fR and \f(CW\*(C`base\*(C'\fR,
either of which establish an inheritance relationship:
.PP
.Vb 2
\&        use parent qw(Foo);
\&        use base qw(Foo);
.Ve
.PP
In the case of namespaces found in \f(CW\*(C`base\*(C'\fR or \f(CW\*(C`parent\*(C'\fR, the value of
the \f(CW\*(C`direct\*(C'\fR method is false. In all other cases, it is true. You
can then skip those namespaces:
.PP
.Vb 3
\&        my $details = $extor\->get_modules_with_details( $file );
\&        foreach my $detail ( @$details ) {
\&                next unless $detail\->direct;
\&
\&                ...
\&                }
.Ve
.PP
This module does not discover runtime machinations to load something,
such as string evals:
.PP
.Vb 1
\&        eval "use Foo";
\&
\&        my $bar = \*(AqBar\*(Aq;
\&        eval "use $bar";
.Ve
.PP
If you want that, you might consider Module::ExtractUse (a confusingly
similar name).
.IP new 4
.IX Item "new"
Makes an object. The object doesn't do anything just yet, but you need
it to call the methods.
.IP init 4
.IX Item "init"
Set up the object. You shouldn't need to call this yourself.
.IP "get_modules( FILE )" 4
.IX Item "get_modules( FILE )"
Returns a list of namespaces explicity use-d in FILE. Returns the
empty list if the file does not exist or if it can't parse the file.
.Sp
Each used namespace is only in the list even if it is used multiple
times in the file. The order of the list does not correspond to
anything so don't use the order to infer anything.
.IP "get_modules_with_details( FILE )" 4
.IX Item "get_modules_with_details( FILE )"
Returns a list of hash references, one reference for each namespace
explicitly use-d in FILE. Each reference has keys for:
.Sp
.Vb 5
\&        namespace \- the namespace, always defined
\&        version   \- defined if a module version was specified
\&        imports   \- an array reference to the import list
\&        pragma    \- true if the module thinks this namespace is a pragma
\&        direct    \- false if the module name came from parent or base
.Ve
.Sp
Each used namespace is only in the list even if it is used multiple
times in the file. The order of the list does not correspond to
anything so don't use the order to infer anything.
.IP error 4
.IX Item "error"
Return the error from the last call to \f(CW\*(C`get_modules\*(C'\fR.
.SH "TO DO"
.IX Header "TO DO"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Module::ScanDeps, Module::Extract
.SH "SOURCE AVAILABILITY"
.IX Header "SOURCE AVAILABILITY"
The source code is in Github:
.PP
.Vb 1
\&        https://github.com/briandfoy/module\-extract\-use
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
brian d foy, \f(CW\*(C`<briandfoy@pobox.com>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright © 2008\-2024, brian d foy \f(CW\*(C`<briandfoy@pobox.com>\*(C'\fR. All rights reserved.
.PP
This project is under the Artistic License 2.0.