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_perl_global( $element )"
34 Given a PPI::Token::Symbol or a string, returns true if that token
35 represents one of the global variables provided by the English
36 module, or one of the builtin global variables like %SIG, %ENV, or
37 @ARGV. The sigil on the symbol is ignored, so things like $ARGV or
38 $ENV will still return true.
39 "is_perl_builtin( $element )"
41 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
42 true if that token represents a call to any of the builtin
43 functions defined in Perl 5.8.8.
44 "is_perl_bareword( $element )"
46 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
47 true if that token represents a bareword (e.g. "if", "else", "sub",
48 "package") defined in Perl 5.8.8.
49 "is_perl_filehandle( $element )"
51 Given a PPI::Token::Word, or string, returns true if that token
52 represents one of the global filehandles (e.g. "STDIN", "STDERR",
53 "STDOUT", "ARGV") that are defined in Perl 5.8.8. Note that this
54 function will return false if given a filehandle that is
55 represented as a typeglob (e.g. *STDIN)
56 "is_perl_builtin_with_list_context( $element )"
58 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
59 true if that token represents a call to any of the builtin
60 functions defined in Perl 5.8.8 that provide a list context to the
61 following tokens.
62 "is_perl_builtin_with_multiple_arguments( $element )"
64 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
65 true if that token represents a call to any of the builtin
66 functions defined in Perl 5.8.8 that can take multiple arguments.
67 "is_perl_builtin_with_no_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 cannot take any arguments.
72 "is_perl_builtin_with_one_argument( $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 takes one and only one
77 argument.
78 "is_perl_builtin_with_optional_argument( $element )"
80 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
81 true if that token represents a call to any of the builtin
82 functions defined in Perl 5.8.8 that takes no more than one
83 argument.
84 The sets of values for which
86 "is_perl_builtin_with_multiple_arguments()",
87 "is_perl_builtin_with_no_arguments()",
88 "is_perl_builtin_with_one_argument()", and
89 "is_perl_builtin_with_optional_argument()" return true are disjoint
90 and their union is precisely the set of values that
91 "is_perl_builtin()" will return true for.
92 "is_perl_builtin_with_zero_and_or_one_arguments( $element )"
94 Given a PPI::Token::Word, PPI::Statement::Sub, or string, returns
95 true if that token represents a call to any of the builtin
96 functions defined in Perl 5.8.8 that takes no and/or one argument.
97 Returns true if any of "is_perl_builtin_with_no_arguments()",
99 "is_perl_builtin_with_one_argument()", and
100 "is_perl_builtin_with_optional_argument()" returns true.
101 "is_qualified_name( $name )"
103 Given a string, PPI::Token::Word, or PPI::Token::Symbol, answers
104 whether it has a module component, i.e. contains "::".
105 "precedence_of( $element )"
107 Given a PPI::Token::Operator or a string, returns the precedence of
108 the operator, where 1 is the highest precedence. Returns undef if
109 the precedence can't be determined (which is usually because it is
110 not an operator).
111 "is_hash_key( $element )"
113 Given a PPI::Element, returns true if the element is a literal hash
114 key. PPI doesn't distinguish between regular barewords (like
115 keywords or subroutine calls) and barewords in hash subscripts
116 (which are considered literal). So this subroutine is useful if
117 your Policy is searching for PPI::Token::Word elements and you want
118 to filter out the hash subscript variety. In both of the following
119 examples, "foo" is considered a hash key:
120 $hash1{foo} = 1;
122 %hash2 = (foo => 1);
123 But if the bareword is followed by an argument list, then perl
125 treats it as a function call. So in these examples, "foo" is not
126 considered a hash key:
127 $hash1{ foo() } = 1;
129 &hash2 = (foo() => 1);
130 "is_included_module_name( $element )"
132 Given a PPI::Token::Word, returns true if the element is the name
133 of a module that is being included via "use", "require", or "no".
134 "is_integer( $value )"
136 Answers whether the parameter, as a string, looks like an integral
137 value.
138 "is_class_name( $element )"
140 Given a PPI::Token::Word, returns true if the element that
141 immediately follows this element is the dereference operator "->".
142 When a bareword has a "->" on the right side, it usually means that
143 it is the name of the class (from which a method is being called).
144 "is_label_pointer( $element )"
146 Given a PPI::Token::Word, returns true if the element is the label
147 in a "next", "last", "redo", or "goto" statement. Note this is not
148 the same thing as the label declaration.
149 "is_method_call( $element )"
151 Given a PPI::Token::Word, returns true if the element that
152 immediately precedes this element is the dereference operator "->".
153 When a bareword has a "->" on the left side, it usually means that
154 it is the name of a method (that is being called from a class).
155 "is_package_declaration( $element )"
157 Given a PPI::Token::Word, returns true if the element is the name
158 of a package that is being declared.
159 "is_subroutine_name( $element )"
161 Given a PPI::Token::Word, returns true if the element is the name
162 of a subroutine declaration. This is useful for distinguishing
163 barewords and from function calls from subroutine declarations.
164 "is_function_call( $element )"
166 Given a PPI::Token::Word returns true if the element appears to be
167 call to a static function. Specifically, this function returns
168 true if "is_hash_key", "is_method_call", "is_subroutine_name",
169 "is_included_module_name", "is_package_declaration",
170 "is_perl_bareword", "is_perl_filehandle", "is_label_pointer" and
171 "is_subroutine_name" all return false for the given element.
172 "first_arg( $element )"
174 Given a PPI::Element that is presumed to be a function call (which
175 is usually a PPI::Token::Word), return the first argument. This is
176 similar of "parse_arg_list()" and follows the same logic. Note
177 that for the code:
178 int($x + 0.5)
180 this function will return just the $x, not the whole expression.
182 This is different from the behavior of "parse_arg_list()". Another
183 caveat is:
184 int(($x + $y) + 0.5)
186 which returns "($x + $y)" as a PPI::Structure::List instance.
188 "parse_arg_list( $element )"
190 Given a PPI::Element that is presumed to be a function call (which
191 is usually a PPI::Token::Word), splits the argument expressions
192 into arrays of tokens. Returns a list containing references to
193 each of those arrays. This is useful because parentheses are
194 optional when calling a function, and PPI parses them very
195 differently. So this method is a poor-man's parse tree of PPI
196 nodes. It's not bullet-proof because it doesn't respect
197 precedence. In general, I don't like the way this function works,
198 so don't count on it to be stable (or even present).
199 "split_nodes_on_comma( @nodes )"
201 This has the same return type as "parse_arg_list()" but expects to
202 be passed the nodes that represent the interior of a list, like:
203 'foo', 1, 2, 'bar'
205 "is_script( $document )"
207 This subroutine is deprecated and will be removed in a future
208 release. You should use the "is_program()" in
209 Perl::Critic::Document method instead.
210 "is_in_void_context( $token )"
212 Given a PPI::Token, answer whether it appears to be in a void
213 context.
214 "policy_long_name( $policy_name )"
216 Given a policy class name in long or short form, return the long
217 form.
218 "policy_short_name( $policy_name )"
220 Given a policy class name in long or short form, return the short
221 form.
222 "all_perl_files( @directories )"
224 Given a list of directories, recursively searches through all the
225 directories (depth first) and returns a list of paths for all the
226 files that are Perl code files. Any administrative files for CVS
227 or Subversion are skipped, as are things that look like temporary
228 or backup files.
229 A Perl code file is:
231 · Any file that ends in .PL, .pl, .pm, or .t
233 · Any file that has a first line with a shebang containing 'perl'
235 "severity_to_number( $severity )"
237 If $severity is given as an integer, this function returns
238 $severity but normalized to lie between $SEVERITY_LOWEST and
239 $SEVERITY_HIGHEST. If $severity is given as a string, this
240 function returns the corresponding severity number. If the string
241 doesn't have a corresponding number, this function will throw an
242 exception.
243 "is_valid_numeric_verbosity( $severity )"
245 Answers whether the argument has a translation to a Violation
246 format.
247 "verbosity_to_format( $verbosity_level )"
249 Given a verbosity level between 1 and 10, returns the corresponding
250 predefined format string. These formats are suitable for passing
251 to the "set_format" method in Perl::Critic::Violation. See the
252 perlcritic documentation for a listing of the predefined formats.
253 "hashify( @list )"
255 Given @list, return a hash where @list is in the keys and each
256 value is 1. Duplicate values in @list are silently squished.
257 "interpolate( $literal )"
259 Given a $literal string that may contain control characters (e.g..
260 '\t' '\n'), this function does a double interpolation on the string
261 and returns it as if it had been declared in double quotes. For
262 example:
263 'foo \t bar \n' ...becomes... "foo \t bar \n"
265 "shebang_line( $document )"
267 Given a PPI::Document, test if it starts with "#!". If so, return
268 that line. Otherwise return undef.
269 "words_from_string( $str )"
271 Given config string $str, return all the words from the string.
272 This is safer than splitting on whitespace.
273 "is_unchecked_call( $element )"
275 Given a PPI::Element, test to see if it contains a function call
276 whose return value is not checked.
277
279 $COMMA
280 $FATCOMMA
281 $COLON
282 $SCOLON
283 $QUOTE
284 $DQUOTE
285 $BACKTICK
286 $PERIOD
287 $PIPE
288 $EMPTY
289 $EQUAL
290 $SPACE
291 $SLASH
292 $BSLASH
293 $LEFT_PAREN
294 $RIGHT_PAREN
295 These character constants give clear names to commonly-used strings
296 that can be hard to read when surrounded by quotes and other
297 punctuation. Can be imported in one go via the ":characters" tag.
298 $SEVERITY_HIGHEST
300 $SEVERITY_HIGH
301 $SEVERITY_MEDIUM
302 $SEVERITY_LOW
303 $SEVERITY_LOWEST
304 These numeric constants define the relative severity of violating
305 each Perl::Critic::Policy. The "get_severity" and
306 "default_severity" methods of every Policy subclass must return one
307 of these values. Can be imported via the ":severities" tag.
308 $DEFAULT_VERBOSITY
310 The default numeric verbosity.
311 $DEFAULT_VERBOSITY_WITH_FILE_NAME
313 The numeric verbosity that corresponds to the format indicated by
314 $DEFAULT_VERBOSITY, but with the file name prefixed to it.
315 $TRUE
317 $FALSE
318 These are simple booleans. 1 and 0 respectively. Be mindful of
319 using these with string equality. "$FALSE ne $EMPTY". Can be
320 imported via the ":booleans" tag.
321
323 The following groups of functions and constants are available as
324 parameters to a "use Perl::Critic::Util" statement.
325 ":all"
327 The lot.
328 ":booleans"
330 Includes: $TRUE, $FALSE
331 ":severities"
333 Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
334 $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
335 ":characters"
337 Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
338 $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH
339 $LEFT_PAREN $RIGHT_PAREN
340 ":classification"
342 Includes: "is_function_call", "is_hash_key",
343 "is_included_module_name", "is_integer", "is_method_call",
344 "is_package_declaration", "is_perl_builtin", "is_perl_global",
345 "is_perl_builtin_with_list_context"
346 "is_perl_builtin_with_multiple_arguments"
347 "is_perl_builtin_with_no_arguments"
348 "is_perl_builtin_with_one_argument"
349 "is_perl_builtin_with_optional_argument"
350 "is_perl_builtin_with_zero_and_or_one_arguments" "is_script",
351 "is_subroutine_name", "is_unchecked_call"
352 "is_valid_numeric_verbosity"
353 See also Perl::Critic::Utils::PPI.
355 ":data_conversion"
357 Generic manipulation, not having anything specific to do with
358 Perl::Critic.
359 Includes: "hashify", "words_from_string", "interpolate"
361 ":ppi"
363 Things for dealing with PPI, other than classification.
364 Includes: "first_arg", "parse_arg_list"
366 See also Perl::Critic::Utils::PPI.
368 ":internal_lookup"
370 Translations between internal representations.
371 Includes: "severity_to_number", "verbosity_to_format"
373 ":language"
375 Information about Perl not programmatically available elsewhere.
376 Includes: "precedence_of"
378 ":deprecated"
380 Not surprisingly, things that are deprecated. It is preferred to
381 use this tag to get to these functions, rather than the function
382 names themselves, so as to mark any module using them as needing
383 cleanup.
384 Includes: "find_keywords"
386
388 Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
389 Perl::Critic::Utils::PPI,
390
392 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
393
395 Copyright (c) 2005-2011 Imaginative Software Systems. All rights
396 reserved.
397 This program is free software; you can redistribute it and/or modify it
399 under the same terms as Perl itself. The full text of this license can
400 be found in the LICENSE file included with this module.
401perl v5.16.3 2014-06-09 Perl::Critic::Utils(3)