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 Given a PPI::Document, test if it starts with "/#!.*/". If so, it
208 is judged to be a script instead of a module. Also, if the
209 filename of the document ends in ".PL" then it is also judged to be
210 a script. However, this only works if the document is a
211 PPI::Document::File. If it isn't, then the filename is not
212 available and it has no bearing on how the document is judged. See
213 "shebang_line()".
214 "is_in_void_context( $token )"
216 Given a PPI::Token, answer whether it appears to be in a void
217 context.
218 "policy_long_name( $policy_name )"
220 Given a policy class name in long or short form, return the long
221 form.
222 "policy_short_name( $policy_name )"
224 Given a policy class name in long or short form, return the short
225 form.
226 "all_perl_files( @directories )"
228 Given a list of directories, recursively searches through all the
229 directories (depth first) and returns a list of paths for all the
230 files that are Perl code files. Any administrative files for CVS
231 or Subversion are skipped, as are things that look like temporary
232 or backup files.
233 A Perl code file is:
235 · Any file that ends in .PL, .pl, .pm, or .t
237 · Any file that has a first line with a shebang containing 'perl'
239 "severity_to_number( $severity )"
241 If $severity is given as an integer, this function returns
242 $severity but normalized to lie between $SEVERITY_LOWEST and
243 $SEVERITY_HIGHEST. If $severity is given as a string, this
244 function returns the corresponding severity number. If the string
245 doesn't have a corresponding number, this function will throw an
246 exception.
247 "is_valid_numeric_verbosity( $severity )"
249 Answers whether the argument has a translation to a Violation
250 format.
251 "verbosity_to_format( $verbosity_level )"
253 Given a verbosity level between 1 and 10, returns the corresponding
254 predefined format string. These formats are suitable for passing
255 to the "set_format" method in Perl::Critic::Violation. See the
256 perlcritic documentation for a listing of the predefined formats.
257 "hashify( @list )"
259 Given @list, return a hash where @list is in the keys and each
260 value is 1. Duplicate values in @list are silently squished.
261 "interpolate( $literal )"
263 Given a $literal string that may contain control characters (e.g..
264 '\t' '\n'), this function does a double interpolation on the string
265 and returns it as if it had been declared in double quotes. For
266 example:
267 'foo \t bar \n' ...becomes... "foo \t bar \n"
269 "shebang_line( $document )"
271 Given a PPI::Document, test if it starts with "#!". If so, return
272 that line. Otherwise return undef.
273 "words_from_string( $str )"
275 Given config string $str, return all the words from the string.
276 This is safer than splitting on whitespace.
277 "is_unchecked_call( $element )"
279 Given a PPI::Element, test to see if it contains a function call
280 whose return value is not checked.
281
283 $COMMA
284 $FATCOMMA
285 $COLON
286 $SCOLON
287 $QUOTE
288 $DQUOTE
289 $BACKTICK
290 $PERIOD
291 $PIPE
292 $EMPTY
293 $EQUAL
294 $SPACE
295 $SLASH
296 $BSLASH
297 $LEFT_PAREN
298 $RIGHT_PAREN
299 These character constants give clear names to commonly-used strings
300 that can be hard to read when surrounded by quotes and other
301 punctuation. Can be imported in one go via the ":characters" tag.
302 $SEVERITY_HIGHEST
304 $SEVERITY_HIGH
305 $SEVERITY_MEDIUM
306 $SEVERITY_LOW
307 $SEVERITY_LOWEST
308 These numeric constants define the relative severity of violating
309 each Perl::Critic::Policy. The "get_severity" and
310 "default_severity" methods of every Policy subclass must return one
311 of these values. Can be imported via the ":severities" tag.
312 $DEFAULT_VERBOSITY
314 The default numeric verbosity.
315 $DEFAULT_VERBOSITY_WITH_FILE_NAME
317 The numeric verbosity that corresponds to the format indicated by
318 $DEFAULT_VERBOSITY, but with the file name prefixed to it.
319 $TRUE
321 $FALSE
322 These are simple booleans. 1 and 0 respectively. Be mindful of
323 using these with string equality. "$FALSE ne $EMPTY". Can be
324 imported via the ":booleans" tag.
325
327 The following groups of functions and constants are available as
328 parameters to a "use Perl::Critic::Util" statement.
329 ":all"
331 The lot.
332 ":booleans"
334 Includes: $TRUE, $FALSE
335 ":severities"
337 Includes: $SEVERITY_HIGHEST, $SEVERITY_HIGH, $SEVERITY_MEDIUM,
338 $SEVERITY_LOW, $SEVERITY_LOWEST, @SEVERITY_NAMES
339 ":characters"
341 Includes: $COLON, $COMMA, $DQUOTE, $EMPTY, $FATCOMMA, $PERIOD,
342 $PIPE, $QUOTE, $BACKTICK, $SCOLON, $SPACE, $SLASH, $BSLASH
343 $LEFT_PAREN $RIGHT_PAREN
344 ":classification"
346 Includes: "is_function_call", "is_hash_key",
347 "is_included_module_name", "is_integer", "is_method_call",
348 "is_package_declaration", "is_perl_builtin", "is_perl_global",
349 "is_perl_builtin_with_list_context"
350 "is_perl_builtin_with_multiple_arguments"
351 "is_perl_builtin_with_no_arguments"
352 "is_perl_builtin_with_one_argument"
353 "is_perl_builtin_with_optional_argument"
354 "is_perl_builtin_with_zero_and_or_one_arguments" "is_script",
355 "is_subroutine_name", "is_unchecked_call"
356 "is_valid_numeric_verbosity"
357 See also Perl::Critic::Utils::PPI.
359 ":data_conversion"
361 Generic manipulation, not having anything specific to do with
362 Perl::Critic.
363 Includes: "hashify", "words_from_string", "interpolate"
365 ":ppi"
367 Things for dealing with PPI, other than classification.
368 Includes: "first_arg", "parse_arg_list"
370 See also Perl::Critic::Utils::PPI.
372 ":internal_lookup"
374 Translations between internal representations.
375 Includes: "severity_to_number", "verbosity_to_format"
377 ":language"
379 Information about Perl not programmatically available elsewhere.
380 Includes: "precedence_of"
382 ":deprecated"
384 Not surprisingly, things that are deprecated. It is preferred to
385 use this tag to get to these functions, rather than the function
386 names themselves, so as to mark any module using them as needing
387 cleanup.
388 Includes: "find_keywords"
390
392 Perl::Critic::Utils::Constants, Perl::Critic::Utils::McCabe,
393 Perl::Critic::Utils::PPI,
394
396 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
397
399 Copyright (c) 2005-2009 Jeffrey Ryan Thalhammer. All rights reserved.
400 This program is free software; you can redistribute it and/or modify it
402 under the same terms as Perl itself. The full text of this license can
403 be found in the LICENSE file included with this module.
404perl v5.12.1 2010-09-08 Perl::Critic::Utils(3)