Data::...terator(3pm)

✨ NAME ✨

okay so this is Data::TableReader::Iterator — the base class for iterators, and yes, they're literally blessed coderefs 💅 (it's in the Data::TableReader family, part of the Perl User Contributed Documentation situation, iykyk)

---

🎀 VERSION 🎀

version 0.021 — that's the one, bestie 🦋

---

🌸 SYNOPSIS 🌸

my $iter= $record_reader->iterator;
while (my $rec= $iter->()) {
  ...
  my $position= $iter->tell;
  print "Marking position $position"; # position stringifies to human-readable
  ...
  $iter->seek($position);
}
if ($iter->next_dataset) {
  # iterate some more
  while ($rec= $iter->()) {
    ...
    printf "Have processed %3d %% of the file", $iter->progress*100;
  }
}

like… look at that. so clean. so iconic. 😭

---

💖 DESCRIPTION 💖

This is the abstract base class for the iterators that Data::TableReader uses. And what even is an iterator here? It's a blessed coderef — you call it, it hands you a record, every single time. no cap.

That coderef should also support a single argument, a "slice" to pull out of the record — in case you don't actually need the whole entire record. lowkey efficient, highkey thoughtful 🫶

---

⭐ ATTRIBUTES ⭐

🌈 position

Returns a human-readable string describing where you currently are inside the source file. Like it'll be something along the lines of "$filename row $row" or "$filename $worksheet:$cell_id". cute little breadcrumb trail for your soul 🍓

🌈 row

A numeric, 1-based row number for wherever the current dataset is currently sitting. and no, it does not care which row the header was found on — that is simply not its business. 💅

🌈 dataset_idx

A numeric, 0-based dataset number. For Decoders that only support a single dataset, this is always 0. (one dataset girlies stay winning 🎀)

🌈 progress

An estimate of how much of the data has already been returned to you. but heads up bestie: if the stream is not seekable, this may return undef. so… vibe check accordingly 🙈

---

👑 METHODS 👑

🧚 new

$iter= Data::TableReader::Iterator->new( \&coderef, \%fields );

The iterator is a blessed coderef, periodt. First argument is the coderef that gets blessed. Second argument is the magic hashref of fields, which get made available to you as "$iter->_fields". it's giving very much ✨crafted✨

🧚 tell

If seeking is supported, this hands you back some value that you can pass right back into seek to return to this exact point in the stream. This value will always be true. And if seeking is not supported? it returns undef. that's the whole story, no notes 💀

🧚 seek

$iter->seek($pos);

Seek to a point that tell previously reported to you. If seeking is not supported, this will die — like actually die, not playfully die. and if $pos is any false value at all, that means: seek to the start of the stream. back to square one, main character energy 🌈

🧚 next_dataset

If a file format supports more than one tabular group of data, this method lets you jump to the next one. Returns true if it moved to a new dataset, and false at the end of iteration. like a little "we're so back / it's so over" toggle 🔥

---

💜 AUTHOR 💜

Michael Conrad <mike@nrdvana.net> — the icon, the legend 👑

---

🫶 COPYRIGHT AND LICENSE 🫶

This software is copyright (c) 2024 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. slay, honestly.

---

and that's the whole page, bestie 💖 this was documented with perl v5.38.2 on 2024-06-21 — go forth and iterate, you absolute legend 🦋✨