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.