Login
Vanquised can_be_disabled() method.
[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
7b3a5e91 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
c2018d77 431#-----------------------------------------------------------------------------
0f8f6b42 432
3fbc79a5
ES
433## no critic (Subroutines::RequireFinalReturn)
434sub throw_parameter_value_exception {
435 my ( $self, $option_name, $option_value, $source, $message_suffix ) = @_;
436
437 $self->new_parameter_value_exception(
438 $option_name, $option_value, $source, $message_suffix
439 )
440 ->throw();
441}
442## use critic
443
444
445#-----------------------------------------------------------------------------
446
fd5bd7b5 447# Static methods.
c2018d77 448
7b3a5e91
ES
449sub set_format { return $format = $_[0] } ## no critic(ArgUnpacking)
450sub get_format { return $format }
1f4dafe4
JRT
451
452#-----------------------------------------------------------------------------
453
c2018d77 454sub to_string {
6e7d6c9f 455 my ($self, @args) = @_;
c2018d77
JRT
456
457 # Wrap the more expensive ones in sub{} to postpone evaluation
458 my %fspec = (
0f8f6b42
ES
459 'P' => sub { $self->get_long_name() },
460 'p' => sub { $self->get_short_name() },
c2f5bc1f
ES
461 'a' => sub { dor($self->get_abstract(), $EMPTY) },
462 'O' => sub { $self->_format_parameters(@_) },
463 'U' => sub { $self->_format_lack_of_parameter_metadata(@_) },
464 'S' => sub { $self->default_severity() },
465 's' => sub { $self->get_severity() },
c2018d77
JRT
466 'T' => sub { join $SPACE, $self->default_themes() },
467 't' => sub { join $SPACE, $self->get_themes() },
459ede25
ES
468 'V' => sub { dor( $self->default_maximum_violations_per_document(), $NO_LIMIT ) },
469 'v' => sub { dor( $self->get_maximum_violations_per_document(), $NO_LIMIT ) },
c2018d77 470 );
7b3a5e91 471 return stringf(get_format(), %fspec);
c2018d77
JRT
472}
473
0f8f6b42 474sub _format_parameters {
fd5bd7b5 475 my ($self, $format) = @_;
8c83273d
ES
476
477 return $EMPTY if not $self->parameter_metadata_available();
478
479 my $separator;
480 if ($format) {
481 $separator = $EMPTY;
482 } else {
483 $separator = $SPACE;
484 $format = '%n';
485 }
486
487 return
488 join
489 $separator,
490 map { $_->to_formatted_string($format) } @{ $self->get_parameters() };
491}
492
493sub _format_lack_of_parameter_metadata {
494 my ($self, $message) = @_;
495
496 return $EMPTY if $self->parameter_metadata_available();
497 return interpolate($message) if $message;
498
499 return
500 'Cannot programmatically discover what parameters this policy takes.';
fd5bd7b5
JRT
501}
502
2b141872
ES
503sub _get_source_file {
504 my ($self) = @_;
505
506 my $relative_path =
507 File::Spec->catfile( split m/::/xms, ref $self ) . '.pm';
508
509 return $INC{$relative_path};
510}
511
b67a8c74 512
c2018d77
JRT
513#-----------------------------------------------------------------------------
514# Apparently, some perls do not implicitly stringify overloading
515# objects before doing a comparison. This causes a couple of our
516# sorting tests to fail. To work around this, we overload C<cmp> to
517# do it explicitly.
518#
519# 20060503 - More information: This problem has been traced to
520# Test::Simple versions <= 0.60, not perl itself. Upgrading to
521# Test::Simple v0.62 will fix the problem. But rather than forcing
522# everyone to upgrade, I have decided to leave this workaround in
523# place.
524
525sub _compare { return "$_[0]" cmp "$_[1]" }
526
59b05e08
JRT
5271;
528
529__END__
530
6036a254 531#-----------------------------------------------------------------------------
9f1d5408 532
59b05e08
JRT
533=pod
534
535=head1 NAME
536
c728943a 537Perl::Critic::Policy - Base class for all Policy modules.
59b05e08 538
16d279c3 539
59b05e08
JRT
540=head1 DESCRIPTION
541
542Perl::Critic::Policy is the abstract base class for all Policy
6bf9b465
JRT
543objects. If you're developing your own Policies, your job is to
544implement and override its methods in a subclass. To work with the
11f53956
ES
545L<Perl::Critic|Perl::Critic> engine, your implementation must behave
546as described below. For a detailed explanation on how to make new
547Policy modules, please see the
548L<Perl::Critic::DEVELOPER|Perl::Critic::DEVELOPER> document included
549in this distribution.
59b05e08 550
16d279c3 551
59b05e08
JRT
552=head1 METHODS
553
16d279c3 554=over
59b05e08 555
8c050cac 556=item C<< new(key1 => value1, key2 => value2 ... ) >>
59b05e08 557
985e0116
ES
558Returns a reference to a new subclass of Perl::Critic::Policy. If your
559Policy requires any special arguments, they will be passed in here as
11f53956
ES
560key-value pairs. Users of L<perlcritic|perlcritic> can specify these
561in their config file. Unless you override the C<new> method, the
562default method simply returns a reference to an empty hash that has
563been blessed into your subclass. However, you really should not
564override this; override C<initialize_if_enabled()> instead.
985e0116
ES
565
566This constructor is always called regardless of whether the user has
567enabled this Policy or not.
568
16d279c3 569
bb5a5c57 570=item C<< initialize_if_enabled( $config ) >>
985e0116 571
bb5a5c57
ES
572This receives an instance of
573L<Perl::Critic::PolicyConfig|Perl::Critic::PolicyConfig> as a
574parameter, and is only invoked if this Policy is enabled by the user.
985e0116
ES
575Thus, this is the preferred place for subclasses to do any
576initialization.
577
578Implementations of this method should return a boolean value
579indicating whether the Policy should continue to be enabled. For most
580subclasses, this will always be C<$TRUE>. Policies that depend upon
581external modules or other system facilities that may or may not be
582available should test for the availability of these dependencies and
583return C<$FALSE> if they are not.
59b05e08 584
16d279c3 585
78afb6d4 586=item C<< prepare_to_scan_document( $document ) >>
bb5a5c57 587
78afb6d4
ES
588The parameter is about to be scanned by this Policy. Whatever this
589Policy wants to do in terms of preparation should happen here.
590Returns a boolean value indicating whether the document should be
591scanned at all; if this is a false value, this Policy won't be applied
592to the document. By default, does nothing but return C<$TRUE>.
bb5a5c57
ES
593
594
8c050cac 595=item C< violates( $element, $document ) >
59b05e08 596
11f53956
ES
597Given a L<PPI::Element|PPI::Element> and a
598L<PPI::Document|PPI::Document>, returns one or more
599L<Perl::Critic::Violation|Perl::Critic::Violation> objects if the
600C<$element> violates this Policy. If there are no violations, then it
601returns an empty list. If the Policy encounters an exception, then it
602should C<croak> with an error message and let the caller decide how to
603handle it.
59b05e08 604
9f1d5408
JRT
605C<violates()> is an abstract method and it will abort if you attempt
606to invoke it directly. It is the heart of all Policy modules, and
607your subclass B<must> override this method.
59b05e08 608
16d279c3 609
8c050cac 610=item C< violation( $description, $explanation, $element ) >
815b71d0
AL
611
612Returns a reference to a new C<Perl::Critic::Violation> object. The
613arguments are a description of the violation (as string), an
614explanation for the policy (as string) or a series of page numbers in
11f53956
ES
615PBP (as an ARRAY ref), a reference to the L<PPI|PPI> element that
616caused the violation.
815b71d0 617
11f53956
ES
618These are the same as the constructor to
619L<Perl::Critic::Violation|Perl::Critic::Violation>, but without the
620severity. The Policy itself knows the severity.
815b71d0 621
16d279c3 622
3fbc79a5
ES
623=item C< new_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) >
624
625Create a
11f53956 626L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>
3fbc79a5
ES
627for this Policy.
628
629
8c83273d
ES
630=item C< throw_parameter_value_exception( $option_name, $option_value, $source, $message_suffix ) >
631
632Create and throw a
11f53956 633L<Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue|Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue>.
8c83273d
ES
634Useful in parameter parser implementations.
635
16d279c3 636
0f8f6b42
ES
637=item C< get_long_name() >
638
639Return the full package name of this policy.
640
16d279c3 641
0f8f6b42
ES
642=item C< get_short_name() >
643
644Return the name of this policy without the "Perl::Critic::Policy::"
645prefix.
646
16d279c3 647
8c050cac 648=item C< applies_to() >
bf159007 649
9f1d5408
JRT
650Returns a list of the names of PPI classes that this Policy cares
651about. By default, the result is C<PPI::Element>. Overriding this
652method in Policy subclasses should lead to significant performance
653increases.
654
16d279c3
ES
655
656=item C< default_maximum_violations_per_document() >
657
658Returns the default maximum number of violations for this policy to
659report per document. By default, this not defined, but subclasses may
660override this.
661
662
663=item C< get_maximum_violations_per_document() >
664
665Returns the maximum number of violations this policy will report for a
666single document. If this is not defined, then there is no limit. If
667L<set_maximum_violations_per_document()> has not been invoked, then
668L<default_maximum_violations_per_document()> is returned.
669
670
671=item C< set_maximum_violations_per_document() >
672
673Specify the maximum violations that this policy should report for a
674document.
675
676
8c050cac 677=item C< default_severity() >
9f1d5408
JRT
678
679Returns the default severity for violating this Policy. See the
11f53956
ES
680C<$SEVERITY> constants in L<Perl::Critic::Utils|Perl::Critic::Utils>
681for an enumeration of possible severity values. By default, this
682method returns C<$SEVERITY_LOWEST>. Authors of Perl::Critic::Policy
683subclasses should override this method to return a value that they
684feel is appropriate for their Policy. In general, Polices that are
685widely accepted or tend to prevent bugs should have a higher severity
686than those that are more subjective or cosmetic in nature.
9f1d5408 687
16d279c3 688
8c050cac 689=item C< get_severity() >
9f1d5408
JRT
690
691Returns the severity of violating this Policy. If the severity has
692not been explicitly defined by calling C<set_severity>, then the
693C<default_severity> is returned. See the C<$SEVERITY> constants in
11f53956
ES
694L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of
695possible severity values.
9f1d5408 696
16d279c3 697
8c050cac 698=item C< set_severity( $N ) >
9f1d5408
JRT
699
700Sets the severity for violating this Policy. Clients of
701Perl::Critic::Policy objects can call this method to assign a
702different severity to the Policy if they don't agree with the
703C<default_severity>. See the C<$SEVERITY> constants in
11f53956
ES
704L<Perl::Critic::Utils|Perl::Critic::Utils> for an enumeration of
705possible values.
dff08b70 706
16d279c3 707
8c050cac 708=item C< default_themes() >
faa35de4
JRT
709
710Returns a sorted list of the default themes associated with this
711Policy. The default method returns an empty list. Policy authors
712should override this method to return a list of themes that are
713appropriate for their policy.
714
16d279c3 715
8c050cac 716=item C< get_themes() >
faa35de4
JRT
717
718Returns a sorted list of the themes associated with this Policy. If
dc93df4f 719you haven't added themes or set the themes explicitly, this method
faa35de4
JRT
720just returns the default themes.
721
16d279c3 722
8c050cac 723=item C< set_themes( @THEME_LIST ) >
faa35de4
JRT
724
725Sets the themes associated with this Policy. Any existing themes are
726overwritten. Duplicate themes will be removed.
727
16d279c3 728
8c050cac 729=item C< add_themes( @THEME_LIST ) >
faa35de4
JRT
730
731Appends additional themes to this Policy. Any existing themes are
732preserved. Duplicate themes will be removed.
733
16d279c3 734
c2f5bc1f
ES
735=item C< get_abstract() >
736
737Retrieve the abstract for this policy (the part of the NAME section of
738the POD after the module name), if it is available.
739
740
b2236a84
ES
741=item C< get_raw_abstract() >
742
743Retrieve the abstract for this policy (the part of the NAME section of
744the POD after the module name), if it is available, in the unparsed
745form.
746
747
8c83273d
ES
748=item C< parameter_metadata_available() >
749
750Returns whether information about the parameters is available.
751
16d279c3 752
8c83273d
ES
753=item C< get_parameters() >
754
755Returns a reference to an array containing instances of
11f53956 756L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter>.
8c83273d
ES
757
758Note that this will return an empty list if the parameters for this
759policy are unknown. In order to differentiate between this
760circumstance and the one where this policy does not take any
761parameters, it is necessary to call C<parameter_metadata_available()>.
762
16d279c3 763
8c83273d
ES
764=item C< get_parameter( $parameter_name ) >
765
11f53956
ES
766Returns the
767L<Perl::Critic::PolicyParameter|Perl::Critic::PolicyParameter> with
768the specified name.
8c83273d 769
16d279c3 770
7b3a5e91 771=item C<set_format( $format )>
1f4dafe4 772
0f8f6b42
ES
773Class method. Sets the format for all Policy objects when they are
774evaluated in string context. The default is C<"%p\n">. See
775L<"OVERLOADS"> for formatting options.
1f4dafe4 776
16d279c3 777
1f4dafe4
JRT
778=item C<get_format()>
779
0f8f6b42
ES
780Class method. Returns the current format for all Policy objects when
781they are evaluated in string context.
1f4dafe4 782
16d279c3 783
14a6a3ef
CD
784=item C<to_string()>
785
786Returns a string representation of the policy. The content of the
7b3a5e91
ES
787string depends on the current value returned by C<get_format()>.
788See L<"OVERLOADS"> for the details.
14a6a3ef 789
16d279c3 790
59b05e08
JRT
791=back
792
16d279c3 793
59b05e08
JRT
794=head1 DOCUMENTATION
795
11f53956
ES
796When your Policy module first C<use>s
797L<Perl::Critic::Violation|Perl::Critic::Violation>, it will try and
798extract the DESCRIPTION section of your Policy module's POD. This
799information is displayed by Perl::Critic if the verbosity level is set
800accordingly. Therefore, please include a DESCRIPTION section in the
801POD for any Policy modules that you author. Thanks.
59b05e08 802
16d279c3 803
14a6a3ef
CD
804=head1 OVERLOADS
805
806Perl::Critic::Violation overloads the C<""> operator to produce neat
7b3a5e91 807little messages when evaluated in string context.
14a6a3ef
CD
808
809Formats are a combination of literal and escape characters similar to
810the way C<sprintf> works. If you want to know the specific formatting
11f53956
ES
811capabilities, look at L<String::Format|String::Format>. Valid escape
812characters are:
14a6a3ef 813
16d279c3 814
fc5b8cef
ES
815=over
816
c2f5bc1f
ES
817=item C<%P>
818
819Name of the Policy module.
820
821
822=item C<%p>
823
824Name of the Policy without the C<Perl::Critic::Policy::> prefix.
825
826
827=item C<%a>
828
829The policy abstract.
830
831
fc5b8cef
ES
832=item C<%O>
833
8c83273d
ES
834List of supported policy parameters. Takes an option of a format
835string for L<Perl::Critic::PolicyParameter/"to_formatted_string">.
836For example, this can be used like C<%{%n - %d\n}O> to get a list of
837parameter names followed by their descriptions.
838
16d279c3 839
8c83273d
ES
840=item C<%U>
841
842A message stating that the parameters for the policy are unknown if
843C<parameter_metadata_available()> returns false. Takes an option of
844what the message should be, which defaults to "Cannot programmatically
845discover what parameters this policy takes.". The value of this
846option is interpolated in order to expand the standard escape
847sequences (C<\n>, C<\t>, etc.).
fc5b8cef 848
16d279c3 849
fc5b8cef
ES
850=item C<%S>
851
852The default severity level of the policy.
853
16d279c3 854
fc5b8cef
ES
855=item C<%s>
856
857The current severity level of the policy.
858
16d279c3 859
fc5b8cef
ES
860=item C<%T>
861
862The default themes for the policy.
863
16d279c3 864
fc5b8cef
ES
865=item C<%t>
866
867The current themes for the policy.
868
16d279c3 869
c2f5bc1f
ES
870=item C<%V>
871
872The default maximum number of violations per document of the policy.
873
874
875=item C<%v>
876
877The current maximum number of violations per document of the policy.
878
879
fc5b8cef
ES
880=back
881
14a6a3ef 882
59b05e08
JRT
883=head1 AUTHOR
884
885Jeffrey Ryan Thalhammer <thaljef@cpan.org>
886
16d279c3 887
59b05e08
JRT
888=head1 COPYRIGHT
889
20dfddeb 890Copyright (c) 2005-2008 Jeffrey Ryan Thalhammer. All rights reserved.
59b05e08
JRT
891
892This program is free software; you can redistribute it and/or modify
893it under the same terms as Perl itself. The full text of this license
894can be found in the LICENSE file included with this module.
895
896=cut
737d3b65
CD
897
898# Local Variables:
899# mode: cperl
900# cperl-indent-level: 4
901# fill-column: 78
902# indent-tabs-mode: nil
903# c-indentation-style: bsd
904# End:
96fed375 905# ex: set ts=8 sts=4 sw=4 tw=78 ft=perl expandtab shiftround :