Unix/Linux Go Back    


CentOS 7.0 - man page for perl::critic::utils (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::Utils(3)	       User Contributed Perl Documentation	   Perl::Critic::Utils(3)

NAME
       Perl::Critic::Utils - General utility subroutines and constants for Perl::Critic and
       derivative distributions.

DESCRIPTION
       This module provides several static subs and variables that are useful for developing
       Perl::Critic::Policy subclasses.  Unless you are writing Policy modules, you probably
       don't care about this package.

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

IMPORTABLE SUBS
       "find_keywords( $doc, $keyword )"
	   DEPRECATED: Since version 0.11, every Policy is evaluated at each element of the
	   document.  So you shouldn't need to go looking for a particular keyword.  If you do
	   want to use this, please import it via the ":deprecated" tag, rather than directly, to
	   mark the module as needing updating.

	   Given a PPI::Document as $doc, returns a reference to an array containing all the
	   PPI::Token::Word elements that match $keyword.  This can be used to find any built-in
	   function, method call, bareword, or reserved keyword.  It will not match variables,
	   subroutine names, literal strings, numbers, or symbols.  If the document doesn't
	   contain any matches, returns undef.

       "is_perl_global( $element )"
	   Given a PPI::Token::Symbol or a string, returns true if that token represents one of
	   the global variables provided by the English module, or one of the builtin global
	   variables like %SIG, %ENV, or @ARGV.  The sigil on the symbol is ignored, so things
	   like $ARGV or $ENV will still return true.

       "is_perl_builtin( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8.

       "is_perl_bareword( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a bareword (e.g. "if", "else", "sub", "package") defined in Perl 5.8.8.

       "is_perl_filehandle( $element )"
	   Given a PPI::Token::Word, or string, returns true if that token represents one of the
	   global filehandles (e.g. "STDIN", "STDERR", "STDOUT", "ARGV") that are defined in Perl
	   5.8.8.  Note that this function will return false if given a filehandle that is
	   represented as a typeglob (e.g. *STDIN)

       "is_perl_builtin_with_list_context( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that provide a
	   list context to the following tokens.

       "is_perl_builtin_with_multiple_arguments( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that can take
	   multiple arguments.

       "is_perl_builtin_with_no_arguments( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that cannot
	   take any arguments.

       "is_perl_builtin_with_one_argument( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that takes one
	   and only one argument.

       "is_perl_builtin_with_optional_argument( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that takes no
	   more than one argument.

	   The sets of values for which "is_perl_builtin_with_multiple_arguments()",
	   "is_perl_builtin_with_no_arguments()", "is_perl_builtin_with_one_argument()", and
	   "is_perl_builtin_with_optional_argument()" return true are disjoint and their union is
	   precisely the set of values that "is_perl_builtin()" will return true for.

       "is_perl_builtin_with_zero_and_or_one_arguments( $element )"
	   Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns true if that token
	   represents a call to any of the builtin functions defined in Perl 5.8.8 that takes no
	   and/or one argument.

	   Returns true if any of "is_perl_builtin_with_no_arguments()",
	   "is_perl_builtin_with_one_argument()", and "is_perl_builtin_with_optional_argument()"
	   returns true.

       "is_qualified_name( $name )"
	   Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers whether it has a
	   module component, i.e. contains "::".

       "precedence_of( $element )"
	   Given a PPI::Token::Operator or a string, returns the precedence of the operator,
	   where 1 is the highest precedence.  Returns undef if the precedence can't be
	   determined (which is usually because it is not an operator).

       "is_hash_key( $element )"
	   Given a PPI::Element, returns true if the element is a literal hash key.  PPI doesn't
	   distinguish between regular barewords (like keywords or subroutine calls) and
	   barewords in hash subscripts (which are considered literal).  So this subroutine is
	   useful if your Policy is searching for PPI::Token::Word elements and you want to
	   filter out the hash subscript variety.  In both of the following examples, "foo" is
	   considered a hash key:

	       $hash1{foo} = 1;
	       %hash2 = (foo => 1);

	   But if the bareword is followed by an argument list, then perl treats it as a function
	   call.  So in these examples, "foo" is not considered a hash key:

	       $hash1{ foo() } = 1;
	       &hash2 = (foo() => 1);

       "is_included_module_name( $element )"
	   Given a PPI::Token::Word, returns true if the element is the name of a module that is
	   being included via "use", "require", or "no".

       "is_integer( $value )"
	   Answers whether the parameter, as a string, looks like an integral value.

       "is_class_name( $element )"
	   Given a PPI::Token::Word, returns true if the element that immediately follows this
	   element is the dereference operator "->". When a bareword has a "->" on the right
	   side, it usually means that it is the name of the class (from which a method is being
	   called).

       "is_label_pointer( $element )"
	   Given a PPI::Token::Word, returns true if the element is the label in a "next",
	   "last", "redo", or "goto" statement.  Note this is not the same thing as the label
	   declaration.

       "is_method_call( $element )"
	   Given a PPI::Token::Word, returns true if the element that immediately precedes this
	   element is the dereference operator "->". When a bareword has a "->" on the left side,
	   it usually means that it is the name of a method (that is being called from a class).

       "is_package_declaration( $element )"
	   Given a PPI::Token::Word, returns true if the element is the name of a package that is
	   being declared.

       "is_subroutine_name( $element )"
	   Given a PPI::Token::Word, returns true if the element is the name of a subroutine
	   declaration.  This is useful for distinguishing barewords and from function calls from
	   subroutine declarations.

       "is_function_call( $element )"
	   Given a PPI::Token::Word returns true if the element appears to be call to a static
	   function.  Specifically, this function returns true if "is_hash_key",
	   "is_method_call", "is_subroutine_name", "is_included_module_name",
	   "is_package_declaration", "is_perl_bareword", "is_perl_filehandle", "is_label_pointer"
	   and "is_subroutine_name" all return false for the given element.

       "first_arg( $element )"
	   Given a PPI::Element that is presumed to be a function call (which is usually a
	   PPI::Token::Word), return the first argument.  This is similar of "parse_arg_list()"
	   and follows the same logic.	Note that for the code:

	       int($x + 0.5)

	   this function will return just the $x, not the whole expression.  This is different
	   from the behavior of "parse_arg_list()".  Another caveat is:

	       int(($x + $y) + 0.5)

	   which returns "($x + $y)" as a PPI::Structure::List instance.

       "parse_arg_list( $element )"
	   Given a PPI::Element that is presumed to be a function call (which is usually a
	   PPI::Token::Word), splits the argument expressions into arrays of tokens.  Returns a
	   list containing references to each of those arrays.	This is useful because
	   parentheses are optional when calling a function, and PPI parses them very
	   differently.  So this method is a poor-man's parse tree of PPI nodes.  It's not
	   bullet-proof because it doesn't respect precedence.	In general, I don't like the way
	   this function works, so don't count on it to be stable (or even present).

       "split_nodes_on_comma( @nodes )"
	   This has the same return type as "parse_arg_list()" but expects to be passed the nodes
	   that represent the interior of a list, like:

	       'foo', 1, 2, 'bar'

       "is_script( $document )"
	   This subroutine is deprecated and will be removed in a future release. You should use
	   the "is_program()" in Perl::Critic::Document method instead.

       "is_in_void_context( $token )"
	   Given a PPI::Token, answer whether it appears to be in a void context.

       "policy_long_name( $policy_name )"
	   Given a policy class name in long or short form, return the long form.

       "policy_short_name( $policy_name )"
	   Given a policy class name in long or short form, return the short form.

       "all_perl_files( @directories )"
	   Given a list of directories, recursively searches through all the directories (depth
	   first) and returns a list of paths for all the files that are Perl code files.  Any
	   administrative files for CVS or Subversion are skipped, as are things that look like
	   temporary or backup files.

	   A Perl code file is:

	   o   Any file that ends in .PL, .pl, .pm, or .t

	   o   Any file that has a first line with a shebang containing 'perl'

       "severity_to_number( $severity )"
	   If $severity is given as an integer, this function returns $severity but normalized to
	   lie between $SEVERITY_LOWEST and $SEVERITY_HIGHEST.	If $severity is given as a
	   string, this function returns the corresponding severity number.  If the string
	   doesn't have a corresponding number, this function will throw an exception.

       "is_valid_numeric_verbosity( $severity )"
	   Answers whether the argument has a translation to a Violation format.

       "verbosity_to_format( $verbosity_level )"
	   Given a verbosity level between 1 and 10, returns the corresponding predefined format
	   string.  These formats are suitable for passing to the "set_format" method in
	   Perl::Critic::Violation.  See the perlcritic documentation for a listing of the
	   predefined formats.

       "hashify( @list )"
	   Given @list, return a hash where @list is in the keys and each value is 1.  Duplicate
	   values in @list are silently squished.

       "interpolate( $literal )"
	   Given a $literal string that may contain control characters (e.g..  '\t' '\n'), this
	   function does a double interpolation on the string and returns it as if it had been
	   declared in double quotes.  For example:

	       'foo \t bar \n' ...becomes... "foo \t bar \n"

       "shebang_line( $document )"
	   Given a PPI::Document, test if it starts with "#!".	If so, return that line.
	   Otherwise return undef.

       "words_from_string( $str )"
	   Given config string $str, return all the words from the string.  This is safer than
	   splitting on whitespace.

       "is_unchecked_call( $element )"
	   Given a PPI::Element, test to see if it contains a function call whose return value is
	   not checked.

IMPORTABLE VARIABLES
       $COMMA
       $FATCOMMA
       $COLON
       $SCOLON
       $QUOTE
       $DQUOTE
       $BACKTICK
       $PERIOD
       $PIPE
       $EMPTY
       $EQUAL
       $SPACE
       $SLASH
       $BSLASH
       $LEFT_PAREN
       $RIGHT_PAREN
	   These character constants give clear names to commonly-used strings that can be hard
	   to read when surrounded by quotes and other punctuation.  Can be imported in one go
	   via the ":characters" tag.

       $SEVERITY_HIGHEST
       $SEVERITY_HIGH
       $SEVERITY_MEDIUM
       $SEVERITY_LOW
       $SEVERITY_LOWEST
	   These numeric constants define the relative severity of violating each
	   Perl::Critic::Policy.  The "get_severity" and "default_severity" methods of every
	   Policy subclass must return one of these values. Can be imported via the ":severities"
	   tag.

       $DEFAULT_VERBOSITY
	   The default numeric verbosity.

       $DEFAULT_VERBOSITY_WITH_FILE_NAME
	   The numeric verbosity that corresponds to the format indicated by $DEFAULT_VERBOSITY,
	   but with the file name prefixed to it.

       $TRUE
       $FALSE
	   These are simple booleans. 1 and 0 respectively.  Be mindful of using these with
	   string equality.  "$FALSE ne $EMPTY".  Can be imported via the ":booleans" tag.

IMPORT TAGS
       The following groups of functions and constants are available as parameters to a "use
       Perl::Critic::Util" statement.

       ":all"
	   The lot.

       ":booleans"
	   Includes: $TRUE, $FALSE

       ":severities"
	   Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM, $SEVERITY_LOW,
	   $SEVERITY_LOWEST, @SEVERITY_NAMES

       ":characters"
	   Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD, $PIPE, $QUOTE,
	   $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH $LEFT_PAREN $RIGHT_PAREN

       ":classification"
	   Includes: "is_function_call", "is_hash_key", "is_included_module_name", "is_integer",
	   "is_method_call", "is_package_declaration", "is_perl_builtin", "is_perl_global",
	   "is_perl_builtin_with_list_context" "is_perl_builtin_with_multiple_arguments"
	   "is_perl_builtin_with_no_arguments" "is_perl_builtin_with_one_argument"
	   "is_perl_builtin_with_optional_argument"
	   "is_perl_builtin_with_zero_and_or_one_arguments" "is_script", "is_subroutine_name",
	   "is_unchecked_call" "is_valid_numeric_verbosity"

	   See also Perl::Critic::Utils::PPI.

       ":data_conversion"
	   Generic manipulation, not having anything specific to do with Perl::Critic.

	   Includes: "hashify", "words_from_string", "interpolate"

       ":ppi"
	   Things for dealing with PPI, other than classification.

	   Includes: "first_arg", "parse_arg_list"

	   See also Perl::Critic::Utils::PPI.

       ":internal_lookup"
	   Translations between internal representations.

	   Includes: "severity_to_number", "verbosity_to_format"

       ":language"
	   Information about Perl not programmatically available elsewhere.

	   Includes: "precedence_of"

       ":deprecated"
	   Not surprisingly, things that are deprecated.  It is preferred to use this tag to get
	   to these functions, rather than the function names themselves, so as to mark any
	   module using them as needing cleanup.

	   Includes: "find_keywords"

SEE ALSO
       Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe, Perl::Critic::Utils::PPI,

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::Utils(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:23 PM.