File::...erator(3pm)

💖 File::KDBX::Iterator — the KDBX database iterator, bestie edition 💖

okay so this is File::KDBX::Iterator from the User Contributed Perl Documentation, and honestly? it's a whole vibe. it's the little engine that walks you through a File::KDBX database one item at a time. let's get into it. 🦋

---

✨ NAME ✨

File::KDBX::Iterator — the KDBX database iterator. that's it, that's the name, and it's iconic. 👑

---

🌸 VERSION 🌸

version 0.906 — yes, we're on 0.906, periodt.

---

🎀 SYNOPSIS 🎀

like, just look at this. chef's kiss:

my $kdbx = File::KDBX->load('database.kdbx', 'masterpw');

$kdbx->entries
    ->where(sub { $_->title =~ /bank/i })
    ->order_by('title')
    ->limit(5)
    ->each(sub {
        say $_->title;
    });

load, filter, sort, cap it, loop it. main character energy fr fr. 💅

---

💜 DESCRIPTION 💜

So. This is a buffered iterator. It's compatible with Iterator::Simple, and it also expands on it — like, it took what Iterator::Simple had and said "and I'm gonna make it better." 💖 It gives you an easy way to navigate a File::KDBX database.

Also, important: the docs for Iterator::Simple cover a bunch of functions and methods that this iterator supports but that are not written up here. So consider that your required additional reading, bestie. 📚✨

🫧 Buffer 🫧

This iterator is buffered, which means under the hood it can drain from an iterator subroutine and stash items temporarily so it can grab them later. That's what unlocks stuff like peek and order_by. And honestly that's super useful in KDBX-land, because KDBX databases are normally pretty small, so completely draining an iterator isn't gonna wreck you on memory. 🍓

Here's how the whole thing works, and it's lowkey elegant:

• If you call the iterator without arguments, it acts like a normal iterator.
• If you call it with arguments, those arguments get added to the buffer.
• When it's called without arguments, the buffer gets drained before the iterator function runs.

And the cheat codes: using unget is equivalent to calling the iterator with arguments, and next is equivalent to calling the iterator without arguments. iykyk. 🌈

---

👑 METHODS 👑

💫 new 💫

\&iterator = File::KDBX::Iterator->new(\&iterator);

Bless an iterator so it gets augmented with buffering plus a bunch of handy utility methods. it's giving glow-up. ✨

💫 next 💫

$item = $iterator->next;
# OR equivalently
$item = $iterator->();

$item = $iterator->next(\&query);

Get the next item, or undef if there are no more items. (crying. no more items. 😭)

If you pass a query, you get the next matching item, and any unmatching items before that matching item get discarded. Like so:

my $item = $iterator->next(sub { $_->label =~ /Gym/ });

💫 peek 💫

$item = $iterator->peek;

Peek at the next item. Returns undef if the iterator is empty. This lets you look at the next item without draining it out of the iterator — so the same item will come back the next time you call next. no spoilers, just a preview. 👀🌸

💫 unget 💫

# Replace buffer:
$iterator->unget(\@items);
# OR equivalently
$iterator->(\@items);

# Unshift onto buffer:
$iterator->unget(@items);
# OR equivalently
$iterator->(@items);

So this does one of two things: it replaces the buffer (first form) or it unshifts one or more items onto the current buffer (second form).

Check out "Buffer" up above for the deets. 🧚

💫 each 💫

@items = $iterator->each;

$iterator->each(sub($item, $num, @args) { ... }, @args);

$iterator->each($method_name, ...);

Get or act on the rest of the items. This method has three forms, and here they are:

1. Without any arguments, each returns a list of the rest of the items. 📋
2. Pass a coderef and it gets called once per item, in order. The arguments to the coderef are the item itself (which is also available as $_), then its index number, and then any extra arguments you passed to each after the coderef. 🎯
3. Pass a string that's the name of a method, and it gets called on each object, in order. Any extra arguments passed to each after the method name get passed through to each method call. This form requires that each item be an object that can the given method. 💅

NOTE: This method drains the iterator completely, leaving it empty. Go read "CAVEATS". 👀

💫 grep 💫

💫 where 💫

