Stone::Cursor(3pm)

✨ Stone::Cursor ✨

okay bestie, welcome to the Stone::Cursor manual page, a.k.a. the User Contributed Perl Documentation page, and honestly? it's giving tiny-but-mighty 💖 this is the little helper that lets you walk through a Stone one tag-and-value at a time, no cap.

---

🌸 NAME 🌸

Stone::Cursor — Traverse tags and values of a Stone 🦋

---

💅 SYNOPSIS 💅

use Boulder::Store;
$store = Boulder::Store->new('./soccer_teams');

my $stone = $store->get(28);
$cursor = $stone->cursor;
while (my ($key,$value) = $cursor->each) {
  print "$value: Go Bluejays!\n" if $key eq 'State' and $value eq 'Katonah';
}

like…… look at her go 🫶 you grab a stone, you ask it for a cursor, you loop with each, and you print the thing when the key and value line up. iconic behavior fr fr.

---

🎀 DESCRIPTION 🎀

Boulder::Cursor is a utility class that lets you spin up one or more iterators across a Stone object. (and yes, bestie, the DESCRIPTION is out here calling itself Boulder::Cursor while the NAME says Stone::Cursor — that's just what the page says, we don't question the lore 💀)

what is it for? traversing large Stone objects so you can find the parts of the record you care about, or change them. it's the "walk the whole thing without losing your mind" tool. 🧚

👑 CLASS METHODS 👑

• Boulder::Cursor->new($stone) — hands you a fresh Boulder::Cursor sitting over the Stone object you passed in. if that object isn't a Stone, or a descendant of one? error time, bestie. 😭 also, real talk: you're usually not calling this directly — you get here indirectly through the Stone cursor() method:

my $cursor = $stone->cursor;

🌈 OBJECT METHODS 🌈

• $cursor->each() — iterates over the attached Stone. every iteration hands back a two-valued list: a tag path and a value. the tag path is in a form you can use with Stone::index() — and in fact, a cursor is used internally to implement the Stone::dump() method, so this thing is literally pulling its weight behind the scenes 👑 when you hit the end of the Stone, each() returns an empty list, and after that it just starts over again from the beginning. no drama, it's a loop-de-loop. 🔁

⚠️ heads up though: if you try to insert or delete from the stone while you're iterating over it, all attached cursors will reset to the beginnning. yes, all of them. no cap. don't do that to your cursors mid-loop 🙈

for example:

$cursor = $s->cursor;
while (($key,$value) = $cursor->each) {
   print "$value: BOW WOW!\n" if $key=~/pet/;
}

• $cursor->reset() — rewinds the cursor all the way back to the beginning of the associated Stone. fresh start, main character energy, we love to see it 💖

---

🫶 AUTHOR 🫶

Lincoln D. Stein <lstein@cshl.org>. ✨

---

💜 COPYRIGHT 💜

Copyright 1997-1999, Cold Spring Harbor Laboratory, Cold Spring Harbor NY. This module can be used and distributed on the same terms as Perl itself. 🎀

---

⭐ SEE ALSO ⭐

• Boulder
• Stone

---

and that's the whole page, bestie 💅 perl v5.34.0, dated 2022-06-08 — shoutout to the Stone::Cursor(3pm) footer for keeping us honest. go forth and traverse, you gorgeous iterator 🌸🦋✨