oracular (3) Module::Extract::Use.3pm.gz

NAME

       Module::Extract::Use - Discover the modules a module explicitly uses

SYNOPSIS

               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\n",
                               $detail->module, $detail->version,
                               join ' ', @{ $detail->imports }
                       }

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 "eval "require $class"". It only reports modules
       that the file loads directly or are in the import lists for parent or base.

       The module can handle the conventional inclusion of modules with either "use" or "require" as the
       statement:

               use Foo;
               require Foo;

               use Foo 1.23;
               use Foo qw(this that);

       It now finds "require" as an expression, which is useful to lazily load a module once (and may be
       faster):

               sub do_something {
                       state $rc = require Foo;
                       ...
                       }

       Additionally, it finds module names used with "parent" and "base", either of which establish an
       inheritance relationship:

               use parent qw(Foo);
               use base qw(Foo);

       In the case of namespaces found in "base" or "parent", the value of the "direct" method is false. In all
       other cases, it is true. You can then skip those namespaces:

               my $details = $extor->get_modules_with_details( $file );
               foreach my $detail ( @$details ) {
                       next unless $detail->direct;

                       ...
                       }

       This module does not discover runtime machinations to load something, such as string evals:

               eval "use Foo";

               my $bar = 'Bar';
               eval "use $bar";

       If you want that, you might consider Module::ExtractUse (a confusingly similar name).

       new Makes an object. The object doesn't do anything just yet, but you need it to call the methods.

       init
           Set up the object. You shouldn't need to call this yourself.

       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.

           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.

       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:

                   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

           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.

       error
           Return the error from the last call to "get_modules".

TO DO

SEE ALSO

       Module::ScanDeps, Module::Extract

SOURCE AVAILABILITY

       The source code is in Github:

               https://github.com/briandfoy/module-extract-use

AUTHOR

       brian d foy, "<briandfoy@pobox.com>"

COPYRIGHT AND LICENSE

       Copyright © 2008-2024, brian d foy "<briandfoy@pobox.com>". All rights reserved.

       This project is under the Artistic License 2.0.