1File::KDBX::Iterator(3)User Contributed Perl DocumentatioFnile::KDBX::Iterator(3)
2
6 File::KDBX::Iterator - KDBX database iterator
7
9 version 0.906
10
12 my $kdbx = File::KDBX->load('database.kdbx', 'masterpw');
13 $kdbx->entries
15 ->where(sub { $_->title =~ /bank/i })
16 ->order_by('title')
17 ->limit(5)
18 ->each(sub {
19 say $_->title;
20 });
21
23 A buffered iterator compatible with and expanding upon
24 Iterator::Simple, this provides an easy way to navigate a File::KDBX
25 database. The documentation for Iterator::Simple documents functions
26 and methods supported by this iterator that are not documented here, so
27 consider that additional reading.
28 Buffer
30 This iterator is buffered, meaning it can drain from an iterator
31 subroutine under the hood, storing items temporarily to be accessed
32 later. This allows features like "peek" and "order_by" which might be
33 useful in the context of KDBX databases which are normally pretty small
34 so draining an iterator completely isn't cost-prohibitive in terms of
35 memory usage.
36 The way this works is that if you call an iterator without arguments,
38 it acts like a normal iterator. If you call it with arguments, however,
39 the arguments are added to the buffer. When called without arguments,
40 the buffer is drained before the iterator function is. Using "unget" is
41 equivalent to calling the iterator with arguments, and "next" is
42 equivalent to calling the iterator without arguments.
43
45 new
46 \&iterator = File::KDBX::Iterator->new(\&iterator);
47 Bless an iterator to augment it with buffering plus some useful utility
49 methods.
50 next
52 $item = $iterator->next;
53 # OR equivalently
54 $item = $iterator->();
55 $item = $iterator->next(\&query);
57 Get the next item or "undef" if there are no more items. If a query is
59 passed, get the next matching item, discarding any unmatching items
60 before the matching item. Example:
61 my $item = $iterator->next(sub { $_->label =~ /Gym/ });
63 peek
65 $item = $iterator->peek;
66 Peek at the next item. Returns "undef" if the iterator is empty. This
68 allows you to access the next item without draining it from the
69 iterator. The same item will be returned the next time "next" is
70 called.
71 unget
73 # Replace buffer:
74 $iterator->unget(\@items);
75 # OR equivalently
76 $iterator->(\@items);
77 # Unshift onto buffer:
79 $iterator->unget(@items);
80 # OR equivalently
81 $iterator->(@items);
82 Replace the buffer (first form) or unshift one or more items to the
84 current buffer (second form).
85 See "Buffer".
87 each
89 @items = $iterator->each;
90 $iterator->each(sub($item, $num, @args) { ... }, @args);
92 $iterator->each($method_name, ...);
94 Get or act on the rest of the items. This method has three forms:
96 1. Without arguments, "each" returns a list of the rest of the items.
98 2. Pass a coderef to be called once per item, in order. Arguments to
100 the coderef are the item itself (also available as $_), its index
101 number and then any extra arguments that were passed to "each"
102 after the coderef.
103 3. Pass a string that is the name of a method to be called on each
105 object, in order. Any extra arguments passed to "each" after the
106 method name are passed through to each method call. This form
107 requires each item be an object that "can" the given method.
108 NOTE: This method drains the iterator completely, leaving it empty. See
110 "CAVEATS".
111 grep
113 where
114 \&iterator = $iterator->grep(\&query);
115 \&iterator = $iterator->grep(sub($item) { ... });
116 Get a new iterator draining from an existing iterator but providing
118 only items that pass a test or are matched by a query. In its basic
119 form this method is very much like perl's built-in grep function,
120 except for iterators.
121 There are many examples of the various forms of this method at "QUERY"
123 in File::KDBX.
124 map
126 \&iterator = $iterator->map(\&code);
127 Get a new iterator draining from an existing iterator but providing
129 modified items. In its basic form this method is very much like perl's
130 built-in map function, except for iterators.
131 order_by
133 \&iterator = $iterator->sort_by($field, %options);
134 \&iterator = $iterator->sort_by(\&get_value, %options);
135 Get a new iterator draining from an existing iterator but providing
137 items sorted by an object field. Sorting is done using Unicode::Collate
138 (if available) or "cmp" to sort alphanumerically. The "\&get_value"
139 subroutine is called once for each item and should return a string
140 value. Options:
141 • "ascending" - Order ascending if true, descending otherwise
143 (default: true)
144 • "case" - If true, take case into account, otherwise ignore case
146 (default: true)
147 • "collate" - If true, use Unicode::Collate (if available), otherwise
149 use perl built-ins (default: true)
150 • Any Unicode::Collate option is also supported.
152 NOTE: This method drains the iterator completely and places the sorted
154 items onto the buffer. See "CAVEATS".
155 sort_by
157 Alias for "order_by".
158 norder_by
160 \&iterator = $iterator->nsort_by($field, %options);
161 \&iterator = $iterator->nsort_by(\&get_value, %options);
162 Get a new iterator draining from an existing iterator but providing
164 items sorted by an object field. Sorting is done numerically using
165 "<=>". The "\&get_value" subroutine or $field accessor is called once
166 for each item and should return a numerical value. Options:
167 • "ascending" - Order ascending if true, descending otherwise
169 (default: true)
170 NOTE: This method drains the iterator completely and places the sorted
172 items onto the buffer. See "CAVEATS".
173 nsort_by
175 Alias for "norder_by".
176 limit
178 \&iterator = $iterator->limit($count);
179 Get a new iterator draining from an existing iterator but providing
181 only a limited number of items.
182 "limit" is an alias for "$iterator->head($count)" in Iterator::Simple.
184 to_array
186 \@array = $iterator->to_array;
187 Get the rest of the items from an iterator as an arrayref.
189 NOTE: This method drains the iterator completely, leaving it empty. See
191 "CAVEATS".
192 count
194 $size = $iterator->count;
195 Count the rest of the items from an iterator.
197 NOTE: This method drains the iterator completely but restores it to its
199 pre-drained state. See "CAVEATS".
200 size
202 Alias for "count".
203
205 Some methods attempt to drain the iterator completely before returning.
206 For obvious reasons, this won't work for infinite iterators because
207 your computer doesn't have infinite memory. This isn't a practical
208 issue with File::KDBX lists which are always finite -- unless you do
209 something weird like force a child group to be its own ancestor -- but
210 I'm noting it here as a potential issue if you use this iterator class
211 for other things (which you probably shouldn't do).
212 KDBX databases are always fully-loaded into memory anyway, so there's
214 not a significant memory cost to draining an iterator completely.
215
217 Please report any bugs or feature requests on the bugtracker website
218 <https://github.com/chazmcgarvey/File-KDBX/issues>
219 When submitting a bug or request, please include a test-file or a patch
221 to an existing test-file that illustrates the bug or desired feature.
222
224 Charles McGarvey <ccm@cpan.org>
225
227 This software is copyright (c) 2022 by Charles McGarvey.
228 This is free software; you can redistribute it and/or modify it under
230 the same terms as the Perl 5 programming language system itself.
231perl v5.36.1 2023-09-27 File::KDBX::Iterator(3)