NAME

       PPIx::QuoteLike::Utils - Utility subroutines for PPIx::QuoteLike;

SYNOPSIS

        use PPIx::QuoteLike::Utils qw{ __variables };

        say for __variables( PPI::Document->new( \'$foo' );

DESCRIPTION

       This Perl module holds code for PPIx::QuoteLike that did not seem to fit anywhere else.

SUBROUTINES

       This module supports the following public subroutines:

   column_number
       This subroutine/method returns the column number of the first character in the element, or "undef" if
       that can not be determined.

   is_ppi_quotelike_element
       This subroutine returns true if its argument is a PPI::Element that this package is capable of dealing
       with. That is, one of the following:

           PPI::Token::Quote
           PPI::Token::QuoteLike::Backtick
           PPI::Token::QuoteLike::Command
           PPI::Token::QuoteLike::Readline
           PPI::Token::HereDoc

       It returns false for unblessed references and for non-references.

   line_number
       This subroutine/method returns the line number of the first character in the element, or "undef" if that
       can not be determined.

   logical_filename
       This subroutine/method returns the logical file name (taking "#line" directives into account) of the file
       containing first character in the element, or "undef" if that can not be determined.

   logical_line_number
       This subroutine/method returns the logical line number (taking "#line" directives into account) of the
       first character in the element, or "undef" if that can not be determined.

   __normalize_interpolation_for_ppi
       Despite the leading underscores, this exportable subroutine is public and supported. The underscores are
       so it will not appear to be public code to various tools when imported into other code.

       This subroutine takes as its argument a string representing an interpolation. It removes such things as
       braces around variable names to make it into more normal Perl -- which is to say Perl that produces a
       more normal PPI parse. Sample transformations are:

        '${foo}'        => '$foo'
        '@{[ foo() ]}'  => 'foo()'
        '${\( foo() )}' => 'foo()'

       NOTE that this is not intended for general code cleanup.  Specifically, it assumes that its argument is
       an interpolation and only an interpolation. Feeding it anything else is unsupported, and probably will
       not return anything useful.

   statement
       This subroutine/method returns the PPI::Statement that contains this element, or nothing if the statement
       can not be determined.

       In general this method will return something only under the following conditions:

       •   The element is contained in a PPIx::Regexp object;

       •   That object was initialized from a PPI::Element;

       •   The PPI::Element is contained in a statement.

   visual_column_number
       This subroutine/method returns the visual column number (taking tabs into account) of the first character
       in the element, or "undef" if that can not be determined.

   __variables
        say for __variables( PPI::Document->new( \'$foo' );

       NOTE  that  this  subroutine  is discouraged, and may well be deprecated and removed. I have two problems
       with it. The first is that it returns variable names rather than PPI::Element  objects,  leaving  you  no
       idea  how  the  variables  are  used.  The  second  is  that  it  does  not  properly  handle things like
       "${^CAPTURE[0]}", and it seems infeasible to make it do so. It was originally written for the benefit  of
       Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter,  but  has proven inadequate to that policy's
       needs.

       Despite the leading underscores, this exportable subroutine is public and supported. The underscores  are
       so it will not appear to be public code to various tools when imported into other code.

       This  subroutine  takes as its only argument a PPI::Element, and returns the names of all variables found
       in that element, in no particular order. Scope is not taken into account.

       In addition to reporting variables parsed as such by PPI, and various corner cases such as  "${]}"  where
       PPI is blind to the use of the variable, this subroutine looks inside the following PPI classes:

           PPI::Token::Quote
           PPI::Token::QuoteLike::Backtick
           PPI::Token::QuoteLike::Command
           PPI::Token::QuoteLike::Readline
           PPI::Token::HereDoc

       If PPIx::Regexp is installed, it will also look inside

           PPI::Token::QuoteLike::Regexp
           PPI::Token::Regexp::Match
           PPI::Token::Regexp::Substitute

       Unfortunately  I can not make "PPIx::Regexp" a requirement for this module, because of the possibility of
       a circular dependency.

SUPPORT

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

AUTHOR

       Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

       Copyright (C) 2016-2022 by Thomas R. Wyant, III

       This  program  is  free  software;  you can redistribute it and/or modify it under the same terms as Perl
       5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

       This program is distributed in the hope that it will be useful, but without any  warranty;  without  even
       the implied warranty of merchantability or fitness for a particular purpose.

perl v5.36.0                                       2022-09-21                        PPIx::QuoteLike::Utils(3pm)