blib/lib/Perl/Critic/Theme.pm

filter: Statementstmt 100% 66 / 66 Branchbran 83.3% 10 / 12 Conditioncond 50.0% 3 / 6 MC/DCmcdc 25.0% 1 / 4 Subroutinesub 100% 14 / 14 Podpod 100% 4 / 4 totaltotal 92.4% 98 / 106 CC 9 SCAR 10.1
CC
9
Cov
94%
policy_is_thematic
6.1
_init
3.0
cook_rule
2.0
CRAP 2.8
« blib/lib/Perl/Critic/Policy/Subroutines/ProhibitExplicitReturnUndef.pm ↑ Summary blib/lib/Perl/Critic/Policy/Variables/RequireInitializationForLocalVars.pm »
1 package Perl::Critic::Theme;
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 English qw(-no_match_vars);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 40 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 40 ▶use Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 40 ▶use Perl::Critic::Utils qw( :characters :data_conversion );
Subroutine BEGIN: called CC=1 SCAR=0.0
12 40 ▶use Perl::Critic::Exception::Fatal::Internal qw( throw_internal );
Subroutine BEGIN: called CC=1 SCAR=0.0
13 use Perl::Critic::Exception::Configuration::Option::Global::ParameterValue
14 40 ▶ qw( throw_global_value );
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 #-----------------------------------------------------------------------------
17  
18 40 our $VERSION = '1.150';
19  
20 #-----------------------------------------------------------------------------
21  
22 40 Readonly::Array our @EXPORT_OK => qw{
23 $RULE_INVALID_CHARACTER_REGEX
24 cook_rule
25 };
26  
27 #-----------------------------------------------------------------------------
28  
29 40 Readonly::Scalar our $RULE_INVALID_CHARACTER_REGEX =>
30 qr/ ( [^()\s\w\d+\-*&|!] ) /xms;
31  
32 #-----------------------------------------------------------------------------
33  
34 40 Readonly::Scalar my $CONFIG_KEY => 'theme';
35  
36 #-----------------------------------------------------------------------------
37  
38 sub new {
39  
40 321 ▶ my ( $class, %args ) = @_;
Subroutine new: called CC=1 SCAR=0.0
Pod documented
41 321 my $self = bless {}, $class;
42 321 $self->_init( %args );
43 313 return $self;
44 }
45  
46 #-----------------------------------------------------------------------------
47  
48 sub _init {
49  
50 321 ▶ my ($self, %args) = @_;
Subroutine _init: called CC=3 SCAR=11.0
51 321 ▶ my $rule = $args{-rule} || $EMPTY;
Condition66%2/3
$args{'-rule'} || $Perl::Critic::Theme::EMPTY
l!l&&r!l&&!r
940227
MC/DC50%1/2
$args{'-rule'} || $Perl::Critic::Theme::EMPTY
$args{'-rule'} $Perl::Critic::Theme::EMPTY
Truth table66%2/3
A || B
A= $args{'-rule'}B= $Perl::Critic::Theme::EMPTY
ABresult
1X1
011
000
52  
53 321 ▶ if ( $rule =~ m/$RULE_INVALID_CHARACTER_REGEX/xms ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rule =~ /$Perl::Critic::Theme::RULE_INVALID_CHARACTER_REGEX/msx) 8 313 321
54 8 throw_global_value
55 option_name => $CONFIG_KEY,
56 option_value => $rule,
57 message_suffix => qq{contains an invalid character: "$1".};
58 }
59  
60 313 $self->{_rule} = cook_rule( $rule );
61  
62 313 return $self;
63 }
64  
65 #-----------------------------------------------------------------------------
66  
67 sub rule {
68 5 ▶ my $self = shift;
Subroutine rule: called CC=1 SCAR=0.0
Pod documented
69 5 return $self->{_rule};
70 }
71  
72 #-----------------------------------------------------------------------------
73  
74 sub policy_is_thematic {
75  
76 13485 ▶ my ($self, %args) = @_;
Subroutine policy_is_thematic: called CC=6 SCAR=18.0
Pod documented
77 my $policy = $args{-policy}
78 13485 ▶ || throw_internal 'The -policy argument is required';
Condition33%1/3
$args{'-policy'} || throw_internal('The -policy argument is required')
l!l&&r!l&&!r
1348500
MC/DC0%0/2
$args{'-policy'} || throw_internal('The -policy argument is required')
$args{'-policy'} throw_internal('The -policy argument is required')
Truth table33%1/3
A || B
A= $args{'-policy'}B= throw_internal('The -policy argument is required')
ABresult
1X1
011
000
79 13485 ▶ ref $policy
Branch: 1 branch
BranchTrueFalseTotal
ref $policy or throw_internal("The -policy must be an object") 0 13485 13485
80 || throw_internal 'The -policy must be an object';
81  
82 13485 ▶ my $rule = $self->{_rule} or return 1;
Branch: 1 branch
BranchTrueFalseTotal
my $rule = $self->{"_rule"} or return 1 3479 10006 13485
83 10006 my %themes = hashify( $policy->get_themes() );
84  
85 # This bit of magic turns the rule into a perl expression that can be
86 # eval-ed for truth. Each theme name in the rule is translated to 1 or 0
87 # if the $policy belongs in that theme. For example:
88 #
89 # 'bugs && (pbp || core)' ...could become... '1 && (0 || 1)'
90  
91 10006 my $as_code = $rule; #Making a copy, so $rule is preserved
92 10006 ▶ $as_code =~ s/ ( [\w\d]+ ) /exists $themes{$1} || 0/gexms;
Branch: 1 branch
BranchTrueFalseTotal
exists $themes{$1} or 0 3245 9371 12616
93 10006 my $is_thematic = eval $as_code; ## no critic (ProhibitStringyEval)
94  
95 10006 ▶ if ($EVAL_ERROR) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Perl::Critic::Theme::EVAL_ERROR) 1 10005 10006
96 1 throw_global_value
97 option_name => $CONFIG_KEY,
98 option_value => $rule,
99 message_suffix => q{contains a syntax error.};
100 }
101  
102 10005 return $is_thematic;
103 }
104  
105 #-----------------------------------------------------------------------------
106  
107 sub cook_rule {
108 609 ▶ my ($raw_rule) = @_;
Subroutine cook_rule: called CC=2 SCAR=6.9
Pod documented
109 609 ▶ return if not defined $raw_rule;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $raw_rule 0 609 609
110  
111 #Translate logical operators
112 609 $raw_rule =~ s{\b not \b}{!}ixmsg; # "not" -> "!"
113 609 $raw_rule =~ s{\b and \b}{&&}ixmsg; # "and" -> "&&"
114 609 $raw_rule =~ s{\b or \b}{||}ixmsg; # "or" -> "||"
115  
116 #Translate algebra operators (for backward compatibility)
117 609 $raw_rule =~ s{\A [-] }{!}ixmsg; # "-" -> "!" e.g. difference
118 609 $raw_rule =~ s{ [-] }{&& !}ixmsg; # "-" -> "&& !" e.g. difference
119 609 $raw_rule =~ s{ [*] }{&&}ixmsg; # "*" -> "&&" e.g. intersection
120 609 $raw_rule =~ s{ [+] }{||}ixmsg; # "+" -> "||" e.g. union
121  
122 609 my $cooked_rule = lc $raw_rule; #Is now cooked!
123 609 return $cooked_rule;
124 }
125  
126  
127 40 1;
128  
129 __END__
130  
131 #-----------------------------------------------------------------------------
132  
133 =pod
134  
135 =head1 NAME
136  
137 Perl::Critic::Theme - Construct thematic sets of policies.
138  
139  
140 =head1 DESCRIPTION
141  
142 This is a helper class for evaluating theme expressions into sets of
143 Policy objects. There are no user-serviceable parts here.
144  
145  
146 =head1 INTERFACE SUPPORT
147  
148 This is considered to be a non-public class. Its interface is subject
149 to change without notice.
150  
151  
152 =head1 METHODS
153  
154 =over
155  
156 =item C<< new( -rule => $rule_expression ) >>
157  
158 Returns a reference to a new Perl::Critic::Theme object. C<-rule> is
159 a string expression that evaluates to true or false for each Policy..
160 See L<"THEME RULES"> for more information.
161  
162  
163 =item C<< policy_is_thematic( -policy => $policy ) >>
164  
165 Given a reference to a L<Perl::Critic::Policy|Perl::Critic::Policy>
166 object, this method returns evaluates the rule against the themes that
167 are associated with the Policy. Returns 1 if the Policy satisfies the
168 rule, 0 otherwise.
169  
170  
171 =item C< rule() >
172  
173 Returns the rule expression that was used to construct this Theme.
174 The rule may have been translated into a normalized expression. See
175 L<"THEME RULES"> for more information.
176  
177 =back
178  
179  
180 =head2 THEME RULES
181  
182 A theme rule is a simple boolean expression, where the operands are
183 the names of any of the themes associated with the
184 Perl::Critic::Polices.
185  
186 Theme names can be combined with logical operators to form arbitrarily
187 complex expressions. Precedence is the same as normal mathematics,
188 but you can use parentheses to enforce precedence as well. Supported
189 operators are:
190  
191 Operator Altertative Example
192 ----------------------------------------------------------------
193 && and 'pbp && core'
194 || or 'pbp || (bugs && security)'
195 ! not 'pbp && ! (portability || complexity)
196  
197 See L<Perl::Critic/"CONFIGURATION"> for more information about
198 customizing the themes for each Policy.
199  
200  
201 =head1 SUBROUTINES
202  
203 =over
204  
205 =item C<cook_rule( $rule )>
206  
207 Standardize a rule into almost executable Perl code. The "almost"
208 comes from the fact that theme names are left as is.
209  
210  
211 =back
212  
213  
214 =head1 CONSTANTS
215  
216 =over
217  
218 =item C<$RULE_INVALID_CHARACTER_REGEX>
219  
220 A regular expression that will return the first character in the
221 matched expression that is not valid in a rule.
222  
223  
224 =back
225  
226  
227 =head1 AUTHOR
228  
229 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
230  
231  
232 =head1 COPYRIGHT
233  
234 Copyright (c) 2006-2023 Imaginative Software Systems
235  
236 This program is free software; you can redistribute it and/or modify
237 it under the same terms as Perl itself. The full text of this license
238 can be found in the LICENSE file included with this module.
239  
240 =cut
241  
242 ##############################################################################
243 # Local Variables:
244 # mode: cperl
245 # cperl-indent-level: 4
246 # fill-column: 78
247 # indent-tabs-mode: nil
248 # c-indentation-style: bsd
249 # End:
250 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/Policy/Subroutines/ProhibitExplicitReturnUndef.pm ↑ Summary blib/lib/Perl/Critic/Policy/Variables/RequireInitializationForLocalVars.pm »