documenting ->collect in HTML::Zoom::FilterBuilder

HTML::Zoom::FilterBuilder.pm.patch

diff --git a/lib/HTML/Zoom/FilterBuilder.pm b/lib/HTML/Zoom/FilterBuilder.pm
index 50398b3..809e267 100644
--- a/lib/HTML/Zoom/FilterBuilder.pm
+++ b/lib/HTML/Zoom/FilterBuilder.pm
@@ -381,7 +381,7 @@ alter the content of that stream.
 
 This class defines the following public API
 
-=head2 set_attribute ( $attr=>value | {name=>$attr,value=>$value} )
+=head2 set_attribute ( $attr=>$value | {name=>$attr,value=>$value} )
 
 Sets an attribute of a given name to a given value for all matching selections.
 
@@ -396,7 +396,7 @@ Overrides existing values, if such exist.  When multiple L</set_attribute>
 calls are made against the same or overlapping selection sets, the final
 call wins.
 
-=head2 add_to_attribute ( $attr=>value | {name=>$attr,value=>$value} )
+=head2 add_to_attribute ( $attr=>$value | {name=>$attr,value=>$value} )
 
 Adds a value to an existing attribute, or creates one if the attribute does not
 yet exist.
@@ -421,21 +421,101 @@ Removes an attribute and all its values.
 
 Removes attributes from the original stream or events already added.
 
-=head2 collect
+=head2 collect ( [options] )
 
-    TBD
+Collects and extracts results of L<HTML::Zoom/select>.  It takes the following
+optional common options as hash reference.
 
-=head2 collect_content
+=over
 
-    TBD
+=item into [ARRAY REFERENCE]
 
-=head2 add_before
+Where to save collected events (selected elements).
 
-    TBD
+    $z1->select('#main-content')
+       ->collect({ into => \@body })
+       ->run;
+    $z2->select('#main-content')
+       ->replace(\@body)
+       ->memoize;
 
-=head2 add_after
+=item filter [CODE]
 
-    TBD
+Run filter on collected elements (locally setting $_ to stream, and passing
+stream as an argument to given code reference).  Note that $_ is an alias to the
+stream, so it can be used to modify stream.
+
+    $z->select('.outer')
+      ->collect({
+        filter => sub { $_->select('.inner')->replace_content('bar!') },
+        passthrough => 1
+      })
+
+=item passthrough [BOOLEAN]
+
+Extract copy of elements; the stream is unchanged (it does not remove collected
+elements).
+
+    HTML::Zoom->from_html('<foo><bar /></foo>')
+      ->select('foo')
+      ->collect({ content => 1 })
+      ->to_html
+
+returns '<foo></foo>', while with C<passthrough>
+
+    HTML::Zoom->from_html('<foo><bar /></foo>')
+      ->select('foo')
+      ->collect({ content => 1, passthough => 1 })
+      ->to_html
+
+returns '<foo><bar /></foo>'.
+
+Using simply '$zoom->collect({ passthrough => 1 });' turns
+L<HTML::Zoom> object into list of events.
+
+=item content [BOOLEAN]
+
+Collect content of the element, and not element itself.
+
+See also L</collect_content>.
+
+=item flush_before [BOOLEAN]
+
+Generate C<flush> event before collecting, to ensure that the HTML generated up
+to selected element being collected is thushed throught to the browser.
+
+=back
+
+=head2 collect_content ( [options] )
+
+Collects contents of L<HTML::Zoom/select> result.
+
+    HTML::Zoom->from_file($foo)
+              ->select('#main-content')
+              ->collect_content({ into => \@foo_body })
+              ->run;
+    $z->select('#foo')
+      ->replace_content(\@foo_body)
+      ->memoize;
+
+Equivalent to running L</collect> with C<content> option.
+
+=head2 add_before ( $content )
+
+Given a L<HTML::Zoom/select> result, add given content (which might be string,
+array or another L<HTML::Zoom> object) before it.
+
+    $html_zoom
+        ->select('input[name="foo"]')
+        ->add_before(\ '<span class="warning">required field</span>');
+
+=head2 add_after ( $content )
+
+Like L</add_before>, only after L<HTML::Zoom/select> result.
+
+    $html_zoom
+        ->select('p')
+        ->add_after("\n\n");
 
 =head2 prepend_content
 
@@ -445,22 +525,76 @@ Removes attributes from the original stream or events already added.
 
     TBD
 
-=head2 replace
+=head2 replace ( $replacement, [ options ] )
 
-    TBD
+Given a L<HTML::Zoom/select> result, replace it with a string, array or another
+L<HTML::Zoom> object.  It takes the same optional common options as L</collect>
+(via hash reference).
 
 =head2 replace_content
 
 Given a L<HTML::Zoom/select> result, replace the content with a string, array
 or another L<HTML::Zoom> object.
 
-=head2 repeat
+    $html_zoom
+      ->select('title, #greeting')
+      ->replace_content('Hello world!');
 
-    TBD
+=head2 repeat ( $repeat_for, [ options ] )
 
-=head2 repeat_content
+Replace result of L<HTML::Zoom/select> (of collected elements) with list of
+elements, given as array reference, iterator (code reference) or L<HTML::Zoom>
+object.
+
+    my @list = qw(foo bar baz);
+    my $z2 = $zoom->select('.item')->repeat(sub {
+       if (my $name = shift @list) {
+          return sub { $_->select('.item-name')->replace_content($name) }
+       } else {
+          return
+       }
+    }, { flush_before => 1 });
+
+In addition to common options as in L</collect>, it also supports
+
+=over
+
+=item repeat_between [SELECTOR]
+
+Selects object to be repeated between items.  In the case of array this object
+is put between elements, in case of iterator it is put between results of
+subsequent iterations, in the case of stream it is put between events
+($stream->next).
+
+=back
+
+=head2 repeat_content ( $repeat_for, [ options ] )
+
+Given a L<HTML::Zoom/select> result, replace the content with provided or
+generated list of elements.  Accepts the same options as L</repeat>.
+
+Equivalent to using C<contents> option with L</repeat>.
+
+    $html_zoom
+       ->select('#list')
+       ->repeat_content(
+          [
+             sub {
+                $_->select('.name')->replace_content('Matt')
+                  ->select('.age')->replace_content('26')
+             },
+             sub {
+                $_->select('.name')->replace_content('Mark')
+                  ->select('.age')->replace_content('0x29')
+             },
+             sub {
+                $_->select('.name')->replace_content('Epitaph')
+                  ->select('.age')->replace_content('<redacted>')
+             },
+          ],
+          { repeat_between => '.between' }
+       );
 
-    TBD
 
 =head1 ALSO SEE