--- name: "Perl::Critic::Violation" section: "3pm" platform: "linux" package: "perl-perl-critic" version: "1.156-3" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Perl::Critic::Violation" --- # Perl::Critic::Violation(3pm) A violation of a Policy found in some source code. ## 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 \ ## COPYRIGHT Copyright (c) 2005-2023 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.