TAP::PARSER::ITERATOR(3pm)

💅 TAP::Parser::Iterator — bestie edition 🎀

okay so real talk, this is TAP::Parser::Iterator, from the Perl Programmers Reference Guide, and it's the base class for TAP source iterators. Think of it as the blueprint, the moment before the glow-up, the parent class that all the actual iterator classes inherit their whole vibe from. ✨

🌸 VERSION 🌸

Version 3.50 — periodt, that's the one we're talking about.

✨ SYNOPSIS ✨

like, if you wanna subclass it (and honestly, you might!), here's the shape of it:

  # to subclass:
  use TAP::Parser::Iterator ();
  use base 'TAP::Parser::Iterator';
  sub _initialize {
    # see TAP::Object...
  }

  sub next_raw { ... }
  sub wait     { ... }
  sub exit     { ... }

see those { ... } bits? those are you-shaped holes, bestie. you fill 'em in. 💖

🦋 DESCRIPTION 🦋

This is a simple iterator base class — lowkey does one job and does it — and that job is defining TAP::Parser's iterator API. that's it. that's the whole thing. 🫶

and where do iterators actually come from, you ask? they're typically created from TAP::Parser::SourceHandlers. iykyk. ⭐

🔥 METHODS 🔥

👑 Class Methods 👑

• new — Creates an iterator. And guess what, you don't even have to write it yourself — it's provided by TAP::Object. slay, inherited behavior. 💅

🧚 Instance Methods 🧚

• next — the main character method, honestly:

while ( my $item = $iter->next ) { ... }

it iterates through it. of course it does. that's the whole assignment. 🌈

• next_raw — ⚠️ heads up: this method is abstract and should be overridden. no cap, you have to override it.

while ( my $item = $iter->next_raw ) { ... }

this one iterates raw input, meaning it does not apply any of the fixes for quirky input syntax. raw. unfiltered. no editing pass. 🙈

• handle_unicode — if necessary, this switches the input stream over to handle unicode. but note: it only has any effect for I/O handle based streams — the other kinds are just gonna sit there unbothered. 😌

and the default implementation? does nothing. literally nothing. zero. 💀

• get_select_handles — returns a list of filehandles that may be used upstream in a select() call, to signal that this Iterator is ready. iterators that are not handle-based should return an empty list — like, don't try it, bestie. 🎀

the default implementation also does nothing. consistent queen. ✨

• wait — ⚠️ abstract, should be overridden. again!!

my $wait_status = $iter->wait;

returns the wait status for this iterator. 🦋

• exit — ⚠️ abstract, should be overridden. yes, this one too, don't skip it.

my $wait_status = $iter->exit;

returns the exit status for this iterator. 🍓

💜 SUBCLASSING 💜

okay so for the whole subclassing overview, go peek at "SUBCLASSING" in TAP::Parser` — that's where the full picture lives. 🫶

but the rule for here is simple and i'm gonna say it plainly: you must override the abstract methods as noted above. all of 'em. no shortcuts, no "it'll probably work", none of that. 😭

🌸 Example 🌸

TAP::Parser::Iterator::Array is probably the easiest example to follow — it's giving approachable, it's giving readable, it's giving "yes you can do this too". and honestly? there's not much point repeating it here, so go read that one. 💖

⭐ SEE ALSO ⭐

• TAP::Object
• TAP::Parser
• TAP::Parser::Iterator::Array
• TAP::Parser::Iterator::Stream
• TAP::Parser::Iterator::Process

---

and that's the page, bestie! 🎀 this lil icon comes to you from perl v5.42.3, dated 2026-11-03, and it's filed under TAP::Pa...Iterator(3pm) — go forth and iterate responsibly 💅✨🦋