PPI::Transform(3)

💅 PPI::Transform — bestie edition

okay so real quick, this is PPI::Transform, from the User Contributed Perl Documentation set, and it's about to be your new hyperfixation 🦋

---

✨ NAME ✨

PPI::Transform — the abstract base class for document transformation classes. it's giving "blueprint energy", not "do the thing itself" energy 💖

---

🌸 DESCRIPTION 🌸

PPI::Transform hands you a whole API for building classes and objects that modify or transform PPI documents. like, the vibe is: you make a subclass, it does the actual work, this module sets the ground rules. no cap. 👑

---

🎀 METHODS 🎀

new

my $transform = PPI::Transform->new(
    param1 => 'value1',
    param2 => 'value2',
);

the new constructor spins up a fresh object for your PPI::Transform subclass. a default constructor is already provided for you — it takes no params and just makes a basic, empty, little guy. a blank slate. a fresh face. ✨

if you do want your transform's constructor to take params, they have to come in as a list of key/value pairs. that's the rule, bestie, i don't make them.

it returns a new PPI::Transform-compatible object, or it returns undef if something went wrong 😭

document

the document method is the one each subclass has to implement itself — it takes a single argument of a PPI::Document object, and it modifies it in place the way that particular transform class is supposed to.

and yes, that's right, it will not clone the document object and it should not clone the document object. if you don't want your original getting changed, you gotta clone it yourself before you pass it in. protect your peace, protect your source 🫶

it returns the number of changes made to the document. if the transform can't track the quantity — including the situation where it literally cannot tell IF it made a change — it should return 1. it returns zero if no changes were made, or undef if an error happens.

by default that error is probably just you passed in something that wasn't a PPI::Document, but depending on the subclass it might mean extra errors too. 👀

apply

the apply method is for applying the transform to, like, a thing. the argument must be a PPI::Document, or something that can be turned into one and then written back out again.

right now that list is limited to a SCALAR reference. however! there's a handler registration process available if you wanna add support for extra types of object (go peek at the source for this module, iykyk 🔥).

it returns true if the transform was applied, false if there's an error in the transform process, or it may just die if there's a critical error in the apply handler. dramatic but valid 💀

file

# Read from one file and write to another
$transform->file( 'Input.pm' => 'Output.pm' );

# Change a file in place
$transform->file( 'Change.pm' );

the file method modifies a Perl document by filename. pass it a single parameter and it modifies the file in-place. pass it a second parameter and it'll attempt to save the modified file to that alternative filename instead. glow up for your file, on your terms 🌈

it returns true on success, or undef on error.

---

🫶 SUPPORT 🫶

see the support section in the main module. (it's all over there, bestie, go look 💜)

---

👑 AUTHOR 👑

Adam Kennedy <adamk@cpan.org>

---

📜 COPYRIGHT 📜

Copyright 2001 - 2011 Adam Kennedy.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

---

and that's the whole page, no notes. if you're out here writing a transform subclass, remember: don't clone when it says don't clone, and return your numbers honestly. that's the entire personality test 💅

okay bye bestie, go transform something iconic ✨💖🦋

perl v5.42.0 · 2026-01-17 · PPI::Transform(3) — she slayed, she's archived, she's still relevant fr fr 🌸🎀