Version 0.900

[chaz/p5-File-KDBX] / lib / File / KDBX / Iterator.pm

diff --git a/lib/File/KDBX/Iterator.pm b/lib/File/KDBX/Iterator.pm
index 5a93f72873e87a2b15a4e54eddfa9115c141da12..3f0124d78b1cc8984c1bc6aac3515708a9a4d919 100644 (file)
--- a/lib/File/KDBX/Iterator.pm
+++ b/lib/File/KDBX/Iterator.pm
@@ -14,7 +14,7 @@ use namespace::clean;
 BEGIN { mark_as_loaded('Iterator::Simple::Iterator') }
 extends 'Iterator::Simple::Iterator';
 
-our $VERSION = '0.800'; # VERSION
+our $VERSION = '0.900'; # VERSION
 
 
 sub new {
@@ -221,7 +221,7 @@ File::KDBX::Iterator - KDBX database iterator
 
 =head1 VERSION
 
-version 0.800
+version 0.900
 
 =head1 SYNOPSIS
 
@@ -244,13 +244,14 @@ supported but this iterator that are not documented here, so consider that addit
 =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 METHODS
 
@@ -258,7 +259,7 @@ arguments, and as L</next> is equivalent to calling the iterator without argumen
 
     \&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.
 
 =head2 next
 
@@ -267,7 +268,6 @@ Blesses an iterator to augment it with buffering plus some useful utility method
     $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:
@@ -283,13 +283,17 @@ without draining it from the iterator. The same item will be returned the next t
 
 =head2 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>.
 
@@ -301,7 +305,7 @@ See L</Buffer>.
 
     $iterator->each($method_name, ...);
 
-Get or act on the rest of the items. There are three forms:
+Get or act on the rest of the items. This method has three forms:
 
 =over 4
 
@@ -311,7 +315,7 @@ Without arguments, C<each> returns a list of the rest of the items.
 
 =item 2
 
-Pass a coderef to be called once per item, in order. Arguments to the coderef are the item itself (also C<$_>), its index number and then any extra arguments that were passed to C<each> after the coderef.
+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.
 
 =item 3
 
@@ -326,16 +330,19 @@ B<NOTE:> This method drains the iterator completely, leaving it empty. See L</CA
 =head2 where
 
     \&iterator = $iterator->grep(\&query);
-    \&iterator = $iterator->grep([\'simple expression', @fields]);
 
 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>.
 
 =head2 map
 
     \&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.
 
 =head2 order_by
 
@@ -366,8 +373,6 @@ Any B<Unicode::Collate> option is also supported.
 
 =back
 
-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>.
 
@@ -392,8 +397,6 @@ C<ascending> - Order ascending if true, descending otherwise (default: true)
 
 =back
 
-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>.
 
@@ -407,7 +410,7 @@ Alias for L</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> as an alias for L<< Iterator::Simple/"$iterator->head($count)" >>.
 
 =head2 to_array