blib/lib/Perl/Critic/Policy/ControlStructures/ProhibitMutatingListFunctions.pm

filter: Statementstmt 38.6% 39 / 101 Branchbran 4.5% 3 / 66 Conditioncond 0.0% 0 / 26 MC/DCmcdc 0.0% 0 / 16 Subroutinesub 60.8% 14 / 23 Podpod 83.3% 5 / 6 totaltotal 25.6% 61 / 238 CC 44 SCAR 44.9
CC
44
Cov
22%
_is_topic_mutating_regex
272.0
_has_topic_side_effect
72.0
_is_assignment_to_topic
72.0
CRAP 89.1
« blib/lib/Perl/Critic/Policy/CodeLayout/ProhibitQuotedWordLists.pm ↑ Summary blib/lib/Perl/Critic/Policy/Subroutines/ProhibitUnusedPrivateSubroutines.pm »
1 package Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions;
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{
9 :booleans :characters :severities :data_conversion :classification :ppi
10 40 ▶};
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 40 ▶use parent 'Perl::Critic::Policy';
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 40 our $VERSION = '1.150';
15  
16 #-----------------------------------------------------------------------------
17  
18 40 Readonly::Array my @BUILTIN_LIST_FUNCS => qw( map grep );
19 40 Readonly::Array my @CPAN_LIST_FUNCS => _get_cpan_list_funcs();
20  
21 #-----------------------------------------------------------------------------
22  
23 sub _get_cpan_list_funcs {
24 return qw( List::Util::first ),
25 40 ▶ map { ('List::MoreUtils::'.$_, 'List::SomeUtils::'.$_) } _get_list_moreutils_funcs();
Subroutine _get_cpan_list_funcs: called CC=1 SCAR=0.0
26 }
27  
28 #-----------------------------------------------------------------------------
29  
30 sub _get_list_moreutils_funcs {
31 40 ▶ return qw(any all none notall true false firstidx first_index
Subroutine _get_list_moreutils_funcs: called CC=1 SCAR=0.0
32 lastidx last_index insert_after insert_after_string);
33 }
34  
35 #-----------------------------------------------------------------------------
36  
37 sub _is_topic {
38 0 ▶ my $elem = shift;
Subroutine _is_topic: not called CC=3 SCAR=24.8
39 0 ▶ return defined $elem
Condition0%0/6
defined $elem && $elem->isa('PPI::Token::Magic') && $elem->content eq '$_'
!ll&&!rl&&r
000
defined $elem and $elem->isa("PPI::Token::Magic")
!ll&&!rl&&r
000
MC/DC0%0/3
defined $elem && $elem->isa('PPI::Token::Magic') && $elem->content eq '$_'
defined $elem $elem->isa("PPI::Token::Magic") $elem->content eq '$_'
Truth table0%0/4
A and B && C
A= defined $elemB= $elem->isa("PPI::Token::Magic")C= $elem->content eq '$_'
ABCresult
0XX0
10X0
1100
1111
40 && $elem->isa('PPI::Token::Magic')
41 && $elem->content() eq q{$_}; ##no critic (InterpolationOfMetachars)
42 }
43  
44  
45 #-----------------------------------------------------------------------------
46  
47 40 Readonly::Scalar my $DESC => q{Don't modify $_ in list functions}; ##no critic (InterpolationOfMetachars)
48 40 Readonly::Scalar my $EXPL => [ 114 ];
49  
50 #-----------------------------------------------------------------------------
51  
52 sub supported_parameters {
53 return (
54 {
55 92 ▶ name => 'list_funcs',
Subroutine supported_parameters: called CC=1 SCAR=0.0
Pod undocumented
56 description => 'The base set of functions to check.',
57 default_string => join ($SPACE, @BUILTIN_LIST_FUNCS, @CPAN_LIST_FUNCS ),
58 behavior => 'string list',
59 },
60 {
61 name => 'add_list_funcs',
62 description => 'The set of functions to check, in addition to those given in list_funcs.',
63 default_string => $EMPTY,
64 behavior => 'string list',
65 },
66 );
67 }
68  
69 75 ▶sub default_severity { return $SEVERITY_HIGHEST }
Subroutine default_severity: called CC=1 SCAR=0.0
Pod documented
70 92 ▶sub default_themes { return qw(core bugs pbp certrule ) }
Subroutine default_themes: called CC=1 SCAR=0.0
Pod documented
71 37 ▶sub applies_to { return 'PPI::Token::Word' }
Subroutine applies_to: called CC=1 SCAR=0.0
Pod documented
72  
73 #-----------------------------------------------------------------------------
74  
75 sub initialize_if_enabled {
76 72 ▶ my ($self, $config) = @_;
Subroutine initialize_if_enabled: called CC=1 SCAR=0.0
Pod documented
77  
78 $self->{_all_list_funcs} = {
79 72 hashify keys %{ $self->{_list_funcs} }, keys %{ $self->{_add_list_funcs} }
80 };
81  
82 72 return $TRUE;
83 }
84  
85 #-----------------------------------------------------------------------------
86  
87 sub violates {
88 361 ▶ my ($self, $elem, $doc) = @_;
Subroutine violates: called CC=6 SCAR=27.6
Pod documented
89  
90 # Is this element a list function?
91 361 ▶ return if not $self->{_all_list_funcs}->{$elem};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"_all_list_funcs"}{$elem} 358 3 361
92 3 ▶ return if not is_function_call($elem);
Branch: 1 branch
BranchTrueFalseTotal
unless is_function_call($elem) 3 0 3
93  
94 # Only the block form of list functions can be analyzed.
95 0 ▶ return if not my $first_arg = first_arg( $elem );
Branch: 1 branch
BranchTrueFalseTotal
unless my $first_arg = first_arg($elem) 0 0 0
96 0 ▶ return if not $first_arg->isa('PPI::Structure::Block');
Branch: 1 branch
BranchTrueFalseTotal
unless $first_arg->isa("PPI::Structure::Block") 0 0 0
97 0 ▶ return if not _has_topic_side_effect( $first_arg, $doc );
Branch: 1 branch
BranchTrueFalseTotal
unless _has_topic_side_effect($first_arg, $doc) 0 0 0
98  
99 # Must be a violation
100 0 return $self->violation( $DESC, $EXPL, $elem );
101 }
102  
103 #-----------------------------------------------------------------------------
104  
105 sub _has_topic_side_effect {
106 0 ▶ my ( $node, $doc ) = @_;
Subroutine _has_topic_side_effect: not called CC=8 SCAR=42.8
107  
108 # Search through all significant elements in the block,
109 # testing each element to see if it mutates the topic.
110 0 ▶ my $tokens = $node->find( 'PPI::Token' ) || [];
Condition0%0/2
$node->find('PPI::Token') || []
l!l
00
MC/DC0%0/1
$node->find('PPI::Token') || []
$node->find('PPI::Token')
Truth table0%0/2
A
A= $node->find('PPI::Token')
Aresult
11
00
111 0 for my $elem ( @{ $tokens } ) {
112 0 ▶ next if not $elem->significant();
Branch: 1 branch
BranchTrueFalseTotal
unless $elem->significant 0 0 0
113 0 ▶ return 1 if _is_assignment_to_topic( $elem );
Branch: 1 branch
BranchTrueFalseTotal
if _is_assignment_to_topic($elem) 0 0 0
114 0 ▶ return 1 if _is_topic_mutating_regex( $elem, $doc );
Branch: 1 branch
BranchTrueFalseTotal
if _is_topic_mutating_regex($elem, $doc) 0 0 0
115 0 ▶ return 1 if _is_topic_mutating_func( $elem );
Branch: 1 branch
BranchTrueFalseTotal
if _is_topic_mutating_func($elem) 0 0 0
116 0 ▶ return 1 if _is_topic_mutating_substr( $elem );
Branch: 1 branch
BranchTrueFalseTotal
if _is_topic_mutating_substr($elem) 0 0 0
117 }
118 0 return;
119 }
120  
121 #-----------------------------------------------------------------------------
122  
123 sub _is_assignment_to_topic {
124 0 ▶ my $elem = shift;
Subroutine _is_assignment_to_topic: not called CC=8 SCAR=42.8
125 0 ▶ return if not _is_topic( $elem );
Branch: 1 branch
BranchTrueFalseTotal
unless _is_topic($elem) 0 0 0
126  
127 0 my $sib = $elem->snext_sibling();
128 0 ▶ if ($sib && $sib->isa('PPI::Token::Operator')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sib and $sib->isa("PPI::Token::Operator")) 0 0 0
Condition0%0/3
$sib and $sib->isa("PPI::Token::Operator")
!ll&&!rl&&r
000
MC/DC0%0/2
$sib and $sib->isa("PPI::Token::Operator")
$sib $sib->isa("PPI::Token::Operator")
Truth table0%0/3
A and B
A= $sibB= $sib->isa("PPI::Token::Operator")
ABresult
0X0
100
111
129 0 ▶ return 1 if _is_assignment_operator( $sib );
Branch: 1 branch
BranchTrueFalseTotal
if _is_assignment_operator($sib) 0 0 0
130 }
131  
132 0 my $psib = $elem->sprevious_sibling();
133 0 ▶ if ($psib && $psib->isa('PPI::Token::Operator')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($psib and $psib->isa("PPI::Token::Operator")) 0 0 0
Condition0%0/3
$psib and $psib->isa("PPI::Token::Operator")
!ll&&!rl&&r
000
MC/DC0%0/2
$psib and $psib->isa("PPI::Token::Operator")
$psib $psib->isa("PPI::Token::Operator")
Truth table0%0/3
A and B
A= $psibB= $psib->isa("PPI::Token::Operator")
ABresult
0X0
100
111
134 0 ▶ return 1 if _is_increment_operator( $psib );
Branch: 1 branch
BranchTrueFalseTotal
if _is_increment_operator($psib) 0 0 0
135 }
136  
137 0 return;
138 }
139  
140 #-----------------------------------------------------------------------------
141  
142 sub _is_topic_mutating_regex {
143 0 ▶ my ( $elem, $doc ) = @_;
Subroutine _is_topic_mutating_regex: not called CC=16 SCAR=56.1
144 0 ▶ return if ! ( $elem->isa('PPI::Token::Regexp::Substitute')
Branch: 1 branch
BranchTrueFalseTotal
unless $elem->isa("PPI::Token::Regexp::Substitute") or $elem->isa("PPI::Token::Regexp::Transliterate") 0 0 0
Condition0%0/3
$elem->isa("PPI::Token::Regexp::Substitute") or $elem->isa("PPI::Token::Regexp::Transliterate")
l!l&&r!l&&!r
000
MC/DC0%0/2
$elem->isa("PPI::Token::Regexp::Substitute") or $elem->isa("PPI::Token::Regexp::Transliterate")
$elem->isa("PPI::Token::Regexp::Substitute") $elem->isa("PPI::Token::Regexp::Transliterate")
Truth table0%0/3
A or B
A= $elem->isa("PPI::Token::Regexp::Substitute")B= $elem->isa("PPI::Token::Regexp::Transliterate")
ABresult
1X1
011
000
145 || $elem->isa('PPI::Token::Regexp::Transliterate') );
146  
147 # Exempt PPI::Token::Regexp::Transliterate objects IF the replacement
148 # string is empty AND neither the /d or /s flags are specified, OR the
149 # replacement string equals the match string AND neither the /c or /s
150 # flags are specified. RT 44515.
151 #
152 # NOTE that, at least as of 5.14.2, tr/// does _not_ participate in the
153 # 'use re /modifiers' mechanism. And a good thing, too, since the
154 # modifiers that _are_ common (/s and /d) mean something completely
155 # different in tr///.
156 0 ▶ if ( $elem->isa( 'PPI::Token::Regexp::Transliterate') ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($elem->isa("PPI::Token::Regexp::Transliterate")) 0 0 0
157 0 my $subs = $elem->get_substitute_string();
158 0 my %mods = $elem->get_modifiers();
159 0 ▶ $mods{r} and return; # Introduced in Perl 5.13.7
Branch: 1 branch
BranchTrueFalseTotal
$mods{"r"} and return 0 0 0
160 0 ▶ if ( $EMPTY eq $subs ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions::EMPTY eq $subs) { } 0 0 0
elsif ($elem->get_match_string eq $subs) { } 0 0 0
161 0 ▶ $mods{d} or $mods{s} or return;
Branch: 1 branch
BranchTrueFalseTotal
$mods{"d"} or $mods{"s"} or return 0 0 0
Condition0%0/3
$mods{"d"} or $mods{"s"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$mods{"d"} or $mods{"s"}
$mods{"d"} $mods{"s"}
Truth table0%0/3
A or B
A= $mods{"d"}B= $mods{"s"}
ABresult
1X1
011
000
162 } elsif ( $elem->get_match_string() eq $subs ) {
163 0 ▶ $mods{c} or $mods{s} or return;
Branch: 1 branch
BranchTrueFalseTotal
$mods{"c"} or $mods{"s"} or return 0 0 0
Condition0%0/3
$mods{"c"} or $mods{"s"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$mods{"c"} or $mods{"s"}
$mods{"c"} $mods{"s"}
Truth table0%0/3
A or B
A= $mods{"c"}B= $mods{"s"}
ABresult
1X1
011
000
164 }
165 }
166  
167 # As of 5.13.2, the substitute built-in supports the /r modifier, which
168 # causes the operation to return the modified string and leave the
169 # original unmodified. This does not parse under earlier Perls, so there
170 # is no version check.
171  
172 0 ▶ if ( $elem->isa( 'PPI::Token::Regexp::Substitute' ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($elem->isa("PPI::Token::Regexp::Substitute")) 0 0 0
173 0 ▶ my $re = $doc->ppix_regexp_from_element( $elem )
Branch: 1 branch
BranchTrueFalseTotal
my $re = $doc->ppix_regexp_from_element($elem) or return 0 0 0
174 or return;
175 0 ▶ $re->modifier_asserted( 'r' )
Branch: 1 branch
BranchTrueFalseTotal
$re->modifier_asserted("r") and return 0 0 0
176 and return;
177 }
178  
179 # If the previous sibling does not exist, then
180 # the regex implicitly binds to $_
181 0 my $prevsib = $elem->sprevious_sibling;
182 0 ▶ return 1 if not $prevsib;
Branch: 1 branch
BranchTrueFalseTotal
unless $prevsib 0 0 0
183  
184 # If the previous sibling does exist, then it
185 # should be a binding operator.
186 0 ▶ return 1 if not _is_binding_operator( $prevsib );
Branch: 1 branch
BranchTrueFalseTotal
unless _is_binding_operator($prevsib) 0 0 0
187  
188 # Check if the sibling before the binding operator
189 # is explicitly set to $_
190 0 my $bound_to = $prevsib->sprevious_sibling;
191 0 return _is_topic( $bound_to );
192 }
193  
194 #-----------------------------------------------------------------------------
195  
196 sub _is_topic_mutating_func {
197 0 ▶ my $elem = shift;
Subroutine _is_topic_mutating_func: not called CC=5 SCAR=34.0
198 0 ▶ return if not $elem->isa('PPI::Token::Word');
Branch: 1 branch
BranchTrueFalseTotal
unless $elem->isa("PPI::Token::Word") 0 0 0
199  
200 0 state $mutator_funcs = { hashify qw( chop chomp undef ) };
201 0 ▶ return if !$mutator_funcs->{$elem->content()};
Branch: 1 branch
BranchTrueFalseTotal
unless $$mutator_funcs{$elem->content} 0 0 0
202  
203 0 ▶ return if not is_function_call( $elem );
Branch: 1 branch
BranchTrueFalseTotal
unless is_function_call($elem) 0 0 0
204  
205 # If these functions have no argument,
206 # they default to mutating $_
207 0 my $first_arg = first_arg( $elem );
208 0 ▶ if (not defined $first_arg) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $first_arg) 0 0 0
209 # undef does not default to $_, unlike the others
210 0 return $elem->content() ne 'undef';
211 }
212 0 return _is_topic( $first_arg );
213 }
214  
215 #-----------------------------------------------------------------------------
216  
217 40 Readonly::Scalar my $MUTATING_SUBSTR_ARG_COUNT => 4;
218  
219 sub _is_topic_mutating_substr {
220 0 ▶ my $elem = shift;
Subroutine _is_topic_mutating_substr: not called CC=4 SCAR=30.0
221 0 ▶ return if $elem->content() ne 'substr';
Branch: 1 branch
BranchTrueFalseTotal
if $elem->content ne "substr" 0 0 0
222 0 ▶ return if not is_function_call( $elem );
Branch: 1 branch
BranchTrueFalseTotal
unless is_function_call($elem) 0 0 0
223  
224 # check and see if the first arg is $_
225 0 my @args = parse_arg_list( $elem );
226 0 ▶ return @args >= $MUTATING_SUBSTR_ARG_COUNT && _is_topic( $args[0]->[0] );
Condition0%0/3
@args >= $MUTATING_SUBSTR_ARG_COUNT && _is_topic($args[0][0])
!ll&&!rl&&r
000
MC/DC0%0/2
@args >= $MUTATING_SUBSTR_ARG_COUNT && _is_topic($args[0][0])
@args >= $MUTATING_SUBSTR_ARG_COUNT _is_topic($args[0][0])
Truth table0%0/3
A && B
A= @args >= $MUTATING_SUBSTR_ARG_COUNTB= _is_topic($args[0][0])
ABresult
0X0
100
111
227 }
228  
229 #-----------------------------------------------------------------------------
230  
231 sub _is_assignment_operator { ## no critic (RequireArgUnpacking)
232 0 ▶ state $assignment_ops = { hashify qw( = *= /= += -= %= **= x= .= &= |= ^= &&= ||= <<= >>= //= ++ --) };
Subroutine _is_assignment_operator: not called CC=1 SCAR=6.9
233 0 return exists $assignment_ops->{$_[0]};
234 }
235  
236 sub _is_increment_operator { ## no critic (RequireArgUnpacking)
237 0 ▶ state $increment_ops = { hashify qw( ++ -- ) };
Subroutine _is_increment_operator: not called CC=1 SCAR=6.9
238 0 return exists $increment_ops->{$_[0]};
239 }
240  
241 sub _is_binding_operator { ## no critic (RequireArgUnpacking)
242 0 ▶ state $binding_ops = { hashify qw( =~ !~ ) };
Subroutine _is_binding_operator: not called CC=1 SCAR=6.9
243 0 return exists $binding_ops->{$_[0]};
244 }
245  
246 40 1;
247  
248 #-----------------------------------------------------------------------------
249  
250 __END__
251  
252 =pod
253  
254 =head1 NAME
255  
256 Perl::Critic::Policy::ControlStructures::ProhibitMutatingListFunctions - Don't modify C<$_> in list functions.
257  
258  
259 =head1 AFFILIATION
260  
261 This Policy is part of the core L<Perl::Critic|Perl::Critic>
262 distribution.
263  
264  
265 =head1 DESCRIPTION
266  
267 C<map>, C<grep> and other list operators are intended to transform
268 arrays into other arrays by applying code to the array elements one by
269 one. For speed, the elements are referenced via a C<$_> alias rather
270 than copying them. As a consequence, if the code block of the C<map>
271 or C<grep> modify C<$_> in any way, then it is actually modifying the
272 source array. This IS technically allowed, but those side effects can
273 be quite surprising, especially when the array being passed is C<@_>
274 or perhaps C<values(%ENV)>! Instead authors should restrict in-place
275 array modification to C<for(@array) { ... }> constructs instead, or
276 use C<List::SomeUtils:apply()> or C<List::MoreUtils::apply()>.
277  
278 =head1 CONFIGURATION
279  
280 By default, this policy applies to the following list functions:
281  
282 map grep
283 List::Util qw(first)
284 List::MoreUtils qw(any all none notall true false firstidx
285 first_index lastidx last_index insert_after
286 insert_after_string)
287 List::SomeUtils qw(any all none notall true false firstidx
288 first_index lastidx last_index insert_after
289 insert_after_string)
290  
291 This list can be overridden the F<.perlcriticrc> file like this:
292  
293 [ControlStructures::ProhibitMutatingListFunctions]
294 list_funcs = map grep List::Util::first
295  
296 Or, one can just append to the list like so:
297  
298 [ControlStructures::ProhibitMutatingListFunctions]
299 add_list_funcs = Foo::Bar::listmunge
300  
301 =head1 LIMITATIONS
302  
303 This policy deliberately does not apply to C<for (@array) { ... }> or
304 C<List::MoreUtils::apply()> C<List::SomeUtils::apply()>.
305  
306 Currently, the policy only detects explicit external module usage like
307 this:
308  
309 my @out = List::MoreUtils::any {s/^foo//} @in;
310 my @out = List::SomeUtils::any {s/^foo//} @in;
311  
312 and not like this:
313  
314 use List::MoreUtils qw(any);
315 my @out = any {s/^foo//} @in;
316  
317 use List::SomeUtils qw(any);
318 my @out = any {s/^foo//} @in;
319  
320 This policy looks only for modifications of C<$_>. Other naughtiness
321 could include modifying C<$a> and C<$b> in C<sort> and the like.
322 That's beyond the scope of this policy.
323  
324  
325 =head1 SEE ALSO
326  
327 There is discussion of this policy at
328 L<http://perlmonks.org/index.pl?node_id=743445>.
329  
330  
331 =head1 AUTHOR
332  
333 Chris Dolan <cdolan@cpan.org>
334  
335 Michael Wolf <MichaelRWolf@att.net>
336  
337  
338 =head1 COPYRIGHT
339  
340 Copyright (c) 2006-2021 Chris Dolan.
341  
342 This program is free software; you can redistribute it and/or modify
343 it under the same terms as Perl itself.
344  
345 =cut
346  
347 # Local Variables:
348 # mode: cperl
349 # cperl-indent-level: 4
350 # fill-column: 78
351 # indent-tabs-mode: nil
352 # End:
353 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
354  
« blib/lib/Perl/Critic/Policy/CodeLayout/ProhibitQuotedWordLists.pm ↑ Summary blib/lib/Perl/Critic/Policy/Subroutines/ProhibitUnusedPrivateSubroutines.pm »