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