1Perl::Critic::ViolationU(s3e)r Contributed Perl DocumentaPteiroln::Critic::Violation(3)
2
6 Perl::Critic::Violation - Represents policy violations
7
9 use PPI;
10 use Perl::Critic::Violation;
11 my $elem = $doc->child(0); #$doc is a PPI::Document object
13 my $desc = 'Offending code'; #Describe the violation
14 my $expl = [1,45,67]; #Page numbers from PBP
15 my $sev = 5; #Severity level of this violation
16 my $vio = Perl::Critic::Violation->new($desc, $expl, $node, $sev);
18
20 Perl::Critic::Violation is the generic representation of an individual
21 Policy violation. Its primary purpose is to provide an abstraction
22 layer so that clients of Perl::Critic don't have to know anything about
23 PPI. The "violations" method of all Perl::Critic::Policy subclasses
24 must return a list of these Perl::Critic::Violation objects.
25
27 "new( $description, $explanation, $element, $severity )"
28 Returns a reference to a new "Perl::Critic::Violation" object.
29 The arguments are a description of the violation (as string),
30 an explanation for the policy (as string) or a series of page
31 numbers in PBP (as an ARRAY ref), a reference to the PPI ele‐
32 ment that caused the violation, and the severity of the viola‐
33 tion (as an integer).
34
36 "description()"
37 Returns a brief description of the policy that has been vio‐
38 lated as a string.
39 "explanation()"
41 Returns an explanation of the policy as a string or as refer‐
42 ence to an array of page numbers in PBP.
43 "location()"
45 Returns a three-element array reference containing the line and
46 real & virtual column numbers where this Violation occurred, as
47 in PPI::Element.
48 "filename()"
50 Returns the path to the file where this Violation occurred. In
51 some cases, the path may be undefined because the source code
52 was not read directly from a file.
53 "severity()"
55 Returns the severity of this Violation as an integer ranging
56 from 1 to 5, where 5 is the "most" severe.
57 "sort_by_severity( @violation_objects )"
59 If you need to sort Violations by severity, use this handy rou‐
60 tine:
61 @sorted = Perl::Critic::Violation::sort_by_severity(@violations);
63 "sort_by_location( @violation_objects )"
65 If you need to sort Violations by location, use this handy rou‐
66 tine:
67 @sorted = Perl::Critic::Violation::sort_by_location(@violations);
69 "diagnostics()"
71 Returns a formatted string containing a full discussion of the
72 motivation for and details of the Policy module that created
73 this Violation. This information is automatically extracted
74 from the "DESCRIPTION" section of the Policy module's POD.
75 "policy()"
77 Returns the name of the Perl::Critic::Policy that created this
78 Violation.
79 "source()"
81 Returns the string of source code that caused this exception.
82 If the code spans multiple lines (e.g. multi-line statements,
83 subroutines or other blocks), then only the first line will be
84 returned.
85 "set_format( $FORMAT )"
87 Class method. Sets the format for all Violation objects when
88 they are evaluated in string context. The default is "'%d at
89 line %l, column %c. %e'". See "OVERLOADS" for formatting
90 options.
91 "get_format()"
93 Class method. Returns the current format for all Violation
94 objects when they are evaluated in string context.
95 "to_string()"
97 Returns a string representation of this violation. The content
98 of the string depends on the current value of the $FORMAT pack‐
99 age variable. See "OVERLOADS" for the details.
100
102 $Perl::Critic::Violation::FORMAT
103 DEPRECATED: Use the "set_format" and "get_format" methods
104 instead.
105 Sets the format for all Violation objects when they are evalu‐
107 ated in string context. The default is '%d at line %l, column
108 %c. %e'. See "OVERLOADS" for formatting options. If you want
109 to change $FORMAT, you should probably localize it first.
110
112 Perl::Critic::Violation overloads the "" operator to produce neat lit‐
113 tle messages when evaluated in string context. The format depends on
114 the current value of the $FORMAT package variable.
115 Formats are a combination of literal and escape characters similar to
117 the way "sprintf" works. If you want to know the specific formatting
118 capabilities, look at String::Format. Valid escape characters are:
119 Escape Meaning
121 ------- ----------------------------------------------------------------
122 %c Column number where the violation occurred
123 %d Full diagnostic discussion of the violation
124 %e Explanation of violation or page numbers in PBP
125 %F Just the name of the file where the violation occurred.
126 %f Path to the file where the violation occurred.
127 %l Line number where the violation occurred
128 %m Brief description of the violation
129 %P Full name of the Policy module that created the violation
130 %p Name of the Policy without the Perl::Critic::Policy:: prefix
131 %r The string of source code that caused the violation
132 %s The severity level of the violation
133 Here are some examples:
135 $Perl::Critic::Violation::FORMAT = "%m at line %l, column %c.\n";
137 #looks like "Mixed case variable name at line 6, column 23."
138 $Perl::Critic::Violation::FORMAT = "%m near '%r'\n";
140 #looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'"
141 $Perl::Critic::Violation::FORMAT = "%l:%c:%p\n";
143 #looks like "6:23:NamingConventions::ProhibitMixedCaseVars"
144 $Perl::Critic::Violation::FORMAT = "%m at line %l. %e. \n%d\n";
146 #looks like "Mixed case variable name at line 6. See page 44 of PBP.
147 Conway's recommended naming convention is to use lower-case words
148 separated by underscores. Well-recognized acronyms can be in ALL
149 CAPS, but must be separated by underscores from other parts of the
150 name."
151
153 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
154
156 Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. All rights reserved.
157 This program is free software; you can redistribute it and/or modify it
159 under the same terms as Perl itself. The full text of this license can
160 be found in the LICENSE file included with this module.
161perl v5.8.8 2007-03-20 Perl::Critic::Violation(3)