1Perl::Critic::Utils(3)User Contributed Perl DocumentationPerl::Critic::Utils(3)
2
6 Perl::Critic::Utils - General utility subroutines and constants for
7 Perl::Critic and derivative distributions.
8
10 This module provides several static subs and variables that are useful
11 for developing Perl::Critic::Policy subclasses. Unless you are writing
12 Policy modules, you probably don't care about this package.
13
15 This is considered to be a public module. Any changes to its interface
16 will go through a deprecation cycle.
17
19 "find_keywords( $doc, $keyword )"
20 DEPRECATED: Since version 0.11, every Policy is evaluated at each
21 element of the document. So you shouldn't need to go looking for a
22 particular keyword. If you do want to use this, please import it
23 via the ":deprecated" tag, rather than directly, to mark the module
24 as needing updating.
25 Given a PPI::Document as $doc, returns a reference to an array
27 containing all the PPI::Token::Word elements that match $keyword.
28 This can be used to find any built-in function, method call,
29 bareword, or reserved keyword. It will not match variables,
30 subroutine names, literal strings, numbers, or symbols. If the
31 document doesn't contain any matches, returns undef.
32 "is_assignment_operator( $element )"
34 Given a PPI::Token::Operator or a string, returns true if that
35 token represents one of the assignment operators (e.g. "= &&= ||=
36 //= += -=" etc.).
37 "is_perl_global( $element )"
39 Given a PPI::Token::Symbol or a string, returns true if that token
40 represents one of the global variables provided by the English
41 module, or one of the builtin global variables like %SIG, %ENV, or
42 @ARGV. The sigil on the symbol is ignored, so things like $ARGV or
43 $ENV will still return true.
44 "is_perl_builtin( $element )"
46 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
47 true if that token represents a call to any of the builtin
48 functions defined in Perl 5.8.8.
49 "is_perl_bareword( $element )"
51 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
52 true if that token represents a bareword (e.g. "if", "else", "sub",
53 "package") defined in Perl 5.8.8.
54 "is_perl_filehandle( $element )"
56 Given a PPI::Token::Word, or string, returns true if that token
57 represents one of the global filehandles (e.g. "STDIN", "STDERR",
58 "STDOUT", "ARGV") that are defined in Perl 5.8.8. Note that this
59 function will return false if given a filehandle that is
60 represented as a typeglob (e.g. *STDIN)
61 "is_perl_builtin_with_list_context( $element )"
63 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
64 true if that token represents a call to any of the builtin
65 functions defined in Perl 5.8.8 that provide a list context to the
66 following tokens.
67 "is_perl_builtin_with_multiple_arguments( $element )"
69 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
70 true if that token represents a call to any of the builtin
71 functions defined in Perl 5.8.8 that can take multiple arguments.
72 "is_perl_builtin_with_no_arguments( $element )"
74 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
75 true if that token represents a call to any of the builtin
76 functions defined in Perl 5.8.8 that cannot take any arguments.
77 "is_perl_builtin_with_one_argument( $element )"
79 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
80 true if that token represents a call to any of the builtin
81 functions defined in Perl 5.8.8 that takes one and only one
82 argument.
83 "is_perl_builtin_with_optional_argument( $element )"
85 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
86 true if that token represents a call to any of the builtin
87 functions defined in Perl 5.8.8 that takes no more than one
88 argument.
89 The sets of values for which
91 "is_perl_builtin_with_multiple_arguments()",
92 "is_perl_builtin_with_no_arguments()",
93 "is_perl_builtin_with_one_argument()", and
94 "is_perl_builtin_with_optional_argument()" return true are disjoint
95 and their union is precisely the set of values that
96 "is_perl_builtin()" will return true for.
97 "is_perl_builtin_with_zero_and_or_one_arguments( $element )"
99 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
100 true if that token represents a call to any of the builtin
101 functions defined in Perl 5.8.8 that takes no and/or one argument.
102 Returns true if any of "is_perl_builtin_with_no_arguments()",
104 "is_perl_builtin_with_one_argument()", and
105 "is_perl_builtin_with_optional_argument()" returns true.
106 "is_qualified_name( $name )"
108 Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers
109 whether it has a module component, i.e. contains "::".
110 "precedence_of( $element )"
112 Given a PPI::Token::Operator or a string, returns the precedence of
113 the operator, where 1 is the highest precedence. Returns undef if
114 the precedence can't be determined (which is usually because it is
115 not an operator).
116 "is_hash_key( $element )"
118 Given a PPI::Element, returns true if the element is a literal hash
119 key. PPI doesn't distinguish between regular barewords (like
120 keywords or subroutine calls) and barewords in hash subscripts
121 (which are considered literal). So this subroutine is useful if
122 your Policy is searching for PPI::Token::Word elements and you want
123 to filter out the hash subscript variety. In both of the following
124 examples, "foo" is considered a hash key:
125 $hash1{foo} = 1;
127 %hash2 = (foo => 1);
128 But if the bareword is followed by an argument list, then perl
130 treats it as a function call. So in these examples, "foo" is not
131 considered a hash key:
132 $hash1{ foo() } = 1;
134 &hash2 = (foo() => 1);
135 "is_included_module_name( $element )"
137 Given a PPI::Token::Word, returns true if the element is the name
138 of a module that is being included via "use", "require", or "no".
139 "is_integer( $value )"
141 Answers whether the parameter, as a string, looks like an integral
142 value.
143 "is_class_name( $element )"
145 Given a PPI::Token::Word, returns true if the element that
146 immediately follows this element is the dereference operator "->".
147 When a bareword has a "->" on the right side, it usually means that
148 it is the name of the class (from which a method is being called).
149 "is_label_pointer( $element )"
151 Given a PPI::Token::Word, returns true if the element is the label
152 in a "next", "last", "redo", or "goto" statement. Note this is not
153 the same thing as the label declaration.
154 "is_method_call( $element )"
156 Given a PPI::Token::Word, returns true if the element that
157 immediately precedes this element is the dereference operator "->".
158 When a bareword has a "->" on the left side, it usually means that
159 it is the name of a method (that is being called from a class).
160 "is_package_declaration( $element )"
162 Given a PPI::Token::Word, returns true if the element is the name
163 of a package that is being declared.
164 "is_subroutine_name( $element )"
166 Given a PPI::Token::Word, returns true if the element is the name
167 of a subroutine declaration. This is useful for distinguishing
168 barewords and from function calls from subroutine declarations.
169 "is_function_call( $element )"
171 Given a PPI::Token::Word returns true if the element appears to be
172 call to a static function. Specifically, this function returns
173 true if "is_hash_key", "is_method_call", "is_subroutine_name",
174 "is_included_module_name", "is_package_declaration",
175 "is_perl_bareword", "is_perl_filehandle", "is_label_pointer" and
176 "is_subroutine_name" all return false for the given element.
177 "first_arg( $element )"
179 Given a PPI::Element that is presumed to be a function call (which
180 is usually a PPI::Token::Word), return the first argument. This is
181 similar of "parse_arg_list()" and follows the same logic. Note
182 that for the code:
183 int($x + 0.5)
185 this function will return just the $x, not the whole expression.
187 This is different from the behavior of "parse_arg_list()". Another
188 caveat is:
189 int(($x + $y) + 0.5)
191 which returns "($x + $y)" as a PPI::Structure::List instance.
193 "parse_arg_list( $element )"
195 Given a PPI::Element that is presumed to be a function call (which
196 is usually a PPI::Token::Word), splits the argument expressions
197 into arrays of tokens. Returns a list containing references to
198 each of those arrays. This is useful because parentheses are
199 optional when calling a function, and PPI parses them very
200 differently. So this method is a poor-man's parse tree of PPI
201 nodes. It's not bullet-proof because it doesn't respect
202 precedence. In general, I don't like the way this function works,
203 so don't count on it to be stable (or even present).
204 "split_nodes_on_comma( @nodes )"
206 This has the same return type as "parse_arg_list()" but expects to
207 be passed the nodes that represent the interior of a list, like:
208 'foo', 1, 2, 'bar'
210 "is_script( $document )"
212 This subroutine is deprecated and will be removed in a future
213 release. You should use the "is_program()" in
214 Perl::Critic::Document method instead.
215 "is_in_void_context( $token )"
217 Given a PPI::Token, answer whether it appears to be in a void
218 context.
219 "policy_long_name( $policy_name )"
221 Given a policy class name in long or short form, return the long
222 form.
223 "policy_short_name( $policy_name )"
225 Given a policy class name in long or short form, return the short
226 form.
227 "all_perl_files( @directories )"
229 Given a list of directories, recursively searches through all the
230 directories (depth first) and returns a list of paths for all the
231 files that are Perl code files. Any administrative files for CVS
232 or Subversion are skipped, as are things that look like temporary
233 or backup files.
234 A Perl code file is:
236 • Any file that ends in .PL, .pl, .pm, .psgi, or .t
238 • Any file that has a first line with a shebang containing 'perl'
240 "severity_to_number( $severity )"
242 If $severity is given as an integer, this function returns
243 $severity but normalized to lie between $SEVERITY_LOWEST and
244 $SEVERITY_HIGHEST. If $severity is given as a string, this
245 function returns the corresponding severity number. If the string
246 doesn't have a corresponding number, this function will throw an
247 exception.
248 "is_valid_numeric_verbosity( $severity )"
250 Answers whether the argument has a translation to a Violation
251 format.
252 "verbosity_to_format( $verbosity_level )"
254 Given a verbosity level between 1 and 10, returns the corresponding
255 predefined format string. These formats are suitable for passing
256 to the "set_format" method in Perl::Critic::Violation. See the
257 perlcritic documentation for a listing of the predefined formats.
258 "hashify( @list )"
260 Given @list, return a hash where @list is in the keys and each
261 value is 1. Duplicate values in @list are silently squished.
262 "interpolate( $literal )"
264 Given a $literal string that may contain control characters (e.g..
265 '\t' '\n'), this function does a double interpolation on the string
266 and returns it as if it had been declared in double quotes. For
267 example:
268 'foo \t bar \n' ...becomes... "foo \t bar \n"
270 "shebang_line( $document )"
272 Given a PPI::Document, test if it starts with "#!". If so, return
273 that line. Otherwise return undef.
274 "words_from_string( $str )"
276 Given config string $str, return all the words from the string.
277 This is safer than splitting on whitespace.
278 "is_unchecked_call( $element, $autodie_modules )"
280 Given a PPI::Element, test to see if it contains a function call
281 whose return value is not checked. The second argument is an array
282 reference of module names which export "autodie". The "autodie"
283 module is always included in this list by default.
284
286 $COMMA
287 $FATCOMMA
288 $COLON
289 $SCOLON
290 $QUOTE
291 $DQUOTE
292 $BACKTICK
293 $PERIOD
294 $PIPE
295 $EMPTY
296 $EQUAL
297 $SPACE
298 $SLASH
299 $BSLASH
300 $LEFT_PAREN
301 $RIGHT_PAREN
302 These character constants give clear names to commonly-used strings
303 that can be hard to read when surrounded by quotes and other
304 punctuation. Can be imported in one go via the ":characters" tag.
305 $SEVERITY_HIGHEST
307 $SEVERITY_HIGH
308 $SEVERITY_MEDIUM
309 $SEVERITY_LOW
310 $SEVERITY_LOWEST
311 These numeric constants define the relative severity of violating
312 each Perl::Critic::Policy. The "get_severity" and
313 "default_severity" methods of every Policy subclass must return one
314 of these values. Can be imported via the ":severities" tag.
315 $DEFAULT_VERBOSITY
317 The default numeric verbosity.
318 $DEFAULT_VERBOSITY_WITH_FILE_NAME
320 The numeric verbosity that corresponds to the format indicated by
321 $DEFAULT_VERBOSITY, but with the file name prefixed to it.
322 $TRUE
324 $FALSE
325 These are simple booleans. 1 and 0 respectively. Be mindful of
326 using these with string equality. "$FALSE ne $EMPTY". Can be
327 imported via the ":booleans" tag.
328
330 The following groups of functions and constants are available as
331 parameters to a "use Perl::Critic::Util" statement.
332 ":all"
334 The lot.
335 ":booleans"
337 Includes: $TRUE, $FALSE
338 ":severities"
340 Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
341 $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
342 ":characters"
344 Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
345 $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH
346 $LEFT_PAREN $RIGHT_PAREN
347 ":classification"
349 Includes: "is_assignment_operator", "is_class_name",
350 "is_function_call", "is_hash_key", "is_included_module_name",
351 "is_integer", "is_label_pointer", "is_method_call",
352 "is_package_declaration", "is_perl_bareword", "is_perl_builtin",
353 "is_perl_filehandle", "is_perl_global",
354 "is_perl_builtin_with_list_context"
355 "is_perl_builtin_with_multiple_arguments"
356 "is_perl_builtin_with_no_arguments"
357 "is_perl_builtin_with_one_argument"
358 "is_perl_builtin_with_optional_argument"
359 "is_perl_builtin_with_zero_and_or_one_arguments"
360 "is_qualified_name", "is_script", "is_subroutine_name",
361 "is_unchecked_call" "is_valid_numeric_verbosity"
362 See also Perl::Critic::Utils::PPI.
364 ":data_conversion"
366 Generic manipulation, not having anything specific to do with
367 Perl::Critic.
368 Includes: "hashify", "words_from_string", "interpolate"
370 ":ppi"
372 Things for dealing with PPI, other than classification.
373 Includes: "first_arg", "parse_arg_list"
375 See also Perl::Critic::Utils::PPI.
377 ":internal_lookup"
379 Translations between internal representations.
380 Includes: "severity_to_number", "verbosity_to_format"
382 ":language"
384 Information about Perl not programmatically available elsewhere.
385 Includes: "precedence_of"
387 ":deprecated"
389 Not surprisingly, things that are deprecated. It is preferred to
390 use this tag to get to these functions, rather than the function
391 names themselves, so as to mark any module using them as needing
392 cleanup.
393 Includes: "find_keywords"
395
397 Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
398 Perl::Critic::Utils::PPI,
399
401 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
402
404 Copyright (c) 2005-2011 Imaginative Software Systems. All rights
405 reserved.
406 This program is free software; you can redistribute it and/or modify it
408 under the same terms as Perl itself. The full text of this license can
409 be found in the LICENSE file included with this module.
410perl v5.36.0 2022-07-22 Perl::Critic::Utils(3)