Perl::...::Utils(3pm)

✨ NAME ✨

Perl::Critic::StricterSubs::Utils — bestie, it's a lil grab-bag of helper subs 🫶

(also, for the record, this page lives in the User Contributed Perl Documentation, and the manual name is literally Perl::...::Utils(3pm) — yes, the dots are doing their own thing, we respect it 💅)

---

🌸 AFFILIATION 🌸

This module is part of Perl::Critic::StricterSubs. It's one of the girlies in that distro, no cap.

---

💖 DESCRIPTION 💖

So this module holds utility methods that are shared by other modules in the Perl::Critic::StricterSubs distro. That's the whole vibe — it's the group chat the other modules text in.

Real talk though: until this distro becomes more mature, the author would discourage you from using these subs outside of this distro. Like, it's giving "not ready for the public yet", so keep it in the family for now, okay? 🙈

---

🎀 IMPORTABLE SUBS 🎀

Okay here's the whole roster, one by one, every single one of them, we are not skipping anybody ✨

• parse_quote_words( $qw_elem ) — grabs the words out of a PPI::Token::Quotelike::Words. That's it, that's the job 🍓
• parse_simple_list( $list_node ) — hands you back the string literals from a PPI::Structure::List.
• parse_literal_list( @nodes ) — returns the string literals contained anywhere in a collection of PPI::Nodes. Anywhere, bestie, it will go find them 🔥
• find_declared_subroutine_names( $doc ) — gives you a list of the names for all the subroutines that are declared in the document. The package will be stripped from the name. Also, a TODO: give examples of what this will return for a given $doc.
• find_declared_constant_names( $doc ) — returns a list of the names for all the constants that were declared in the document using the "constant" pragma. At the moment, only these styles of declaration are supported:

use constant 'FOO' => 42;  #with quotes, no parens
use constant  BAR  => 27;  #no quotes, no parens
use constant (BAZ  => 98); #no quotes, with parens

Multiple declarations per pragma are not supported at all, like zero, nada:

use constant {WANGO => 1, TANGO => 2};  #no love here.

#no love here. — the manpage said it, not me 😭

• find_imported_subroutine_names( $doc ) — returns a list of the names of all subroutines that are imported into the document via use MODULE LIST;. The leading ampersand sigil will be stripped. And yep, another TODO: give examples of what this will return for a given $doc.
• find_subroutine_calls( $doc ) — returns a list of PPI::Elements, where each one is the bareword name of a static subroutine invocation. If the subroutine call is fully-qualified the package will still be attached to the name. In all cases, the leading sigil will be removed. (And, you guessed it — TODO: give examples of what this will return for a given $doc.)
• find_exported_subroutine_names( $doc ) — returns a list of the names of each subroutine that is marked for exportation via @EXPORT or @EXPORT_OK. Heads up bestie: %EXPORT_TAGS are not supported here. TODO: give examples of what this will return for a given $doc.
• get_package_names_from_include_statements( $doc ) — returns a list of module names referred to with a bareword in an include statement. This covers all include statements, such as:

use Foo;
require Foo;

sub load_foo {
   require Foo if $condition;
}

eval{ require Foo };

INIT {
   require Foo;
}

But it does not cover these, and it said so with its whole chest:

require "Foo.pm";
eval { require $foo };

• get_package_names_from_package_statements( $doc ) — returns a list of all the namespaces from all the packages statements that appear in the document. Every single one 👑
• get_include_statements( $doc ) — returns a list of PPI::Statement::Include objects that appear in the document.
• "find_exported_sub_names( $doc, @export_types )" — returns a list of subroutines which are exported via the specified export types. If @export_types is empty, it defaults to qw{ @EXPORT, @EXPORT_OK }.

Subroutine names are returned as in get_all_subs_from_list_of_symbols().

• get_all_subs_from_list_of_symbols( @symbols ) — returns a list of all the input symbols which could be subroutine names.

Subroutine names are considered to be those symbols that don't have scalar, array, hash, or glob sigils. Any subroutine sigils are stripped off; i.e. &foo will be returned as "foo". Slay, sigil removal 💅

---

🦋 SEE ALSO 🦋

• Exporter

---

💜 AUTHOR 💜

Jeffrey Ryan Thalhammer <thaljef@cpan.org> — icon, legend, wrote the thing 🌈

---

👑 COPYRIGHT 👑

Copyright 2007-2024 Jeffrey Ryan Thalhammer and Andy Lester

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.

---

okay and that's the whole page, you read all of it, I'm so proud 🥹 This manual page came to you via perl v5.42.0, dated 2025-07-25, and honestly? iconic. periodt 💅✨