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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::Policy(3User Contributed Perl DocumentatiPerl::Critic::Policy(3)

NAME
       Perl::Critic::Policy - Base class for all Policy	modules.

DESCRIPTION
       Perl::Critic::Policy is the abstract base class for all Policy objects.
       If you're developing your own Policies, your job	is to implement	and
       override	its methods in a subclass.  To work with the Perl::Critic
       engine, your implementation must	behave as described below.  For	a
       detailed	explanation on how to make new Policy modules, please see the
       Perl::Critic::DEVELOPER document	included in this distribution.

INTERFACE SUPPORT
       This is considered to be	a public class.	 Any changes to	its interface
       will go through a deprecation cycle.

METHODS
       "new( ... )"
	   Don't call this.  As	a Policy author, do not	implement this.	 Use
	   the "initialize_if_enabled()" method	for your Policy	setup.	See
	   the developer documentation for more.

       "initialize_if_enabled( $config )"
	   This	receives an instance of	Perl::Critic::PolicyConfig as a
	   parameter, and is only invoked if this Policy is enabled by the
	   user.  Thus,	this is	the preferred place for	subclasses to do any
	   initialization.

	   Implementations of this method should return	a boolean value
	   indicating whether the Policy should	continue to be enabled.	 For
	   most	subclasses, this will always be	$TRUE.	Policies that depend
	   upon	external modules or other system facilities that may or	may
	   not be available should test	for the	availability of	these
	   dependencies	and return $FALSE if they are not.

       "prepare_to_scan_document( $document )"
	   The parameter is about to be	scanned	by this	Policy.	 Whatever this
	   Policy wants	to do in terms of preparation should happen here.
	   Returns a boolean value indicating whether the document should be
	   scanned at all; if this is a	false value, this Policy won't be
	   applied to the document.  By	default, does nothing but return
	   $TRUE.

       " violates( $element, $document ) "
	   Given a PPI::Element	and a PPI::Document, returns one or more
	   Perl::Critic::Violation objects if the $element violates this
	   Policy.  If there are no violations,	then it	returns	an empty list.
	   If the Policy encounters an exception, then it should "croak" with
	   an error message and	let the	caller decide how to handle it.

	   "violates()"	is an abstract method and it will abort	if you attempt
	   to invoke it	directly.  It is the heart of all Policy modules, and
	   your	subclass must override this method.

       " violation( $description, $explanation,	$element ) "
	   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.

	   These are the same as the constructor to Perl::Critic::Violation,
	   but without the severity.  The Policy itself	knows the severity.

       " new_parameter_value_exception(	$option_name, $option_value, $source,
       $message_suffix ) "
	   Create a
	   Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue
	   for this Policy.

       " throw_parameter_value_exception( $option_name,	$option_value,
       $source,	$message_suffix	) "
	   Create and throw a
	   Perl::Critic::Exception::Configuration::Option::Policy::ParameterValue.
	   Useful in parameter parser implementations.

       " get_long_name() "
	   Return the full package name	of this	policy.

       " get_short_name() "
	   Return the name of this policy without the "Perl::Critic::Policy::"
	   prefix.

       " is_enabled() "
	   Answer whether this policy is really	active or not.	Returns	a true
	   value if it is, a false, yet	defined, value if it isn't, and	an
	   undefined value if it hasn't	yet been decided whether it will be.

       " applies_to() "
	   Returns a list of the names of PPI classes that this	Policy cares
	   about.  By default, the result is "PPI::Element".  Overriding this
	   method in Policy subclasses should lead to significant performance
	   increases.

       " default_maximum_violations_per_document() "
	   Returns the default maximum number of violations for	this policy to
	   report per document.	 By default, this not defined, but subclasses
	   may override	this.

       " get_maximum_violations_per_document() "
	   Returns the maximum number of violations this policy	will report
	   for a single	document.  If this is not defined, then	there is no
	   limit.  If "set_maximum_violations_per_document()" has not been
	   invoked, then "default_maximum_violations_per_document()" is
	   returned.

       " set_maximum_violations_per_document() "
	   Specify the maximum violations that this policy should report for a
	   document.

       " default_severity() "
	   Returns the default severity	for violating this Policy.  See	the
	   $SEVERITY constants in Perl::Critic::Utils for an enumeration of
	   possible severity values.  By default, this method returns
	   $SEVERITY_LOWEST.  Authors of Perl::Critic::Policy subclasses
	   should override this	method to return a value that they feel	is
	   appropriate for their Policy.  In general, Polices that are widely
	   accepted or tend to prevent bugs should have	a higher severity than
	   those that are more subjective or cosmetic in nature.

       " get_severity()	"
	   Returns the severity	of violating this Policy.  If the severity has
	   not been explicitly defined by calling "set_severity", then the
	   "default_severity" is returned.  See	the $SEVERITY constants	in
	   Perl::Critic::Utils for an enumeration of possible severity values.

       " set_severity( $N ) "
	   Sets	the severity for violating this	Policy.	 Clients of
	   Perl::Critic::Policy	objects	can call this method to	assign a
	   different severity to the Policy if they don't agree	with the
	   "default_severity".	See the	$SEVERITY constants in
	   Perl::Critic::Utils for an enumeration of possible values.

       " default_themes() "
	   Returns a sorted list of the	default	themes associated with this
	   Policy.  The	default	method returns an empty	list.  Policy authors
	   should override this	method to return a list	of themes that are
	   appropriate for their policy.

       " get_themes() "
	   Returns a sorted list of the	themes associated with this Policy.
	   If you haven't added	themes or set the themes explicitly, this
	   method just returns the default themes.

       " set_themes( @THEME_LIST ) "
	   Sets	the themes associated with this	Policy.	 Any existing themes
	   are overwritten.  Duplicate themes will be removed.

       " add_themes( @THEME_LIST ) "
	   Appends additional themes to	this Policy.  Any existing themes are
	   preserved.  Duplicate themes	will be	removed.

       " get_abstract()	"
	   Retrieve the	abstract for this policy (the part of the NAME section
	   of the POD after the	module name), if it is available.

       " get_raw_abstract() "
	   Retrieve the	abstract for this policy (the part of the NAME section
	   of the POD after the	module name), if it is available, in the
	   unparsed form.

       " parameter_metadata_available()	"
	   Returns whether information about the parameters is available.

       " get_parameters() "
	   Returns a reference to an array containing instances	of
	   Perl::Critic::PolicyParameter.

	   Note	that this will return an empty list if the parameters for this
	   policy are unknown.	In order to differentiate between this
	   circumstance	and the	one where this policy does not take any
	   parameters, it is necessary to call
	   "parameter_metadata_available()".

       "set_format( $format )"
	   Class method.  Sets the format for all Policy objects when they are
	   evaluated in	string context.	 The default is	"%p\n".	 See
	   "OVERLOADS" for formatting options.

       "get_format()"
	   Class method. Returns the current format for	all Policy objects
	   when	they are evaluated in string context.

       "to_string()"
	   Returns a string representation of the policy.  The content of the
	   string depends on the current value returned	by "get_format()".
	   See "OVERLOADS" for the details.

       "is_safe()"
	   Answer whether this Policy can be used to analyze untrusted code,
	   i.e.	the Policy doesn't have	any potential side effects.

	   This	method returns a true value by default.

	   An "unsafe" policy might attempt to compile the code, which,	if you
	   have	"BEGIN"	or "CHECK" blocks that affect files or connect to
	   databases, is not a safe thing to do.  If you are writing a such a
	   Policy, then	you should override this method	to return false.

	   By default Perl::Critic will	not run	unsafe policies.

