--- name: "Module::ExtractUse" section: "3pm" platform: "linux" package: "libmodule-extractuse-perl" version: "0.344-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Module::ExtractUse" --- # Module::ExtractUse(3pm) Find out what modules are used ## NAME Module::ExtractUse - Find out what modules are used ## VERSION version 0.344 ## SYNOPSIS ``` use Module::ExtractUse; # get a parser my $p=Module::ExtractUse->new; # parse from a file $p->extract_use('/path/to/module.pm'); # or parse from a ref to a string in memory $p->extract_use(\$string_containg_code); # use some reporting methods my $used=$p->used; # $used is a HASHREF print $p->used('strict') # true if code includes 'use strict' my @used=$p->array; my $used=$p->string; # you can get optional modules, that is used in eval context, in the same style my $used=$p->used_in_eval; # $used is a HASHREF print $p->used_in_eval('strict') # true if code includes 'use strict' my @used=$p->array_in_eval; my $used=$p->string_in_eval; # and mandatory modules, that is used out of eval context, in the same style, also. my $used=$p->used_out_of_eval; # $used is a HASHREF print $p->used_out_of_eval('strict') # true if code includes 'use strict' my @used=$p->array_out_of_eval; my $used=$p->string_out_of_eval; ``` ## DESCRIPTION `"Module::ExtractUse"` is basically a Parse::RecDescent grammar to parse Perl code. It tries very hard to find all modules (whether pragmas, Core, or from CPAN) used by the parsed code. "Usage" is defined by either calling `"use"` or `"require"`. ### Methods *new* ``` my $p=Module::ExtractUse->new; ``` Returns a parser object *extract\_use($code\_to\_parse)* ``` $p->extract_use('/path/to/module.pm'); $p->extract_use(\$string_containg_code); ``` Runs the parser. `$code_to_parse` can be either a SCALAR, in which case `"Module::ExtractUse"` tries to open the file specified in `$code_to_parse`. Or a reference to a SCALAR, in which case `"Module::ExtractUse"` assumes the referenced scalar contains the source code. The code will be stripped from POD (using Pod::Strip) and split on ";" (semicolon). Each statement (i.e. the stuff between two semicolons) is checked by a simple regular expression. If the statement contains either 'use' or 'require', the statement is handed over to the parser, who then tries to figure out, **what** is used or required. The results will be saved in a data structure that you can examine afterwards. You can call `"extract_use"` several times on different files. It will count how many files were examined and how often each module was used. ### Accessor Methods Those are various ways to get at the result of the parse. Note that `"extract_use"` returns the parser object, so you can say ``` print $p->extract_use($code_to_parse)->string; ``` *used* ``` my $used=$p->used; # $used is a HASHREF print $p->used('strict') # true if code includes 'use strict' ``` If called without an argument, returns a reference to a hash of all used modules. Keys are the names of the modules, values are the number of times they were used. If called with an argument, looks up the value of the argument in the hash and returns the number of times it was found during parsing. This is the preferred accessor. *used\_in\_eval* Same as `"used"`, except for considering in-eval-context only. *used\_out\_of\_eval* Same as `"used"`, except for considering NOT-in-eval-context only. *required* Same as `"used"`, except for considering 'require'd modules only. *required\_in\_eval* Same as `"required"`, except for considering in-eval-context only. *required\_out\_of\_eval* Same as `"required"`, except for considering NOT-in-eval-context only. *noed* Same as `"used"`, except for considering 'no'ed modules only. *noed\_in\_eval* Same as `"noed"`, except for considering in-eval-context only. *noed\_out\_of\_eval* Same as `"noed"`, except for considering NOT-in-eval-context only. *string* ``` print $p->string($seperator) ``` Returns a sorted string of all used modules, joined using the value of `$seperator` or using a blank space as a default; Module names are sorted by ascii value (i.e by `"sort"`) *string\_in\_eval* Same as `"string"`, except for considering in-eval-context only. *string\_out\_of\_eval* Same as `"string"`, except for considering NOT-in-eval-context only. *array* ``` my @array = $p->array; ``` Returns an array of all used modules. *array\_in\_eval* Same as `"array"`, except for considering in-eval-context only. *array\_out\_of\_eval* Same as `"array"`, except for considering NOT-in-eval-context only. *arrayref* ``` my $arrayref = $p->arrayref; ``` Returns a reference to an array of all used modules. Surprise! *arrayref\_in\_eval* Same as `"array_ref"`, except for considering in-eval-context only. *arrayref\_out\_of\_eval* Same as `"array_ref"`, except for considering NOT-in-eval-context only. *files* Returns the number of files parsed by the parser object. ## RE-COMPILING THE GRAMMAR If - for some reasons - you need to alter the grammar, edit the file *grammar* and afterwards run: ``` perl -MParse::RecDescent - grammar Module::ExtractUse::Grammar ``` Make sure you're in the right directory, i.e. in *.../Module/ExtractUse/* ## EXPORTS Nothing. ## SEE ALSO Parse::RecDescent, Module::Extract::Use, Module::ScanDeps, Module::Info, Module::CPANTS::Analyse, Perl::PrereqScanner, Perl::PrereqScanner::Lite, Perl::PrereqScanner::NotQuiteLite ## CONTRIBUTORS - • Anthony Brummett \ implemented support for `"Module::Runtime"` and `"Class::Load"` while participating in the CPAN Pull Request Challenge \ - • Jeremy Mates \ fixed some documentation errors - • Jonathan Yu provided a nice script, `"example/extractuse.pl"` If I forgot to mention your contribution, please send an email or open an issue / ticket. ## AUTHORS - • Thomas Klausner \ - • Kenichi Ishigaki \ ## COPYRIGHT AND LICENSE This software is copyright (c) 2014 - 2021 by Thomas Klausner. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.