1PPIx::QuoteLike::Utils(U3s)er Contributed Perl DocumentatPiPoInx::QuoteLike::Utils(3)
2
6 PPIx::QuoteLike::Utils - Utility subroutines for PPIx::QuoteLike;
7
9 use PPIx::QuoteLike::Utils qw{ __variables };
10 say for __variables( PPI::Document->new( \'$foo' );
12
14 This Perl module holds code for PPIx::QuoteLike that did not seem to
15 fit anywhere else.
16
18 This module supports the following public subroutines:
19 column_number
21 This subroutine/method returns the column number of the first character
22 in the element, or "undef" if that can not be determined.
23 is_ppi_quotelike_element
25 This subroutine returns true if its argument is a PPI::Element that
26 this package is capable of dealing with. That is, one of the following:
27 PPI::Token::Quote
29 PPI::Token::QuoteLike::Backtick
30 PPI::Token::QuoteLike::Command
31 PPI::Token::QuoteLike::Readline
32 PPI::Token::HereDoc
33 It returns false for unblessed references and for non-references.
35 line_number
37 This subroutine/method returns the line number of the first character
38 in the element, or "undef" if that can not be determined.
39 logical_filename
41 This subroutine/method returns the logical file name (taking "#line"
42 directives into account) of the file containing first character in the
43 element, or "undef" if that can not be determined.
44 logical_line_number
46 This subroutine/method returns the logical line number (taking "#line"
47 directives into account) of the first character in the element, or
48 "undef" if that can not be determined.
49 __normalize_interpolation_for_ppi
51 Despite the leading underscores, this exportable subroutine is public
52 and supported. The underscores are so it will not appear to be public
53 code to various tools when imported into other code.
54 This subroutine takes as its argument a string representing an
56 interpolation. It removes such things as braces around variable names
57 to make it into more normal Perl -- which is to say Perl that produces
58 a more normal PPI parse. Sample transformations are:
59 '${foo}' => '$foo'
61 '@{[ foo() ]}' => 'foo()'
62 '${\( foo() )}' => 'foo()'
63 NOTE that this is not intended for general code cleanup. Specifically,
65 it assumes that its argument is an interpolation and only an
66 interpolation. Feeding it anything else is unsupported, and probably
67 will not return anything useful.
68 statement
70 This subroutine/method returns the PPI::Statement that contains this
71 element, or nothing if the statement can not be determined.
72 In general this method will return something only under the following
74 conditions:
75 • The element is contained in a PPIx::Regexp object;
77 • That object was initialized from a PPI::Element;
79 • The PPI::Element is contained in a statement.
81 visual_column_number
83 This subroutine/method returns the visual column number (taking tabs
84 into account) of the first character in the element, or "undef" if that
85 can not be determined.
86 __variables
88 say for __variables( PPI::Document->new( \'$foo' );
89 NOTE that this subroutine is discouraged, and may well be deprecated
91 and removed. I have two problems with it. The first is that it returns
92 variable names rather than PPI::Element objects, leaving you no idea
93 how the variables are used. The second is that it does not properly
94 handle things like "${^CAPTURE[0]}", and it seems infeasible to make it
95 do so. It was originally written for the benefit of
96 Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has
97 proven inadequate to that policy's needs.
98 Despite the leading underscores, this exportable subroutine is public
100 and supported. The underscores are so it will not appear to be public
101 code to various tools when imported into other code.
102 This subroutine takes as its only argument a PPI::Element, and returns
104 the names of all variables found in that element, in no particular
105 order. Scope is not taken into account.
106 In addition to reporting variables parsed as such by PPI, and various
108 corner cases such as "${]}" where PPI is blind to the use of the
109 variable, this subroutine looks inside the following PPI classes:
110 PPI::Token::Quote
112 PPI::Token::QuoteLike::Backtick
113 PPI::Token::QuoteLike::Command
114 PPI::Token::QuoteLike::Readline
115 PPI::Token::HereDoc
116 If PPIx::Regexp is installed, it will also look inside
118 PPI::Token::QuoteLike::Regexp
120 PPI::Token::Regexp::Match
121 PPI::Token::Regexp::Substitute
122 Unfortunately I can not make "PPIx::Regexp" a requirement for this
124 module, because of the possibility of a circular dependency.
125
127 Support is by the author. Please file bug reports at
128 <https://rt.cpan.org/Public/Dist/Display.html?Name=PPIx-QuoteLike>,
129 <https://github.com/trwyant/perl-PPIx-QuoteLike/issues>, or in
130 electronic mail to the author.
131
133 Thomas R. Wyant, III wyant at cpan dot org
134
136 Copyright (C) 2016-2022 by Thomas R. Wyant, III
137 This program is free software; you can redistribute it and/or modify it
139 under the same terms as Perl 5.10.0. For more details, see the full
140 text of the licenses in the directory LICENSES.
141 This program is distributed in the hope that it will be useful, but
143 without any warranty; without even the implied warranty of
144 merchantability or fitness for a particular purpose.
145perl v5.38.0 2023-07-21 PPIx::QuoteLike::Utils(3)