+nodes), placing it as the last children of the first innermost element.
# "123Test
"
$dom->parse('Test
')->at('p')->wrap_content('123')->root;
@@ -639,41 +903,218 @@ children of the first innermost element.
$dom = $dom->xml($bool);
Disable HTML semantics in parser and activate case-sensitivity, defaults to
-auto detection based on processing instructions.
+auto detection based on XML declarations.
-=head1 OPERATORS
+=head1 COLLECTION METHODS
-L overloads the following operators.
+Some L methods return an array-based collection object based on
+L, which can either be accessed directly as an array
+reference, or with the following methods.
-=head2 array
+ # Chain methods
+ $collection->map(sub { ucfirst })->shuffle->each(sub {
+ my ($word, $num) = @_;
+ say "$num: $word";
+ });
- my @nodes = @$dom;
+ # Access array directly to manipulate collection
+ $collection->[23] += 100;
+ say for @$collection;
-Alias for L.
+=head2 compact
- # ""
- $dom->parse('123')->[0];
+ my $new = $collection->compact;
-=head2 bool
+Create a new collection with all elements that are defined and not an empty
+string.
- my $bool = !!$dom;
+ # $collection contains (0, 1, undef, 2, '', 3)
+ $collection->compact->join(', '); # "0, 1, 2, 3"
-Always true.
+=head2 each
-=head2 hash
+ my @elements = $collection->each;
+ $collection = $collection->each(sub {...});
- my %attrs = %$dom;
+Evaluate callback for each element in collection or return all elements as a
+list if none has been provided. The element will be the first argument passed
+to the callback and is also available as C<$_>.
-Alias for L.
+ # Make a numbered list
+ $collection->each(sub {
+ my ($e, $num) = @_;
+ say "$num: $e";
+ });
- # "test"
- $dom->parse('Test
')->at('div')->{id};
+=head2 first
-=head2 stringify
+ my $first = $collection->first;
+ my $first = $collection->first(qr/foo/);
+ my $first = $collection->first(sub {...});
+ my $first = $collection->first($method);
+ my $first = $collection->first($method, @args);
- my $str = "$dom";
+Evaluate regular expression/callback for, or call method on, each element in
+collection and return the first one that matched the regular expression, or for
+which the callback/method returned true. The element will be the first argument
+passed to the callback and is also available as C<$_>.
-Alias for L.
+ # Longer version
+ my $first = $collection->first(sub { $_->$method(@args) });
+
+ # Find first value that contains the word "tiny"
+ my $interesting = $collection->first(qr/tiny/i);
+
+ # Find first value that is greater than 5
+ my $greater = $collection->first(sub { $_ > 5 });
+
+=head2 flatten
+
+ my $new = $collection->flatten;
+
+Flatten nested collections/arrays recursively and create a new collection with
+all elements.
+
+ # $collection contains (1, [2, [3, 4], 5, [6]], 7)
+ $collection->flatten->join(', '); # "1, 2, 3, 4, 5, 6, 7"
+
+=head2 grep
+
+ my $new = $collection->grep(qr/foo/);
+ my $new = $collection->grep(sub {...});
+ my $new = $collection->grep($method);
+ my $new = $collection->grep($method, @args);
+
+Evaluate regular expression/callback for, or call method on, each element in
+collection and create a new collection with all elements that matched the
+regular expression, or for which the callback/method returned true. The element
+will be the first argument passed to the callback and is also available as
+C<$_>.
+
+ # Longer version
+ my $new = $collection->grep(sub { $_->$method(@args) });
+
+ # Find all values that contain the word "tiny"
+ my $interesting = $collection->grep(qr/tiny/i);
+
+ # Find all values that are greater than 5
+ my $greater = $collection->grep(sub { $_ > 5 });
+
+=head2 join
+
+ my $stream = $collection->join;
+ my $stream = $collection->join("\n");
+
+Turn collection into string.
+
+ # Join all values with commas
+ $collection->join(', ');
+
+=head2 last
+
+ my $last = $collection->last;
+
+Return the last element in collection.
+
+=head2 map
+
+ my $new = $collection->map(sub {...});
+ my $new = $collection->map($method);
+ my $new = $collection->map($method, @args);
+
+Evaluate callback for, or call method on, each element in collection and create
+a new collection from the results. The element will be the first argument
+passed to the callback and is also available as C<$_>.
+
+ # Longer version
+ my $new = $collection->map(sub { $_->$method(@args) });
+
+ # Append the word "tiny" to all values
+ my $domified = $collection->map(sub { $_ . 'tiny' });
+
+=head2 reduce
+
+ my $result = $collection->reduce(sub {...});
+ my $result = $collection->reduce(sub {...}, $initial);
+
+Reduce elements in collection with callback, the first element will be used as
+initial value if none has been provided.
+
+ # Calculate the sum of all values
+ my $sum = $collection->reduce(sub { $a + $b });
+
+ # Count how often each value occurs in collection
+ my $hash = $collection->reduce(sub { $a->{$b}++; $a }, {});
+
+=head2 reverse
+
+ my $new = $collection->reverse;
+
+Create a new collection with all elements in reverse order.
+
+=head2 slice
+
+ my $new = $collection->slice(4 .. 7);
+
+Create a new collection with all selected elements.
+
+ # $collection contains ('A', 'B', 'C', 'D', 'E')
+ $collection->slice(1, 2, 4)->join(' '); # "B C E"
+
+=head2 shuffle
+
+ my $new = $collection->shuffle;
+
+Create a new collection with all elements in random order.
+
+=head2 size
+
+ my $size = $collection->size;
+
+Number of elements in collection.
+
+=head2 sort
+
+ my $new = $collection->sort;
+ my $new = $collection->sort(sub {...});
+
+Sort elements based on return value of callback and create a new collection
+from the results.
+
+ # Sort values case-insensitive
+ my $case_insensitive = $collection->sort(sub { uc($a) cmp uc($b) });
+
+=head2 tap
+
+ $collection = $collection->tap(sub {...});
+
+Equivalent to L.
+
+=head2 to_array
+
+ my $array = $collection->to_array;
+
+Turn collection into array reference.
+
+=head2 uniq
+
+ my $new = $collection->uniq;
+ my $new = $collection->uniq(sub {...});
+ my $new = $collection->uniq($method);
+ my $new = $collection->uniq($method, @args);
+
+Create a new collection without duplicate elements, using the string
+representation of either the elements or the return value of the
+callback/method.
+
+ # Longer version
+ my $new = $collection->uniq(sub { $_->$method(@args) });
+
+ # $collection contains ('foo', 'bar', 'bar', 'baz')
+ $collection->uniq->join(' '); # "foo bar baz"
+
+ # $collection contains ([1, 2], [2, 1], [3, 2])
+ $collection->uniq(sub{ $_->[1] })->to_array; # "[[1, 2], [2, 1]]"
=head1 BUGS
@@ -683,9 +1124,21 @@ Report any issues on the public bugtracker.
Dan Book
+Code and tests adapted from L, a lightweight DOM parser by the L team.
+
+=head1 CONTRIBUTORS
+
+=over
+
+=item Matt S Trout (mst)
+
+=back
+
=head1 COPYRIGHT AND LICENSE
-This software is Copyright (c) 2015 by Dan Book.
+Copyright (c) 2008-2015 Sebastian Riedel.
+
+Copyright (c) 2015 L and L for adaptation to standalone format.
This is free software, licensed under:
@@ -693,6 +1146,8 @@ This is free software, licensed under:
=head1 SEE ALSO
-L, L, L, L, L
+L, L, L, L, L
+
+=for Pod::Coverage TO_JSON
=cut