PPIx::...:Utils(3pm)

📦
version 0.023 · 11 versions
, in opensuse-leap 16.0

💖 PPIx::QuoteLike::Utils(3pm) 💖

okay bestie, welcome to the User Contributed Perl Documentation section of the manual — this one's for PPIx::QuoteLike::Utils, and honestly it's the little grab-bag module where all the leftover code goes to live its best life. ✨

🌸 NAME 🌸

PPIx::QuoteLike::Utils — utility subroutines for PPIx::QuoteLike; (yes there's a semicolon at the end of that line, that's canon, we don't question it 💅)

🦋 SYNOPSIS 🦋

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

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

that's it, that's the whole vibe check. copy it exactly, bestie, don't "fix" the parens — they're like that on purpose (or at least, that's what's in the goods 🤫).

🎀 DESCRIPTION 🎀

so this Perl module? it's literally just the home for code that PPIx::QuoteLike needed but that didn't fit anywhere else. like the junk drawer of a module, but make it iconic. no cap. 💖

⭐ SUBROUTINES ⭐

this module supports the following public subroutines, and yes we're going through every single one:

💜 column_number

returns the column number of the first character in the element. or undef if that literally cannot be determined. it's a subroutine and a method, she's versatile like that. 🫶

💜 is_ppi_quotelike_element

returns true if its argument is a PPI::Element that this package is capable of dealing with — i.e. one of these queens:

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

returns false for unblessed references and for non-references. sorry babes, no blessings, no entry. 🙈

💜 line_number

returns the line number of the first character in the element, or undef if that can not be determined. again: subroutine or method. 💅

💜 logical_filename

returns the logical file name — like, taking "#line" directives into account, she's doing the mental math for you 🧠✨ — of the file containing the first character in the element, or undef if that can not be determined.

💜 logical_line_number

returns the logical line number (again, taking "#line" directives into account, we stay consistent) of the first character in the element, or undef if that can not be determined.

💜 __normalize_interpolation_for_ppi

okay so despite the leading underscores, this exportable subroutine is public and supported — the underscores are literally just so it doesn't look like public code to various tools when it gets imported into other code. camouflage. stealth mode. ninja vibes. 🥷

it takes as its argument a string representing an interpolation, and removes stuff like 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, look at these glow-ups:

'${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. so like, don't come for her with your random strings, she's not that kind of subroutine. 💀

💜 statement

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 these 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.

three little requirements, all of them needed, no shortcuts. 🌈

💜 visual_column_number

returns the visual column number (taking tabs into account, because tabs are chaotic and we respect that 🫠) 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. like, the author is not okay with her behaviour, bestie. 😭

there are two problems with it:

  1. it returns variable names rather than PPI::Element objects, which leaves you with zero idea of how the variables are actually used. rude.
  2. it does not properly handle things like "${^CAPTURE[0]}", and it seems infeasible to make it do so. she simply cannot, and we've accepted that.

it was originally written for the benefit of Perl::Critic::Policy::Variables::ProhibitUnusedVarsStricter, but has proven inadequate to that policy's needs. rip to her original purpose. 💀

despite the leading underscores, this exportable subroutine is public and supported — same deal as before, the underscores are just so it won't appear to be public code to various tools when imported into other code. ✨

it 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. it's giving chaos, and honestly? we love that for her.

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

and if PPIx::Regexp is installed, it will also look inside:

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

unfortunately, the author can not make "PPIx::Regexp" a requirement for this module, because of the possibility of a circular dependency. circular dependencies are the enemy fr fr. 🔄💀

🫶 SUPPORT 🫶

support is by the author. please file bug reports at:

(okay so technically I'm not supposed to make links but those URL strings are literally the bug report destinations — copy-paste them into your browser, bestie 💖)

👑 AUTHOR 👑

Thomas R. Wyant, III — wyant at cpan dot org 💌

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. so like, no promises, no guarantees, she's doing her best. 🙏

and that's the whole page, bestie!! 🎀✨ this one's from perl v5.42.0, dated 2022-09-17 — mwah, love that for us. 💋👑💖

📦 where this page comes from