DOCUMENTATION
       When your Policy	module first "use"s Perl::Critic::Violation, it	will
       try and extract the DESCRIPTION section of your Policy module's POD.
       This information	is displayed by	Perl::Critic if	the verbosity level is
       set accordingly.	 Therefore, please include a DESCRIPTION section in
       the POD for any Policy modules that you author.	Thanks.

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:

       %P  Name	of the Policy module.

       %p  Name	of the Policy without the "Perl::Critic::Policy::" prefix.

       %a  The policy abstract.

       %O  List	of supported policy parameters.	 Takes an option of a format
	   string for "to_formatted_string" in Perl::Critic::PolicyParameter.
	   For example,	this can be used like "%{%n - %d\n}O" to get a list of
	   parameter names followed by their descriptions.

       %U  A message stating that the parameters for the policy	are unknown if
	   "parameter_metadata_available()" returns false.  Takes an option of
	   what	the message should be, which defaults to "Cannot
	   programmatically discover what parameters this policy takes.".  The
	   value of this option	is interpolated	in order to expand the
	   standard escape sequences ("\n", "\t", etc.).

       %S  The default severity	level of the policy.

       %s  The current severity	level of the policy.

       %T  The default themes for the policy.

       %t  The current themes for the policy.

       %V  The default maximum number of violations per	document of the
	   policy.

       %v  The current maximum number of violations per	document of the
	   policy.

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::Policy(3)

NAME | DESCRIPTION | INTERFACE SUPPORT | METHODS | DOCUMENTATION | OVERLOADS | AUTHOR | COPYRIGHT

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

home | help