Unix/Linux Go Back    


CentOS 7.0 - man page for perl::critic::policy (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


Perl::Critic::Policy(3)        User Contributed Perl Documentation	  Perl::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.16.3				    2014-06-09			  Perl::Critic::Policy(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 12:00 PM.