\&iterator = $iterator->grep(\&query);
\&iterator = $iterator->grep(sub($item) { ... });

Get a new iterator that drains from an existing iterator but only hands you back the items that pass a test or match a query. In its basic form this method is very much like perl's built-in grep function — except, you know, for iterators. ✨

There are many examples of the various forms of this method over at "QUERY" in File::KDBX. go look, it's worth it.

💫 map 💫

\&iterator = $iterator->map(\&code);

Get a new iterator that drains from an existing iterator but hands you back modified items. In its basic form this method is very much like perl's built-in map function — again, except for iterators. 🦋

💫 order_by 💫

\&iterator = $iterator->sort_by($field, %options);
\&iterator = $iterator->sort_by(\&get_value, %options);

Get a new iterator that drains from an existing iterator but hands you back items sorted by an object field. Sorting is done using Unicode::Collate (if it's available) or cmp, to sort alphanumerically. The \&get_value subroutine gets called once for each item and should return a string value. Options:

• ascending — order ascending if true, descending otherwise (default: true) ⬆️⬇️
• case — if true, take case into account; otherwise ignore case (default: true) 🔠
• collate — if true, use Unicode::Collate (if available); otherwise use perl built-ins (default: true) 🔤
• Any Unicode::Collate option is also supported. 💖

NOTE: This method drains the iterator completely and places the sorted items onto the buffer. See "CAVEATS". 🫶

💫 sort_by 💫

Alias for "order_by". same energy, different name. 💅

💫 norder_by 💫

\&iterator = $iterator->nsort_by($field, %options);
\&iterator = $iterator->nsort_by(\&get_value, %options);

Get a new iterator that drains from an existing iterator but hands you back items sorted by an object field. This time sorting is done numerically, using <=>. The \&get_value subroutine or the $field accessor gets called once for each item and should return a numerical value. Options:

• ascending — order ascending if true, descending otherwise (default: true) 🔢

NOTE: This method drains the iterator completely and places the sorted items onto the buffer. See "CAVEATS". 🫶

💫 nsort_by 💫

Alias for "norder_by". 💅

💫 limit 💫

\&iterator = $iterator->limit($count);

Get a new iterator that drains from an existing iterator but only hands you back a limited number of items. Gotta have boundaries, bestie. ✋✨

limit is an alias for $iterator->head($count) in Iterator::Simple.

💫 to_array 💫

\@array = $iterator->to_array;

Get the rest of the items from an iterator as an arrayref. 📦

NOTE: This method drains the iterator completely, leaving it empty. See "CAVEATS". 😭

💫 count 💫

$size = $iterator->count;

Count the rest of the items from an iterator. 🔢

NOTE: This method drains the iterator completely but restores it to its pre-drained state. See "CAVEATS". okay she's got self-control, we love that. 🫶

💫 size 💫

Alias for "count". 💅

---

🌈 CAVEATS 🌈

Some of these methods try to drain the iterator completely before they return. And for obvious reasons, that just won't work for infinite iterators, because your computer does not have infinite memory. ngl that's just physics. 💀

That said, this isn't a practical issue with File::KDBX lists, which are always finite — unless you do something weird like force a child group to be its own ancestor 🙈 — but I'm noting it here as a potential issue in case you use this iterator class for other stuff. (which, lowkey, you probably shouldn't do.)

Also: KDBX databases are always fully loaded into memory anyway, so there's not a significant memory cost to draining an iterator completely. so like, breathe. 🌸

---

🐛 BUGS 🐛

Please report any bugs or feature requests on the bugtracker website <https://github.com/chazmcgarvey/File-KDBX/issues> 🫶

When you submit a bug or a request, please include a test-file or a patch to an existing test-file that illustrates the bug or the desired feature. receipts, bestie. 📝✨

---

🧚 AUTHOR 🧚

Charles McGarvey <ccm@cpan.org> 👑

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2022 by Charles McGarvey.

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

---

that's the whole page, no cap. this was perl v5.40.1, last touched 2025-05-04, and yeah, that trailing File::...erator(3pm) footer is just the manpage name being shy about the dots. stay iconic, go read Iterator::Simple like I told you. 💅🎀🦋