« blib/lib/Perl/Critic/Policy/ValuesAndExpressions/ProhibitQuotesAsQuotelikeOperatorDelimiters.pm
↑ Summary
blib/lib/Perl/Critic/Exception/AggregateConfiguration.pm »
| 1 | package Perl::Critic::Policy; | ||||||||||||||||||||
| 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 English qw< -no_match_vars >; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 8 | 40 | ▶ | use Readonly; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | |||||||||||||||||||||
| 10 | 40 | ▶ | use File::Spec (); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 11 | 40 | ▶ | use String::Format qw< stringf >; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 12 | |||||||||||||||||||||
| 13 | 40 | ▶ | use overload ( q<""> => 'to_string', cmp => '_compare' ); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 14 | |||||||||||||||||||||
| 15 | 40 | use Perl::Critic::Utils qw< | |||||||||||||||||||
| 16 | :characters | ||||||||||||||||||||
| 17 | :booleans | ||||||||||||||||||||
| 18 | :severities | ||||||||||||||||||||
| 19 | :data_conversion | ||||||||||||||||||||
| 20 | interpolate | ||||||||||||||||||||
| 21 | is_integer | ||||||||||||||||||||
| 22 | policy_long_name | ||||||||||||||||||||
| 23 | policy_short_name | ||||||||||||||||||||
| 24 | severity_to_number | ||||||||||||||||||||
| 25 | 40 | ▶ | >; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 26 | 40 | use Perl::Critic::Utils::POD qw< | |||||||||||||||||||
| 27 | get_module_abstract_for_module | ||||||||||||||||||||
| 28 | get_raw_module_abstract_for_module | ||||||||||||||||||||
| 29 | 40 | ▶ | >; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 30 | 40 | ▶ | use Perl::Critic::Exception::AggregateConfiguration; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 31 | 40 | ▶ | use Perl::Critic::Exception::Configuration; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 32 | 40 | ▶ | use Perl::Critic::Exception::Configuration::Option::Policy::ExtraParameter; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 33 | 40 | ▶ | use Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 34 | use Perl::Critic::Exception::Fatal::PolicyDefinition | ||||||||||||||||||||
| 35 | 40 | ▶ | qw< throw_policy_definition >; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 36 | 40 | ▶ | use Perl::Critic::PolicyConfig qw<>; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 37 | 40 | ▶ | use Perl::Critic::PolicyParameter qw<>; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 38 | 40 | ▶ | use Perl::Critic::Violation qw<>; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 39 | |||||||||||||||||||||
| 40 | 40 | ▶ | use Exception::Class; # this must come after "use P::C::Exception::*" | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 41 | |||||||||||||||||||||
| 42 | 40 | our $VERSION = '1.150'; | |||||||||||||||||||
| 43 | |||||||||||||||||||||
| 44 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 45 | |||||||||||||||||||||
| 46 | 40 | Readonly::Scalar my $NO_LIMIT => 'no_limit'; | |||||||||||||||||||
| 47 | |||||||||||||||||||||
| 48 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 49 | |||||||||||||||||||||
| 50 | 40 | my $format = '%p'; #Default stringy format | |||||||||||||||||||
| 51 | |||||||||||||||||||||
| 52 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 53 | |||||||||||||||||||||
| 54 | sub new { | ||||||||||||||||||||
| 55 | 12979 | ▶ | my ($class, %config) = @_; | ||||||||||||||||||
|
Subroutine
new: called CC=7 SCAR=19.5
Pod
documented
| |||||||||||||||||||||
| 56 | |||||||||||||||||||||
| 57 | 12979 | my $self = bless {}, $class; | |||||||||||||||||||
| 58 | |||||||||||||||||||||
| 59 | 12979 | my $config_object; | |||||||||||||||||||
| 60 | 12979 | ▶ | if ($config{_config_object}) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 61 | 0 | $config_object = $config{_config_object}; | |||||||||||||||||||
| 62 | } | ||||||||||||||||||||
| 63 | else { | ||||||||||||||||||||
| 64 | 12979 | $config_object = | |||||||||||||||||||
| 65 | Perl::Critic::PolicyConfig->new( | ||||||||||||||||||||
| 66 | $self->get_short_name(), | ||||||||||||||||||||
| 67 | \%config, | ||||||||||||||||||||
| 68 | ); | ||||||||||||||||||||
| 69 | } | ||||||||||||||||||||
| 70 | |||||||||||||||||||||
| 71 | 12979 | $self->__set_config( $config_object ); | |||||||||||||||||||
| 72 | |||||||||||||||||||||
| 73 | 12979 | my @parameters; | |||||||||||||||||||
| 74 | 12979 | my $parameter_metadata_available = 0; | |||||||||||||||||||
| 75 | |||||||||||||||||||||
| 76 | 12979 | ▶ | if ( $class->can('supported_parameters') ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 77 | 12919 | $parameter_metadata_available = 1; | |||||||||||||||||||
| 78 | @parameters = | ||||||||||||||||||||
| 79 | map | ||||||||||||||||||||
| 80 | 12919 | { Perl::Critic::PolicyParameter->new($_) } | |||||||||||||||||||
| 81 | $class->supported_parameters(); | ||||||||||||||||||||
| 82 | } | ||||||||||||||||||||
| 83 | 12979 | $self->{_parameter_metadata_available} = $parameter_metadata_available; | |||||||||||||||||||
| 84 | 12979 | $self->{_parameters} = \@parameters; | |||||||||||||||||||
| 85 | |||||||||||||||||||||
| 86 | 12979 | my $errors = Perl::Critic::Exception::AggregateConfiguration->new(); | |||||||||||||||||||
| 87 | 12979 | foreach my $parameter ( @parameters ) { | |||||||||||||||||||
| 88 | eval { | ||||||||||||||||||||
| 89 | 9709 | $parameter->parse_and_validate_config_value( $self, $config_object ); | |||||||||||||||||||
| 90 | } | ||||||||||||||||||||
| 91 | 9709 | ▶ | or do { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 92 | 9709 | $errors->add_exception_or_rethrow($EVAL_ERROR); | |||||||||||||||||||
| 93 | }; | ||||||||||||||||||||
| 94 | |||||||||||||||||||||
| 95 | 9709 | $config_object->remove( $parameter->get_name() ); | |||||||||||||||||||
| 96 | } | ||||||||||||||||||||
| 97 | |||||||||||||||||||||
| 98 | 12979 | ▶ | if ($parameter_metadata_available) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 99 | 12919 | $config_object->handle_extra_parameters( $self, $errors ); | |||||||||||||||||||
| 100 | } | ||||||||||||||||||||
| 101 | |||||||||||||||||||||
| 102 | 12979 | ▶ | if ( $errors->has_exceptions() ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 103 | 146 | $errors->rethrow(); | |||||||||||||||||||
| 104 | } | ||||||||||||||||||||
| 105 | |||||||||||||||||||||
| 106 | 12833 | return $self; | |||||||||||||||||||
| 107 | } | ||||||||||||||||||||
| 108 | |||||||||||||||||||||
| 109 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 110 | |||||||||||||||||||||
| 111 | sub is_safe { | ||||||||||||||||||||
| 112 | 11164 | ▶ | return $TRUE; | ||||||||||||||||||
|
Subroutine
is_safe: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 113 | } | ||||||||||||||||||||
| 114 | |||||||||||||||||||||
| 115 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 116 | |||||||||||||||||||||
| 117 | sub initialize_if_enabled { | ||||||||||||||||||||
| 118 | 7325 | ▶ | return $TRUE; | ||||||||||||||||||
|
Subroutine
initialize_if_enabled: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 119 | } | ||||||||||||||||||||
| 120 | |||||||||||||||||||||
| 121 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 122 | |||||||||||||||||||||
| 123 | sub prepare_to_scan_document { | ||||||||||||||||||||
| 124 | 4261 | ▶ | return $TRUE; | ||||||||||||||||||
|
Subroutine
prepare_to_scan_document: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 125 | } | ||||||||||||||||||||
| 126 | |||||||||||||||||||||
| 127 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 128 | |||||||||||||||||||||
| 129 | sub __get_parameter_name { | ||||||||||||||||||||
| 130 | 8947 | ▶ | my ( $self, $parameter ) = @_; | ||||||||||||||||||
|
Subroutine
__get_parameter_name: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 131 | |||||||||||||||||||||
| 132 | 8947 | return '_' . $parameter->get_name(); | |||||||||||||||||||
| 133 | } | ||||||||||||||||||||
| 134 | |||||||||||||||||||||
| 135 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 136 | |||||||||||||||||||||
| 137 | sub __set_parameter_value { | ||||||||||||||||||||
| 138 | 8848 | ▶ | my ( $self, $parameter, $value ) = @_; | ||||||||||||||||||
|
Subroutine
__set_parameter_value: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 139 | |||||||||||||||||||||
| 140 | 8848 | $self->{ $self->__get_parameter_name($parameter) } = $value; | |||||||||||||||||||
| 141 | |||||||||||||||||||||
| 142 | 8848 | return; | |||||||||||||||||||
| 143 | } | ||||||||||||||||||||
| 144 | |||||||||||||||||||||
| 145 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | sub __set_base_parameters { | ||||||||||||||||||||
| 148 | 12627 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
__set_base_parameters: called CC=5 SCAR=16.1
| |||||||||||||||||||||
| 149 | |||||||||||||||||||||
| 150 | 12627 | my $config = $self->__get_config(); | |||||||||||||||||||
| 151 | 12627 | my $errors = Perl::Critic::Exception::AggregateConfiguration->new(); | |||||||||||||||||||
| 152 | |||||||||||||||||||||
| 153 | 12627 | $self->_set_maximum_violations_per_document($errors); | |||||||||||||||||||
| 154 | |||||||||||||||||||||
| 155 | 12627 | my $user_severity = $config->get_severity(); | |||||||||||||||||||
| 156 | 12627 | ▶ | if ( defined $user_severity ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 157 | 866 | my $normalized_severity = severity_to_number( $user_severity ); | |||||||||||||||||||
| 158 | 865 | $self->set_severity( $normalized_severity ); | |||||||||||||||||||
| 159 | } | ||||||||||||||||||||
| 160 | |||||||||||||||||||||
| 161 | 12626 | my $user_set_themes = $config->get_set_themes(); | |||||||||||||||||||
| 162 | 12626 | ▶ | if ( defined $user_set_themes ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 163 | 145 | my @set_themes = words_from_string( $user_set_themes ); | |||||||||||||||||||
| 164 | 145 | $self->set_themes( @set_themes ); | |||||||||||||||||||
| 165 | } | ||||||||||||||||||||
| 166 | |||||||||||||||||||||
| 167 | 12626 | my $user_add_themes = $config->get_add_themes(); | |||||||||||||||||||
| 168 | 12626 | ▶ | if ( defined $user_add_themes ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 169 | 147 | my @add_themes = words_from_string( $user_add_themes ); | |||||||||||||||||||
| 170 | 147 | $self->add_themes( @add_themes ); | |||||||||||||||||||
| 171 | } | ||||||||||||||||||||
| 172 | |||||||||||||||||||||
| 173 | 12626 | ▶ | if ( $errors->has_exceptions() ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 174 | 0 | $errors->rethrow(); | |||||||||||||||||||
| 175 | } | ||||||||||||||||||||
| 176 | |||||||||||||||||||||
| 177 | 12626 | return; | |||||||||||||||||||
| 178 | } | ||||||||||||||||||||
| 179 | |||||||||||||||||||||
| 180 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 181 | |||||||||||||||||||||
| 182 | sub _set_maximum_violations_per_document { | ||||||||||||||||||||
| 183 | 12627 | ▶ | my ($self, $errors) = @_; | ||||||||||||||||||
|
Subroutine
_set_maximum_violations_per_document: called CC=4 SCAR=15.2
| |||||||||||||||||||||
| 184 | |||||||||||||||||||||
| 185 | 12627 | my $config = $self->__get_config(); | |||||||||||||||||||
| 186 | |||||||||||||||||||||
| 187 | 12627 | ▶ | if ( $config->is_maximum_violations_per_document_unlimited() ) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 188 | 12623 | return; | |||||||||||||||||||
| 189 | } | ||||||||||||||||||||
| 190 | |||||||||||||||||||||
| 191 | 4 | my $user_maximum_violations = | |||||||||||||||||||
| 192 | $config->get_maximum_violations_per_document(); | ||||||||||||||||||||
| 193 | |||||||||||||||||||||
| 194 | 4 | ▶ | if ( not is_integer($user_maximum_violations) ) { | ||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||
| 195 | 0 | $errors->add_exception( | |||||||||||||||||||
| 196 | new_parameter_value_exception( | ||||||||||||||||||||
| 197 | 'maximum_violations_per_document', | ||||||||||||||||||||
| 198 | $user_maximum_violations, | ||||||||||||||||||||
| 199 | undef, | ||||||||||||||||||||
| 200 | "does not look like an integer.\n" | ||||||||||||||||||||
| 201 | ) | ||||||||||||||||||||
| 202 | ); | ||||||||||||||||||||
| 203 | |||||||||||||||||||||
| 204 | 0 | return; | |||||||||||||||||||
| 205 | } | ||||||||||||||||||||
| 206 | elsif ( $user_maximum_violations < 0 ) { | ||||||||||||||||||||
| 207 | 0 | $errors->add_exception( | |||||||||||||||||||
| 208 | new_parameter_value_exception( | ||||||||||||||||||||
| 209 | 'maximum_violations_per_document', | ||||||||||||||||||||
| 210 | $user_maximum_violations, | ||||||||||||||||||||
| 211 | undef, | ||||||||||||||||||||
| 212 | "is not greater than or equal to zero.\n" | ||||||||||||||||||||
| 213 | ) | ||||||||||||||||||||
| 214 | ); | ||||||||||||||||||||
| 215 | |||||||||||||||||||||
| 216 | 0 | return; | |||||||||||||||||||
| 217 | } | ||||||||||||||||||||
| 218 | |||||||||||||||||||||
| 219 | $self->set_maximum_violations_per_document( | ||||||||||||||||||||
| 220 | 4 | $user_maximum_violations | |||||||||||||||||||
| 221 | ); | ||||||||||||||||||||
| 222 | |||||||||||||||||||||
| 223 | 4 | return; | |||||||||||||||||||
| 224 | } | ||||||||||||||||||||
| 225 | |||||||||||||||||||||
| 226 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 227 | |||||||||||||||||||||
| 228 | # Unparsed configuration, P::C::PolicyConfig. Compare with get_parameters(). | ||||||||||||||||||||
| 229 | sub __get_config { | ||||||||||||||||||||
| 230 | 33296 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
__get_config: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 231 | |||||||||||||||||||||
| 232 | 33296 | return $self->{_config}; | |||||||||||||||||||
| 233 | } | ||||||||||||||||||||
| 234 | |||||||||||||||||||||
| 235 | sub __set_config { | ||||||||||||||||||||
| 236 | 25606 | ▶ | my ($self, $config) = @_; | ||||||||||||||||||
|
Subroutine
__set_config: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 237 | |||||||||||||||||||||
| 238 | 25606 | $self->{_config} = $config; | |||||||||||||||||||
| 239 | |||||||||||||||||||||
| 240 | 25606 | return; | |||||||||||||||||||
| 241 | } | ||||||||||||||||||||
| 242 | |||||||||||||||||||||
| 243 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 244 | |||||||||||||||||||||
| 245 | sub get_long_name { | ||||||||||||||||||||
| 246 | 0 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_long_name: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 247 | |||||||||||||||||||||
| 248 | 0 | return policy_long_name(ref $self); | |||||||||||||||||||
| 249 | } | ||||||||||||||||||||
| 250 | |||||||||||||||||||||
| 251 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 252 | |||||||||||||||||||||
| 253 | sub get_short_name { | ||||||||||||||||||||
| 254 | 107449 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_short_name: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 255 | |||||||||||||||||||||
| 256 | 107449 | return policy_short_name(ref $self); | |||||||||||||||||||
| 257 | } | ||||||||||||||||||||
| 258 | |||||||||||||||||||||
| 259 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 260 | |||||||||||||||||||||
| 261 | sub is_enabled { | ||||||||||||||||||||
| 262 | 147 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
is_enabled: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 263 | |||||||||||||||||||||
| 264 | 147 | return $self->{_enabled}; | |||||||||||||||||||
| 265 | } | ||||||||||||||||||||
| 266 | |||||||||||||||||||||
| 267 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 268 | |||||||||||||||||||||
| 269 | sub __set_enabled { | ||||||||||||||||||||
| 270 | 8042 | ▶ | my ($self, $new_value) = @_; | ||||||||||||||||||
|
Subroutine
__set_enabled: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 271 | |||||||||||||||||||||
| 272 | 8042 | $self->{_enabled} = $new_value; | |||||||||||||||||||
| 273 | |||||||||||||||||||||
| 274 | 8042 | return; | |||||||||||||||||||
| 275 | } | ||||||||||||||||||||
| 276 | |||||||||||||||||||||
| 277 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 278 | |||||||||||||||||||||
| 279 | sub applies_to { | ||||||||||||||||||||
| 280 | 1 | ▶ | return qw(PPI::Element); | ||||||||||||||||||
|
Subroutine
applies_to: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 281 | } | ||||||||||||||||||||
| 282 | |||||||||||||||||||||
| 283 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 284 | |||||||||||||||||||||
| 285 | sub set_maximum_violations_per_document { | ||||||||||||||||||||
| 286 | 6 | ▶ | my ($self, $maximum_violations_per_document) = @_; | ||||||||||||||||||
|
Subroutine
set_maximum_violations_per_document: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 287 | |||||||||||||||||||||
| 288 | $self->{_maximum_violations_per_document} = | ||||||||||||||||||||
| 289 | 6 | $maximum_violations_per_document; | |||||||||||||||||||
| 290 | |||||||||||||||||||||
| 291 | 6 | return $self; | |||||||||||||||||||
| 292 | } | ||||||||||||||||||||
| 293 | |||||||||||||||||||||
| 294 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 295 | |||||||||||||||||||||
| 296 | sub get_maximum_violations_per_document { | ||||||||||||||||||||
| 297 | 6083 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_maximum_violations_per_document: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 298 | |||||||||||||||||||||
| 299 | return | ||||||||||||||||||||
| 300 | exists $self->{_maximum_violations_per_document} | ||||||||||||||||||||
| 301 | ? $self->{_maximum_violations_per_document} | ||||||||||||||||||||
| 302 | 6083 | ▶ | : $self->default_maximum_violations_per_document(); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 303 | } | ||||||||||||||||||||
| 304 | |||||||||||||||||||||
| 305 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 306 | |||||||||||||||||||||
| 307 | sub default_maximum_violations_per_document { | ||||||||||||||||||||
| 308 | 5934 | ▶ | return; | ||||||||||||||||||
|
Subroutine
default_maximum_violations_per_document: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 309 | } | ||||||||||||||||||||
| 310 | |||||||||||||||||||||
| 311 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 312 | |||||||||||||||||||||
| 313 | sub set_severity { | ||||||||||||||||||||
| 314 | 866 | ▶ | my ($self, $severity) = @_; | ||||||||||||||||||
|
Subroutine
set_severity: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 315 | 866 | $self->{_severity} = $severity; | |||||||||||||||||||
| 316 | 866 | return $self; | |||||||||||||||||||
| 317 | } | ||||||||||||||||||||
| 318 | |||||||||||||||||||||
| 319 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 320 | |||||||||||||||||||||
| 321 | sub get_severity { | ||||||||||||||||||||
| 322 | 13035 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_severity: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||
| 323 | 13035 | ▶ | return $self->{_severity} || $self->default_severity(); | ||||||||||||||||||
|
Condition66%2/3
$self->{'_severity'} || $self->default_severity
MC/DC0%0/2
$self->{'_severity'} || $self->default_severity
$self->{'_severity'}
$self->default_severity
Truth table66%2/3
A || B
A= $self->{'_severity'}B= $self->default_severity
| |||||||||||||||||||||
| 324 | } | ||||||||||||||||||||
| 325 | |||||||||||||||||||||
| 326 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 327 | |||||||||||||||||||||
| 328 | sub default_severity { | ||||||||||||||||||||
| 329 | 3 | ▶ | return $SEVERITY_LOWEST; | ||||||||||||||||||
|
Subroutine
default_severity: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 330 | } | ||||||||||||||||||||
| 331 | |||||||||||||||||||||
| 332 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 333 | |||||||||||||||||||||
| 334 | sub set_themes { | ||||||||||||||||||||
| 335 | 146 | ▶ | my ($self, @themes) = @_; | ||||||||||||||||||
|
Subroutine
set_themes: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 336 | 146 | $self->{_themes} = [ sort @themes ]; | |||||||||||||||||||
| 337 | 146 | return $self; | |||||||||||||||||||
| 338 | } | ||||||||||||||||||||
| 339 | |||||||||||||||||||||
| 340 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 341 | |||||||||||||||||||||
| 342 | sub get_themes { | ||||||||||||||||||||
| 343 | 13310 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_themes: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 344 | 13310 | ▶ | my @themes = defined $self->{_themes} ? @{ $self->{_themes} } : $self->default_themes(); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 345 | 13310 | my @sorted_themes = sort @themes; | |||||||||||||||||||
| 346 | 13310 | return @sorted_themes; | |||||||||||||||||||
| 347 | } | ||||||||||||||||||||
| 348 | |||||||||||||||||||||
| 349 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 350 | |||||||||||||||||||||
| 351 | sub add_themes { | ||||||||||||||||||||
| 352 | 148 | ▶ | my ($self, @additional_themes) = @_; | ||||||||||||||||||
|
Subroutine
add_themes: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 353 | #By hashifying the themes, we squish duplicates | ||||||||||||||||||||
| 354 | 148 | my %merged = hashify( $self->get_themes(), @additional_themes); | |||||||||||||||||||
| 355 | 148 | $self->{_themes} = [ keys %merged]; | |||||||||||||||||||
| 356 | 148 | return $self; | |||||||||||||||||||
| 357 | } | ||||||||||||||||||||
| 358 | |||||||||||||||||||||
| 359 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 360 | |||||||||||||||||||||
| 361 | sub default_themes { | ||||||||||||||||||||
| 362 | 4 | ▶ | return (); | ||||||||||||||||||
|
Subroutine
default_themes: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 363 | } | ||||||||||||||||||||
| 364 | |||||||||||||||||||||
| 365 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 366 | |||||||||||||||||||||
| 367 | sub get_abstract { | ||||||||||||||||||||
| 368 | 1303 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_abstract: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 369 | |||||||||||||||||||||
| 370 | 1303 | return get_module_abstract_for_module( ref $self ); | |||||||||||||||||||
| 371 | } | ||||||||||||||||||||
| 372 | |||||||||||||||||||||
| 373 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 374 | |||||||||||||||||||||
| 375 | sub get_raw_abstract { | ||||||||||||||||||||
| 376 | 0 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_raw_abstract: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 377 | |||||||||||||||||||||
| 378 | 0 | return get_raw_module_abstract_for_module( ref $self ); | |||||||||||||||||||
| 379 | } | ||||||||||||||||||||
| 380 | |||||||||||||||||||||
| 381 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 382 | |||||||||||||||||||||
| 383 | sub parameter_metadata_available { | ||||||||||||||||||||
| 384 | 2892 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
parameter_metadata_available: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 385 | |||||||||||||||||||||
| 386 | 2892 | return $self->{_parameter_metadata_available}; | |||||||||||||||||||
| 387 | } | ||||||||||||||||||||
| 388 | |||||||||||||||||||||
| 389 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 390 | |||||||||||||||||||||
| 391 | sub get_parameters { | ||||||||||||||||||||
| 392 | 1587 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
get_parameters: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 393 | |||||||||||||||||||||
| 394 | 1587 | return $self->{_parameters}; | |||||||||||||||||||
| 395 | } | ||||||||||||||||||||
| 396 | |||||||||||||||||||||
| 397 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 398 | |||||||||||||||||||||
| 399 | sub violates { | ||||||||||||||||||||
| 400 | 1 | ▶ | my ($self) = @_; | ||||||||||||||||||
|
Subroutine
violates: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 401 | |||||||||||||||||||||
| 402 | 1 | return throw_policy_definition | |||||||||||||||||||
| 403 | $self->get_short_name() . q/ does not implement violates()./; | ||||||||||||||||||||
| 404 | } | ||||||||||||||||||||
| 405 | |||||||||||||||||||||
| 406 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 407 | |||||||||||||||||||||
| 408 | sub violation { ## no critic (ArgUnpacking) | ||||||||||||||||||||
| 409 | 277 | ▶ | my ( $self, $desc, $expl, $elem ) = @_; | ||||||||||||||||||
|
Subroutine
violation: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 410 | # HACK!! Use goto instead of an explicit call because P::C::V::new() uses caller() | ||||||||||||||||||||
| 411 | 277 | my $sev = $self->get_severity(); | |||||||||||||||||||
| 412 | 277 | @_ = ('Perl::Critic::Violation', $desc, $expl, $elem, $sev ); | |||||||||||||||||||
| 413 | 277 | goto &Perl::Critic::Violation::new; | |||||||||||||||||||
| 414 | } | ||||||||||||||||||||
| 415 | |||||||||||||||||||||
| 416 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 417 | |||||||||||||||||||||
| 418 | sub new_parameter_value_exception { | ||||||||||||||||||||
| 419 | 8 | ▶ | my ( $self, $option_name, $option_value, $source, $message_suffix ) = @_; | ||||||||||||||||||
|
Subroutine
new_parameter_value_exception: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 420 | |||||||||||||||||||||
| 421 | 8 | return Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue->new( | |||||||||||||||||||
| 422 | policy => $self->get_short_name(), | ||||||||||||||||||||
| 423 | option_name => $option_name, | ||||||||||||||||||||
| 424 | option_value => $option_value, | ||||||||||||||||||||
| 425 | source => $source, | ||||||||||||||||||||
| 426 | message_suffix => $message_suffix | ||||||||||||||||||||
| 427 | ); | ||||||||||||||||||||
| 428 | } | ||||||||||||||||||||
| 429 | |||||||||||||||||||||
| 430 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 431 | |||||||||||||||||||||
| 432 | ## no critic (Subroutines::RequireFinalReturn) | ||||||||||||||||||||
| 433 | sub throw_parameter_value_exception { | ||||||||||||||||||||
| 434 | 8 | ▶ | my ( $self, $option_name, $option_value, $source, $message_suffix ) = @_; | ||||||||||||||||||
|
Subroutine
throw_parameter_value_exception: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 435 | |||||||||||||||||||||
| 436 | 8 | $self->new_parameter_value_exception( | |||||||||||||||||||
| 437 | $option_name, $option_value, $source, $message_suffix | ||||||||||||||||||||
| 438 | ) | ||||||||||||||||||||
| 439 | ->throw(); | ||||||||||||||||||||
| 440 | } | ||||||||||||||||||||
| 441 | ## use critic | ||||||||||||||||||||
| 442 | |||||||||||||||||||||
| 443 | |||||||||||||||||||||
| 444 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 445 | |||||||||||||||||||||
| 446 | # Static methods. | ||||||||||||||||||||
| 447 | |||||||||||||||||||||
| 448 | 3 | ▶ | sub set_format { return $format = $_[0] } ## no critic(ArgUnpacking) | ||||||||||||||||||
|
Subroutine
set_format: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 449 | 93071 | ▶ | sub get_format { return $format } | ||||||||||||||||||
|
Subroutine
get_format: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 450 | |||||||||||||||||||||
| 451 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 452 | |||||||||||||||||||||
| 453 | sub to_string { | ||||||||||||||||||||
| 454 | 93069 | ▶ | my ($self, @args) = @_; | ||||||||||||||||||
|
Subroutine
to_string: called CC=1 SCAR=0.8
Pod
documented
| |||||||||||||||||||||
| 455 | |||||||||||||||||||||
| 456 | # Wrap the more expensive ones in sub{} to postpone evaluation | ||||||||||||||||||||
| 457 | my %fspec = ( | ||||||||||||||||||||
| 458 | 0 | ▶ | 'P' => sub { $self->get_long_name() }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 459 | 93069 | ▶ | 'p' => sub { $self->get_short_name() }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 460 | 1303 | ▶ | 'a' => sub { $self->get_abstract() // $EMPTY }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=9.2
Condition33%1/3
$self->get_abstract // $Perl::Critic::Policy::EMPTY
MC/DC0%0/2
$self->get_abstract // $Perl::Critic::Policy::EMPTY
$self->get_abstract
$Perl::Critic::Policy::EMPTY
Truth table33%1/3
A // B
A= $self->get_abstractB= $Perl::Critic::Policy::EMPTY
| |||||||||||||||||||||
| 461 | 1303 | ▶ | 'O' => sub { $self->_format_parameters(@_) }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 462 | 1303 | ▶ | 'U' => sub { $self->_format_lack_of_parameter_metadata(@_) }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 463 | 0 | ▶ | 'S' => sub { $self->default_severity() }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 464 | 1450 | ▶ | 's' => sub { $self->get_severity() }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 465 | 0 | ▶ | 'T' => sub { join $SPACE, $self->default_themes() }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||
| 466 | 1450 | ▶ | 't' => sub { join $SPACE, $self->get_themes() }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 467 | 0 | ▶ | 'V' => sub { $self->default_maximum_violations_per_document() // $NO_LIMIT }, | ||||||||||||||||||
|
Subroutine
__ANON__: not called CC=2 SCAR=17.9
Condition0%0/3
$self->default_maximum_violations_per_document // $NO_LIMIT
MC/DC0%0/2
$self->default_maximum_violations_per_document // $NO_LIMIT
$self->default_maximum_violations_per_document
$NO_LIMIT
Truth table0%0/3
A // B
A= $self->default_maximum_violations_per_documentB= $NO_LIMIT
| |||||||||||||||||||||
| 468 | 1303 | ▶ | 'v' => sub { $self->get_maximum_violations_per_document() // $NO_LIMIT }, | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=7.2
Condition66%2/3
$self->get_maximum_violations_per_document // $NO_LIMIT
MC/DC0%0/2
$self->get_maximum_violations_per_document // $NO_LIMIT
$self->get_maximum_violations_per_document
$NO_LIMIT
Truth table66%2/3
A // B
A= $self->get_maximum_violations_per_documentB= $NO_LIMIT
| |||||||||||||||||||||
| 469 | 93069 | ); | |||||||||||||||||||
| 470 | 93069 | return stringf(get_format(), %fspec); | |||||||||||||||||||
| 471 | } | ||||||||||||||||||||
| 472 | |||||||||||||||||||||
| 473 | sub _format_parameters { | ||||||||||||||||||||
| 474 | 1303 | ▶ | my ($self, $parameter_format) = @_; | ||||||||||||||||||
|
Subroutine
_format_parameters: called CC=3 SCAR=11.7
| |||||||||||||||||||||
| 475 | |||||||||||||||||||||
| 476 | 1303 | ▶ | return $EMPTY if not $self->parameter_metadata_available(); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 477 | |||||||||||||||||||||
| 478 | 1303 | my $separator; | |||||||||||||||||||
| 479 | 1303 | ▶ | if ($parameter_format) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 480 | 1303 | $separator = $EMPTY; | |||||||||||||||||||
| 481 | } else { | ||||||||||||||||||||
| 482 | 0 | $separator = $SPACE; | |||||||||||||||||||
| 483 | 0 | $parameter_format = '%n'; | |||||||||||||||||||
| 484 | } | ||||||||||||||||||||
| 485 | |||||||||||||||||||||
| 486 | return | ||||||||||||||||||||
| 487 | join | ||||||||||||||||||||
| 488 | $separator, | ||||||||||||||||||||
| 489 | 1303 | map { $_->to_formatted_string($parameter_format) } @{ $self->get_parameters() }; | |||||||||||||||||||
| 490 | } | ||||||||||||||||||||
| 491 | |||||||||||||||||||||
| 492 | sub _format_lack_of_parameter_metadata { | ||||||||||||||||||||
| 493 | 1303 | ▶ | my ($self, $message) = @_; | ||||||||||||||||||
|
Subroutine
_format_lack_of_parameter_metadata: called CC=3 SCAR=16.5
| |||||||||||||||||||||
| 494 | |||||||||||||||||||||
| 495 | 1303 | ▶ | return $EMPTY if $self->parameter_metadata_available(); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 496 | 0 | ▶ | return interpolate($message) if $message; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 497 | |||||||||||||||||||||
| 498 | return | ||||||||||||||||||||
| 499 | 0 | 'Cannot programmatically discover what parameters this policy takes.'; | |||||||||||||||||||
| 500 | } | ||||||||||||||||||||
| 501 | |||||||||||||||||||||
| 502 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 503 | # Apparently, some perls do not implicitly stringify overloading | ||||||||||||||||||||
| 504 | # objects before doing a comparison. This causes a couple of our | ||||||||||||||||||||
| 505 | # sorting tests to fail. To work around this, we overload C<cmp> to | ||||||||||||||||||||
| 506 | # do it explicitly. | ||||||||||||||||||||
| 507 | # | ||||||||||||||||||||
| 508 | # 20060503 - More information: This problem has been traced to | ||||||||||||||||||||
| 509 | # Test::Simple versions <= 0.60, not perl itself. Upgrading to | ||||||||||||||||||||
| 510 | # Test::Simple v0.62 will fix the problem. But rather than forcing | ||||||||||||||||||||
| 511 | # everyone to upgrade, I have decided to leave this workaround in | ||||||||||||||||||||
| 512 | # place. | ||||||||||||||||||||
| 513 | |||||||||||||||||||||
| 514 | 142 | ▶ | sub _compare { return "$_[0]" cmp "$_[1]" } | ||||||||||||||||||
|
Subroutine
_compare: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 515 | |||||||||||||||||||||
| 516 | 40 | 1; | |||||||||||||||||||
| 517 | |||||||||||||||||||||
| 518 | __END__ | ||||||||||||||||||||
| 519 | |||||||||||||||||||||
| 520 | #----------------------------------------------------------------------------- | ||||||||||||||||||||
| 521 | |||||||||||||||||||||
| 522 | =pod | ||||||||||||||||||||
| 523 | |||||||||||||||||||||
| 524 | =head1 NAME | ||||||||||||||||||||
| 525 | |||||||||||||||||||||
| 526 | Perl::Critic::Policy - Base class for all Policy modules. | ||||||||||||||||||||
| 527 | |||||||||||||||||||||
| 528 | |||||||||||||||||||||
| 529 | =head1 DESCRIPTION | ||||||||||||||||||||
| 530 | |||||||||||||||||||||
| 531 | Perl::Critic::Policy is the abstract base class for all Policy | ||||||||||||||||||||
| 532 | objects. If you're developing your own Policies, your job is to | ||||||||||||||||||||
| 533 | implement and override its methods in a subclass. To work with the | ||||||||||||||||||||
| 534 | L<Perl::Critic|Perl::Critic> engine, your implementation must behave | ||||||||||||||||||||
| 535 | as described below. For a detailed explanation on how to make new | ||||||||||||||||||||
| 536 | Policy modules, please see the | ||||||||||||||||||||
| 537 | L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> document included | ||||||||||||||||||||
| 538 | in this distribution. | ||||||||||||||||||||
| 539 | |||||||||||||||||||||
| 540 | |||||||||||||||||||||
| 541 | =head1 INTERFACE SUPPORT | ||||||||||||||||||||
| 542 | |||||||||||||||||||||
| 543 | This is considered to be a public class. Any changes to its interface | ||||||||||||||||||||
| 544 | will go through a deprecation cycle. | ||||||||||||||||||||
| 545 | |||||||||||||||||||||
| 546 | |||||||||||||||||||||
| 547 | =head1 METHODS | ||||||||||||||||||||
| 548 | |||||||||||||||||||||
| 549 | =over | ||||||||||||||||||||
| 550 | |||||||||||||||||||||
| 551 | =item C<< new( ... ) >> | ||||||||||||||||||||
| 552 | |||||||||||||||||||||
| 553 | Don't call this. As a Policy author, do not implement this. Use the | ||||||||||||||||||||
| 554 | C<initialize_if_enabled()> method for your Policy setup. See the | ||||||||||||||||||||
| 555 | L<developer|Perl::Critic::DEVELOPER> documentation for more. | ||||||||||||||||||||
| 556 | |||||||||||||||||||||
| 557 | |||||||||||||||||||||
| 558 | =item C<< initialize_if_enabled( $config ) >> | ||||||||||||||||||||
| 559 | |||||||||||||||||||||
| 560 | This receives an instance of | ||||||||||||||||||||
| 561 | L<Perl::Critic::PolicyConfig|Perl::Critic::PolicyConfig> as a | ||||||||||||||||||||
| 562 | parameter, and is only invoked if this Policy is enabled by the user. | ||||||||||||||||||||
| 563 | Thus, this is the preferred place for subclasses to do any | ||||||||||||||||||||
| 564 | initialization. | ||||||||||||||||||||
| 565 | |||||||||||||||||||||
| 566 | Implementations of this method should return a boolean value | ||||||||||||||||||||
| 567 | indicating whether the Policy should continue to be enabled. For most | ||||||||||||||||||||
| 568 | subclasses, this will always be C<$TRUE>. Policies that depend upon | ||||||||||||||||||||
| 569 | external modules or other system facilities that may or may not be | ||||||||||||||||||||
| 570 | available should test for the availability of these dependencies and | ||||||||||||||||||||
| 571 | return C<$FALSE> if they are not. | ||||||||||||||||||||
| 572 | |||||||||||||||||||||
| 573 | |||||||||||||||||||||
| 574 | =item C<< prepare_to_scan_document( $document ) >> | ||||||||||||||||||||
| 575 | |||||||||||||||||||||
| 576 | The parameter is about to be scanned by this Policy. Whatever this | ||||||||||||||||||||
| 577 | Policy wants to do in terms of preparation should happen here. | ||||||||||||||||||||
| 578 | Returns a boolean value indicating whether the document should be | ||||||||||||||||||||
| 579 | scanned at all; if this is a false value, this Policy won't be applied | ||||||||||||||||||||
| 580 | to the document. By default, does nothing but return C<$TRUE>. | ||||||||||||||||||||
| 581 | |||||||||||||||||||||
| 582 | |||||||||||||||||||||
| 583 | =item C< violates( $element, $document ) > | ||||||||||||||||||||
| 584 | |||||||||||||||||||||
| 585 | Given a L<PPI::Element|PPI::Element> and a | ||||||||||||||||||||
| 586 | L<PPI::Document|PPI::Document>, returns one or more | ||||||||||||||||||||
| 587 | L<Perl::Critic::Violation|Perl::Critic::Violation> objects if the | ||||||||||||||||||||
| 588 | C<$element> violates this Policy. If there are no violations, then it | ||||||||||||||||||||
| 589 | returns an empty list. If the Policy encounters an exception, then it | ||||||||||||||||||||
| 590 | should C<croak> with an error message and let the caller decide how to | ||||||||||||||||||||
| 591 | handle it. | ||||||||||||||||||||
| 592 | |||||||||||||||||||||
| 593 | C<violates()> is an abstract method and it will abort if you attempt | ||||||||||||||||||||
| 594 | to invoke it directly. It is the heart of all Policy modules, and | ||||||||||||||||||||
| 595 | your subclass B<must> override this method. | ||||||||||||||||||||
| 596 | |||||||||||||||||||||
| 597 | |||||||||||||||||||||
| 598 | =item C< violation( $description, $explanation, $element ) > | ||||||||||||||||||||
| 599 | |||||||||||||||||||||
| 600 | Returns a reference to a new C<Perl::Critic::Violation> object. The | ||||||||||||||||||||
| 601 | arguments are a description of the violation (as string), an | ||||||||||||||||||||
| 602 | explanation for the policy (as string) or a series of page numbers in | ||||||||||||||||||||
| 603 | PBP (as an ARRAY ref), a reference to the L<PPI|PPI> element that | ||||||||||||||||||||
| 604 | caused the violation. | ||||||||||||||||||||
| 605 | |||||||||||||||||||||
| 606 | These are the same as the constructor to | ||||||||||||||||||||
| 607 | L<Perl::Critic::Violation|Perl::Critic::Violation>, but without the | ||||||||||||||||||||
| 608 | severity. The Policy itself knows the severity. | ||||||||||||||||||||
| 609 | |||||||||||||||||||||
| 610 | |||||||||||||||||||||
| 611 | =item C< new_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) > | ||||||||||||||||||||
| 612 | |||||||||||||||||||||
| 613 | Create a | ||||||||||||||||||||
| 614 | L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue> | ||||||||||||||||||||
| 615 | for this Policy. | ||||||||||||||||||||
| 616 | |||||||||||||||||||||
| 617 | |||||||||||||||||||||
| 618 | =item C< throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) > | ||||||||||||||||||||
| 619 | |||||||||||||||||||||
| 620 | Create and throw a | ||||||||||||||||||||
| 621 | L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>. | ||||||||||||||||||||
| 622 | Useful in parameter parser implementations. | ||||||||||||||||||||
| 623 | |||||||||||||||||||||
| 624 | |||||||||||||||||||||
| 625 | =item C< get_long_name() > | ||||||||||||||||||||
| 626 | |||||||||||||||||||||
| 627 | Return the full package name of this policy. | ||||||||||||||||||||
| 628 | |||||||||||||||||||||
| 629 | |||||||||||||||||||||
| 630 | =item C< get_short_name() > | ||||||||||||||||||||
| 631 | |||||||||||||||||||||
| 632 | Return the name of this policy without the "Perl::Critic::Policy::" | ||||||||||||||||||||
| 633 | prefix. | ||||||||||||||||||||
| 634 | |||||||||||||||||||||
| 635 | |||||||||||||||||||||
| 636 | =item C< is_enabled() > | ||||||||||||||||||||
| 637 | |||||||||||||||||||||
| 638 | Answer whether this policy is really active or not. Returns a true | ||||||||||||||||||||
| 639 | value if it is, a false, yet defined, value if it isn't, and an | ||||||||||||||||||||
| 640 | undefined value if it hasn't yet been decided whether it will be. | ||||||||||||||||||||
| 641 | |||||||||||||||||||||
| 642 | |||||||||||||||||||||
| 643 | =item C< applies_to() > | ||||||||||||||||||||
| 644 | |||||||||||||||||||||
| 645 | Returns a list of the names of PPI classes that this Policy cares | ||||||||||||||||||||
| 646 | about. By default, the result is C<PPI::Element>. Overriding this | ||||||||||||||||||||
| 647 | method in Policy subclasses should lead to significant performance | ||||||||||||||||||||
| 648 | increases. | ||||||||||||||||||||
| 649 | |||||||||||||||||||||
| 650 | |||||||||||||||||||||
| 651 | =item C< default_maximum_violations_per_document() > | ||||||||||||||||||||
| 652 | |||||||||||||||||||||
| 653 | Returns the default maximum number of violations for this policy to | ||||||||||||||||||||
| 654 | report per document. By default, this not defined, but subclasses may | ||||||||||||||||||||
| 655 | override this. | ||||||||||||||||||||
| 656 | |||||||||||||||||||||
| 657 | |||||||||||||||||||||
| 658 | =item C< get_maximum_violations_per_document() > | ||||||||||||||||||||
| 659 | |||||||||||||||||||||
| 660 | Returns the maximum number of violations this policy will report for a | ||||||||||||||||||||
| 661 | single document. If this is not defined, then there is no limit. If | ||||||||||||||||||||
| 662 | L</set_maximum_violations_per_document()> has not been invoked, then | ||||||||||||||||||||
| 663 | L</default_maximum_violations_per_document()> is returned. | ||||||||||||||||||||
| 664 | |||||||||||||||||||||
| 665 | |||||||||||||||||||||
| 666 | =item C< set_maximum_violations_per_document() > | ||||||||||||||||||||
| 667 | |||||||||||||||||||||
| 668 | Specify the maximum violations that this policy should report for a | ||||||||||||||||||||
| 669 | document. | ||||||||||||||||||||
| 670 | |||||||||||||||||||||
| 671 | |||||||||||||||||||||
| 672 | =item C< default_severity() > | ||||||||||||||||||||
| 673 | |||||||||||||||||||||
| 674 | Returns the default severity for violating this Policy. See the | ||||||||||||||||||||
| 675 | C<$SEVERITY> constants in L<Perl::Critic::Utils|Perl::Critic::Utils> | ||||||||||||||||||||
| 676 | for an enumeration of possible severity values. By default, this | ||||||||||||||||||||
| 677 | method returns C<$SEVERITY_LOWEST>. Authors of Perl::Critic::Policy | ||||||||||||||||||||
| 678 | subclasses should override this method to return a value that they | ||||||||||||||||||||
| 679 | feel is appropriate for their Policy. In general, Polices that are | ||||||||||||||||||||
| 680 | widely accepted or tend to prevent bugs should have a higher severity | ||||||||||||||||||||
| 681 | than those that are more subjective or cosmetic in nature. | ||||||||||||||||||||
| 682 | |||||||||||||||||||||
| 683 | |||||||||||||||||||||
| 684 | =item C< get_severity() > | ||||||||||||||||||||
| 685 | |||||||||||||||||||||
| 686 | Returns the severity of violating this Policy. If the severity has | ||||||||||||||||||||
| 687 | not been explicitly defined by calling C<set_severity>, then the | ||||||||||||||||||||
| 688 | C<default_severity> is returned. See the C<$SEVERITY> constants in | ||||||||||||||||||||
| 689 | L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of | ||||||||||||||||||||
| 690 | possible severity values. | ||||||||||||||||||||
| 691 | |||||||||||||||||||||
| 692 | |||||||||||||||||||||
| 693 | =item C< set_severity( $N ) > | ||||||||||||||||||||
| 694 | |||||||||||||||||||||
| 695 | Sets the severity for violating this Policy. Clients of | ||||||||||||||||||||
| 696 | Perl::Critic::Policy objects can call this method to assign a | ||||||||||||||||||||
| 697 | different severity to the Policy if they don't agree with the | ||||||||||||||||||||
| 698 | C<default_severity>. See the C<$SEVERITY> constants in | ||||||||||||||||||||
| 699 | L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of | ||||||||||||||||||||
| 700 | possible values. | ||||||||||||||||||||
| 701 | |||||||||||||||||||||
| 702 | |||||||||||||||||||||
| 703 | =item C< default_themes() > | ||||||||||||||||||||
| 704 | |||||||||||||||||||||
| 705 | Returns a sorted list of the default themes associated with this | ||||||||||||||||||||
| 706 | Policy. The default method returns an empty list. Policy authors | ||||||||||||||||||||
| 707 | should override this method to return a list of themes that are | ||||||||||||||||||||
| 708 | appropriate for their policy. | ||||||||||||||||||||
| 709 | |||||||||||||||||||||
| 710 | |||||||||||||||||||||
| 711 | =item C< get_themes() > | ||||||||||||||||||||
| 712 | |||||||||||||||||||||
| 713 | Returns a sorted list of the themes associated with this Policy. If | ||||||||||||||||||||
| 714 | you haven't added themes or set the themes explicitly, this method | ||||||||||||||||||||
| 715 | just returns the default themes. | ||||||||||||||||||||
| 716 | |||||||||||||||||||||
| 717 | |||||||||||||||||||||
| 718 | =item C< set_themes( @THEME_LIST ) > | ||||||||||||||||||||
| 719 | |||||||||||||||||||||
| 720 | Sets the themes associated with this Policy. Any existing themes are | ||||||||||||||||||||
| 721 | overwritten. Duplicate themes will be removed. | ||||||||||||||||||||
| 722 | |||||||||||||||||||||
| 723 | |||||||||||||||||||||
| 724 | =item C< add_themes( @THEME_LIST ) > | ||||||||||||||||||||
| 725 | |||||||||||||||||||||
| 726 | Appends additional themes to this Policy. Any existing themes are | ||||||||||||||||||||
| 727 | preserved. Duplicate themes will be removed. | ||||||||||||||||||||
| 728 | |||||||||||||||||||||
| 729 | |||||||||||||||||||||
| 730 | =item C< get_abstract() > | ||||||||||||||||||||
| 731 | |||||||||||||||||||||
| 732 | Retrieve the abstract for this policy (the part of the NAME section of | ||||||||||||||||||||
| 733 | the POD after the module name), if it is available. | ||||||||||||||||||||
| 734 | |||||||||||||||||||||
| 735 | |||||||||||||||||||||
| 736 | =item C< get_raw_abstract() > | ||||||||||||||||||||
| 737 | |||||||||||||||||||||
| 738 | Retrieve the abstract for this policy (the part of the NAME section of | ||||||||||||||||||||
| 739 | the POD after the module name), if it is available, in the unparsed | ||||||||||||||||||||
| 740 | form. | ||||||||||||||||||||
| 741 | |||||||||||||||||||||
| 742 | |||||||||||||||||||||
| 743 | =item C< parameter_metadata_available() > | ||||||||||||||||||||
| 744 | |||||||||||||||||||||
| 745 | Returns whether information about the parameters is available. | ||||||||||||||||||||
| 746 | |||||||||||||||||||||
| 747 | |||||||||||||||||||||
| 748 | =item C< get_parameters() > | ||||||||||||||||||||
| 749 | |||||||||||||||||||||
| 750 | Returns a reference to an array containing instances of | ||||||||||||||||||||
| 751 | L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter>. | ||||||||||||||||||||
| 752 | |||||||||||||||||||||
| 753 | Note that this will return an empty list if the parameters for this | ||||||||||||||||||||
| 754 | policy are unknown. In order to differentiate between this | ||||||||||||||||||||
| 755 | circumstance and the one where this policy does not take any | ||||||||||||||||||||
| 756 | parameters, it is necessary to call C<parameter_metadata_available()>. | ||||||||||||||||||||
| 757 | |||||||||||||||||||||
| 758 | |||||||||||||||||||||
| 759 | =item C<set_format( $format )> | ||||||||||||||||||||
| 760 | |||||||||||||||||||||
| 761 | Class method. Sets the format for all Policy objects when they are | ||||||||||||||||||||
| 762 | evaluated in string context. The default is C<"%p\n">. See | ||||||||||||||||||||
| 763 | L<"OVERLOADS"> for formatting options. | ||||||||||||||||||||
| 764 | |||||||||||||||||||||
| 765 | |||||||||||||||||||||
| 766 | =item C<get_format()> | ||||||||||||||||||||
| 767 | |||||||||||||||||||||
| 768 | Class method. Returns the current format for all Policy objects when | ||||||||||||||||||||
| 769 | they are evaluated in string context. | ||||||||||||||||||||
| 770 | |||||||||||||||||||||
| 771 | |||||||||||||||||||||
| 772 | =item C<to_string()> | ||||||||||||||||||||
| 773 | |||||||||||||||||||||
| 774 | Returns a string representation of the policy. The content of the | ||||||||||||||||||||
| 775 | string depends on the current value returned by C<get_format()>. | ||||||||||||||||||||
| 776 | See L<"OVERLOADS"> for the details. | ||||||||||||||||||||
| 777 | |||||||||||||||||||||
| 778 | |||||||||||||||||||||
| 779 | =item C<is_safe()> | ||||||||||||||||||||
| 780 | |||||||||||||||||||||
| 781 | Answer whether this Policy can be used to analyze untrusted code, i.e. the | ||||||||||||||||||||
| 782 | Policy doesn't have any potential side effects. | ||||||||||||||||||||
| 783 | |||||||||||||||||||||
| 784 | This method returns a true value by default. | ||||||||||||||||||||
| 785 | |||||||||||||||||||||
| 786 | An "unsafe" policy might attempt to compile the code, which, if you have | ||||||||||||||||||||
| 787 | C<BEGIN> or C<CHECK> blocks that affect files or connect to databases, is not | ||||||||||||||||||||
| 788 | a safe thing to do. If you are writing a such a Policy, then you should | ||||||||||||||||||||
| 789 | override this method to return false. | ||||||||||||||||||||
| 790 | |||||||||||||||||||||
| 791 | By default L<Perl::Critic|Perl::Critic> will not run unsafe policies. | ||||||||||||||||||||
| 792 | |||||||||||||||||||||
| 793 | |||||||||||||||||||||
| 794 | |||||||||||||||||||||
| 795 | =back | ||||||||||||||||||||
| 796 | |||||||||||||||||||||
| 797 | |||||||||||||||||||||
| 798 | =head1 DOCUMENTATION | ||||||||||||||||||||
| 799 | |||||||||||||||||||||
| 800 | When your Policy module first C<use>s | ||||||||||||||||||||
| 801 | L<Perl::Critic::Violation|Perl::Critic::Violation>, it will try and | ||||||||||||||||||||
| 802 | extract the DESCRIPTION section of your Policy module's POD. This | ||||||||||||||||||||
| 803 | information is displayed by Perl::Critic if the verbosity level is set | ||||||||||||||||||||
| 804 | accordingly. Therefore, please include a DESCRIPTION section in the | ||||||||||||||||||||
| 805 | POD for any Policy modules that you author. Thanks. | ||||||||||||||||||||
| 806 | |||||||||||||||||||||
| 807 | |||||||||||||||||||||
| 808 | =head1 OVERLOADS | ||||||||||||||||||||
| 809 | |||||||||||||||||||||
| 810 | Perl::Critic::Violation overloads the C<""> operator to produce neat | ||||||||||||||||||||
| 811 | little messages when evaluated in string context. | ||||||||||||||||||||
| 812 | |||||||||||||||||||||
| 813 | Formats are a combination of literal and escape characters similar to | ||||||||||||||||||||
| 814 | the way C<sprintf> works. If you want to know the specific formatting | ||||||||||||||||||||
| 815 | capabilities, look at L<String::Format|String::Format>. Valid escape | ||||||||||||||||||||
| 816 | characters are: | ||||||||||||||||||||
| 817 | |||||||||||||||||||||
| 818 | |||||||||||||||||||||
| 819 | =over | ||||||||||||||||||||
| 820 | |||||||||||||||||||||
| 821 | =item C<%P> | ||||||||||||||||||||
| 822 | |||||||||||||||||||||
| 823 | Name of the Policy module. | ||||||||||||||||||||
| 824 | |||||||||||||||||||||
| 825 | |||||||||||||||||||||
| 826 | =item C<%p> | ||||||||||||||||||||
| 827 | |||||||||||||||||||||
| 828 | Name of the Policy without the C<Perl::Critic::Policy::> prefix. | ||||||||||||||||||||
| 829 | |||||||||||||||||||||
| 830 | |||||||||||||||||||||
| 831 | =item C<%a> | ||||||||||||||||||||
| 832 | |||||||||||||||||||||
| 833 | The policy abstract. | ||||||||||||||||||||
| 834 | |||||||||||||||||||||
| 835 | |||||||||||||||||||||
| 836 | =item C<%O> | ||||||||||||||||||||
| 837 | |||||||||||||||||||||
| 838 | List of supported policy parameters. Takes an option of a format | ||||||||||||||||||||
| 839 | string for L<Perl::Critic::PolicyParameter/"to_formatted_string">. | ||||||||||||||||||||
| 840 | For example, this can be used like C<%{%n - %d\n}O> to get a list of | ||||||||||||||||||||
| 841 | parameter names followed by their descriptions. | ||||||||||||||||||||
| 842 | |||||||||||||||||||||
| 843 | |||||||||||||||||||||
| 844 | =item C<%U> | ||||||||||||||||||||
| 845 | |||||||||||||||||||||
| 846 | A message stating that the parameters for the policy are unknown if | ||||||||||||||||||||
| 847 | C<parameter_metadata_available()> returns false. Takes an option of | ||||||||||||||||||||
| 848 | what the message should be, which defaults to "Cannot programmatically | ||||||||||||||||||||
| 849 | discover what parameters this policy takes.". The value of this | ||||||||||||||||||||
| 850 | option is interpolated in order to expand the standard escape | ||||||||||||||||||||
| 851 | sequences (C<\n>, C<\t>, etc.). | ||||||||||||||||||||
| 852 | |||||||||||||||||||||
| 853 | |||||||||||||||||||||
| 854 | =item C<%S> | ||||||||||||||||||||
| 855 | |||||||||||||||||||||
| 856 | The default severity level of the policy. | ||||||||||||||||||||
| 857 | |||||||||||||||||||||
| 858 | |||||||||||||||||||||
| 859 | =item C<%s> | ||||||||||||||||||||
| 860 | |||||||||||||||||||||
| 861 | The current severity level of the policy. | ||||||||||||||||||||
| 862 | |||||||||||||||||||||
| 863 | |||||||||||||||||||||
| 864 | =item C<%T> | ||||||||||||||||||||
| 865 | |||||||||||||||||||||
| 866 | The default themes for the policy. | ||||||||||||||||||||
| 867 | |||||||||||||||||||||
| 868 | |||||||||||||||||||||
| 869 | =item C<%t> | ||||||||||||||||||||
| 870 | |||||||||||||||||||||
| 871 | The current themes for the policy. | ||||||||||||||||||||
| 872 | |||||||||||||||||||||
| 873 | |||||||||||||||||||||
| 874 | =item C<%V> | ||||||||||||||||||||
| 875 | |||||||||||||||||||||
| 876 | The default maximum number of violations per document of the policy. | ||||||||||||||||||||
| 877 | |||||||||||||||||||||
| 878 | |||||||||||||||||||||
| 879 | =item C<%v> | ||||||||||||||||||||
| 880 | |||||||||||||||||||||
| 881 | The current maximum number of violations per document of the policy. | ||||||||||||||||||||
| 882 | |||||||||||||||||||||
| 883 | |||||||||||||||||||||
| 884 | =back | ||||||||||||||||||||
| 885 | |||||||||||||||||||||
| 886 | |||||||||||||||||||||
| 887 | =head1 AUTHOR | ||||||||||||||||||||
| 888 | |||||||||||||||||||||
| 889 | Jeffrey Ryan Thalhammer <jeff@imaginative-software.com> | ||||||||||||||||||||
| 890 | |||||||||||||||||||||
| 891 | |||||||||||||||||||||
| 892 | =head1 COPYRIGHT | ||||||||||||||||||||
| 893 | |||||||||||||||||||||
| 894 | Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved. | ||||||||||||||||||||
| 895 | |||||||||||||||||||||
| 896 | This program is free software; you can redistribute it and/or modify | ||||||||||||||||||||
| 897 | it under the same terms as Perl itself. The full text of this license | ||||||||||||||||||||
| 898 | can be found in the LICENSE file included with this module. | ||||||||||||||||||||
| 899 | |||||||||||||||||||||
| 900 | =cut | ||||||||||||||||||||
| 901 | |||||||||||||||||||||
| 902 | # Local Variables: | ||||||||||||||||||||
| 903 | # mode: cperl | ||||||||||||||||||||
| 904 | # cperl-indent-level: 4 | ||||||||||||||||||||
| 905 | # fill-column: 78 | ||||||||||||||||||||
| 906 | # indent-tabs-mode: nil | ||||||||||||||||||||
| 907 | # c-indentation-style: bsd | ||||||||||||||||||||
| 908 | # End: | ||||||||||||||||||||
| 909 | # ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround : | ||||||||||||||||||||