1Perl::Critic::Utils(3pmU)ser Contributed Perl DocumentatiPoenrl::Critic::Utils(3pm)
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.
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").
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"). Note that this function will return false if
59 given a filehandle that is represented as a typeglob (e.g. *STDIN)
60 is_perl_builtin_with_list_context( $element )
62 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
63 true if that token represents a call to any of the builtin
64 functions that provide a list context to the following tokens.
65 is_perl_builtin_with_multiple_arguments( $element )
67 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
68 true if that token represents a call to any of the builtin
69 functions that can take multiple arguments.
70 is_perl_builtin_with_no_arguments( $element )
72 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
73 true if that token represents a call to any of the builtin
74 functions that cannot take any arguments.
75 is_perl_builtin_with_one_argument( $element )
77 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
78 true if that token represents a call to any of the builtin
79 functions that takes one and only one argument.
80 is_perl_builtin_with_optional_argument( $element )
82 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
83 true if that token represents a call to any of the builtin
84 functions that takes no more than one argument.
85 The sets of values for which
87 is_perl_builtin_with_multiple_arguments(),
88 is_perl_builtin_with_no_arguments(),
89 is_perl_builtin_with_one_argument(), and
90 is_perl_builtin_with_optional_argument() return true are disjoint
91 and their union is precisely the set of values that
92 is_perl_builtin() will return true for.
93 is_perl_builtin_with_zero_and_or_one_arguments( $element )
95 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
96 true if that token represents a call to any of the builtin
97 functions that takes no and/or one argument.
98 Returns true if any of is_perl_builtin_with_no_arguments(),
100 is_perl_builtin_with_one_argument(), and
101 is_perl_builtin_with_optional_argument() returns true.
102 is_qualified_name( $name )
104 Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers
105 whether it has a module component, i.e. contains "::".
106 precedence_of( $element )
108 Given a PPI::Token::Operator or a string, returns the precedence of
109 the operator, where 1 is the highest precedence. Returns undef if
110 the precedence can't be determined (which is usually because it is
111 not an operator).
112 is_hash_key( $element )
114 Given a PPI::Element, returns true if the element is a literal hash
115 key. PPI doesn't distinguish between regular barewords (like
116 keywords or subroutine calls) and barewords in hash subscripts
117 (which are considered literal). So this subroutine is useful if
118 your Policy is searching for PPI::Token::Word elements and you want
119 to filter out the hash subscript variety. In both of the following
120 examples, "foo" is considered a hash key:
121 $hash1{foo} = 1;
123 %hash2 = (foo => 1);
124 But if the bareword is followed by an argument list, then perl
126 treats it as a function call. So in these examples, "foo" is not
127 considered a hash key:
128 $hash1{ foo() } = 1;
130 &hash2 = (foo() => 1);
131 is_included_module_name( $element )
133 Given a PPI::Token::Word, returns true if the element is the name
134 of a module that is being included via "use", "require", or "no".
135 is_integer( $value )
137 Answers whether the parameter, as a string, looks like an integral
138 value.
139 is_class_name( $element )
141 Given a PPI::Token::Word, returns true if the element that
142 immediately follows this element is the dereference operator "->".
143 When a bareword has a "->" on the right side, it usually means that
144 it is the name of the class (from which a method is being called).
145 is_label_pointer( $element )
147 Given a PPI::Token::Word, returns true if the element is the label
148 in a "next", "last", "redo", or "goto" statement. Note this is not
149 the same thing as the label declaration.
150 is_method_call( $element )
152 Given a PPI::Token::Word, returns true if the element that
153 immediately precedes this element is the dereference operator "->".
154 When a bareword has a "->" on the left side, it usually means that
155 it is the name of a method (that is being called from a class).
156 is_package_declaration( $element )
158 Given a PPI::Token::Word, returns true if the element is the name
159 of a package that is being declared.
160 is_subroutine_name( $element )
162 Given a PPI::Token::Word, returns true if the element is the name
163 of a subroutine declaration. This is useful for distinguishing
164 barewords and from function calls from subroutine declarations.
165 is_function_call( $element )
167 Given a PPI::Token::Word returns true if the element appears to be
168 call to a static function. Specifically, this function returns
169 true if "is_hash_key", "is_method_call", "is_subroutine_name",
170 "is_included_module_name", "is_package_declaration",
171 "is_perl_bareword", "is_perl_filehandle", "is_label_pointer" and
172 "is_subroutine_name" all return false for the given element.
173 first_arg( $element )
175 Given a PPI::Element that is presumed to be a function call (which
176 is usually a PPI::Token::Word), return the first argument. This is
177 similar of parse_arg_list() and follows the same logic. Note that
178 for the code:
179 int($x + 0.5)
181 this function will return just the $x, not the whole expression.
183 This is different from the behavior of parse_arg_list(). Another
184 caveat is:
185 int(($x + $y) + 0.5)
187 which returns "($x + $y)" as a PPI::Structure::List instance.
189 parse_arg_list( $element )
191 Given a PPI::Element that is presumed to be a function call (which
192 is usually a PPI::Token::Word), splits the argument expressions
193 into arrays of tokens. Returns a list containing references to
194 each of those arrays. This is useful because parentheses are
195 optional when calling a function, and PPI parses them very
196 differently. So this method is a poor-man's parse tree of PPI
197 nodes. It's not bullet-proof because it doesn't respect
198 precedence. In general, I don't like the way this function works,
199 so don't count on it to be stable (or even present).
200 split_nodes_on_comma( @nodes )
202 This has the same return type as parse_arg_list() but expects to be
203 passed the nodes that represent the interior of a list, like:
204 'foo', 1, 2, 'bar'
206 is_script( $document )
208 This subroutine is deprecated and will be removed in a future
209 release. You should use the "is_program()" in
210 Perl::Critic::Document method instead.
211 is_in_void_context( $token )
213 Given a PPI::Token, answer whether it appears to be in a void
214 context.
215 policy_long_name( $policy_name )
217 Given a policy class name in long or short form, return the long
218 form.
219 policy_short_name( $policy_name )
221 Given a policy class name in long or short form, return the short
222 form.
223 all_perl_files( @directories )
225 Given a list of directories, recursively searches through all the
226 directories (depth first) and returns a list of paths for all the
227 files that are Perl code files. Any administrative files for CVS
228 or Subversion are skipped, as are things that look like temporary
229 or backup files.
230 A Perl code file is:
232 • Any file that ends in .PL, .pl, .pm, .psgi, or .t
234 • Any file that has a first line with a shebang containing 'perl'
236 severity_to_number( $severity )
238 If $severity is given as an integer, this function returns
239 $severity but normalized to lie between $SEVERITY_LOWEST and
240 $SEVERITY_HIGHEST. If $severity is given as a string, this
241 function returns the corresponding severity number. If the string
242 doesn't have a corresponding number, this function will throw an
243 exception.
244 is_valid_numeric_verbosity( $severity )
246 Answers whether the argument has a translation to a Violation
247 format.
248 verbosity_to_format( $verbosity_level )
250 Given a verbosity level between 1 and 10, returns the corresponding
251 predefined format string. These formats are suitable for passing
252 to the "set_format" method in Perl::Critic::Violation. See the
253 perlcritic documentation for a listing of the predefined formats.
254 hashify( @list )
256 Given @list, return a hash where @list is in the keys and each
257 value is 1. Duplicate values in @list are silently squished.
258 interpolate( $literal )
260 Given a $literal string that may contain control characters (e.g..
261 '\t' '\n'), this function does a double interpolation on the string
262 and returns it as if it had been declared in double quotes. For
263 example:
264 'foo \t bar \n' ...becomes... "foo \t bar \n"
266 shebang_line( $document )
268 Given a PPI::Document, test if it starts with "#!". If so, return
269 that line. Otherwise return undef.
270 words_from_string( $str )
272 Given config string $str, return all the words from the string.
273 This is safer than splitting on whitespace.
274 "is_unchecked_call( $element, $autodie_modules )"
276 Given a PPI::Element, test to see if it contains a function call
277 whose return value is not checked. The second argument is an array
278 reference of module names which export "autodie". The "autodie"
279 module is always included in this list by default.
280
282 $COMMA
283 $FATCOMMA
284 $COLON
285 $SCOLON
286 $QUOTE
287 $DQUOTE
288 $BACKTICK
289 $PERIOD
290 $PIPE
291 $EMPTY
292 $EQUAL
293 $SPACE
294 $SLASH
295 $BSLASH
296 $LEFT_PAREN
297 $RIGHT_PAREN
298 These character constants give clear names to commonly-used strings
299 that can be hard to read when surrounded by quotes and other
300 punctuation. Can be imported in one go via the ":characters" tag.
301 $SEVERITY_HIGHEST
303 $SEVERITY_HIGH
304 $SEVERITY_MEDIUM
305 $SEVERITY_LOW
306 $SEVERITY_LOWEST
307 These numeric constants define the relative severity of violating
308 each Perl::Critic::Policy. The "get_severity" and
309 "default_severity" methods of every Policy subclass must return one
310 of these values. Can be imported via the ":severities" tag.
311 $DEFAULT_VERBOSITY
313 The default numeric verbosity.
314 $DEFAULT_VERBOSITY_WITH_FILE_NAME
316 The numeric verbosity that corresponds to the format indicated by
317 $DEFAULT_VERBOSITY, but with the file name prefixed to it.
318 $TRUE
320 $FALSE
321 These are simple booleans. 1 and 0 respectively. Be mindful of
322 using these with string equality. "$FALSE ne $EMPTY". Can be
323 imported via the ":booleans" tag.
324
326 The following groups of functions and constants are available as
327 parameters to a "use Perl::Critic::Util" statement.
328 ":all"
330 The lot.
331 ":booleans"
333 Includes: $TRUE, $FALSE
334 ":severities"
336 Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
337 $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
338 ":characters"
340 Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
341 $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH
342 $LEFT_PAREN $RIGHT_PAREN
343 ":classification"
345 Includes: "is_assignment_operator", "is_class_name",
346 "is_function_call", "is_hash_key", "is_included_module_name",
347 "is_integer", "is_label_pointer", "is_method_call",
348 "is_package_declaration", "is_perl_bareword", "is_perl_builtin",
349 "is_perl_filehandle", "is_perl_global",
350 "is_perl_builtin_with_list_context"
351 "is_perl_builtin_with_multiple_arguments"
352 "is_perl_builtin_with_no_arguments"
353 "is_perl_builtin_with_one_argument"
354 "is_perl_builtin_with_optional_argument"
355 "is_perl_builtin_with_zero_and_or_one_arguments"
356 "is_qualified_name", "is_script", "is_subroutine_name",
357 "is_unchecked_call" "is_valid_numeric_verbosity"
358 See also Perl::Critic::Utils::PPI.
360 ":data_conversion"
362 Generic manipulation, not having anything specific to do with
363 Perl::Critic.
364 Includes: "hashify", "words_from_string", "interpolate"
366 ":ppi"
368 Things for dealing with PPI, other than classification.
369 Includes: "first_arg", "parse_arg_list"
371 See also Perl::Critic::Utils::PPI.
373 ":internal_lookup"
375 Translations between internal representations.
376 Includes: "severity_to_number", "verbosity_to_format"
378 ":language"
380 Information about Perl not programmatically available elsewhere.
381 Includes: "precedence_of"
383 ":deprecated"
385 Not surprisingly, things that are deprecated. It is preferred to
386 use this tag to get to these functions, rather than the function
387 names themselves, so as to mark any module using them as needing
388 cleanup.
389 Includes: "find_keywords"
391
393 Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
394 Perl::Critic::Utils::PPI,
395
397 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
398
400 Copyright (c) 2005-2023 Imaginative Software Systems
401 This program is free software; you can redistribute it and/or modify it
403 under the same terms as Perl itself. The full text of this license can
404 be found in the LICENSE file included with this module.
405perl v5.38.0 2023-09-25 Perl::Critic::Utils(3pm)