Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::ViolatioUser Contributed Perl DocumentPerl::Critic::Violation(3)

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.

perl v5.24.1			  2017-07-02	    Perl::Critic::Violation(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE SUPPORT | CONSTRUCTOR | METHODS | OVERLOADS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Violation&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help