Perl::Critic::Violation - Represents policy violations
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.
violations
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).
Perl::Critic::Violation
description()
Returns a brief description of the policy that has been violated as a string.
explanation()
Returns an explanation of the policy as a string or as reference to an array of page numbers in PBP.
location()
Returns a three-element array reference containing the line and real & virtual column numbers where this Violation occurred, as in PPI::Element.
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.
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.
DESCRIPTION
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 first line will be returned.
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.
'%d at line %l, column %c. %e'
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.
$FORMAT
$Perl::Critic::Violation::FORMAT
DEPRECATED: Use the set_format and get_format methods instead.
set_format
get_format
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. If you want to change $FORMAT, you should probably localize it first.
Perl::Critic::Violation overloads the "" operator to produce neat little messages when evaluated in string context. The format depends on the current value of the $FORMAT package variable.
""
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:
sprintf
Escape Meaning ------- ---------------------------------------------------------------- %c Column number where the violation occurred %d Full diagnostic discussion of the violation %e Explanation of violation or page numbers in PBP %F Just the name of the file where the violation occurred. %f Path to the file where the violation occurred. %l 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 %s The severity level of the violation
Here are some examples:
$Perl::Critic::Violation::FORMAT = "%m at line %l, column %c.\n"; #looks like "Mixed case variable name at line 6, column 23." $Perl::Critic::Violation::FORMAT = "%m near '%r'\n"; #looks like "Mixed case variable name near 'my $theGreatAnswer = 42;'" $Perl::Critic::Violation::FORMAT = "%l:%c:%p\n"; #looks like "6:23:NamingConventions::ProhibitMixedCaseVars" $Perl::Critic::Violation::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 <thaljef@cpan.org>
Copyright (c) 2005-2007 Jeffrey Ryan Thalhammer. 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.
To install Perl::Critic, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl::Critic
CPAN shell
perl -MCPAN -e shell install Perl::Critic
For more information on module installation, please visit the detailed CPAN module installation guide.