1PPIx::QuoteLike(3)    User Contributed Perl Documentation   PPIx::QuoteLike(3)
2
3
4

NAME

6       PPIx::QuoteLike - Parse Perl string literals and string-literal-like
7       things.
8

SYNOPSIS

10        use PPIx::QuoteLike;
11
12        my $str = PPIx::QuoteLike->new( q<"fu$bar"> );
13        say $str->interpolates() ?
14           'interpolates' :
15           'does not interpolate';
16

DESCRIPTION

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
22       The parse is fairly straightforward, and a little poking around with
23       eg/pqldump should show how it normally goes.
24
25       But there is at least one quote-like thing that probably needs some
26       explanation.
27
28   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
35        <<~EOD
36            How doth the little crocodile
37            Improve his shining tail
38            EOD
39
40       will have the three indentations represented by whitespace objects and
41       each line of the literal represented by its own string object, but
42
43        <<~EOD
44        How doth the little crocodile
45        Improve his shining tail
46        EOD
47
48       will parse the same as the non-indented version, except for the
49       addition of the token representing the '~'.
50
51       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

DEPRECATION NOTICE

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
64       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

INHERITANCE

69       "PPIx::QuoteLike" is not descended from any other class.
70
71       "PPIx::QuoteLike" has no descendants.
72

METHODS

74       This class supports the following public methods:
75
76   new
77        my $str = PPIx::QuoteLike->new( $source, %arg );
78
79       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
83       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
92       "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
97       Additional optional arguments can be passed as name/value pairs.
98       Supported arguments are:
99
100       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
105           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
109       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
115       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
121       postderef
122           THIS ARGUMENT IS DEPRECATED.  See DEPRECATION NOTICE above for the
123           details.
124
125           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
131       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
138       All other arguments are unsupported and reserved to the author.
139
140   child
141        my $kid = $str->child( 0 );
142
143       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
148   children
149        my @kids = $str->children();
150
151       This method returns all child elements. Children do not include the
152       type(), or the start() or finish() delimiters.
153
154   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
158   content
159        say $str->content();
160
161       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
165   delimiters
166        say $str->delimiters();
167
168       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
173   elements
174        my @elem = $str->elements();
175
176       This method returns all elements of the object. This includes type(),
177       start(), children(), and finish(), in that order.
178
179   failures
180        say $str->failures();
181
182       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
187   find
188        for ( @{[ $str->find( $criteria ) || [] } ) {
189            ...
190        }
191
192       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
196       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
201   finish
202        say map { $_->content() } $str->finish();
203
204       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
211       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
215   handles
216        say PPIx::QuoteLike->handles( $string ) ?
217            "We can handle $string" :
218            "We can not handle $string";
219
220       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
224   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
229       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
232   interpolates
233        say $str->interpolates() ?
234            'The string interpolates' :
235            'The string does not interpolate';
236
237       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
242   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
246   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
250       The array is compatible with the corresponding PPI::Element method.
251
252   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
257   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
262   parent
263       This method returns nothing, since the invocant is only used at the top
264       of the object hierarchy.
265
266   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
273   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
280   schild
281        my $skid = $str->schild( 0 );
282
283       This method returns the significant child elements whose index is given
284       by the argument. Negative indices are interpreted in the usual way.
285
286   schildren
287        my @skids = $str->schildren();
288
289       This method returns the significant children.
290
291   source
292        my $source = $str->source();
293
294       This method returns the $source argument to new(), whatever it was.
295
296   start
297        say map { $_->content() } $str->start();
298
299       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
306       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
310   statement
311       This method returns the PPI::Statement that contains this string, or
312       nothing if the statement can not be determined.
313
314       In general this method will return something only under the following
315       conditions:
316
317       •   The string is contained in a PPIx::QuoteLike object;
318
319       •   That object was initialized from a PPI::Element;
320
321       •   The PPI::Element is contained in a statement.
322
323   top
324       This method returns the top of the hierarchy -- in this case, the
325       invocant.
326
327   type
328        my $type = $str->type();
329
330       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
336       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
342   variables
343        say "Interpolates $_" for $str->variables();
344
345       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
352       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
357   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

RESTRICTIONS

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
367   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
373        $ perl -le 'print "Foo\FBar"'
374
375       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
379   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
384       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
389   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
394   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
400       Acme::PerlML, which renders Perl as XML.
401
402       "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
406       Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
407       be written in the ISO 646 character set.
408
409       Perl6::Pugs. Enough said.
410

SUPPORT

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

AUTHOR

418       Thomas R. Wyant, III wyant at cpan dot org
419
421       Copyright (C) 2016-2021 by Thomas R. Wyant, III
422
423       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
427       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.
430
431
432
433perl v5.32.1                      2021-03-26                PPIx::QuoteLike(3)
Impressum