sourCEntral - mobile manpages

pdf

Perl::Critic::Violation

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.

pdf