blib/lib/Perl/Critic/Annotation.pm

filter: Statementstmt 95.5% 108 / 113 Branchbran 81.8% 36 / 44 Conditioncond 58.6% 17 / 29 MC/DCmcdc 31.5% 6 / 19 Subroutinesub 94.4% 17 / 18 Podpod 100% 8 / 8 totaltotal 83.1% 192 / 231 CC 34 SCAR 22.4
CC
34
Cov
87%
_init
18.6
_is_single_line_annotation_on_simple_statement
9.4
disables_policy
5.2
CRAP 9.4
« blib/lib/Perl/Critic/Policy/Variables/ProhibitLocalVars.pm ↑ Summary blib/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitLongChainsOfMethodCalls.pm »
1 package Perl::Critic::Annotation;
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  
7 40 ▶use Carp qw(confess);
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 40 ▶use Perl::Critic::PolicyFactory;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 40 ▶use Perl::Critic::Utils qw(:characters hashify);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 40 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 #-----------------------------------------------------------------------------
14  
15 40 our $VERSION = '1.150';
16  
17 40 Readonly::Scalar my $LAST_ELEMENT => -1;
18  
19 #=============================================================================
20 # CLASS methods
21  
22 sub create_annotations {
23 89 ▶ my ($class, $doc) = @_;
Subroutine create_annotations: called CC=3 SCAR=11.0
Pod documented
24  
25 89 my @annotations;
26 89 ▶ my $comment_elements_ref = $doc->find('PPI::Token::Comment') || return;
Condition100%2/2
$doc->find('PPI::Token::Comment') || (return)
l!l
7910
MC/DC100%1/1
$doc->find('PPI::Token::Comment') || (return)
$doc->find('PPI::Token::Comment')
Truth table100%2/2
A
A= $doc->find('PPI::Token::Comment')
Aresult
11
00
27 79 my $annotation_rx = qr{\A (?: [#]! .*? )? \s* [#][#] \s* no \s+ critic}xms;
28 79 for my $annotation_element ( grep { m/$annotation_rx/smx } @{$comment_elements_ref} ) {
29 72 push @annotations, Perl::Critic::Annotation->new( -element => $annotation_element);
30 }
31  
32 79 return @annotations;
33 }
34  
35 #-----------------------------------------------------------------------------
36  
37 sub new {
38 72 ▶ my ($class, @args) = @_;
Subroutine new: called CC=1 SCAR=0.0
Pod documented
39 72 my $self = bless {}, $class;
40 72 $self->_init(@args);
41 72 return $self;
42 }
43  
44 #=============================================================================
45 # OBJECT methods
46  
47 sub _init {
48 72 ▶ my ($self, %args) = @_;
Subroutine _init: called CC=18 SCAR=29.2
49 72 ▶ my $annotation_element = $args{-element} || confess '-element argument is required';
Condition33%1/3
$args{'-element'} || confess('-element argument is required')
l!l&&r!l&&!r
7200
MC/DC0%0/2
$args{'-element'} || confess('-element argument is required')
$args{'-element'} confess('-element argument is required')
Truth table33%1/3
A || B
A= $args{'-element'}B= confess('-element argument is required')
ABresult
1X1
011
000
50 72 $self->{_element} = $annotation_element;
51  
52 72 my %disabled_policies = _parse_annotation( $annotation_element );
53 72 ▶ $self->{_disables_all_policies} = %disabled_policies ? 0 : 1;
Branch: 1 branch
BranchTrueFalseTotal
%disabled_policies ? : 40 32 72
54 72 $self->{_disabled_policies} = \%disabled_policies;
55  
56 # Grab surrounding nodes to determine the context.
57 # This determines whether the annotation applies to
58 # the current line or the block that follows.
59 72 my $annotation_line = $annotation_element->logical_line_number();
60 72 my $parent = $annotation_element->parent();
61 72 ▶ my $grandparent = $parent ? $parent->parent() : undef;
Branch: 1 branch
BranchTrueFalseTotal
$parent ? : 72 0 72
62  
63 # Handle case when it appears on the shebang line. In this
64 # situation, it only affects the first line, not the whole doc
65 72 ▶ if ( $annotation_element =~ m{\A [#]!}xms) {
Branch: 1 branch
BranchTrueFalseTotal
if ($annotation_element =~ /\A [#]!/msx) 2 70 72
66 2 $self->{_effective_range} = [$annotation_line, $annotation_line];
67 2 return $self;
68 }
69  
70 # Handle single-line usage on simple statements. In this
71 # situation, it only affects the line that it appears on.
72 70 ▶ if ( _is_single_line_annotation_on_simple_statement( $annotation_element )
Branch: 1 branch
BranchTrueFalseTotal
if (_is_single_line_annotation_on_simple_statement($annotation_element)) 35 35 70
73 ) {
74 35 $self->{_effective_range} = [$annotation_line, $annotation_line];
75 35 return $self;
76 }
77  
78 # Handle single-line usage on compound statements. In this
79 # situation -- um -- I'm not sure how this works, but it does.
80 35 ▶ if ( ref $parent eq 'PPI::Structure::Block' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $parent eq "PPI::Structure::Block") 11 24 35
81 11 ▶ if ( ref $grandparent eq 'PPI::Statement::Compound'
Branch: 1 branch
BranchTrueFalseTotal
if (ref $grandparent eq "PPI::Statement::Compound" or ref $grandparent eq "PPI::Statement::Sub") 11 0 11
Condition66%2/3
ref $grandparent eq "PPI::Statement::Compound" or ref $grandparent eq "PPI::Statement::Sub"
l!l&&r!l&&!r
830
MC/DC0%0/2
ref $grandparent eq "PPI::Statement::Compound" or ref $grandparent eq "PPI::Statement::Sub"
ref $grandparent eq "PPI::Statement::Compound" ref $grandparent eq "PPI::Statement::Sub"
Truth table66%2/3
A or B
A= ref $grandparent eq "PPI::Statement::Compound"B= ref $grandparent eq "PPI::Statement::Sub"
ABresult
1X1
011
000
82 || ref $grandparent eq 'PPI::Statement::Sub' ) {
83 11 ▶ if ( $parent->logical_line_number() == $annotation_line ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($parent->logical_line_number == $annotation_line) 6 5 11
84 6 my $grandparent_line = $grandparent->logical_line_number();
85 6 $self->{_effective_range} = [$grandparent_line, $grandparent_line];
86 6 return $self;
87 }
88 }
89 }
90  
91  
92 # Handle multi-line usage. This is either a "no critic" ..
93 # "use critic" region or a block where "no critic" is in effect
94 # until the end of the scope. The start is the always the "no
95 # critic" which we already found. So now we have to search for the end.
96 29 my $end = $annotation_element;
97 29 my $use_critic = qr{\A \s* [#][#] \s* use \s+ critic}xms;
98  
99 SIB:
100 29 ▶ while ( my $esib = $end->next_sibling() ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $esib = $end->next_sibling) 165 16 181
101 165 $end = $esib; # keep track of last sibling encountered in this scope
102 165 ▶ last SIB if $esib->isa('PPI::Token::Comment') && $esib =~ $use_critic;
Branch: 1 branch
BranchTrueFalseTotal
if $esib->isa("PPI::Token::Comment") and $esib =~ /$use_critic/ 13 152 165
Condition100%3/3
$esib->isa("PPI::Token::Comment") and $esib =~ /$use_critic/
!ll&&!rl&&r
145713
MC/DC100%2/2
$esib->isa("PPI::Token::Comment") and $esib =~ /$use_critic/
$esib->isa("PPI::Token::Comment") $esib =~ /$use_critic/
Truth table100%3/3
A and B
A= $esib->isa("PPI::Token::Comment")B= $esib =~ /$use_critic/
ABresult
0X0
100
111
103 }
104  
105 # PPI parses __END__ as a PPI::Statement::End, and everything following is
106 # a child of that statement. That means if we encounter an __END__, we
107 # need to descend into it and continue the analysis.
108 29 ▶ if ( $end->isa( 'PPI::Statement::End' ) and my $kid = $end->child( 0 ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($end->isa("PPI::Statement::End") and my $kid = $end->child(0)) 1 28 29
Condition66%2/3
$end->isa("PPI::Statement::End") and my $kid = $end->child(0)
!ll&&!rl&&r
2801
MC/DC50%1/2
$end->isa("PPI::Statement::End") and my $kid = $end->child(0)
$end->isa("PPI::Statement::End") my $kid = $end->child(0)
Truth table66%2/3
A and B
A= $end->isa("PPI::Statement::End")B= my $kid = $end->child(0)
ABresult
0X0
100
111
109 1 $end = $kid;
110 SIB:
111 1 ▶ while ( my $esib = $end->next_sibling() ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $esib = $end->next_sibling) 3 1 4
112 3 $end = $esib;
113 3 ▶ last SIB if $esib->isa( 'PPI::Token::Comment' ) &&
Branch: 1 branch
BranchTrueFalseTotal
if $esib->isa("PPI::Token::Comment") and $esib->content =~ /$use_critic/ 0 3 3
Condition33%1/3
$esib->isa("PPI::Token::Comment") and $esib->content =~ /$use_critic/
!ll&&!rl&&r
300
MC/DC0%0/2
$esib->isa("PPI::Token::Comment") and $esib->content =~ /$use_critic/
$esib->isa("PPI::Token::Comment") $esib->content =~ /$use_critic/
Truth table33%1/3
A and B
A= $esib->isa("PPI::Token::Comment")B= $esib->content =~ /$use_critic/
ABresult
0X0
100
111
114 $esib->content() =~ $use_critic;
115 }
116 }
117  
118 # We either found an end or hit the end of the scope.
119 29 my $ending_line = $end->logical_line_number();
120 29 $self->{_effective_range} = [$annotation_line, $ending_line];
121 29 return $self;
122 }
123  
124 #-----------------------------------------------------------------------------
125  
126 sub element {
127 0 ▶ my ($self) = @_;
Subroutine element: not called CC=1 SCAR=6.9
Pod documented
128 0 return $self->{_element};
129 }
130  
131 #-----------------------------------------------------------------------------
132  
133 sub effective_range {
134 71 ▶ my $self = shift;
Subroutine effective_range: called CC=1 SCAR=0.0
Pod documented
135 71 return @{ $self->{_effective_range} };
136 }
137  
138 #-----------------------------------------------------------------------------
139  
140 sub disabled_policies {
141 29 ▶ my $self = shift;
Subroutine disabled_policies: called CC=1 SCAR=0.0
Pod documented
142 29 return keys %{ $self->{_disabled_policies} };
143 }
144  
145 #-----------------------------------------------------------------------------
146  
147 sub disables_policy {
148 8 ▶ my ($self, $policy_name) = @_;
Subroutine disables_policy: called CC=3 SCAR=16.5
Pod documented
149 8 ▶ return 1 if $self->{_disabled_policies}->{$policy_name};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_disabled_policies"}{$policy_name} 8 0 8
150 0 ▶ return 1 if $self->disables_all_policies();
Branch: 1 branch
BranchTrueFalseTotal
if $self->disables_all_policies 0 0 0
151 0 return 0;
152 }
153  
154 #-----------------------------------------------------------------------------
155  
156 sub disables_all_policies {
157 71 ▶ my ($self) = @_;
Subroutine disables_all_policies: called CC=1 SCAR=0.0
Pod documented
158 71 return $self->{_disables_all_policies};
159 }
160  
161 #-----------------------------------------------------------------------------
162  
163 sub disables_line {
164 13 ▶ my ($self, $line_number) = @_;
Subroutine disables_line: called CC=3 SCAR=13.3
Pod documented
165 13 my $effective_range = $self->{_effective_range};
166 13 ▶ return 1 if $line_number >= $effective_range->[0]
Branch: 1 branch
BranchTrueFalseTotal
if $line_number >= $effective_range->[0] and $line_number <= $effective_range->[$LAST_ELEMENT] 13 0 13
Condition33%1/3
$line_number >= $effective_range->[0] and $line_number <= $effective_range->[$LAST_ELEMENT]
!ll&&!rl&&r
0013
MC/DC0%0/2
$line_number >= $effective_range->[0] and $line_number <= $effective_range->[$LAST_ELEMENT]
$line_number >= $effective_range->[0] $line_number <= $effective_range->[$LAST_ELEMENT]
Truth table33%1/3
A and B
A= $line_number >= $effective_range->[0]B= $line_number <= $effective_range->[$LAST_ELEMENT]
ABresult
0X0
100
111
167 and $line_number <= $effective_range->[$LAST_ELEMENT];
168 0 return 0;
169 }
170  
171 #-----------------------------------------------------------------------------
172  
173 # Recognize a single-line annotation on a simple statement.
174 sub _is_single_line_annotation_on_simple_statement {
175 70 ▶ my ( $annotation_element ) = @_;
Subroutine _is_single_line_annotation_on_simple_statement: called CC=9 SCAR=22.4
176 70 my $annotation_line = $annotation_element->logical_line_number();
177  
178 # If there is no sibling, we are clearly not a single-line annotation of
179 # any sort.
180 70 ▶ my $sib = $annotation_element->sprevious_sibling()
Branch: 1 branch
BranchTrueFalseTotal
my $sib = $annotation_element->sprevious_sibling or return 0 24 46 70
181 or return 0;
182  
183 # The easy case: the sibling (whatever it is) is on the same line as the
184 # annotation.
185 46 ▶ $sib->logical_line_number() == $annotation_line
Branch: 1 branch
BranchTrueFalseTotal
$sib->logical_line_number == $annotation_line and return 1 34 12 46
186 and return 1;
187  
188 # If the sibling is a node, we may have an annotation on one line of a
189 # statement that was split over multiple lines. So we descend through the
190 # children, keeping the last significant child of each, until we bottom
191 # out. If the ultimate significant descendant is on the same line as the
192 # annotation, we accept the annotation as a single-line annotation.
193 12 ▶ if ( $sib->isa( 'PPI::Node' ) &&
Branch: 1 branch
BranchTrueFalseTotal
if ($sib->isa("PPI::Node") and $sib->logical_line_number < $annotation_line) 12 0 12
Condition33%1/3
$sib->isa("PPI::Node") and $sib->logical_line_number < $annotation_line
!ll&&!rl&&r
0012
MC/DC0%0/2
$sib->isa("PPI::Node") and $sib->logical_line_number < $annotation_line
$sib->isa("PPI::Node") $sib->logical_line_number < $annotation_line
Truth table33%1/3
A and B
A= $sib->isa("PPI::Node")B= $sib->logical_line_number < $annotation_line
ABresult
0X0
100
111
194 $sib->logical_line_number() < $annotation_line
195 ) {
196 12 my $neighbor = $sib;
197 12 ▶ while ( $neighbor->isa( 'PPI::Node' )
Branch: 1 branch
BranchTrueFalseTotal
if ($neighbor->isa("PPI::Node") and my $kid = $neighbor->schild($LAST_ELEMENT)) 12 12 24
Condition66%2/3
$neighbor->isa("PPI::Node") and my $kid = $neighbor->schild($LAST_ELEMENT)
!ll&&!rl&&r
12012
MC/DC50%1/2
$neighbor->isa("PPI::Node") and my $kid = $neighbor->schild($LAST_ELEMENT)
$neighbor->isa("PPI::Node") my $kid = $neighbor->schild($LAST_ELEMENT)
Truth table66%2/3
A and B
A= $neighbor->isa("PPI::Node")B= my $kid = $neighbor->schild($LAST_ELEMENT)
ABresult
0X0
100
111
198 and my $kid = $neighbor->schild( $LAST_ELEMENT ) ) {
199 12 $neighbor = $kid;
200 }
201 12 ▶ if ( $neighbor &&
Branch: 1 branch
BranchTrueFalseTotal
if ($neighbor and $neighbor->logical_line_number == $annotation_line) 1 11 12
Condition66%2/3
$neighbor and $neighbor->logical_line_number == $annotation_line
!ll&&!rl&&r
0111
MC/DC50%1/2
$neighbor and $neighbor->logical_line_number == $annotation_line
$neighbor $neighbor->logical_line_number == $annotation_line
Truth table66%2/3
A and B
A= $neighborB= $neighbor->logical_line_number == $annotation_line
ABresult
0X0
100
111
202 $neighbor->logical_line_number() == $annotation_line
203 ) {
204 1 return 1;
205 }
206 }
207  
208 # We do not understand any other sort of single-line annotation. Accepting
209 # the annotation as such (if it is) is Someone Else's Problem.
210 11 return 0;
211 }
212  
213 #-----------------------------------------------------------------------------
214  
215 sub _parse_annotation {
216  
217 72 ▶ my ($annotation_element) = @_;
Subroutine _parse_annotation: called CC=3 SCAR=11.0
218  
219 #############################################################################
220 # This regex captures the list of Policy name patterns that are to be
221 # disabled. It is generally assumed that the element has already been
222 # verified as a no-critic annotation. So if this regex does not match,
223 # then it implies that all Policies are to be disabled.
224 #
225 72 my $no_critic = qr{\#\# \s* no \s+ critic \s* (?:qw)? [(["'] ([\s\w:,]+) }xms;
226 # -------------------------- ------- ----- -----------
227 # | | | |
228 # "## no critic" with optional spaces | | |
229 # | | |
230 # Policy list may be prefixed with "qw" | |
231 # | |
232 # Optional Policy list must begin with one of these |
233 # |
234 # Capture entire Policy list (with delimiters) here
235 #
236 #############################################################################
237  
238 72 my @disabled_policy_names;
239 72 ▶ if ( my ($patterns_string) = $annotation_element =~ $no_critic ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($patterns_string) = $annotation_element =~ /$no_critic/) 40 32 72
240  
241 # Compose the specified modules into a regex alternation. Wrap each
242 # in a no-capturing group to permit "|" in the modules specification.
243  
244 40 my @policy_name_patterns = grep { $_ ne $EMPTY }
245 split m{\s *[,\s] \s*}xms, $patterns_string;
246 40 my $re = join $PIPE, map {"(?:$_)"} @policy_name_patterns;
247 40 my @site_policy_names = Perl::Critic::PolicyFactory::site_policy_names();
248 40 @disabled_policy_names = grep {m/$re/ixms} @site_policy_names;
249  
250 # It is possible that the Policy patterns listed in the annotation do not
251 # match any of the site policy names. This could happen when running
252 # on a machine that does not have the same set of Policies as the author.
253 # So we must return something here, otherwise all Policies will be
254 # disabled. We probably need to add a mechanism to (optionally) warn
255 # about this, just to help the author avoid writing invalid Policy names.
256  
257 40 ▶ if (not @disabled_policy_names) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@disabled_policy_names) 2 38 40
258 2 @disabled_policy_names = @policy_name_patterns;
259 }
260 }
261  
262 72 return hashify(@disabled_policy_names);
263 }
264  
265 #-----------------------------------------------------------------------------
266  
267 40 1;
268  
269 __END__
270  
271 =pod
272  
273 =head1 NAME
274  
275 Perl::Critic::Annotation - A "## no critic" annotation in a document.
276  
277  
278 =head1 SYNOPSIS
279  
280 use Perl::Critic::Annotation;
281 $annotation = Perl::Critic::Annotation->new( -element => $no_critic_ppi_element );
282  
283 $bool = $annotation->disables_line( $number );
284 $bool = $annotation->disables_policy( $policy_object );
285 $bool = $annotation->disables_all_policies();
286  
287 ($start, $end) = $annotation->effective_range();
288 @disabled_policy_names = $annotation->disabled_policies();
289  
290  
291 =head1 DESCRIPTION
292  
293 C<Perl::Critic::Annotation> represents a single C<"## no critic">
294 annotation in a L<PPI::Document>. The Annotation takes care of parsing
295 the annotation and keeps track of which lines and Policies it affects.
296 It is intended to encapsulate the details of the no-critic
297 annotations, and to provide a way for Policy objects to interact with
298 the annotations (via a L<Perl::Critic::Document|Perl::Critic::Document>).
299  
300  
301 =head1 INTERFACE SUPPORT
302  
303 This is considered to be a non-public class. Its interface is subject
304 to change without notice.
305  
306  
307 =head1 CLASS METHODS
308  
309 =over
310  
311 =item create_annotations( -doc => $doc )
312  
313 Given a L<Perl::Critic::Document|Perl::Critic::Document>, finds all the C<"## no critic">
314 annotations and constructs a new C<Perl::Critic::Annotation> for each
315 one and returns them. The order of the returned objects is not
316 defined. It is generally expected that clients will use this
317 interface rather than calling the C<Perl::Critic::Annotation>
318 constructor directly.
319  
320  
321 =back
322  
323  
324 =head1 CONSTRUCTOR
325  
326 =over
327  
328 =item C<< new( -element => $ppi_annotation_element ) >>
329  
330 Returns a reference to a new Annotation object. The B<-element>
331 argument is required and should be a C<PPI::Token::Comment> that
332 conforms to the C<"## no critic"> syntax.
333  
334  
335 =back
336  
337  
338 =head1 METHODS
339  
340 =over
341  
342 =item C<< disables_line( $line ) >>
343  
344 Returns true if this Annotation disables C<$line> for any (or all)
345 Policies.
346  
347  
348 =item C<< disables_policy( $policy_object ) >>
349  
350 =item C<< disables_policy( $policy_name ) >>
351  
352 Returns true if this Annotation disables C<$polciy_object> or
353 C<$policy_name> at any (or all) lines.
354  
355  
356 =item C<< disables_all_policies() >>
357  
358 Returns true if this Annotation disables all Policies at any (or all)
359 lines. If this method returns true, C<disabled_policies> will return
360 an empty list.
361  
362  
363 =item C<< effective_range() >>
364  
365 Returns a two-element list, representing the first and last line
366 numbers where this Annotation has effect.
367  
368  
369 =item C<< disabled_policies() >>
370  
371 Returns a list of the names of the Policies that are affected by this
372 Annotation. If this list is empty, then it means that all Policies
373 are affected by this Annotation, and C<disables_all_policies()> should
374 return true.
375  
376  
377 =item C<< element() >>
378  
379 Returns the L<PPI::Element|PPI::Element> where this annotation started. This is
380 typically an instance of L<PPI::Token::Comment|PPI::Token::Comment>.
381  
382  
383 =back
384  
385  
386 =head1 AUTHOR
387  
388 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
389  
390  
391 =head1 COPYRIGHT
392  
393 Copyright (c) 2005-2023 Imaginative Software Systems
394  
395 This program is free software; you can redistribute it and/or modify
396 it under the same terms as Perl itself. The full text of this license
397 can be found in the LICENSE file included with this module.
398  
399 =cut
400  
401 ##############################################################################
402 # Local Variables:
403 # mode: cperl
404 # cperl-indent-level: 4
405 # fill-column: 78
406 # indent-tabs-mode: nil
407 # c-indentation-style: bsd
408 # End:
409 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/Policy/Variables/ProhibitLocalVars.pm ↑ Summary blib/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitLongChainsOfMethodCalls.pm »