Perl::Critic::Policy::Subroutines::ProhibitUnusedPrivateSubroutines3pm

Affiliation

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

Overview

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.

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