1Perl::Critic::StricterSUusbesr(3C)ontributed Perl DocumePnetralt:i:oCnritic::StricterSubs(3)
2
3
4

NAME

6       Perl::Critic::StricterSubs - Perl::Critic plugin for stricter
7       subroutine checks
8

AFFILIATION

10       This module has no functionality, but instead contains documentation
11       for this distribution and acts as a means of pulling other modules into
12       a bundle.  All of the Policy modules contained herein will have an
13       "AFFILIATION" section announcing their participation in this grouping.
14

DESCRIPTION

16       As a dynamic language, Perl doesn't require you to define subroutines
17       until run-time.  Although this is a powerful feature, it can also be a
18       major source of bugs.  For example, you might mistype the name of a
19       subroutine, or call a subroutine from another module without including
20       that module or importing that subroutine.  And unless you have very
21       good test coverage, you might not know about these bugs until you have
22       already launched your code.
23
24       The Perl::Critic::Policy modules in this distribution are aimed at
25       reducing errors caused by invoking subroutines that are not defined.
26       Each Policy can be used separately.  But when applied together, they
27       enforce a specific and deliberate coding style that minimizes the
28       chance of writing code that makes calls to undefined subroutines.
29
30       This coding style will not appeal to everyone.  Some folks will surely
31       find this coding style to be too verbose or too restrictive.  In
32       particular, importing via Exporter tags and pattern matching is
33       purposely not supported.  But hopefully, these Policies will encourage
34       you to consciously consider the inherent trade-offs of your current
35       coding style.
36

LIMITATIONS

38       Perl::Critic is a static analyzer, so the Policies in this distro only
39       pertain to static subroutines.  That is, subroutine calls that
40       typically look like one of these:
41
42         foo();
43         Bar::baz( $string );
44         Quux->new( @args );
45
46       At present, Perl::Critic cannot not know the class ancestry of any
47       particular object reference.  Thus, the Policies in this distro do not
48       cover object methods, such as these:
49
50         $object->foo();
51
52       Still, it is difficult for Perl::Critic to know precisely which static
53       subroutines will be defined at run time.  Therefore, these Policies are
54       expected to report some false violations.  So you probably don't want
55       to use these Policies with Test::Perl::Critic or other frameworks that
56       expect 100% violation-free code.  Instead, I suggest using these
57       Policies with the perlcritic command to perform ad hoc analysis of your
58       code.
59

INCLUDED POLICIES

61       The following Policy modules are shipped in this distribution.  See the
62       documentation within each module for details on its specific behavior.
63
64   Perl::Critic::Policy::Modules::RequireExplicitInclusion
65       If you refer to symbols in another package, you must explicitly include
66       that module.  [Severity: 4]
67
68   Perl::Critic::Policy::Subroutines::ProhibitCallsToUndeclaredSubs
69       Unqualified subroutines must always be declared or explicitly imported
70       within the file. [Severity: 4]
71
72   Perl::Critic::Policy::Subroutines::ProhibitCallsToUnexportedSubs
73       Only allow calls to external subroutines that are named in @EXPORT or
74       @EXPORT_OK. [Severity: 4]
75
76   Perl::Critic::Policy::Subroutines::ProhibitExportingUndeclaredSubs
77       All subroutines named for @EXPORT or @EXPORT_OK must be defined in the
78       file.  [Severity: 4]
79
80   Perl::Critic::Policy::Subroutines::ProhibitQualifiedSubDeclarations
81       Do not declare subroutines with fully-qualified names [Severity: 3]
82

CONFIGURATION

84       After installing the "Perl-Critic-StricterSubs" distro, all the
85       included Policies available to the Perl::Critic engine.  The Policies
86       in this distro all belong to the "strictersubs" theme, so you can
87       disable all of them at once using either of these methods:
88
89         # In your .perlcriticrc file...
90         theme = not strictersubs
91
92         # With the perlcritic command-line...
93         $> perlcritic --theme='not stricter_subs' MyModule.pm
94
95       See "CONFIGURATION" in Perl::Critic section for more information about
96       configuring the Perl::Critic engine.
97
98       Each Policy in this distro may support additional configuration
99       settings that can be accessed through your .perlcriticrc file.  See the
100       perldoc in each Policy for more details.
101

ACKNOWLEDGEMENTS

103       DEVELOPMENT of the "Perl-Critic-StricterSubs" distribution was financed
104       by a grant from The Mathworks (<http://mathworks.com>).  The
105       Perl::Critic team sincerely thanks The Mathworks for their generous
106       support of the Perl community and open-source software.
107

AUTHOR

109       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
110

112       Copyright (c) 2007-2022 Jeffrey Ryan Thalhammer.
113
114       This program is free software; you can redistribute it and/or modify it
115       under the same terms as Perl itself.  The full text of this license can
116       be found in the LICENSE file included with this module.
117
118
119
120perl v5.34.1                      2022-04-27     Perl::Critic::StricterSubs(3)
Impressum