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

filter: Statementstmt 91.6% 55 / 60 Branchbran 68.7% 22 / 32 Conditioncond 0.0% 0 / 7 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 100% 19 / 19 Podpod 80.0% 4 / 5 totaltotal 78.7% 100 / 127 CC 20 SCAR 19.0
CC
20
Cov
78%
_is_readonly_version
23.8
_is_version_declaration
6.6
_is_vars_version
3.1
CRAP 6.7
« blib/lib/Perl/Critic/OptionsProcessor.pm ↑ Summary blib/lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockMap.pm »
1 package Perl::Critic::Policy::Modules::RequireVersionVar;
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 List::SomeUtils qw(any);
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 40 ▶use Perl::Critic::Utils qw{ :severities };
Subroutine BEGIN: called CC=1 SCAR=0.0
11 40 ▶use parent 'Perl::Critic::Policy';
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 40 our $VERSION = '1.150';
14  
15 #-----------------------------------------------------------------------------
16  
17 40 Readonly::Scalar my $DESC => q{No package-scoped "$VERSION" variable found}; ## no critic (RequireInterpolation)
18 40 Readonly::Scalar my $EXPL => [ 404 ];
19  
20 #-----------------------------------------------------------------------------
21  
22 91 ▶sub supported_parameters { return () }
Subroutine supported_parameters: called CC=1 SCAR=0.0
Pod undocumented
23 79 ▶sub default_severity { return $SEVERITY_LOW }
Subroutine default_severity: called CC=1 SCAR=0.0
Pod documented
24 86 ▶sub default_themes { return qw(core pbp readability) }
Subroutine default_themes: called CC=1 SCAR=0.0
Pod documented
25 31 ▶sub applies_to { return 'PPI::Document' }
Subroutine applies_to: called CC=1 SCAR=0.0
Pod documented
26  
27 #-----------------------------------------------------------------------------
28  
29 sub violates {
30 31 ▶ my ( $self, $elem, $doc ) = @_;
Subroutine violates: called CC=2 SCAR=6.9
Pod documented
31  
32 31 ▶ return if $doc->find_first( \&_is_version_declaration );
Branch: 1 branch
BranchTrueFalseTotal
if $doc->find_first(\&Perl::Critic::Policy::Modules::RequireVersionVar::_is_version_declaration) 27 4 31
33  
34 #If we get here, then no $VERSION was found
35 4 return $self->violation( $DESC, $EXPL, $doc );
36 }
37  
38 #-----------------------------------------------------------------------------
39  
40 sub _is_version_declaration { ## no critic (ArgUnpacking)
41 592 ▶ return 1 if _is_our_version(@_);
Subroutine _is_version_declaration: called CC=6 SCAR=18.8
Branch: 1 branch
BranchTrueFalseTotal
if _is_our_version(@_) 27 565 592
42 565 ▶ return 1 if _is_vars_version(@_);
Branch: 1 branch
BranchTrueFalseTotal
if _is_vars_version(@_) 0 565 565
43 565 ▶ return 1 if _is_package_version(@_);
Branch: 1 branch
BranchTrueFalseTotal
if _is_package_version(@_) 0 565 565
44 565 ▶ return 1 if _is_readonly_version(@_);
Branch: 1 branch
BranchTrueFalseTotal
if _is_readonly_version(@_) 0 565 565
45 565 ▶ return 1 if _is_package_argument_version(@_);
Branch: 1 branch
BranchTrueFalseTotal
if _is_package_argument_version(@_) 0 565 565
46 565 return 0;
47 }
48  
49 #-----------------------------------------------------------------------------
50  
51 sub _is_our_version {
52 592 ▶ my (undef, $elem) = @_;
Subroutine _is_our_version: called CC=3 SCAR=11.0
53 592 ▶ $elem->isa('PPI::Statement::Variable') || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Statement::Variable") or return 0 565 27 592
54 27 ▶ $elem->type() eq 'our' || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->type eq "our" or return 0 0 27 27
55 27 ▶ return any { $_ eq '$VERSION' } $elem->variables(); ## no critic (RequireInterpolation)
Subroutine __ANON__: called CC=1 SCAR=0.0
56 }
57  
58 #-----------------------------------------------------------------------------
59  
60 sub _is_vars_version {
61 565 ▶ my (undef, $elem) = @_;
Subroutine _is_vars_version: called CC=3 SCAR=11.4
62 565 ▶ $elem->isa('PPI::Statement::Include') || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Statement::Include") or return 0 510 55 565
63 55 ▶ $elem->pragma() eq 'vars' || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->pragma eq "vars" or return 0 55 0 55
64 0 return $elem =~ m{ \$VERSION }xms; #Crude, but usually works
65 }
66  
67 #-----------------------------------------------------------------------------
68  
69 sub _is_package_version {
70 565 ▶ my (undef, $elem) = @_;
Subroutine _is_package_version: called CC=2 SCAR=6.9
71 565 ▶ $elem->isa('PPI::Token::Symbol') || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Token::Symbol") or return 0 559 6 565
72 6 return $elem =~ m{ \A \$ \S+ ::VERSION \z }xms;
73 #TODO: ensure that it is in _this_ package!
74 }
75  
76 #-----------------------------------------------------------------------------
77  
78 sub _is_readonly_version {
79  
80 #---------------------------------------------------------------
81 # Readonly VERSION statements usually come in one of two forms:
82 #
83 # Readonly our $VERSION = 1.0;
84 # Readonly::Scalar our $VERSION = 1.0;
85 #---------------------------------------------------------------
86  
87 565 ▶ my (undef, $elem) = @_;
Subroutine _is_readonly_version: called CC=7 SCAR=31.7
88 565 ▶ $elem->isa('PPI::Token::Symbol') || return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Token::Symbol") or return 0 559 6 565
89 6 ▶ return 0 if $elem !~ m{ \A \$VERSION \z }xms;
Branch: 1 branch
BranchTrueFalseTotal
unless $elem =~ / \A \$VERSION \z /msx 6 0 6
90  
91 0 ▶ my $psib = $elem->sprevious_sibling() || return 0;
Condition0%0/2
$elem->sprevious_sibling || (return 0)
l!l
00
MC/DC0%0/1
$elem->sprevious_sibling || (return 0)
$elem->sprevious_sibling
Truth table0%0/2
A
A= $elem->sprevious_sibling
Aresult
11
00
92 0 ▶ return 0 if $psib ne 'our';
Branch: 1 branch
BranchTrueFalseTotal
if $psib ne "our" 0 0 0
93  
94 0 ▶ my $ppsib = $psib->sprevious_sibling() || return 0;
Condition0%0/2
$psib->sprevious_sibling || (return 0)
l!l
00
MC/DC0%0/1
$psib->sprevious_sibling || (return 0)
$psib->sprevious_sibling
Truth table0%0/2
A
A= $psib->sprevious_sibling
Aresult
11
00
95 0 ▶ return $ppsib eq 'Readonly' || $ppsib eq 'Readonly::Scalar';
Condition0%0/3
$ppsib eq 'Readonly' || $ppsib eq 'Readonly::Scalar'
l!l&&r!l&&!r
000
MC/DC0%0/2
$ppsib eq 'Readonly' || $ppsib eq 'Readonly::Scalar'
$ppsib eq 'Readonly' $ppsib eq 'Readonly::Scalar'
Truth table0%0/3
A || B
A= $ppsib eq 'Readonly'B= $ppsib eq 'Readonly::Scalar'
ABresult
1X1
011
000
96 }
97  
98 #-----------------------------------------------------------------------------
99  
100 sub _is_package_argument_version {
101 565 ▶ my (undef, $elem) = @_;
Subroutine _is_package_argument_version: called CC=3 SCAR=11.0
102 565 ▶ $elem->isa( 'PPI::Statement::Package' ) or return 0;
Branch: 1 branch
BranchTrueFalseTotal
$elem->isa("PPI::Statement::Package") or return 0 537 28 565
103 # Perldoc for 5.12.3 documents the statement as
104 # package NAMESPACE VERSION
105 # with no comma, and the compiler in fact does not accept one.
106 28 ▶ my $ver = $elem->schild( 2 )
Branch: 1 branch
BranchTrueFalseTotal
my $ver = $elem->schild(2) or return 0 0 28 28
107 or return 0;
108 28 return $ver->isa( 'PPI::Token::Number' );
109 }
110  
111 40 1;
112  
113 __END__
114  
115 #-----------------------------------------------------------------------------
116  
117 =pod
118  
119 =head1 NAME
120  
121 Perl::Critic::Policy::Modules::RequireVersionVar - Give every module a C<$VERSION> number.
122  
123  
124 =head1 AFFILIATION
125  
126 This Policy is part of the core L<Perl::Critic|Perl::Critic>
127 distribution.
128  
129  
130 =head1 DESCRIPTION
131  
132 Every Perl file (modules, libraries, and programs) should have a
133 package-scoped C<$VERSION> variable. The C<$VERSION> allows clients to
134 insist on a particular revision of your file like this:
135  
136 use SomeModule 2.4; #Only loads version 2.4
137  
138 This Policy scans your file for any package variable named
139 C<$VERSION>. I'm assuming that you are using C<strict>, so you'll
140 have to declare it like one of these:
141  
142 our $VERSION = 1.0611;
143 $MyPackage::VERSION = 1.061;
144 use vars qw($VERSION);
145 use version; our $VERSION = qv(1.0611);
146  
147 Perl's version system does not recognize lexical variables such as
148  
149 my $VERSION = 1.0611;
150  
151 so they are not accepted by this policy.
152  
153 A common practice is to use the C<$Revision$> keyword to
154 automatically define the C<$VERSION> variable like this:
155  
156 our ($VERSION) = '$Revision$' =~ m{ \$Revision: \s+ (\S+) }x;
157  
158  
159 =head1 CONFIGURATION
160  
161 This Policy is not configurable except for the standard options.
162  
163  
164 =head1 NOTES
165  
166 Conway recommends using the C<version> pragma instead of raw numbers
167 or 'v-strings.' However, this Policy only insists that the
168 C<$VERSION> be defined somehow. I may try to extend this in the
169 future.
170  
171  
172 =head1 TO DO
173  
174 Add check that C<$VERSION> is independently evaluatable. In
175 particular, prohibit this:
176  
177 our $VERSION = $Other::Module::VERSION;
178  
179 This doesn't work because PAUSE and other tools literally copy your
180 version declaration out of your module and evaluates it in isolation,
181 at which point there's nothing in C<Other::Module>, and so the
182 C<$VERSION> is undefined.
183  
184  
185 =head1 AUTHOR
186  
187 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
188  
189  
190 =head1 COPYRIGHT
191  
192 Copyright (c) 2005-2021 Imaginative Software Systems. All rights reserved.
193  
194 This program is free software; you can redistribute it and/or modify
195 it under the same terms as Perl itself. The full text of this license
196 can be found in the LICENSE file included with this module.
197  
198 =cut
199  
200 # Local Variables:
201 # mode: cperl
202 # cperl-indent-level: 4
203 # fill-column: 78
204 # indent-tabs-mode: nil
205 # c-indentation-style: bsd
206 # End:
207 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/OptionsProcessor.pm ↑ Summary blib/lib/Perl/Critic/Policy/BuiltinFunctions/RequireBlockMap.pm »