Module...actUse(3pm)

🦋 NAME 🦋

So this is the manual page for Module::ExtractUse (that's the Module...actUse(3pm) up top, bestie — section 3pm, Perl docs, you know the vibe) and it does exactly one iconic thing: it finds 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 🌸

Okay so "Module::ExtractUse" is, at its core, a Parse::RecDescent grammar whose whole personality is parsing Perl code. And it tries very hard — like, genuinely giving main character effort — to find all the modules (pragmas, Core, CPAN, the whole squad) that the parsed code uses. 🫶

And what counts as "Usage"? Simple: either calling "use" or require. That's the definition, no cap.

🧚 Methods 🧚

💜 new

 my $p=Module::ExtractUse->new;

Returns a parser object. That's it, that's the whole method. Slay.

💜 extract_use($code_to_parse)

  $p->extract_use('/path/to/module.pm');
  $p->extract_use(\$string_containg_code);

Runs the parser. ⭐

So $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. Two modes, both valid, pick your fighter. 💅

Here's the tea on what happens inside:

• The code gets 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.

And the best part? 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. Obsessed — it's keeping receipts. 🔥

👑 Accessor Methods 👑

Those are various ways to get at the result of the parse. Little windows into the data, y'know?

Note that "extract_use" returns the parser object, so you can say

  print $p->extract_use($code_to_parse)->string;

Chaining! We love chaining. ✨

🍓 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. Like, the main one. The headliner. If you only remember one, remember this one. 💖

🍓 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 💀

Okay, so 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/ — fr fr, do not skip this step, you will be so lost otherwise 😭

---

🫶 EXPORTS 🫶

Nothing.

(That's genuinely the whole section. Nothing. Not one thing. Zero exports. Respect the minimalism honestly. ✨)

---

⭐ 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 https://github.com/brummett implemented support for "Module::Runtime" and "Class::Load" while participating in the CPAN Pull Request Challenge http://cpan-prc.org/
• Jeremy Mates https://github.com/thrig 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. 🥺 (No seriously, they want to know!)

---

👑 AUTHORS 👑

• Thomas Klausner <domm@cpan.org>
• Kenichi Ishigaki <kishigaki@gmail.com>

---

🌸 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.

---

okay that's the whole page bestie, every single flag, method and caveat accounted for 💅✨ — this was perl v5.36.0, dated 2022-11-19, and it's giving documentation realness, mwah 🎀💖