Perl::...outines(3pm)

✨ hiii bestie ✨ welcome to a User Contributed Perl Documentation page — the manual label is the truncated-looking Perl::...outines(3pm), and the star of the show is Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines. Buckle up. 💅

💖 NAME 💖

• Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines — Prevent unused private subroutines.

🫶 AFFILIATION 🫶

This Policy is part of the core Perl::Critic distribution. 👑

💅 DESCRIPTION 💅

By convention, Perl authors (like authors in many other languages) indicate private methods and variables by inserting a leading underscore before the identifier. This policy catches such subroutines which are not used in the file which declares them. 🕵️‍♀️

Now, what counts as a “use”? This module defines a 'use' of a subroutine as:

• a subroutine or method call to it (other than from inside the subroutine itself),
• a reference to it (i.e. my $foo = \&_foo),
• a goto to it outside the subroutine itself (i.e. goto &_foo),
• or the use of the subroutine’s name as an even-numbered argument to use overload.

🎀 CONFIGURATION 🎀

You can define what a private subroutine name looks like by specifying a regular expression for the private_name_regex option in your .perlcriticrc:

[Subroutines::ProhibitUnusedPrivateSubroutines]
private_name_regex = _(?!_)\w+

The above example is a way of saying that subroutines that start with a double underscore are not considered to be private. (Perl::Critic, in its implementation, uses leading double underscores to indicate a distribution-private subroutine -- one that is allowed to be invoked by other Perl::Critic modules, but not by anything outside of Perl::Critic.) 🌸

You can configure additional subroutines to accept by specifying them in a space-delimited list to the allow option:

[Subroutines::ProhibitUnusedPrivateSubroutines]
allow = _bar _baz

These are added to the default list of exemptions from this policy. So the above allows sub _bar {} and sub _baz {}, even if they are not referred to in the module that defines them. 🎀

You can allow a whole class or subroutine names by defining a regular expression that matches allowed names.

[Subroutines::ProhibitUnusedPrivateSubroutines]
allow_name_regex = _build_\w+

You can configure this policy not to check private subroutines declared in a file that uses one or more particular named modules. This allows you to, for example, exclude unused private subroutine checking in classes that are roles. 🌈

[Subroutines::ProhibitUnusedPrivateSubroutines]
skip_when_using = Moose::Role Moo::Role Role::Tiny

🦋 HISTORY 🦋

This policy is derived from Perl::Critic::Policy::Subroutines::ProtectPrivateSubs, which looks at the other side of the problem. 🔍

💀 BUGS 💀

Okay, known bugs and caveats, no cap:

Does not forbid sub Foo::_foo{} because it does not know (and can not assume) what is in the Foo package. 😭

Does not respect the scope caused by multiple packages in the same file. For example a file:

package Foo;
sub _is_private { print "A private sub!"; }

package Bar;
_is_private();

Will not trigger a violation even though Foo::_is_private is not called. Similarly, skip_when_using currently works on a file level, not on a package scope level. 💀

🌈 SEE ALSO 🌈

Perl::Critic::Policy::Subroutines::ProtectPrivateSubs.

👑 AUTHOR 👑

Chris Dolan <cdolan@cpan.org> 🫶

⭐ COPYRIGHT ⭐

Copyright (c) 2009-2021 Thomas R. Wyant, III. 👑

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 that’s the whole page bestie — every detail is here, fr fr. 💖 This one’s from perl v5.42.0, dated 2024-10-23, with the footer label Perl::...outines(3pm). bye! 🎀✨