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/Perl-Critic/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.
63
64       Starting with version 0.012_01, the first use of this argument warned.
65       With version 0.016_01, all uses warn. With version 0.017_01 all uses
66       are fatal. With 0.0.021_01, all mention of this argument is removed,
67       except of course for this notice.
68

INHERITANCE

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

METHODS

75       This class supports the following public methods:
76
77   new
78        my $str = PPIx::QuoteLike->new( $source, %arg );
79
80       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
84       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
93       "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
98       Additional optional arguments can be passed as name/value pairs.
99       Supported arguments are:
100
101       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
106           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
110       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
116       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
122       trace
123           This Boolean argument causes a trace of the parse to be written to
124           standard out. Setting this to a true value is unsupported in the
125           sense that the author makes no representation as to what will
126           happen if you do it, and reserves the right to make changes to the
127           functionality, or retract it completely, without notice.
128
129       All other arguments are unsupported and reserved to the author.
130
131   child
132        my $kid = $str->child( 0 );
133
134       This method returns the child element whose index is given as the
135       argument. Children do not include the type(), or the start() or
136       finish() delimiters. Negative indices are valid, and given the usual
137       Perl interpretation.
138
139   children
140        my @kids = $str->children();
141
142       This method returns all child elements. Children do not include the
143       type(), or the start() or finish() delimiters.
144
145   column_number
146       This method returns the column number of the first character in the
147       element, or "undef" if that can not be determined.
148
149   content
150        say $str->content();
151
152       This method returns the content of the object. If the original argument
153       was a valid Perl string, this should be the same as the originally-
154       parsed string.
155
156   delimiters
157        say $str->delimiters();
158
159       This method returns the delimiters of the object, as a string. This
160       will be two characters unless the argument to new() was a here
161       document, missing its end delimiter, or an invalid string. In the
162       latter case the return might be anything.
163
164   elements
165        my @elem = $str->elements();
166
167       This method returns all elements of the object. This includes type(),
168       start(), children(), and finish(), in that order.
169
170   failures
171        say $str->failures();
172
173       This method returns the number of parse failures found. These are
174       instances where the parser could not figure out what was going on, and
175       should be the same as the number of PPIx::QuoteLike::Token::Unknown
176       objects returned by elements().
177
178   find
179        for ( @{[ $str->find( $criteria ) || [] } ) {
180            ...
181        }
182
183       This method finds and returns a reference to an array of all elements
184       that meet the given criteria. If nothing is found, a false value is
185       returned.
186
187       The $criteria can be either the name of a PPIx::QuoteLike::Token class,
188       or a code reference. In the latter case, the code is called for each
189       element in elements(), with the element as the only argument. The
190       element is included in the output if the code returns a true value.
191
192   finish
193        say map { $_->content() } $str->finish();
194
195       This method returns the finishing elements of the parse. It is actually
196       an array, with the first element being a
197       PPIx::QuoteLike::Token::Delimiter.  If the parse is of a here document
198       there will be a second element, which will be a
199       PPIx::QuoteLike::Token::Whitespace containing the trailing new line
200       character.
201
202       If called in list context you get the whole array. If called in scalar
203       context you get the element whose index is given in the argument, or
204       element zero if no argument is specified.
205
206   handles
207        say PPIx::QuoteLike->handles( $string ) ?
208            "We can handle $string" :
209            "We can not handle $string";
210
211       This convenience static method returns a true value if this package can
212       be expected to handle the content of $string (be it scalar or object),
213       and a false value otherwise.
214
215   indentation
216       This method returns the indentation string if the object represents an
217       indented here document, or "undef" if it represents anything else,
218       including an unindented here document.
219
220       Note that if indented syntax is used but the here document is not in
221       fact indented, this will return '', which evaluates to false.
222
223   interpolates
224        say $str->interpolates() ?
225            'The string interpolates' :
226            'The string does not interpolate';
227
228       This method returns a true value if the parsed string interpolates, and
229       a false value if it does not. This does not indicate whether any
230       interpolation actually takes place, only whether the string is double-
231       quotish or single-quotish.
232
233   line_number
234       This method returns the line number of the first character in the
235       element, or "undef" if that can not be determined.
236
237   location
238       This method returns a reference to an array describing the position of
239       the string, or "undef" if the location is unavailable.
240
241       The array is compatible with the corresponding PPI::Element method.
242
243   logical_filename
244       This method returns the logical file name (taking "#line" directives
245       into account) of the file containing first character in the element, or
246       "undef" if that can not be determined.
247
248   logical_line_number
249       This method returns the logical line number (taking "#line" directives
250       into account) of the first character in the element, or "undef" if that
251       can not be determined.
252
253   parent
254       This method returns nothing, since the invocant is only used at the top
255       of the object hierarchy.
256
257   perl_version_introduced
258       This method returns the maximum value of "perl_version_introduced"
259       returned by any of its elements. In other words, it returns the minimum
260       version of Perl under which this quote-like object is valid. If there
261       are no elements, 5.000 is returned, since that is the minimum value of
262       Perl supported by this package.
263
264   perl_version_removed
265       This method returns the minimum defined value of "perl_version_removed"
266       returned by any of the quote-like object's elements. In other words, it
267       returns the lowest version of Perl in which this object is "not" valid.
268       If there are no elements, or if no element has a defined
269       "perl_version_removed", "undef" is returned.
270
271   schild
272        my $skid = $str->schild( 0 );
273
274       This method returns the significant child elements whose index is given
275       by the argument. Negative indices are interpreted in the usual way.
276
277   schildren
278        my @skids = $str->schildren();
279
280       This method returns the significant children.
281
282   source
283        my $source = $str->source();
284
285       This method returns the $source argument to new(), whatever it was.
286
287   start
288        say map { $_->content() } $str->start();
289
290       This method returns the starting elements of the parse. It is actually
291       an array, with the first element being a
292       PPIx::QuoteLike::Token::Delimiter.  If the parse is of a here document
293       there will be a second element, which will be a
294       PPIx::QuoteLike::Token::Whitespace containing the trailing new line
295       character.
296
297       If called in list context you get the whole array. If called in scalar
298       context you get the element whose index is given in the argument, or
299       element zero if no argument is specified.
300
301   statement
302       This method returns the PPI::Statement that contains this string, or
303       nothing if the statement can not be determined.
304
305       In general this method will return something only under the following
306       conditions:
307
308       •   The string is contained in a PPIx::QuoteLike object;
309
310       •   That object was initialized from a PPI::Element;
311
312       •   The PPI::Element is contained in a statement.
313
314   top
315       This method returns the top of the hierarchy -- in this case, the
316       invocant.
317
318   type
319        my $type = $str->type();
320
321       This method returns the type object. This will be a
322       PPIx::QuoteLike::Token::Structure if the parse was successful;
323       otherwise it might be "undef". Its contents will be everything up to
324       the start delimiter, and will typically be 'q', 'qq', 'qx',  '<<'  (for
325       here documents), or '' (for quoted strings).
326
327       The type data are actually an array. If the second element is present
328       it will be the white space (if any) separating the actual type from the
329       value.  If called in list context you get the whole array. If called in
330       scalar context you get the element whose index is given in the
331       argument, or element zero if no argument is specified.
332
333   variables
334        say "Interpolates $_" for $str->variables();
335
336       NOTE that this method is discouraged, and may well be deprecated and
337       removed. I have two problems with it. The first is that it returns
338       variable names rather than PPI::Element objects, leaving you no idea
339       how the variables are used. The second is that it does not properly
340       handle things like "${^CAPTURE[0]}", and it seems infeasible to make it
341       do so. It was originally written for the benefit of
342       Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
343       proven inadequate to that policy's needs.
344
345       This convenience method returns all interpolated variables. Each is
346       returned only once, and they are returned in no particular order. If
347       the object does not represent a string that interpolates, nothing is
348       returned.
349
350   visual_column_number
351       This method returns the visual column number (taking tabs into account)
352       of the first character in the element, or "undef" if that can not be
353       determined.
354

RESTRICTIONS

356       By the nature of this module, it is never going to get everything
357       right.  Many of the known problem areas involve interpolations one way
358       or another.
359
360   Changes in Syntax
361       Sometimes the introduction of new syntax changes the way a string is
362       parsed. For example, the "\F" (fold case) case control was introduced
363       in Perl 5.15.8. But it did not represent a syntax error prior to that
364       version of Perl, it was simply parsed as "F". So
365
366        $ perl -le 'print "Foo\FBar"'
367
368       prints "FooFBar" under Perl 5.14.4, but "Foobar" under 5.16.0.
369       "PPIx::QuoteLike" generally assumes the more modern parse in cases like
370       this.
371
372   Static Parsing
373       It is well known that Perl can not be statically parsed. That is, you
374       can not completely parse a piece of Perl code without executing that
375       same code.
376
377       Nevertheless, this class is trying to statically parse quote-like
378       things. I do not have any examples of where the parse of a quote-like
379       thing would change based on what is interpolated, but neither can I
380       rule it out. Caveat user.
381
382   PPI Restrictions
383       As of version 0.015 of this module, the only known instance of this is
384       the handling of indented here documents, as discussed above under
385       Indented Here Documents.
386
387   Non-Standard Syntax
388       There are modules out there that alter the syntax of Perl. If the
389       syntax of a quote-like string is altered, this module has no way to
390       understand that it has been altered, much less to adapt to the
391       alteration. The following modules are known to cause problems:
392
393       Acme::PerlML, which renders Perl as XML.
394
395       "Data::PostfixDeref", which causes Perl to interpret suffixed empty
396       brackets as dereferencing the thing they suffix. This module by Ben
397       Morrow ("BMORROW") appears to have been retracted.
398
399       Filter::Trigraph, which recognizes ANSI C trigraphs, allowing Perl to
400       be written in the ISO 646 character set.
401
402       Perl6::Pugs. Enough said.
403

SUPPORT

405       Support is by the author. Please file bug reports at
406       <https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-QuoteLike>,
407       <https://github.com/trwyant/perl-PPIx-QuoteLike/issues>, or in
408       electronic mail to the author.
409

AUTHOR

411       Thomas R. Wyant, III wyant at cpan dot org
412
414       Copyright (C) 2016-2022 by Thomas R. Wyant, III
415
416       This program is free software; you can redistribute it and/or modify it
417       under the same terms as Perl 5.10.0. For more details, see the full
418       text of the licenses in the directory LICENSES.
419
420       This program is distributed in the hope that it will be useful, but
421       without any warranty; without even the implied warranty of
422       merchantability or fitness for a particular purpose.
423
424
425
426perl v5.36.0                      2023-01-20                PPIx::QuoteLike(3)
Impressum