blib/lib/Perl/Critic/Policy/Modules/RequireExplicitPackage.pm

filter: Statementstmt 100% 50 / 50 Branchbran 83.3% 15 / 18 Conditioncond 83.3% 5 / 6 MC/DCmcdc 75.0% 3 / 4 Subroutinesub 100% 14 / 14 Podpod 85.7% 6 / 7 totaltotal 93.9% 93 / 99 CC 13 SCAR 13.5
CC
13
Cov
95%
violates
7.0
_is_statement_of_interest
6.1
prepare_to_scan_document
2.0
CRAP 3.9
« blib/lib/Perl/Critic/Policy/Variables/ProhibitPackageVars.pm ↑ Summary blib/lib/Perl/Critic/Policy/ClassHierarchies/ProhibitOneArgBless.pm »
1 package Perl::Critic::Policy::Modules::RequireExplicitPackage;
2  
3 40 ▶use 5.010001;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 40 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 40 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 40 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 40 ▶use Perl::Critic::Utils qw{ :booleans :severities :classification };
Subroutine BEGIN: called CC=1 SCAR=0.0
9 40 ▶use parent 'Perl::Critic::Policy';
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 40 our $VERSION = '1.150';
12  
13 #-----------------------------------------------------------------------------
14  
15 40 Readonly::Scalar my $EXPL => q{Violates encapsulation};
16 40 Readonly::Scalar my $DESC => q{Code not contained in explicit package};
17  
18 #-----------------------------------------------------------------------------
19  
20 sub supported_parameters {
21 return (
22 {
23 92 ▶ name => 'exempt_scripts',
Subroutine supported_parameters: called CC=1 SCAR=0.0
Pod undocumented
24 description => q{Don't require programs to contain a package statement.},
25 default_string => '1',
26 behavior => 'boolean',
27 },
28 {
29 name => 'allow_import_of',
30 description => q{Allow the specified modules to be imported outside a package},
31 behavior => 'string list',
32 },
33 );
34 }
35  
36 80 ▶sub default_severity { return $SEVERITY_HIGH }
Subroutine default_severity: called CC=1 SCAR=0.0
Pod documented
37 74 ▶sub default_themes { return qw( core bugs ) }
Subroutine default_themes: called CC=1 SCAR=0.0
Pod documented
38 32 ▶sub applies_to { return 'PPI::Document' }
Subroutine applies_to: called CC=1 SCAR=0.0
Pod documented
39  
40 36 ▶sub default_maximum_violations_per_document { return 1; }
Subroutine default_maximum_violations_per_document: called CC=1 SCAR=0.0
Pod documented
41  
42 #-----------------------------------------------------------------------------
43  
44 sub prepare_to_scan_document {
45 33 ▶ my ( $self, $document ) = @_;
Subroutine prepare_to_scan_document: called CC=2 SCAR=7.1
Pod documented
46  
47 33 ▶ return ! $self->{_exempt_scripts} || $document->is_module();
Condition66%2/3
!$self->{'_exempt_scripts'} || $document->is_module
l!l&&r!l&&!r
0321
MC/DC50%1/2
!$self->{'_exempt_scripts'} || $document->is_module
!$self->{'_exempt_scripts'} $document->is_module
Truth table66%2/3
not(A) || B
A= !$self->{'_exempt_scripts'}B= $document->is_module
ABresult
1X1
011
000
48 }
49  
50 sub violates {
51 32 ▶ my ( $self, $elem, $doc ) = @_;
Subroutine violates: called CC=7 SCAR=19.5
Pod documented
52  
53 # Find the first 'package' statement
54 32 my $package_stmnt = $doc->find_first( 'PPI::Statement::Package' );
55 32 ▶ my $package_line = $package_stmnt ? $package_stmnt->location()->[0] : undef;
Branch: 1 branch
BranchTrueFalseTotal
$package_stmnt ? : 29 3 32
56  
57 # Find all statements that aren't 'package' statements
58 32 my $stmnts_ref = $doc->find( 'PPI::Statement' );
59 32 ▶ return if !$stmnts_ref;
Branch: 1 branch
BranchTrueFalseTotal
unless $stmnts_ref 2 30 32
60 my @non_packages = grep {
61 291 $self->_is_statement_of_interest( $_ )
62 30 } @{$stmnts_ref};
63 30 ▶ return if !@non_packages;
Branch: 1 branch
BranchTrueFalseTotal
unless @non_packages 0 30 30
64  
65 # If the 'package' statement is not defined, or the other
66 # statements appear before the 'package', then it violates.
67  
68 30 my @viols;
69 30 for my $stmnt ( @non_packages ) {
70 262 my $stmnt_line = $stmnt->location()->[0];
71 262 ▶ if ( (! defined $package_line) || ($stmnt_line < $package_line) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $package_line or $stmnt_line < $package_line) 5 257 262
Condition100%3/3
not defined $package_line or $stmnt_line < $package_line
l!l&&r!l&&!r
23257
MC/DC100%2/2
not defined $package_line or $stmnt_line < $package_line
not defined $package_line $stmnt_line < $package_line
Truth table100%3/3
not(A) or B
A= not defined $package_lineB= $stmnt_line < $package_line
ABresult
1X1
011
000
72 5 push @viols, $self->violation( $DESC, $EXPL, $stmnt );
73 }
74 }
75  
76 30 return @viols;
77 }
78  
79 sub _is_statement_of_interest {
80 291 ▶ my ( $self, $elem ) = @_;
Subroutine _is_statement_of_interest: called CC=6 SCAR=18.0
81  
82 291 ▶ $elem
Branch: 1 branch
BranchTrueFalseTotal
$elem or return $Perl::Critic::Policy::Modules::RequireExplicitPackage::FALSE 0 291 291
83 or return $FALSE;
84  
85 291 ▶ $elem->isa( 'PPI::Statement::Package' )
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Statement::Package") and return $Perl::Critic::Policy::Modules::RequireExplicitPackage::FALSE 29 262 291
86 and return $FALSE;
87  
88 262 ▶ if ( $elem->isa( 'PPI::Statement::Include' ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($elem->isa("PPI::Statement::Include")) 59 203 262
89 59 ▶ if ( my $module = $elem->module() ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $module = $elem->module) 57 2 59
90 57 ▶ $self->{_allow_import_of}{$module}
Branch: 1 branch
BranchTrueFalseTotal
$self->{"_allow_import_of"}{$module} and return $Perl::Critic::Policy::Modules::RequireExplicitPackage::FALSE 0 57 57
91 and return $FALSE;
92 }
93 }
94  
95 262 return $TRUE;
96 }
97  
98 40 1;
99  
100 __END__
101  
102 #-----------------------------------------------------------------------------
103  
104 =pod
105  
106 =head1 NAME
107  
108 Perl::Critic::Policy::Modules::RequireExplicitPackage - Always make the C<package> explicit.
109  
110  
111 =head1 AFFILIATION
112  
113 This Policy is part of the core L<Perl::Critic|Perl::Critic>
114 distribution.
115  
116  
117 =head1 DESCRIPTION
118  
119 In general, the first statement of any Perl module or library should
120 be a C<package> statement. Otherwise, all the code that comes before
121 the C<package> statement is getting executed in the caller's package,
122 and you have no idea who that is. Good encapsulation and common
123 decency require your module to keep its innards to itself.
124  
125 There are some valid reasons for not having a C<package> statement at
126 all. But make sure you understand them before assuming that you
127 should do it too.
128  
129 The maximum number of violations per document for this policy defaults
130 to 1.
131  
132  
133  
134 =head1 CONFIGURATION
135  
136 As for programs, most people understand that the default package is
137 C<main>, so this Policy doesn't apply to files that begin with a perl
138 shebang. If you want to require an explicit C<package> declaration in
139 all files, including programs, then add the following to your
140 F<.perlcriticrc> file
141  
142 [Modules::RequireExplicitPackage]
143 exempt_scripts = 0
144  
145 Some users may find it desirable to exempt the load of specific modules
146 from this policy. For example, Perl does not support Unicode module
147 names because of portability problems. Users who are not concerned about
148 this and intend to use C<UTF-8> module names will need to specify
149 C<use utf8;> before the package declaration. To do this, add the
150 following to your F<.perlcriticrc> file
151  
152 [Modules::RequireExplicitPackage]
153 allow_import_of = utf8
154  
155 The C<allow_import_of> configuration option takes multiple module names,
156 separated by spaces.
157  
158  
159 =head1 IMPORTANT CHANGES
160  
161 This policy was formerly called C<ProhibitUnpackagedCode> which
162 sounded a bit odd. If you get lots of "Cannot load policy module"
163 errors, then you probably need to change C<ProhibitUnpackagedCode> to
164 C<RequireExplicitPackage> in your F<.perlcriticrc> file.
165  
166  
167 =head1 AUTHOR
168  
169 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
170  
171  
172 =head1 COPYRIGHT
173  
174 Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved.
175  
176 This program is free software; you can redistribute it and/or modify
177 it under the same terms as Perl itself. The full text of this license
178 can be found in the LICENSE file included with this module.
179  
180 =cut
181  
182 # Local Variables:
183 # mode: cperl
184 # cperl-indent-level: 4
185 # fill-column: 78
186 # indent-tabs-mode: nil
187 # c-indentation-style: bsd
188 # End:
189 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/Policy/Variables/ProhibitPackageVars.pm ↑ Summary blib/lib/Perl/Critic/Policy/ClassHierarchies/ProhibitOneArgBless.pm »