NAME

Perl::Critic::Violation - Represents policy violations

SYNOPSIS

  use PPI;
  use Perl::Critic::Violation;

  my $loc  = $node->location();   #$node is a PPI::Node object
  my $desc = 'Offending code';    #Describe the violation
  my $expl = [1,45,67];           #Page numbers from PBB
  my $vio  = Perl::Critic::Violation->new($desc, $expl, $loc);

DESCRIPTION

Perl::Critic::Violation is the generic represntation 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.

CONSTRUCTOR

new( $description, $explanation, $location )

Retruns 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 PBB (as an ARRAY ref), and the location of the violation (as an ARRAY ref). The $location must have two elements, representing the line and column number, in that order.

METHODS

description ( void )

Returns a brief description of the policy that has been volated as a string.

explanation( void )

Returns the explanation for this policy as a string or as reference to an array of page numbers in PBB.

location( void )

Returns a two-element list containing the line and column number where the violation occurred.

diagnostics( void )

This feature is experimental. Returns a formatted string containing a full discussion of the motivation, 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( void )

Returns the name of the Perl::Critic::Policy module that created this Violation.

to_string( void )

Returns a string repesentation of this violation. The content of the string depends on the current value of the $FORMAT package variable. See "OVERLOADS" for the details.

FIELDS

$Perl::Critic::Violation::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 localize it first.

OVERLOADS

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:

  Escape    Meaning
  -------   -------------------------------------------------------
  %m        Brief description of the violation
  %l        Line number where the violation occured
  %c        Column number where the violation occured
  %e        Explanation of violation or page numbers in PBP
  %d        Full diagnostic discussion of the violation
  %p        Name of the Policy module that created 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 = "%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."

AUTHOR

Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

Copyright (c) 2005 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.