Perl::...olation(3pm)

📦
version 1.156.0 · 12 versions
, in opensuse-leap 16.0

💖 NAME 💖

okay so this is the Perl::...olation(3pm) manual page (User Contributed Perl Documentation), and it's literally all about Perl::Critic::Violation — a violation of a Policy found in some source code. periodt. ✨

✨ SYNOPSIS ✨

Bestie, here's the setup, no cap:

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. slay. 🫶

👑 INTERFACE SUPPORT 👑

This is considered to be a public class. Any changes to its interface will go through a deprecation cycle. So like, respect the API, bestie. 💅

🎀 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. So like, when you stringify a violation, it serves looks. 💅

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:

  • %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. iykyk. 💜

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 (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. 🌈

that's the whole page, bestie — from perl v5.42.0, dated 2024-10-23, on the Perl::...olation(3pm) manual page. 💖✨

📦 where this page comes from