Perl::...dImport(3pm)

🦋 NAME 🦋

Perl::...dImport — bestie, that's the cute lil' manpage name up top (yes it's the truncated version, the real star of the show is the policy below 💅). What it does: TooMuchCode::ProhibitUnusedImport — find unused imports. Periodt. 🔍

---

💖 DESCRIPTION 💖

Okay so first things first, what even is an "import"? An import is a subroutine brought to you by a use statement. That's it, that's the whole vibe. 🎀

Now, from the documentation of use, there are like, several forms of calling use. This policy scans for these two forms:

use Module VERSION LIST
use Module LIST

...and honestly? Only the one with LIST written in qw(). The rest can stay home. 🙈

Conventionally, the LIST after use Module is known as arguments, and conventionally, when it's written with qw(), that LIST gets treated as an import list — which is, like, a list of symbols that becomes available in the current namespace. Slay. ✨

For example, the word baz in the following statement is one of such:

use Foo qw( baz );

Symbols in the import list are often subroutine names or variable names. And if they're not used in the following program? They do not need to be imported, no cap. 🚫

Now, an experienced perl programmer would know that everything I just said is only true by convention. But here's the tea: there are so many modules on CPAN that already follow this convention. Which is a good one to follow, and yes, I recommend you follow it. 🫶

This policy checks only import lists written in qw(). Other forms are ignored — or rather, they're too complicated to be correctly supported. Not a skill issue, just reality. 💀

The syntax of the Importer module is also supported, but only the ones with qw() at the end:

use Importer 'Foo' => qw( baz );

Modules with non-trivial forms of arguments may have nothing to do with symbol-importing at all. But it might be used with a qw() LIST at the end. Should you wish to do so, you may choose to let perlcritic ignore certain modules by setting the ignored_modules in .perlcriticrc. For example:

[TooMuchCode::ProhibitUnusedImport]
ignored_modules = Git::Sub Regexp::Common

Alternatively, you may choose not to write the module arguments as a qw() list. Your call, main character. 👑

🌸 Moose Types 🌸

Moose Types can also be imported, but bestie, their symbols may not be used as-is. Instead, some other helper functions are generated with names based on the Type. For example:

use My::Type::Library::Numeric qw( PositiveInt );
use My::Type::Library::String qw( LowerCaseStr );

my $foo = 'Bar';
my $ok  = is_PositiveInt($foo);
my $lower = to_LowerCaseStr($foo);

So the module My::Type::Library::Numeric exports is_PositiveInt as well as PositiveInt. And while PositiveInt is not directly used in the following code, it should be considered as being used. Same deal for LowerCaseStr. It's giving "used by association" 💅

When importing from a Type library, subroutines named like is_* and to_* are not in the import list, but they are also imported. Sneaky lil' helpers. 🧚

By default, the following modules are treated as Type libraries:

• MooseX::Types::Moose
• MooseX::Types::Common::Numeric
• MooseX::Types::Common::String

The list can be grown by including your module names to the moose_type_modules in the .perlcriticrc:

[TooMuchCode::ProhibitUnusedImport]
moose_type_modules = My::Type::Library::Numeric My::Type::Library::String

---

And that's the whole page, babe 🎀 — this was perl v5.36.0, dated 2023-10-05, filed under Perl::...dImport(3pm). Go forth and clean up those unused imports, you absolute icon. 💖✨🦋