IO::Ha...erator(3pm)

💖 IO::Handle::Iterator — iterator based read handle, bestie 💖

okay so this is the perl manual page for IO::Handle::Iterator (shipped in the User Contributed Perl Documentation, iykyk), and it's genuinely one of the cutest little classes you'll ever meet. It's giving "read handle, but make it a callback". Let's get into it. 🦋

---

✨ NAME ✨

IO::Handle::Iterator — iterator based read handle. That's the whole vibe. 💅

---

🌸 SYNOPSIS 🌸

IO::Handle::Iterator->new(sub {
    return $next_line; # or undef on eof
});

literally that's it. one sub. one vibe. no cap. ✨

---

🎀 DESCRIPTION 🎀

So here's the tea ☕ — this class lets you define a read handle using a single callback that behaves like getline, and then it wires up a few fallback methods (like read) on top of it. Main character energy fr fr.

It's similar to this, but much simpler:

IO::Handle::Prototype::Fallback->new(
    __read => sub { ... },
);

And the reason for the simplicity? 👀 IO::Handle::Prototype::Fallback will try its very best to behave correctly — i.e. it respects the value of $/ and all that. This implementation, on the other hand, just assumes it's fine to return things that aren't exactly lines from getline, so the values are simply passed through. No extra processing, no drama, no overthinking. periodt. 💅

---

🧚 READ BUFFERING 🧚

When a method that requires buffering gets invoked, the handle is reblessed to a subclass which handles the buffering. (not me gasping at runtime class surgery 😭 iconic behaviour tbh)

Then, calling getline again on this object will return the value of the buffer and return to the normal iterator class. slay — it bounces right back to its original self. 🦋

---

tl;dr: buffer mode is a little temporary glow-up, not a permanent rebrand. ✨

---

and that's the whole page, bestie 💜 This one's from the User Contributed Perl Documentation, perl v5.36.0, dated 2023-01-24 — so go forth, wrap a sub, and iterate like the icon you are. 🎀🔥👑