1PPIx::QuoteLike(3) User Contributed Perl Documentation PPIx::QuoteLike(3)
2
6 PPIx::QuoteLike - Parse Perl string literals and string-literal-like
7 things.
8
10 use PPIx::QuoteLike;
11 my $str = PPIx::QuoteLike->new( q<"fu$bar"> );
13 say $str->interpolates() ?
14 'interpolates' :
15 'does not interpolate';
16
18 This Perl class parses Perl string literals and things that are
19 reasonably like string literals. Its real reason for being is to find
20 interpolated variables for Perl::Critic policies and similar code.
21 The parse is fairly straightforward, and a little poking around with
23 eg/pqldump should show how it normally goes.
24 But there is at least one quote-like thing that probably needs some
26 explanation.
27 Indented Here Documents
29 These were introduced in Perl 5.25.7 (November 2016) but not recognized
30 by this module until its version 0.015 (February 2021). The indentation
31 is parsed as PPIx::QuoteLike::Token::Whitespace objects, provided it is
32 at least one character wide, otherwise it is not represented in the
33 parse. That is to say,
34 <<~EOD
36 How doth the little crocodile
37 Improve his shining tail
38 EOD
39 will have the three indentations represented by whitespace objects and
41 each line of the literal represented by its own string object, but
42 <<~EOD
44 How doth the little crocodile
45 Improve his shining tail
46 EOD
47 will parse the same as the non-indented version, except for the
49 addition of the token representing the '~'.
50 PPI is ahead of this module, and recognized indented here documents as
52 of its version 1.246 (May 2019). Unfortunately, as of version 1.270 the
53 indent gets lost in the parse, so a "PPIx::QuoteLike" object
54 initialized from such a PPI::Token::HereDoc will be seen as having an
55 indentation of '' regardless of the actual indentation in the source.
56 I believe this restriction will go away when
57 <https://github.com/Perl-Critic/PPI/issues/251> is resolved.
58
60 The postderef argument to new() is being put through a deprecation
61 cycle and retracted. After the retraction, postfix dereferences will
62 always be recognized. This is the default behaviour now.
63 Starting with version 0.012_01, the first use of this argument warned.
65 With version 0.016_01, all uses will warn. With version 0.017_01 all
66 uses will be fatal. With the first release after April 15 2022, all
67 mention of this argument will be removed.
68
70 "PPIx::QuoteLike" is not descended from any other class.
71 "PPIx::QuoteLike" has no descendants.
73
75 This class supports the following public methods:
76 new
78 my $str = PPIx::QuoteLike->new( $source, %arg );
79 This static method parses the argument, and returns a new object
81 containing the parse. The $source argument can be either a scalar or an
82 appropriate PPI::Element object.
83 If the $source argument is a scalar, it is presumed to represent a
85 quote-like literal of some sort, provided it begins like one. Otherwise
86 this method will return nothing. The scalar representation of a here
87 document is a multi-line string whose first line consists of the
88 leading " << " and the start delimiter, and whose subsequent lines
89 consist of the content of the here document and the end delimiter.
90 Indented here documents were not supported by this class until version
91 0.015.
92 "PPI" classes that can be handled are PPI::Token::Quote,
94 PPI::Token::QuoteLike::Backtick, PPI::Token::QuoteLike::Command,
95 PPI::Token::QuoteLike::Readline, and PPI::Token::HereDoc. Any other
96 object will cause "new()" to return nothing.
97 Additional optional arguments can be passed as name/value pairs.
99 Supported arguments are:
100 encoding
102 This is the encoding of the $source. If this is specified as
103 something other than "undef", the $source will be decoded before
104 processing.
105 If the $source is a "PPI::Element", this encoding is used only if
107 the document that contains the element has neither a byte order
108 mark nor 'use utf8'.
109 index_locations
111 This Boolean argument determines whether the locations of the
112 tokens should be computed. It defaults to true if the $source
113 argument is a PPI::Element or if the "location" argument was
114 provided, and false otherwise.
115 location
117 This argument is a reference to an array compatible with that
118 returned by the PPI::Element location() method. It defaults to the
119 location of the $source argument if that was a PPI::Element,
120 otherwise no locations will be available.
121 postderef
123 THIS ARGUMENT IS DEPRECATED. See DEPRECATION NOTICE above for the
124 details.
125 This Boolean argument determines whether postfix dereferencing is
127 recognized in interpolation. If unspecified, or specified as
128 "undef", it defaults to true. In version 0.012 it defaulted to the
129 value of $PPIx::QuoteLike::DEFAULT_POSTDEREF. This variable was not
130 exported, and was true by default.
131 trace
133 This Boolean argument causes a trace of the parse to be written to
134 standard out. Setting this to a true value is unsupported in the
135 sense that the author makes no representation as to what will
136 happen if you do it, and reserves the right to make changes to the
137 functionality, or retract it completely, without notice.
138 All other arguments are unsupported and reserved to the author.
140 child
142 my $kid = $str->child( 0 );
143 This method returns the child element whose index is given as the
145 argument. Children do not include the type(), or the start() or
146 finish() delimiters. Negative indices are valid, and given the usual
147 Perl interpretation.
148 children
150 my @kids = $str->children();
151 This method returns all child elements. Children do not include the
153 type(), or the start() or finish() delimiters.
154 column_number
156 This method returns the column number of the first character in the
157 element, or "undef" if that can not be determined.
158 content
160 say $str->content();
161 This method returns the content of the object. If the original argument
163 was a valid Perl string, this should be the same as the originally-
164 parsed string.
165 delimiters
167 say $str->delimiters();
168 This method returns the delimiters of the object, as a string. This
170 will be two characters unless the argument to new() was a here
171 document, missing its end delimiter, or an invalid string. In the
172 latter case the return might be anything.
173 elements
175 my @elem = $str->elements();
176 This method returns all elements of the object. This includes type(),
178 start(), children(), and finish(), in that order.
179 failures
181 say $str->failures();
182 This method returns the number of parse failures found. These are
184 instances where the parser could not figure out what was going on, and
185 should be the same as the number of PPIx::QuoteLike::Token::Unknown
186 objects returned by elements().
187 find
189 for ( @{[ $str->find( $criteria ) || [] } ) {
190 ...
191 }
192 This method finds and returns a reference to an array of all elements
194 that meet the given criteria. If nothing is found, a false value is
195 returned.
196 The $criteria can be either the name of a PPIx::QuoteLike::Token class,
198 or a code reference. In the latter case, the code is called for each
199 element in elements(), with the element as the only argument. The
200 element is included in the output if the code returns a true value.
201 finish
203 say map { $_->content() } $str->finish();
204 This method returns the finishing elements of the parse. It is actually
206 an array, with the first element being a
207 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
208 there will be a second element, which will be a
209 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
210 character.
211 If called in list context you get the whole array. If called in scalar
213 context you get the element whose index is given in the argument, or
214 element zero if no argument is specified.
215 handles
217 say PPIx::QuoteLike->handles( $string ) ?
218 "We can handle $string" :
219 "We can not handle $string";
220 This convenience static method returns a true value if this package can
222 be expected to handle the content of $string (be it scalar or object),
223 and a false value otherwise.
224 indentation
226 This method returns the indentation string if the object represents an
227 indented here document, or "undef" if it represents anything else,
228 including an unindented here document.
229 Note that if indented syntax is used but the here document is not in
231 fact indented, this will return '', which evaluates to false.
232 interpolates
234 say $str->interpolates() ?
235 'The string interpolates' :
236 'The string does not interpolate';
237 This method returns a true value if the parsed string interpolates, and
239 a false value if it does not. This does not indicate whether any
240 interpolation actually takes place, only whether the string is double-
241 quotish or single-quotish.
242 line_number
244 This method returns the line number of the first character in the
245 element, or "undef" if that can not be determined.
246 location
248 This method returns a reference to an array describing the position of
249 the string, or "undef" if the location is unavailable.
250 The array is compatible with the corresponding PPI::Element method.
252 logical_filename
254 This method returns the logical file name (taking "#line" directives
255 into account) of the file containing first character in the element, or
256 "undef" if that can not be determined.
257 logical_line_number
259 This method returns the logical line number (taking "#line" directives
260 into account) of the first character in the element, or "undef" if that
261 can not be determined.
262 parent
264 This method returns nothing, since the invocant is only used at the top
265 of the object hierarchy.
266 perl_version_introduced
268 This method returns the maximum value of "perl_version_introduced"
269 returned by any of its elements. In other words, it returns the minimum
270 version of Perl under which this quote-like object is valid. If there
271 are no elements, 5.000 is returned, since that is the minimum value of
272 Perl supported by this package.
273 perl_version_removed
275 This method returns the minimum defined value of "perl_version_removed"
276 returned by any of the quote-like object's elements. In other words, it
277 returns the lowest version of Perl in which this object is "not" valid.
278 If there are no elements, or if no element has a defined
279 "perl_version_removed", "undef" is returned.
280 schild
282 my $skid = $str->schild( 0 );
283 This method returns the significant child elements whose index is given
285 by the argument. Negative indices are interpreted in the usual way.
286 schildren
288 my @skids = $str->schildren();
289 This method returns the significant children.
291 source
293 my $source = $str->source();
294 This method returns the $source argument to new(), whatever it was.
296 start
298 say map { $_->content() } $str->start();
299 This method returns the starting elements of the parse. It is actually
301 an array, with the first element being a
302 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
303 there will be a second element, which will be a
304 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
305 character.
306 If called in list context you get the whole array. If called in scalar
308 context you get the element whose index is given in the argument, or
309 element zero if no argument is specified.
310 statement
312 This method returns the PPI::Statement that contains this string, or
313 nothing if the statement can not be determined.
314 In general this method will return something only under the following
316 conditions:
317 • The string is contained in a PPIx::QuoteLike object;
319 • That object was initialized from a PPI::Element;
321 • The PPI::Element is contained in a statement.
323 top
325 This method returns the top of the hierarchy -- in this case, the
326 invocant.
327 type
329 my $type = $str->type();
330 This method returns the type object. This will be a
332 PPIx::QuoteLike::Token::Structure if the parse was successful;
333 otherwise it might be "undef". Its contents will be everything up to
334 the start delimiter, and will typically be 'q', 'qq', 'qx', '<<' (for
335 here documents), or '' (for quoted strings).
336 The type data are actually an array. If the second element is present
338 it will be the white space (if any) separating the actual type from the
339 value. If called in list context you get the whole array. If called in
340 scalar context you get the element whose index is given in the
341 argument, or element zero if no argument is specified.
342 variables
344 say "Interpolates $_" for $str->variables();
345 NOTE that this method is discouraged, and may well be deprecated and
347 removed. My problem with it is that it returns variable names rather
348 than PPI::Element objects, leaving you no idea how the variables are
349 used. It was originally written for the benefit of
350 Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
351 proven inadequate to that policy's needs.
352 This convenience method returns all interpolated variables. Each is
354 returned only once, and they are returned in no particular order. If
355 the object does not represent a string that interpolates, nothing is
356 returned.
357 visual_column_number
359 This method returns the visual column number (taking tabs into account)
360 of the first character in the element, or "undef" if that can not be
361 determined.
362
364 By the nature of this module, it is never going to get everything
365 right. Many of the known problem areas involve interpolations one way
366 or another.
367 Changes in Syntax
369 Sometimes the introduction of new syntax changes the way a string is
370 parsed. For example, the "\F" (fold case) case control was introduced
371 in Perl 5.15.8. But it did not represent a syntax error prior to that
372 version of Perl, it was simply parsed as "F". So
373 $ perl -le 'print "Foo\FBar"'
375 prints "FooFBar" under Perl 5.14.4, but "Foobar" under 5.16.0.
377 "PPIx::QuoteLike" generally assumes the more modern parse in cases like
378 this.
379 Static Parsing
381 It is well known that Perl can not be statically parsed. That is, you
382 can not completely parse a piece of Perl code without executing that
383 same code.
384 Nevertheless, this class is trying to statically parse quote-like
386 things. I do not have any examples of where the parse of a quote-like
387 thing would change based on what is interpolated, but neither can I
388 rule it out. Caveat user.
389 PPI Restrictions
391 As of version 0.015 of this module, the only known instance of this is
392 the handling of indented here documents, as discussed above under
393 Indented Here Documents.
394 Non-Standard Syntax
396 There are modules out there that alter the syntax of Perl. If the
397 syntax of a quote-like string is altered, this module has no way to
398 understand that it has been altered, much less to adapt to the
399 alteration. The following modules are known to cause problems:
400 Acme::PerlML, which renders Perl as XML.
402 "Data::PostfixDeref", which causes Perl to interpret suffixed empty
404 brackets as dereferencing the thing they suffix. This module by Ben
405 Morrow ("BMORROW") appears to have been retracted.
406 Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
408 be written in the ISO 646 character set.
409 Perl6::Pugs. Enough said.
411
413 Support is by the author. Please file bug reports at
414 <https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-QuoteLike>,
415 <https://github.com/trwyant/perl-PPIx-QuoteLike/issues>, or in
416 electronic mail to the author.
417
419 Thomas R. Wyant, III wyant at cpan dot org
420
422 Copyright (C) 2016-2022 by Thomas R. Wyant, III
423 This program is free software; you can redistribute it and/or modify it
425 under the same terms as Perl 5.10.0. For more details, see the full
426 text of the licenses in the directory LICENSES.
427 This program is distributed in the hope that it will be useful, but
429 without any warranty; without even the implied warranty of
430 merchantability or fitness for a particular purpose.
431perl v5.34.0 2022-03-22 PPIx::QuoteLike(3)