.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "File::KDBX::Iterator 3pm" .TH File::KDBX::Iterator 3pm "2022-11-20" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::KDBX::Iterator \- KDBX database iterator .SH "VERSION" .IX Header "VERSION" version 0.906 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $kdbx = File::KDBX\->load(\*(Aqdatabase.kdbx\*(Aq, \*(Aqmasterpw\*(Aq); \& \& $kdbx\->entries \& \->where(sub { $_\->title =~ /bank/i }) \& \->order_by(\*(Aqtitle\*(Aq) \& \->limit(5) \& \->each(sub { \& say $_\->title; \& }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A buffered iterator compatible with and expanding upon Iterator::Simple, this provides an easy way to navigate a File::KDBX database. The documentation for \fBIterator::Simple\fR documents functions and methods supported by this iterator that are not documented here, so consider that additional reading. .SS "Buffer" .IX Subsection "Buffer" This iterator is buffered, meaning it can drain from an iterator subroutine under the hood, storing items temporarily to be accessed later. This allows features like \*(L"peek\*(R" and \*(L"order_by\*(R" which might be useful in the context of \s-1KDBX\s0 databases which are normally pretty small so draining an iterator completely isn't cost-prohibitive in terms of memory usage. .PP The way this works is that if you call an iterator without arguments, it acts like a normal iterator. If you call it with arguments, however, the arguments are added to the buffer. When called without arguments, the buffer is drained before the iterator function is. Using \*(L"unget\*(R" is equivalent to calling the iterator with arguments, and \*(L"next\*(R" is equivalent to calling the iterator without arguments. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& \e&iterator = File::KDBX::Iterator\->new(\e&iterator); .Ve .PP Bless an iterator to augment it with buffering plus some useful utility methods. .SS "next" .IX Subsection "next" .Vb 3 \& $item = $iterator\->next; \& # OR equivalently \& $item = $iterator\->(); \& \& $item = $iterator\->next(\e&query); .Ve .PP Get the next item or \f(CW\*(C`undef\*(C'\fR if there are no more items. If a query is passed, get the next matching item, discarding any unmatching items before the matching item. Example: .PP .Vb 1 \& my $item = $iterator\->next(sub { $_\->label =~ /Gym/ }); .Ve .SS "peek" .IX Subsection "peek" .Vb 1 \& $item = $iterator\->peek; .Ve .PP Peek at the next item. Returns \f(CW\*(C`undef\*(C'\fR if the iterator is empty. This allows you to access the next item without draining it from the iterator. The same item will be returned the next time \*(L"next\*(R" is called. .SS "unget" .IX Subsection "unget" .Vb 4 \& # Replace buffer: \& $iterator\->unget(\e@items); \& # OR equivalently \& $iterator\->(\e@items); \& \& # Unshift onto buffer: \& $iterator\->unget(@items); \& # OR equivalently \& $iterator\->(@items); .Ve .PP Replace the buffer (first form) or unshift one or more items to the current buffer (second form). .PP See \*(L"Buffer\*(R". .SS "each" .IX Subsection "each" .Vb 1 \& @items = $iterator\->each; \& \& $iterator\->each(sub($item, $num, @args) { ... }, @args); \& \& $iterator\->each($method_name, ...); .Ve .PP Get or act on the rest of the items. This method has three forms: .IP "1." 4 Without arguments, \f(CW\*(C`each\*(C'\fR returns a list of the rest of the items. .IP "2." 4 Pass a coderef to be called once per item, in order. Arguments to the coderef are the item itself (also available as \f(CW$_\fR), its index number and then any extra arguments that were passed to \f(CW\*(C`each\*(C'\fR after the coderef. .IP "3." 4 Pass a string that is the name of a method to be called on each object, in order. Any extra arguments passed to \f(CW\*(C`each\*(C'\fR after the method name are passed through to each method call. This form requires each item be an object that \f(CW\*(C`can\*(C'\fR the given method. .PP \&\fB\s-1NOTE:\s0\fR This method drains the iterator completely, leaving it empty. See \*(L"\s-1CAVEATS\*(R"\s0. .SS "grep" .IX Subsection "grep" .SS "where" .IX Subsection "where" .Vb 2 \& \e&iterator = $iterator\->grep(\e&query); \& \e&iterator = $iterator\->grep(sub($item) { ... }); .Ve .PP Get a new iterator draining from an existing iterator but providing only items that pass a test or are matched by a query. In its basic form this method is very much like perl's built-in grep function, except for iterators. .PP There are many examples of the various forms of this method at \*(L"\s-1QUERY\*(R"\s0 in File::KDBX. .SS "map" .IX Subsection "map" .Vb 1 \& \e&iterator = $iterator\->map(\e&code); .Ve .PP Get a new iterator draining from an existing iterator but providing modified items. In its basic form this method is very much like perl's built-in map function, except for iterators. .SS "order_by" .IX Subsection "order_by" .Vb 2 \& \e&iterator = $iterator\->sort_by($field, %options); \& \e&iterator = $iterator\->sort_by(\e&get_value, %options); .Ve .PP Get a new iterator draining from an existing iterator but providing items sorted by an object field. Sorting is done using Unicode::Collate (if available) or \f(CW\*(C`cmp\*(C'\fR to sort alphanumerically. The \f(CW\*(C`\e&get_value\*(C'\fR subroutine is called once for each item and should return a string value. Options: .IP "\(bu" 4 \&\f(CW\*(C`ascending\*(C'\fR \- Order ascending if true, descending otherwise (default: true) .IP "\(bu" 4 \&\f(CW\*(C`case\*(C'\fR \- If true, take case into account, otherwise ignore case (default: true) .IP "\(bu" 4 \&\f(CW\*(C`collate\*(C'\fR \- If true, use \fBUnicode::Collate\fR (if available), otherwise use perl built-ins (default: true) .IP "\(bu" 4 Any \fBUnicode::Collate\fR option is also supported. .PP \&\fB\s-1NOTE:\s0\fR This method drains the iterator completely and places the sorted items onto the buffer. See \&\*(L"\s-1CAVEATS\*(R"\s0. .SS "sort_by" .IX Subsection "sort_by" Alias for \*(L"order_by\*(R". .SS "norder_by" .IX Subsection "norder_by" .Vb 2 \& \e&iterator = $iterator\->nsort_by($field, %options); \& \e&iterator = $iterator\->nsort_by(\e&get_value, %options); .Ve .PP Get a new iterator draining from an existing iterator but providing items sorted by an object field. Sorting is done numerically using \f(CW\*(C`<=>\*(C'\fR. The \f(CW\*(C`\e&get_value\*(C'\fR subroutine or \f(CW$field\fR accessor is called once for each item and should return a numerical value. Options: .IP "\(bu" 4 \&\f(CW\*(C`ascending\*(C'\fR \- Order ascending if true, descending otherwise (default: true) .PP \&\fB\s-1NOTE:\s0\fR This method drains the iterator completely and places the sorted items onto the buffer. See \&\*(L"\s-1CAVEATS\*(R"\s0. .SS "nsort_by" .IX Subsection "nsort_by" Alias for \*(L"norder_by\*(R". .SS "limit" .IX Subsection "limit" .Vb 1 \& \e&iterator = $iterator\->limit($count); .Ve .PP Get a new iterator draining from an existing iterator but providing only a limited number of items. .PP \&\f(CW\*(C`limit\*(C'\fR is an alias for \*(L"$iterator\->head($count)\*(R" in Iterator::Simple. .SS "to_array" .IX Subsection "to_array" .Vb 1 \& \e@array = $iterator\->to_array; .Ve .PP Get the rest of the items from an iterator as an arrayref. .PP \&\fB\s-1NOTE:\s0\fR This method drains the iterator completely, leaving it empty. See \*(L"\s-1CAVEATS\*(R"\s0. .SS "count" .IX Subsection "count" .Vb 1 \& $size = $iterator\->count; .Ve .PP Count the rest of the items from an iterator. .PP \&\fB\s-1NOTE:\s0\fR This method drains the iterator completely but restores it to its pre-drained state. See \*(L"\s-1CAVEATS\*(R"\s0. .SS "size" .IX Subsection "size" Alias for \*(L"count\*(R". .SH "CAVEATS" .IX Header "CAVEATS" Some methods attempt to drain the iterator completely before returning. For obvious reasons, this won't work for infinite iterators because your computer doesn't have infinite memory. This isn't a practical issue with \&\fBFile::KDBX\fR 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 if you use this iterator class for other things (which you probably shouldn't do). .PP \&\s-1KDBX\s0 databases are always fully-loaded into memory anyway, so there's not a significant memory cost to draining an iterator completely. .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website .PP When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. .SH "AUTHOR" .IX Header "AUTHOR" Charles McGarvey .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2022 by Charles McGarvey. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.