Perl::Critic::Violation - A violation of a Policy found in some source code. |
Perl::Critic::Violation - A violation of a Policy found in some source code.
use PPI; use Perl::Critic::Violation;
my $elem = $doc->child(0); # $doc is a PPI::Document object my $desc = 'Offending code'; # Describe the violation my $expl = [1,45,67]; # Page numbers from PBP my $sev = 5; # Severity level of this violation
my $vio = Perl::Critic::Violation->new($desc, $expl, $node, $sev);
Perl::Critic::Violation is the generic representation of an individual
Policy violation. Its primary purpose is to provide an abstraction
layer so that clients of Perl::Critic don't have to
know anything about PPI. The violations
method of all
Perl::Critic::Policy subclasses must return a
list of these Perl::Critic::Violation objects.
This is considered to be a public class. Any changes to its interface will go through a deprecation cycle.
new( $description, $explanation, $element, $severity )
Perl::Critic::Violation
object. The
arguments are a description of the violation (as string), an
explanation for the policy (as string) or a series of page numbers in
PBP (as an ARRAY ref), a reference to the PPI element that
caused the violation, and the severity of the violation (as an
integer).
description()
explanation()
location()
line_number()
,
logical_line_number()
, column_number()
,
visual_column_number()
, and logical_filename()
methods instead.
Returns a five-element array reference containing the line and real & virtual column and logical numbers and logical file name where this Violation occurred, as in PPI::Element.
line_number()
logical_line_number()
#line
directives in the code.
column_number()
visual_column_number()
filename()
logical_filename()
filename()
when there was a #line
directive
in the code.
severity()
sort_by_severity( @violation_objects )
@sorted = Perl::Critic::Violation::sort_by_severity(@violations);
sort_by_location( @violation_objects )
@sorted = Perl::Critic::Violation::sort_by_location(@violations);
diagnostics()
DESCRIPTION
section of the Policy module's POD.
policy()
source()
element_class()
set_format( $format )
'%d at line %l, column
%c. %e'
. See OVERLOADS for formatting options.
get_format()
to_string()
$format
package
variable. See OVERLOADS for the details.
Perl::Critic::Violation overloads the ""
operator to produce neat
little messages when evaluated in string context.
Formats are a combination of literal and escape characters similar to
the way sprintf
works. If you want to know the specific formatting
capabilities, look at String::Format. Valid escape
characters are:
Escape Meaning ------- ---------------------------------------------------------------- %c Column number where the violation occurred %d Full diagnostic discussion of the violation (DESCRIPTION in POD) %e Explanation of violation or page numbers in PBP %F Just the name of the logical file where the violation occurred. %f Path to the logical file where the violation occurred. %G Just the name of the physical file where the violation occurred. %g Path to the physical file where the violation occurred. %l Logical line number where the violation occurred %L Physical line number where the violation occurred %m Brief description of the violation %P Full name of the Policy module that created the violation %p Name of the Policy without the Perl::Critic::Policy:: prefix %r The string of source code that caused the violation %C The class of the PPI::Element that caused the violation %s The severity level of the violation
Explanation of the %F
, %f
, %G
, %G
, %l
, and %L
formats:
Using #line
directives, you can affect what perl thinks the current line
number and file name are; see Plain Old Comments (Not!) in the perlsyn manpage for
the details. Under normal circumstances, the values of %F
, %f
, and
%l
will match the values of %G
, %g
, and %L
, respectively. In the
presence of a #line
directive, the values of %F
, %f
, and %l
will
change to take that directive into account. The values of %G
, %g
, and
%L
are unaffected by those directives.
Here are some examples:
Perl::Critic::Violation::set_format("%m at line %l, column %c.\n"); # looks like "Mixed case variable name at line 6, column 23."
Perl::Critic::Violation::set_format("%m near '%r'\n"); # looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'"
Perl::Critic::Violation::set_format("%l:%c:%p\n"); # looks like "6:23:NamingConventions::Capitalization"
Perl::Critic::Violation::set_format("%m at line %l. %e. \n%d\n"); # looks like "Mixed case variable name at line 6. See page 44 of PBP. Conway's recommended naming convention is to use lower-case words separated by underscores. Well-recognized acronyms can be in ALL CAPS, but must be separated by underscores from other parts of the name."
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
Copyright (c) 2005-2011 Imaginative Software Systems. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the LICENSE file included with this module.
Perl::Critic::Violation - A violation of a Policy found in some source code. |