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/adamkennedy/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 will
65 warn. With the first release after April 8 2020, all uses will warn.
66 After a further six months, all uses will become fatal.
67
69 "PPIx::QuoteLike" is not descended from any other class.
70 "PPIx::QuoteLike" has no descendants.
72
74 This class supports the following public methods:
75 new
77 my $str = PPIx::QuoteLike->new( $source, %arg );
78 This static method parses the argument, and returns a new object
80 containing the parse. The $source argument can be either a scalar or an
81 appropriate PPI::Element object.
82 If the $source argument is a scalar, it is presumed to represent a
84 quote-like literal of some sort, provided it begins like one. Otherwise
85 this method will return nothing. The scalar representation of a here
86 document is a multi-line string whose first line consists of the
87 leading " << " and the start delimiter, and whose subsequent lines
88 consist of the content of the here document and the end delimiter.
89 Indented here documents were not supported by this class until version
90 0.015.
91 "PPI" classes that can be handled are PPI::Token::Quote,
93 PPI::Token::QuoteLike::Backtick, PPI::Token::QuoteLike::Command,
94 PPI::Token::QuoteLike::Readline, and PPI::Token::HereDoc. Any other
95 object will cause "new()" to return nothing.
96 Additional optional arguments can be passed as name/value pairs.
98 Supported arguments are:
99 encoding
101 This is the encoding of the $source. If this is specified as
102 something other than "undef", the $source will be decoded before
103 processing.
104 If the $source is a "PPI::Element", this encoding is used only if
106 the document that contains the element has neither a byte order
107 mark nor 'use utf8'.
108 index_locations
110 This Boolean argument determines whether the locations of the
111 tokens should be computed. It defaults to true if the $source
112 argument is a PPI::Element or if the "location" argument was
113 provided, and false otherwise.
114 location
116 This argument is a reference to an array compatible with that
117 returned by the PPI::Element location() method. It defaults to the
118 location of the $source argument if that was a PPI::Element,
119 otherwise no locations will be available.
120 postderef
122 THIS ARGUMENT IS DEPRECATED. See DEPRECATION NOTICE above for the
123 details.
124 This Boolean argument determines whether postfix dereferencing is
126 recognized in interpolation. If unspecified, or specified as
127 "undef", it defaults to true. In version 0.012 it defaulted to the
128 value of $PPIx::QuoteLike::DEFAULT_POSTDEREF. This variable was not
129 exported, and was true by default.
130 trace
132 This Boolean argument causes a trace of the parse to be written to
133 standard out. Setting this to a true value is unsupported in the
134 sense that the author makes no representation as to what will
135 happen if you do it, and reserves the right to make changes to the
136 functionality, or retract it completely, without notice.
137 All other arguments are unsupported and reserved to the author.
139 child
141 my $kid = $str->child( 0 );
142 This method returns the child element whose index is given as the
144 argument. Children do not include the type(), or the start() or
145 finish() delimiters. Negative indices are valid, and given the usual
146 Perl interpretation.
147 children
149 my @kids = $str->children();
150 This method returns all child elements. Children do not include the
152 type(), or the start() or finish() delimiters.
153 column_number
155 This method returns the column number of the first character in the
156 element, or "undef" if that can not be determined.
157 content
159 say $str->content();
160 This method returns the content of the object. If the original argument
162 was a valid Perl string, this should be the same as the originally-
163 parsed string.
164 delimiters
166 say $str->delimiters();
167 This method returns the delimiters of the object, as a string. This
169 will be two characters unless the argument to new() was a here
170 document, missing its end delimiter, or an invalid string. In the
171 latter case the return might be anything.
172 elements
174 my @elem = $str->elements();
175 This method returns all elements of the object. This includes type(),
177 start(), children(), and finish(), in that order.
178 failures
180 say $str->failures();
181 This method returns the number of parse failures found. These are
183 instances where the parser could not figure out what was going on, and
184 should be the same as the number of PPIx::QuoteLike::Token::Unknown
185 objects returned by elements().
186 find
188 for ( @{[ $str->find( $criteria ) || [] } ) {
189 ...
190 }
191 This method finds and returns a reference to an array of all elements
193 that meet the given criteria. If nothing is found, a false value is
194 returned.
195 The $criteria can be either the name of a PPIx::QuoteLike::Token class,
197 or a code reference. In the latter case, the code is called for each
198 element in elements(), with the element as the only argument. The
199 element is included in the output if the code returns a true value.
200 finish
202 say map { $_->content() } $str->finish();
203 This method returns the finishing elements of the parse. It is actually
205 an array, with the first element being a
206 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
207 there will be a second element, which will be a
208 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
209 character.
210 If called in list context you get the whole array. If called in scalar
212 context you get the element whose index is given in the argument, or
213 element zero if no argument is specified.
214 handles
216 say PPIx::QuoteLike->handles( $string ) ?
217 "We can handle $string" :
218 "We can not handle $string";
219 This convenience static method returns a true value if this package can
221 be expected to handle the content of $string (be it scalar or object),
222 and a false value otherwise.
223 indentation
225 This method returns the indentation string if the object represents an
226 indented here document, or "undef" if it represents anything else,
227 including an unindented here document.
228 Note that if indented syntax is used but the here document is not in
230 fact indented, this will return '', which evaluates to false.
231 interpolates
233 say $str->interpolates() ?
234 'The string interpolates' :
235 'The string does not interpolate';
236 This method returns a true value if the parsed string interpolates, and
238 a false value if it does not. This does not indicate whether any
239 interpolation actually takes place, only whether the string is double-
240 quotish or single-quotish.
241 line_number
243 This method returns the line number of the first character in the
244 element, or "undef" if that can not be determined.
245 location
247 This method returns a reference to an array describing the position of
248 the string, or "undef" if the location is unavailable.
249 The array is compatible with the corresponding PPI::Element method.
251 logical_filename
253 This method returns the logical file name (taking "#line" directives
254 into account) of the file containing first character in the element, or
255 "undef" if that can not be determined.
256 logical_line_number
258 This method returns the logical line number (taking "#line" directives
259 into account) of the first character in the element, or "undef" if that
260 can not be determined.
261 parent
263 This method returns nothing, since the invocant is only used at the top
264 of the object hierarchy.
265 perl_version_introduced
267 This method returns the maximum value of "perl_version_introduced"
268 returned by any of its elements. In other words, it returns the minimum
269 version of Perl under which this quote-like object is valid. If there
270 are no elements, 5.000 is returned, since that is the minimum value of
271 Perl supported by this package.
272 perl_version_removed
274 This method returns the minimum defined value of "perl_version_removed"
275 returned by any of the quote-like object's elements. In other words, it
276 returns the lowest version of Perl in which this object is "not" valid.
277 If there are no elements, or if no element has a defined
278 "perl_version_removed", "undef" is returned.
279 schild
281 my $skid = $str->schild( 0 );
282 This method returns the significant child elements whose index is given
284 by the argument. Negative indices are interpreted in the usual way.
285 schildren
287 my @skids = $str->schildren();
288 This method returns the significant children.
290 source
292 my $source = $str->source();
293 This method returns the $source argument to new(), whatever it was.
295 start
297 say map { $_->content() } $str->start();
298 This method returns the starting elements of the parse. It is actually
300 an array, with the first element being a
301 PPIx::QuoteLike::Token::Delimiter. If the parse is of a here document
302 there will be a second element, which will be a
303 PPIx::QuoteLike::Token::Whitespace containing the trailing new line
304 character.
305 If called in list context you get the whole array. If called in scalar
307 context you get the element whose index is given in the argument, or
308 element zero if no argument is specified.
309 statement
311 This method returns the PPI::Statement that contains this string, or
312 nothing if the statement can not be determined.
313 In general this method will return something only under the following
315 conditions:
316 • The string is contained in a PPIx::QuoteLike object;
318 • That object was initialized from a PPI::Element;
320 • The PPI::Element is contained in a statement.
322 top
324 This method returns the top of the hierarchy -- in this case, the
325 invocant.
326 type
328 my $type = $str->type();
329 This method returns the type object. This will be a
331 PPIx::QuoteLike::Token::Structure if the parse was successful;
332 otherwise it might be "undef". Its contents will be everything up to
333 the start delimiter, and will typically be 'q', 'qq', 'qx', '<<' (for
334 here documents), or '' (for quoted strings).
335 The type data are actually an array. If the second element is present
337 it will be the white space (if any) separating the actual type from the
338 value. If called in list context you get the whole array. If called in
339 scalar context you get the element whose index is given in the
340 argument, or element zero if no argument is specified.
341 variables
343 say "Interpolates $_" for $str->variables();
344 NOTE that this method is discouraged, and may well be deprecated and
346 removed. My problem with it is that it returns variable names rather
347 than PPI::Element objects, leaving you no idea how the variables are
348 used. It was originally written for the benefit of
349 Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
350 proven inadequate to that policy's needs.
351 This convenience method returns all interpolated variables. Each is
353 returned only once, and they are returned in no particular order. If
354 the object does not represent a string that interpolates, nothing is
355 returned.
356 visual_column_number
358 This method returns the visual column number (taking tabs into account)
359 of the first character in the element, or "undef" if that can not be
360 determined.
361
363 By the nature of this module, it is never going to get everything
364 right. Many of the known problem areas involve interpolations one way
365 or another.
366 Changes in Syntax
368 Sometimes the introduction of new syntax changes the way a string is
369 parsed. For example, the "\F" (fold case) case control was introduced
370 in Perl 5.15.8. But it did not represent a syntax error prior to that
371 version of Perl, it was simply parsed as "F". So
372 $ perl -le 'print "Foo\FBar"'
374 prints "FooFBar" under Perl 5.14.4, but "Foobar" under 5.16.0.
376 "PPIx::QuoteLike" generally assumes the more modern parse in cases like
377 this.
378 Static Parsing
380 It is well known that Perl can not be statically parsed. That is, you
381 can not completely parse a piece of Perl code without executing that
382 same code.
383 Nevertheless, this class is trying to statically parse quote-like
385 things. I do not have any examples of where the parse of a quote-like
386 thing would change based on what is interpolated, but neither can I
387 rule it out. Caveat user.
388 PPI Restrictions
390 As of version 0.015 of this module, the only known instance of this is
391 the handling of indented here documents, as discussed above under
392 Indented Here Documents.
393 Non-Standard Syntax
395 There are modules out there that alter the syntax of Perl. If the
396 syntax of a quote-like string is altered, this module has no way to
397 understand that it has been altered, much less to adapt to the
398 alteration. The following modules are known to cause problems:
399 Acme::PerlML, which renders Perl as XML.
401 "Data::PostfixDeref", which causes Perl to interpret suffixed empty
403 brackets as dereferencing the thing they suffix. This module by Ben
404 Morrow ("BMORROW") appears to have been retracted.
405 Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
407 be written in the ISO 646 character set.
408 Perl6::Pugs. Enough said.
410
412 Support is by the author. Please file bug reports at
413 <https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-QuoteLike>,
414 <https://github.com/trwyant/perl-PPIx-QuoteLike/issues>, or in
415 electronic mail to the author.
416
418 Thomas R. Wyant, III wyant at cpan dot org
419
421 Copyright (C) 2016-2021 by Thomas R. Wyant, III
422 This program is free software; you can redistribute it and/or modify it
424 under the same terms as Perl 5.10.0. For more details, see the full
425 text of the licenses in the directory LICENSES.
426 This program is distributed in the hope that it will be useful, but
428 without any warranty; without even the implied warranty of
429 merchantability or fitness for a particular purpose.
430perl v5.32.1 2021-03-26 PPIx::QuoteLike(3)