X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=lib%2FFile%2FKDBX%2FIterator.pm;h=bf7b4eb060a284a634d121cfa017856cc0948e75;hb=99dbb5c5175265d05f9019a15a3b67877408256f;hp=c9fc7612c452fe0318b5f0d9489befd674cbe697;hpb=8ccefe1cedea9b0886a44ad096aa5710528eaac7;p=chaz%2Fp5-File-KDBX

diff --git a/lib/File/KDBX/Iterator.pm b/lib/File/KDBX/Iterator.pm
index c9fc761..bf7b4eb 100644
--- a/lib/File/KDBX/Iterator.pm
+++ b/lib/File/KDBX/Iterator.pm
@@ -1,5 +1,5 @@
 package File::KDBX::Iterator;
-# PACKAGE: KDBX database iterator
+# ABSTRACT: KDBX database iterator
 
 use warnings;
 use strict;
@@ -8,7 +8,7 @@ use File::KDBX::Error;
 use File::KDBX::Util qw(:class :load :search);
 use Iterator::Simple;
 use Module::Loaded;
-use Ref::Util qw(is_arrayref is_coderef is_scalarref);
+use Ref::Util qw(is_arrayref is_coderef is_ref is_scalarref);
 use namespace::clean;
 
 BEGIN { mark_as_loaded('Iterator::Simple::Iterator') }
@@ -20,7 +20,7 @@ our $VERSION = '999.999'; # VERSION
 
     \&iterator = File::KDBX::Iterator->new(\&iterator);
 
-Blesses an iterator to augment it with buffering plus some useful utility methods.
+Bless an iterator to augment it with buffering plus some useful utility methods.
 
 =cut
 
@@ -54,7 +54,6 @@ sub new {
     $item = $iterator->();
 
     $item = $iterator->next(\&query);
-    $item = $iterator->next([\'simple expression', @fields]);
 
 Get the next item or C<undef> 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:
@@ -94,13 +93,17 @@ sub peek {
 
 =method unget
 
+    # Replace buffer:
     $iterator->unget(\@items);
-    $iterator->unget(...);
     # OR equivalently
     $iterator->(\@items);
-    $iterator->(...);
 
-Replace the buffer or unshift one or more items to the current buffer.
+    # Unshift onto buffer:
+    $iterator->unget(@items);
+    # OR equivalently
+    $iterator->(@items);
+
+Replace the buffer (first form) or unshift one or more items to the current buffer (second form).
 
 See L</Buffer>.
 
@@ -115,11 +118,20 @@ sub unget {
 
     @items = $iterator->each;
 
-    $iterator->each(sub($item, $num) { ... });
+    $iterator->each(sub($item, $num, @args) { ... }, @args);
+
+    $iterator->each($method_name, ...);
 
-Get the rest of the items. There are two forms: Without arguments, C<each> returns a list of the rest of the
-items. Or pass a coderef to be called once per item, in order. The item is passed as the first argument to the
-given subroutine and is also available as C<$_>.
+Get or act on the rest of the items. This method has three forms:
+
+=for :list
+1. Without arguments, C<each> returns a list of the rest of the items.
+2. Pass a coderef to be called once per item, in order. Arguments to the coderef are the item itself (also
+   available as C<$_>), its index number and then any extra arguments that were passed to C<each> after the
+   coderef.
+3. Pass a string that is the name of a method to be called on each object, in order. Any extra arguments
+   passed to C<each> after the method name are passed through to each method call. This form requires each
+   item be an object that C<can> the given method.
 
 B<NOTE:> This method drains the iterator completely, leaving it empty. See L</CAVEATS>.
 
@@ -129,8 +141,13 @@ sub each {
     my $self = shift;
     my $cb = shift or return @{$self->to_array};
 
-    my $count = 0;
-    $cb->($_, $count++) while defined (local $_ = $self->());
+    if (is_coderef($cb)) {
+        my $count = 0;
+        $cb->($_, $count++, @_) while defined (local $_ = $self->());
+    }
+    elsif (!is_ref($cb)) {
+        $_->$cb(@_) while defined (local $_ = $self->());
+    }
     return $self;
 }
 
@@ -139,10 +156,13 @@ sub each {
 =method where
 
     \&iterator = $iterator->grep(\&query);
-    \&iterator = $iterator->grep([\'simple expression', @fields]);
+    \&iterator = $iterator->grep(sub($item) { ... });
 
 Get a new iterator draining from an existing iterator but providing only items that pass a test or are matched
-by a query.
+by a query. In its basic form this method is very much like perl's built-in grep function, except for
+iterators.
+
+There are many examples of the various forms of this method at L<File::KDBX/QUERY>.
 
 =cut
 
@@ -164,7 +184,8 @@ sub grep {
 
     \&iterator = $iterator->map(\&code);
 
-Get a new iterator draining from an existing iterator but providing modified items.
+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.
 
 =cut
 
@@ -194,8 +215,6 @@ subroutine is called once for each item and should return a string value. Option
 * C<collate> - If true, use B<Unicode::Collate> (if available), otherwise use perl built-ins (default: true)
 * Any B<Unicode::Collate> option is also supported.
 
-C<sort_by> and C<order_by> are aliases.
-
 B<NOTE:> This method drains the iterator completely and places the sorted items onto the buffer. See
 L</CAVEATS>.
 
@@ -261,8 +280,6 @@ each item and should return a numerical value. Options:
 =for :list
 * C<ascending> - Order ascending if true, descending otherwise (default: true)
 
-C<nsort_by> and C<norder_by> are aliases.
-
 B<NOTE:> This method drains the iterator completely and places the sorted items onto the buffer. See
 L</CAVEATS>.
 
@@ -303,7 +320,7 @@ sub nsort_by { shift->norder_by(@_) }
 
 Get a new iterator draining from an existing iterator but providing only a limited number of items.
 
-C<limit> as an alias for L<Iterator::Simple/"$iterator->head($count)">.
+C<limit> is an alias for L<< Iterator::Simple/"$iterator->head($count)" >>.
 
 =cut
 
@@ -378,18 +395,19 @@ __END__
 
 A buffered iterator compatible with and expanding upon L<Iterator::Simple>, this provides an easy way to
 navigate a L<File::KDBX> database. The documentation for B<Iterator::Simple> documents functions and methods
-supported but this iterator that are not documented here, so consider that additional reading.
+supported by this iterator that are not documented here, so consider that additional reading.
 
 =head2 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> and L</sort> which might be useful in the
-context of KDBX databases which are normally pretty small so draining an iterator isn't cost-prohibitive.
+temporarily to be accessed later. This allows features like L</peek> and L</order_by> which might be useful in
+the context of KDBX databases which are normally pretty small so draining an iterator completely isn't
+cost-prohibitive in terms of memory usage.
 
 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> is equivalent to calling the iterator with
-arguments, and as L</next> is equivalent to calling the iterator without arguments.
+arguments, and L</next> is equivalent to calling the iterator without arguments.
 
 =head1 CAVEATS
 
@@ -399,4 +417,7 @@ B<File::KDBX> lists which are always finite -- unless you do something weird lik
 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).
 
+KDBX databases are always fully-loaded into memory anyway, so there's not a significant memory cost to
+draining an iterator completely.
+
 =cut