1Perl::Critic::ViolationU(s3e)r Contributed Perl DocumentaPteiroln::Critic::Violation(3)
2
3
4

NAME

6       Perl::Critic::Violation - A violation of a Policy found in some source
7       code.
8

SYNOPSIS

10         use PPI;
11         use Perl::Critic::Violation;
12
13         my $elem = $doc->child(0);      # $doc is a PPI::Document object
14         my $desc = 'Offending code';    # Describe the violation
15         my $expl = [1,45,67];           # Page numbers from PBP
16         my $sev  = 5;                   # Severity level of this violation
17
18         my $vio  = Perl::Critic::Violation->new($desc, $expl, $node, $sev);
19

DESCRIPTION

21       Perl::Critic::Violation is the generic representation of an individual
22       Policy violation.  Its primary purpose is to provide an abstraction
23       layer so that clients of Perl::Critic don't have to know anything about
24       PPI.  The "violations" method of all Perl::Critic::Policy subclasses
25       must return a list of these Perl::Critic::Violation objects.
26

INTERFACE SUPPORT

28       This is considered to be a public class.  Any changes to its interface
29       will go through a deprecation cycle.
30

CONSTRUCTOR

32       "new( $description, $explanation, $element, $severity )"
33           Returns a reference to a new "Perl::Critic::Violation" object. The
34           arguments are a description of the violation (as string), an
35           explanation for the policy (as string) or a series of page numbers
36           in PBP (as an ARRAY ref), a reference to the PPI element that
37           caused the violation, and the severity of the violation (as an
38           integer).
39

METHODS

41       "description()"
42           Returns a brief description of the specific violation.  In other
43           words, this value may change on a per violation basis.
44
45       "explanation()"
46           Returns an explanation of the policy as a string or as reference to
47           an array of page numbers in PBP.  This value will generally not
48           change based upon the specific code violating the policy.
49
50       "location()"
51           Don't use this method.  Use the "line_number()",
52           "logical_line_number()", "column_number()",
53           "visual_column_number()", and "logical_filename()" methods instead.
54
55           Returns a five-element array reference containing the line and real
56           & virtual column and logical numbers and logical file name where
57           this Violation occurred, as in PPI::Element.
58
59       "line_number()"
60           Returns the physical line number that the violation was found on.
61
62       "logical_line_number()"
63           Returns the logical line number that the violation was found on.
64           This can differ from the physical line number when there were
65           "#line" directives in the code.
66
67       "column_number()"
68           Returns the physical column that the violation was found at.  This
69           means that hard tab characters count as a single character.
70
71       "visual_column_number()"
72           Returns the column that the violation was found at, as it would
73           appear if hard tab characters were expanded, based upon the value
74           of "tab_width [ $width ]" in PPI::Document.
75
76       "filename()"
77           Returns the path to the file where this Violation occurred.  In
78           some cases, the path may be undefined because the source code was
79           not read directly from a file.
80
81       "logical_filename()"
82           Returns the logical path to the file where the Violation occurred.
83           This can differ from "filename()" when there was a "#line"
84           directive in the code.
85
86       "severity()"
87           Returns the severity of this Violation as an integer ranging from 1
88           to 5, where 5 is the "most" severe.
89
90       "sort_by_severity( @violation_objects )"
91           If you need to sort Violations by severity, use this handy routine:
92
93               @sorted = Perl::Critic::Violation::sort_by_severity(@violations);
94
95       "sort_by_location( @violation_objects )"
96           If you need to sort Violations by location, use this handy routine:
97
98               @sorted = Perl::Critic::Violation::sort_by_location(@violations);
99
100       "diagnostics()"
101           Returns a formatted string containing a full discussion of the
102           motivation for and details of the Policy module that created this
103           Violation.  This information is automatically extracted from the
104           "DESCRIPTION" section of the Policy module's POD.
105
106       "policy()"
107           Returns the name of the Perl::Critic::Policy that created this
108           Violation.
109
110       "source()"
111           Returns the string of source code that caused this exception.  If
112           the code spans multiple lines (e.g. multi-line statements,
113           subroutines or other blocks), then only the first line will be
114           returned.
115
116       "element_class()"
117           Returns the PPI::Element subclass of the code that caused this
118           exception.
119
120       "set_format( $format )"
121           Class method.  Sets the format for all Violation objects when they
122           are evaluated in string context.  The default is '%d at line %l,
123           column %c. %e'.  See "OVERLOADS" for formatting options.
124
125       "get_format()"
126           Class method. Returns the current format for all Violation objects
127           when they are evaluated in string context.
128
129       "to_string()"
130           Returns a string representation of this violation.  The content of
131           the string depends on the current value of the $format package
132           variable.  See "OVERLOADS" for the details.
133

OVERLOADS

135       Perl::Critic::Violation overloads the "" operator to produce neat
136       little messages when evaluated in string context.
137
138       Formats are a combination of literal and escape characters similar to
139       the way "sprintf" works.  If you want to know the specific formatting
140       capabilities, look at String::Format. Valid escape characters are:
141
142           Escape    Meaning
143           -------   ----------------------------------------------------------------
144           %c        Column number where the violation occurred
145           %d        Full diagnostic discussion of the violation (DESCRIPTION in POD)
146           %e        Explanation of violation or page numbers in PBP
147           %F        Just the name of the logical file where the violation occurred.
148           %f        Path to the logical file where the violation occurred.
149           %G        Just the name of the physical file where the violation occurred.
150           %g        Path to the physical file where the violation occurred.
151           %l        Logical line number where the violation occurred
152           %L        Physical line number where the violation occurred
153           %m        Brief description of the violation
154           %P        Full name of the Policy module that created the violation
155           %p        Name of the Policy without the Perl::Critic::Policy:: prefix
156           %r        The string of source code that caused the violation
157           %C        The class of the PPI::Element that caused the violation
158           %s        The severity level of the violation
159
160       Explanation of the %F, %f, %G, %G, %l, and %L formats: Using "#line"
161       directives, you can affect what perl thinks the current line number and
162       file name are; see "Plain Old Comments (Not!)" in perlsyn for the
163       details.  Under normal circumstances, the values of %F, %f, and %l will
164       match the values of %G, %g, and %L, respectively.  In the presence of a
165       "#line" directive, the values of %F, %f, and %l will change to take
166       that directive into account.  The values of %G, %g, and %L are
167       unaffected by those directives.
168
169       Here are some examples:
170
171           Perl::Critic::Violation::set_format("%m at line %l, column %c.\n");
172           # looks like "Mixed case variable name at line 6, column 23."
173
174           Perl::Critic::Violation::set_format("%m near '%r'\n");
175           # looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'"
176
177           Perl::Critic::Violation::set_format("%l:%c:%p\n");
178           # looks like "6:23:NamingConventions::Capitalization"
179
180           Perl::Critic::Violation::set_format("%m at line %l. %e. \n%d\n");
181           # looks like "Mixed case variable name at line 6.  See page 44 of PBP.
182             Conway's recommended naming convention is to use lower-case words
183             separated by underscores.  Well-recognized acronyms can be in ALL
184             CAPS, but must be separated by underscores from other parts of the
185             name."
186

AUTHOR

188       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
189
191       Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer.  All rights reserved.
192
193       This program is free software; you can redistribute it and/or modify it
194       under the same terms as Perl itself.  The full text of this license can
195       be found in the LICENSE file included with this module.
196
197
198
199perl v5.12.1                      2010-09-08        Perl::Critic::Violation(3)
Impressum