1Perl::Critic::Policy(3)User Contributed Perl DocumentatioPnerl::Critic::Policy(3)
2
6 Perl::Critic::Policy - Base class for all Policy modules
7
9 Perl::Critic::Policy is the abstract base class for all Policy objects.
10 If you're developing your own Policies, your job is to implement and
11 override its methods in a subclass. To work with the Perl::Critic
12 engine, your implementation must behave as described below. For a
13 detailed explanation on how to make new Policy modules, please see the
14 Perl::Critic::DEVELOPER document included in this distribution.
15
17 "new(key1 => value1, key2 => value2 ... )"
18 Returns a reference to a new subclass of Perl::Critic::Policy.
19 If your Policy requires any special arguments, they should be
20 passed in here as key-value pairs. Users of perlcritic can
21 specify these in their config file. Unless you override the
22 "new" method, the default method simply returns a reference to
23 an empty hash that has been blessed into your subclass.
24 " violates( $element, $document ) "
26 Given a PPI::Element and a PPI::Document, returns one or more
27 Perl::Critic::Violation objects if the $element violates this
28 Policy. If there are no violations, then it returns an empty
29 list. If the Policy encounters an exception, then it should
30 "croak" with an error message and let the caller decide how to
31 handle it.
32 "violates()" is an abstract method and it will abort if you
34 attempt to invoke it directly. It is the heart of all Policy
35 modules, and your subclass must override this method.
36 " violation( $description, $explanation, $element ) "
38 Returns a reference to a new "Perl::Critic::Violation" object.
39 The arguments are a description of the violation (as string),
40 an explanation for the policy (as string) or a series of page
41 numbers in PBP (as an ARRAY ref), a reference to the PPI ele‐
42 ment that caused the violation.
43 These are the same as the constructor to Perl::Critic::Viola‐
45 tion, but without the severity. The Policy itself knows the
46 severity.
47 " applies_to() "
49 Returns a list of the names of PPI classes that this Policy
50 cares about. By default, the result is "PPI::Element". Over‐
51 riding this method in Policy subclasses should lead to signifi‐
52 cant performance increases.
53 " default_severity() "
55 Returns the default severity for violating this Policy. See
56 the $SEVERITY constants in Perl::Critic::Utils for an enumera‐
57 tion of possible severity values. By default, this method
58 returns $SEVERITY_LOWEST. Authors of Perl::Critic::Policy sub‐
59 classes should override this method to return a value that they
60 feel is appropriate for their Policy. In general, Polices that
61 are widely accepted or tend to prevent bugs should have a
62 higher severity than those that are more subjective or cosmetic
63 in nature.
64 " get_severity() "
66 Returns the severity of violating this Policy. If the severity
67 has not been explicitly defined by calling "set_severity", then
68 the "default_severity" is returned. See the $SEVERITY con‐
69 stants in Perl::Critic::Utils for an enumeration of possible
70 severity values.
71 " set_severity( $N ) "
73 Sets the severity for violating this Policy. Clients of
74 Perl::Critic::Policy objects can call this method to assign a
75 different severity to the Policy if they don't agree with the
76 "default_severity". See the $SEVERITY constants in
77 Perl::Critic::Utils for an enumeration of possible values.
78 " default_themes() "
80 Returns a sorted list of the default themes associated with
81 this Policy. The default method returns an empty list. Policy
82 authors should override this method to return a list of themes
83 that are appropriate for their policy.
84 " get_themes() "
86 Returns a sorted list of the themes associated with this Pol‐
87 icy. If you haven't added themes or set the themes explicitly,
88 this method just returns the default themes.
89 " set_themes( @THEME_LIST ) "
91 Sets the themes associated with this Policy. Any existing
92 themes are overwritten. Duplicate themes will be removed.
93 " add_themes( @THEME_LIST ) "
95 Appends additional themes to this Policy. Any existing themes
96 are preserved. Duplicate themes will be removed.
97 "set_format( $FORMAT )"
99 Class method. Sets the format for all Policy objects when they
100 are evaluated in string context. The default is "%p\n". See
101 "OVERLOADS" for formatting options.
102 "get_format()"
104 Class method. Returns the current format for all Policy objects
105 when they are evaluated in string context.
106 "to_string()"
108 Returns a string representation of the policy. The content of
109 the string depends on the current value of the $FORMAT package
110 variable. See "OVERLOADS" for the details.
111
113 When your Policy module first "use"s Perl::Critic::Violation, it will
114 try and extract the DESCRIPTION section of your Policy module's POD.
115 This information is displayed by Perl::Critic if the verbosity level is
116 set accordingly. Therefore, please include a DESCRIPTION section in
117 the POD for any Policy modules that you author. Thanks.
118
120 Perl::Critic::Violation overloads the "" operator to produce neat lit‐
121 tle messages when evaluated in string context. The format depends on
122 the current value of the $FORMAT package variable.
123 Formats are a combination of literal and escape characters similar to
125 the way "sprintf" works. If you want to know the specific formatting
126 capabilities, look at String::Format. Valid escape characters are:
127 Escape Meaning
129 ------- -----------------------------------------------------------------
130 %O Comma-delimited list of supported policy parameters
131 %P Name of the Policy module
132 %p Name of the Policy without the Perl::Critic::Policy:: prefix
133 %S The default severity level of the policy
134 %s The current severity level of the policy
135 %T The default themes for the policy
136 %t The current themes for the policy
137
139 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
140
142 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
143 This program is free software; you can redistribute it and/or modify it
145 under the same terms as Perl itself. The full text of this license can
146 be found in the LICENSE file included with this module.
147perl v5.8.8 2007-03-20 Perl::Critic::Policy(3)