PPI::To...tespace(3)

💖 PPI::Token::Whitespace — the perl manpage, but make it cute 💖

okay bestie, sit down, hydrate, because today we're talking about PPI::Token::Whitespace from the User Contributed Perl Documentation collection. yes, it's a whole manual page about spaces. no, i'm not joking. and honestly? it's kind of iconic. 🎀

---

✨ NAME ✨

PPI::Token::Whitespace — the tokens that represent ordinary white space. that's it. that's the whole job. queen behavior. 👑

---

🌸 INHERITANCE 🌸

the family tree, and yes she comes from good stock:

PPI::Token::Whitespace
isa PPI::Token
    isa PPI::Element

so like, she's a PPI::Token, which is itself a PPI::Element. generational excellence fr fr. 💅

---

🦋 DESCRIPTION 🦋

so PPI is a full "round-trip" parser, which means it records every last byte in a file and makes absolutely sure that byte is chillin' inside the PPI::Document object. every. single. one. no byte left behind. 🫶

and yes, that includes whitespace. in fact — and this is the part that lives in my head rent free — Perl documents are seen as "floating in a sea of whitespace". 🌊 so basically any document you look at is gonna contain vast quantities of PPI::Token::Whitespace objects. like, an embarrassing amount. they're everywhere. they're the background characters with main character energy.

for the most part though? you shouldn't notice them. or at least, you shouldn't have to notice them. they're lowkey just vibing in the background. ✨

what this means practically: you should be doing things like consistently using the "S for significant" series of PPI::Node and PPI::Element methods to get stuff done. that's the move.

so if you want the *n*th child element, you should be using schild rather than child. same energy with snext_sibling, sprevious_sibling, and so on and so forth. the "s" is doing the heavy lifting, bestie. don't skip it. 💀

---

💅 METHODS 💅

again — and i cannot stress this enough — for the most part you really should not need to do anything very significant with whitespace. it's not that kind of party.

but! there are a couple of convenience methods provided, beyond the ones you already get from the parent PPI::Token and PPI::Element classes. little treats. 🍓

🎀 null

because PPI sees documents as sitting on a sort of substrate made of whitespace, there are a couple of corner cases that get particularly nasty if they don't find whitespace in certain places. like, truly unhinged behavior.

imagine walking down the beach to go into the ocean, and then quite unexpectedly falling off the side of the planet. yeah. it's somewhat equivalent to that. including the whole screaming death bit. 😭

the null method is a convenience provided to get some internals out of some of these corner cases. it's the little rescue ladder. 🪜

specifically, it creates a whitespace token that represents nothing — or at least, the null string ''. it's a handy way to have some "whitespace" right where you need it, without having to have any actual characters. ghost whitespace. phantom spaces. immaterial. 👻

🧚 tidy

tidy is a convenience method for removing unneeded whitespace.

specifically, it removes any whitespace from the end of a line. trailing whitespace? not on her watch. ✂️

note that this does not include POD, where you may well need to keep certain types of whitespace. the entire POD chunk lives in its own PPI::Token::Pod object. so hands off the POD, okay? 🙈

---

🌈 SUPPORT 🌈

see the support section in the main module. that's where the help lives. go check it. 🫶

---

👑 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, bestie!! 🎉

cute little sign-off for you: this was perl v5.42.0, dated 2026-01-17, and it's the PPI::To...tespace(3) page — yes the title is truncated with dots, that's just how the manpage header rolls, it's giving mystery, it's giving suspense, it's giving "guess the rest of the filename". slay. 💖✨🌸