blib/lib/Perl/Critic/PolicyParameter.pm

filter: Statementstmt 96.2% 128 / 133 Branchbran 64.2% 18 / 28 Conditioncond 33.3% 3 / 9 MC/DCmcdc 16.6% 1 / 6 Subroutinesub 97.2% 35 / 36 Podpod 85.7% 6 / 7 totaltotal 87.2% 191 / 219 CC 18 SCAR 7.7
CC
18
Cov
88%
__ANON__
6.0
new
5.4
_generate_full_description
3.2
CRAP 2.2
« blib/lib/Perl/Critic/Exception/Configuration/Option/Global/ParameterValue.pm ↑ Summary blib/lib/Perl/Critic/Policy/InputOutput/RequireCheckedClose.pm »
1 package Perl::Critic::PolicyParameter;
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 Exporter 'import';
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 40 Readonly::Array our @EXPORT_OK => qw{ $NO_DESCRIPTION_AVAILABLE };
11  
12 40 ▶use String::Format qw{ stringf };
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 use Perl::Critic::Exception::Fatal::PolicyDefinition
15 40 ▶ qw{ throw_policy_definition };
Subroutine BEGIN: called CC=1 SCAR=0.0
16 40 ▶use Perl::Critic::PolicyParameter::Behavior;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 40 ▶use Perl::Critic::PolicyParameter::Behavior::Boolean;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 40 ▶use Perl::Critic::PolicyParameter::Behavior::Enumeration;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 40 ▶use Perl::Critic::PolicyParameter::Behavior::Integer;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 40 ▶use Perl::Critic::PolicyParameter::Behavior::String;
Subroutine BEGIN: called CC=1 SCAR=0.0
21 40 ▶use Perl::Critic::PolicyParameter::Behavior::StringList;
Subroutine BEGIN: called CC=1 SCAR=0.0
22  
23 40 ▶use Perl::Critic::Utils qw( :characters interpolate );
Subroutine BEGIN: called CC=1 SCAR=0.0
24  
25 40 our $VERSION = '1.150';
26  
27 40 Readonly::Scalar our $NO_DESCRIPTION_AVAILABLE => 'No description available.';
28  
29 #-----------------------------------------------------------------------------
30  
31 # Grrr... one of the OO limitations of Perl: you can't put references to
32 # subclases in a superclass (well, not nicely). This map and method belong
33 # in Behavior.pm.
34 40 Readonly::Hash my %BEHAVIORS =>
35 (
36 'boolean' => Perl::Critic::PolicyParameter::Behavior::Boolean->new(),
37 'enumeration' => Perl::Critic::PolicyParameter::Behavior::Enumeration->new(),
38 'integer' => Perl::Critic::PolicyParameter::Behavior::Integer->new(),
39 'string' => Perl::Critic::PolicyParameter::Behavior::String->new(),
40 'string list' => Perl::Critic::PolicyParameter::Behavior::StringList->new(),
41 );
42  
43 sub _get_behavior_for_name {
44 9835 ▶ my $behavior_name = shift;
Subroutine _get_behavior_for_name: called CC=2 SCAR=7.1
45  
46 9835 ▶ my $behavior = $BEHAVIORS{$behavior_name}
Branch: 1 branch
BranchTrueFalseTotal
my $behavior = $BEHAVIORS{$behavior_name} or throw_policy_definition(qq[There's no "$behavior_name" behavior.]) 0 9835 9835
47 or throw_policy_definition qq{There's no "$behavior_name" behavior.};
48  
49 9835 return $behavior;
50 }
51  
52 #-----------------------------------------------------------------------------
53  
54 sub new {
55 9835 ▶ my ($class, $specification) = @_;
Subroutine new: called CC=5 SCAR=16.9
Pod undocumented
56 9835 my $self = bless {}, $class;
57  
58 9835 ▶ defined $specification
Branch: 1 branch
BranchTrueFalseTotal
defined $specification or throw_policy_definition("Attempt to create a ", __PACKAGE__, " without a specification.") 0 9835 9835
59 or throw_policy_definition
60 'Attempt to create a ', __PACKAGE__, ' without a specification.';
61  
62 9835 my $behavior_specification;
63  
64 9835 my $specification_type = ref $specification;
65 9835 ▶ if ( not $specification_type ) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $specification_type) { } 0 9835 9835
66 0 $self->{_name} = $specification;
67  
68 0 $behavior_specification = {};
69 } else {
70 9835 ▶ $specification_type eq 'HASH'
Branch: 1 branch
BranchTrueFalseTotal
$specification_type eq "HASH" or throw_policy_definition("Attempt to create a ", __PACKAGE__, " with a $specification_type as a specification.") 0 9835 9835
71 or throw_policy_definition
72 'Attempt to create a ',
73 __PACKAGE__,
74 " with a $specification_type as a specification.",
75 ;
76  
77 defined $specification->{name}
78 9835 ▶ or throw_policy_definition
Branch: 1 branch
BranchTrueFalseTotal
defined $specification->{"name"} or throw_policy_definition("Attempt to create a ", __PACKAGE__, " without a name.") 0 9835 9835
79 'Attempt to create a ', __PACKAGE__, ' without a name.';
80 9835 $self->{_name} = $specification->{name};
81  
82 9835 $behavior_specification = $specification;
83 }
84  
85 9835 $self->_initialize_from_behavior($behavior_specification);
86 9831 $self->_finish_standard_initialization($behavior_specification);
87  
88 9831 return $self;
89 }
90  
91 # See if the specification includes a Behavior name, and if so, let the
92 # Behavior with that name plug in its implementations of parser, etc.
93 sub _initialize_from_behavior {
94 9835 ▶ my ($self, $specification) = @_;
Subroutine _initialize_from_behavior: called CC=2 SCAR=6.9
95  
96 9835 my $behavior_name = $specification->{behavior};
97 9835 my $behavior;
98 9835 ▶ if ($behavior_name) {
Branch: 1 branch
BranchTrueFalseTotal
if ($behavior_name) { } 8820 1015 9835
99 8820 $behavior = _get_behavior_for_name($behavior_name);
100 } else {
101 1015 $behavior = _get_behavior_for_name('string');
102 }
103  
104 9835 $self->{_behavior} = $behavior;
105 9835 $self->{_behavior_values} = {};
106  
107 9835 $behavior->initialize_parameter($self, $specification);
108  
109 9831 return;
110 }
111  
112 # Grab the rest of the values out of the specification, including overrides
113 # of what the Behavior specified.
114 sub _finish_standard_initialization {
115 9831 ▶ my ($self, $specification) = @_;
Subroutine _finish_standard_initialization: called CC=2 SCAR=7.1
116  
117 my $description =
118 9831 ▶ $specification->{description} || $NO_DESCRIPTION_AVAILABLE;
Condition33%1/3
$specification->{'description'} || $Perl::Critic::PolicyParameter::NO_DESCRIPTION_AVAILABLE
l!l&&r!l&&!r
983100
MC/DC0%0/2
$specification->{'description'} || $Perl::Critic::PolicyParameter::NO_DESCRIPTION_AVAILABLE
$specification->{'description'} $Perl::Critic::PolicyParameter::NO_DESCRIPTION_AVAILABLE
Truth table33%1/3
A || B
A= $specification->{'description'}B= $Perl::Critic::PolicyParameter::NO_DESCRIPTION_AVAILABLE
ABresult
1X1
011
000
119 9831 $self->_set_description($description);
120 9831 $self->_set_default_string($specification->{default_string});
121  
122 9831 $self->_set_parser($specification->{parser});
123  
124 9831 return;
125 }
126  
127 #-----------------------------------------------------------------------------
128  
129 sub get_name {
130 29478 ▶ my $self = shift;
Subroutine get_name: called CC=1 SCAR=0.0
Pod documented
131  
132 29478 return $self->{_name};
133 }
134  
135 #-----------------------------------------------------------------------------
136  
137 sub get_description {
138 1045 ▶ my $self = shift;
Subroutine get_description: called CC=1 SCAR=0.0
Pod documented
139  
140 1045 return $self->{_description};
141 }
142  
143 sub _set_description {
144 9831 ▶ my ($self, $new_value) = @_;
Subroutine _set_description: called CC=2 SCAR=7.0
145  
146 9831 ▶ return if not defined $new_value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $new_value 0 9831 9831
147 9831 $self->{_description} = $new_value;
148  
149 9831 return;
150 }
151  
152 sub _get_description_with_trailing_period {
153 940 ▶ my $self = shift;
Subroutine _get_description_with_trailing_period: called CC=3 SCAR=11.2
154  
155 940 my $description = $self->get_description();
156 940 ▶ if ($description) {
Branch: 1 branch
BranchTrueFalseTotal
if ($description) { } 940 0 940
157 940 ▶ if ( $PERIOD ne substr $description, ( length $description ) - 1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Perl::Critic::PolicyParameter::PERIOD ne substr($description, length($description) - 1)) 99 841 940
158 99 $description .= $PERIOD;
159 }
160 } else {
161 0 $description = $EMPTY;
162 }
163  
164 940 return $description;
165 }
166  
167 #-----------------------------------------------------------------------------
168  
169 sub get_default_string {
170 9786 ▶ my $self = shift;
Subroutine get_default_string: called CC=1 SCAR=0.0
Pod documented
171  
172 9786 return $self->{_default_string};
173 }
174  
175 sub _set_default_string {
176 9831 ▶ my ($self, $new_value) = @_;
Subroutine _set_default_string: called CC=2 SCAR=6.9
177  
178 9831 ▶ return if not defined $new_value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $new_value 829 9002 9831
179 9002 $self->{_default_string} = $new_value;
180  
181 9002 return;
182 }
183  
184 #-----------------------------------------------------------------------------
185  
186 sub _get_behavior {
187 940 ▶ my $self = shift;
Subroutine _get_behavior: called CC=1 SCAR=0.0
188  
189 940 return $self->{_behavior};
190 }
191  
192 sub _get_behavior_values {
193 7525 ▶ my $self = shift;
Subroutine _get_behavior_values: called CC=1 SCAR=0.0
194  
195 7525 return $self->{_behavior_values};
196 }
197  
198 #-----------------------------------------------------------------------------
199  
200 sub _get_parser {
201 9765 ▶ my $self = shift;
Subroutine _get_parser: called CC=1 SCAR=0.0
202  
203 9765 return $self->{_parser};
204 }
205  
206 sub _set_parser {
207 19662 ▶ my ($self, $new_value) = @_;
Subroutine _set_parser: called CC=2 SCAR=6.9
208  
209 19662 ▶ return if not defined $new_value;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $new_value 8635 11027 19662
210 11027 $self->{_parser} = $new_value;
211  
212 11027 return;
213 }
214  
215 #-----------------------------------------------------------------------------
216  
217 sub parse_and_validate_config_value {
218 9765 ▶ my ($self, $policy, $config) = @_;
Subroutine parse_and_validate_config_value: called CC=2 SCAR=7.0
Pod documented
219  
220 9765 my $config_string = $config->{$self->get_name()};
221  
222 9765 my $parser = $self->_get_parser();
223 9765 ▶ if ($parser) {
Branch: 1 branch
BranchTrueFalseTotal
if ($parser) 9765 0 9765
224 9765 $parser->($policy, $self, $config_string);
225 }
226  
227 9757 return;
228 }
229  
230 #-----------------------------------------------------------------------------
231  
232 sub generate_full_description {
233 940 ▶ my ($self) = @_;
Subroutine generate_full_description: called CC=1 SCAR=0.0
Pod documented
234  
235 940 return $self->_get_behavior()->generate_parameter_description($self);
236 }
237  
238 #-----------------------------------------------------------------------------
239  
240 sub _generate_full_description {
241 940 ▶ my ($self, $prefix) = @_;
Subroutine _generate_full_description: called CC=3 SCAR=11.6
242  
243 940 my $description = $self->generate_full_description();
244  
245 940 ▶ if (not $description) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($description) 0 940 940
246 0 return $EMPTY;
247 }
248  
249 940 ▶ if ($prefix) {
Branch: 1 branch
BranchTrueFalseTotal
if ($prefix) 940 0 940
250 940 $description =~ s/ ^ /$prefix/xmsg;
251 }
252  
253 940 return $description;
254 }
255  
256 #-----------------------------------------------------------------------------
257  
258 sub to_formatted_string {
259 940 ▶ my ($self, $format) = @_;
Subroutine to_formatted_string: called CC=1 SCAR=0.6
Pod documented
260  
261 my %specification = (
262 940 ▶ n => sub { $self->get_name() },
Subroutine __ANON__: called CC=1 SCAR=0.0
263 0 ▶ d => sub { $self->get_description() // $EMPTY },
Subroutine __ANON__: not called CC=2 SCAR=17.9
Condition0%0/3
$self->get_description // $Perl::Critic::PolicyParameter::EMPTY
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->get_description // $Perl::Critic::PolicyParameter::EMPTY
$self->get_description $Perl::Critic::PolicyParameter::EMPTY
Truth table0%0/3
A // B
A= $self->get_descriptionB= $Perl::Critic::PolicyParameter::EMPTY
ABresult
1X1
011
000
264 940 ▶ D => sub { $self->get_default_string() // $EMPTY },
Subroutine __ANON__: called CC=2 SCAR=7.2
Condition66%2/3
$self->get_default_string // $Perl::Critic::PolicyParameter::EMPTY
l!l&&r!l&&!r
859081
MC/DC50%1/2
$self->get_default_string // $Perl::Critic::PolicyParameter::EMPTY
$self->get_default_string $Perl::Critic::PolicyParameter::EMPTY
Truth table66%2/3
A // B
A= $self->get_default_stringB= $Perl::Critic::PolicyParameter::EMPTY
ABresult
1X1
011
000
265 940 ▶ f => sub { $self->_generate_full_description(@_) },
Subroutine __ANON__: called CC=1 SCAR=0.0
266 940 );
267  
268 940 return stringf( interpolate($format), %specification );
269 }
270  
271 #-----------------------------------------------------------------------------
272  
273 40 1;
274  
275 __END__
276  
277 #-----------------------------------------------------------------------------
278  
279 =pod
280  
281 =for stopwords parsable
282  
283 =head1 NAME
284  
285 Perl::Critic::PolicyParameter - Metadata about a parameter for a Policy.
286  
287  
288 =head1 DESCRIPTION
289  
290 A provider of validation and parsing of parameter values and metadata
291 about the parameter.
292  
293  
294 =head1 INTERFACE SUPPORT
295  
296 This is considered to be a public class. Any changes to its interface
297 will go through a deprecation cycle.
298  
299  
300 =head1 METHODS
301  
302 =over
303  
304 =item C<get_name()>
305  
306 Return the name of the parameter. This is the key that will be looked
307 for in the F<.perlcriticrc>.
308  
309  
310 =item C<get_description()>
311  
312 Return an explanation of the significance of the parameter, as
313 provided by the developer of the policy.
314  
315  
316 =item C<get_default_string()>
317  
318 Return a representation of the default value of this parameter as it
319 would appear if it was specified in a F<.perlcriticrc> file.
320  
321  
322 =item C<parse_and_validate_config_value( $parser, $config )>
323  
324 Extract the configuration value for this parameter from the overall
325 configuration and initialize the policy based upon it.
326  
327  
328 =item C<generate_full_description()>
329  
330 Produce a more complete explanation of the significance of this
331 parameter than the value returned by C<get_description()>.
332  
333 If no description can be derived, returns the empty string.
334  
335 Note that the result may contain multiple lines.
336  
337  
338 =item C<to_formatted_string( $format )>
339  
340 Generate a string representation of this parameter, based upon the
341 format.
342  
343 The format is a combination of literal and escape characters similar
344 to the way C<sprintf> works. If you want to know the specific
345 formatting capabilities, look at L<String::Format|String::Format>.
346 Valid escape characters are:
347  
348 =over
349  
350 =item C<%n>
351  
352 The name of the parameter.
353  
354 =item C<%d>
355  
356 The description, as supplied by the programmer.
357  
358 =item C<%D>
359  
360 The default value, in a parsable form.
361  
362 =item C<%f>
363  
364 The full description, which is an extension of the value returned by
365 C<%d>. Takes a parameter of a prefix for the beginning of each line.
366  
367  
368 =back
369  
370  
371 =back
372  
373  
374 =head1 SEE ALSO
375  
376 L<Perl::Critic::DEVELOPER/"MAKING YOUR POLICY CONFIGURABLE">
377  
378  
379 =head1 AUTHOR
380  
381 Elliot Shank <perl@galumph.com>
382  
383 =head1 COPYRIGHT
384  
385 Copyright (c) 2006-2023 Elliot Shank.
386  
387 This program is free software; you can redistribute it and/or modify
388 it under the same terms as Perl itself. The full text of this license
389 can be found in the LICENSE file included with this module.
390  
391 =cut
392  
393 # Local Variables:
394 # mode: cperl
395 # cperl-indent-level: 4
396 # fill-column: 78
397 # indent-tabs-mode: nil
398 # c-indentation-style: bsd
399 # End:
400 # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :
« blib/lib/Perl/Critic/Exception/Configuration/Option/Global/ParameterValue.pm ↑ Summary blib/lib/Perl/Critic/Policy/InputOutput/RequireCheckedClose.pm »