NAME¶
Perl::Critic::Violation - A violation of a Policy found in some source code.
SYNOPSIS¶
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);
DESCRIPTION¶
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.
INTERFACE SUPPORT¶
This is considered to be a public class. Any changes to its interface will go
through a deprecation cycle.
CONSTRUCTOR¶
- "new( $description, $explanation, $element, $severity
)"
- Returns a reference to a new
"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).
METHODS¶
- "description()"
- Returns a brief description of the specific violation. In
other words, this value may change on a per violation basis.
- "explanation()"
- Returns an explanation of the policy as a string or as
reference to an array of page numbers in PBP. This value will generally
not change based upon the specific code violating the policy.
- "location()"
- Don't use this method. Use the "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()"
- Returns the physical line number that the violation was
found on.
- "logical_line_number()"
- Returns the logical line number that the violation was
found on. This can differ from the physical line number when there were
"#line" directives in the code.
- "column_number()"
- Returns the physical column that the violation was found
at. This means that hard tab characters count as a single character.
- "visual_column_number()"
- Returns the column that the violation was found at, as it
would appear if hard tab characters were expanded, based upon the value of
"tab_width [ $width ]" in PPI::Document.
- "filename()"
- Returns the path to the file where this Violation occurred.
In some cases, the path may be undefined because the source code was not
read directly from a file.
- "logical_filename()"
- Returns the logical path to the file where the Violation
occurred. This can differ from "filename()" when there was a
"#line" directive in the code.
- "severity()"
- Returns the severity of this Violation as an integer
ranging from 1 to 5, where 5 is the "most" severe.
- "sort_by_severity( @violation_objects )"
- If you need to sort Violations by severity, use this handy
routine:
@sorted = Perl::Critic::Violation::sort_by_severity(@violations);
- "sort_by_location( @violation_objects )"
- If you need to sort Violations by location, use this handy
routine:
@sorted = Perl::Critic::Violation::sort_by_location(@violations);
- "diagnostics()"
- Returns a formatted string containing a full discussion of
the motivation for and details of the Policy module that created this
Violation. This information is automatically extracted from the
"DESCRIPTION" section of the Policy module's POD.
- "policy()"
- Returns the name of the Perl::Critic::Policy that created
this Violation.
- "source()"
- Returns the string of source code that caused this
exception. If the code spans multiple lines (e.g. multi-line statements,
subroutines or other blocks), then only the line containing the violation
will be returned.
- "element_class()"
- Returns the PPI::Element subclass of the code that caused
this exception.
- "set_format( $format )"
- Class method. Sets the format for all Violation objects
when they are evaluated in string context. The default is '%d at line %l,
column %c. %e'. See "OVERLOADS" for formatting options.
- "get_format()"
- Class method. Returns the current format for all Violation
objects when they are evaluated in string context.
- "to_string()"
- Returns a string representation of this violation. The
content of the string depends on the current value of the $format package
variable. See "OVERLOADS" for the details.
OVERLOADS¶
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 perlsyn 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."
AUTHOR¶
Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
COPYRIGHT¶
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.