X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.pod;h=01d617a0760410dfd2758a69f21e6ebd64473971;hb=78ba405129a79256aac6d3d2d95a2758630bda0f;hp=91da133e05f813dc5c407d924cc70e9c5f829258;hpb=e99ef07d6c8b76be11c70996ce7edf40562b4625;p=catagits%2FDOM-Tiny.git diff --git a/README.pod b/README.pod index 91da133..01d617a 100644 --- a/README.pod +++ b/README.pod @@ -2,6 +2,8 @@ =encoding utf8 +=for Pod::Coverage TO_JSON + =head1 NAME DOM::Tiny - Minimalistic HTML/XML DOM parser with CSS selectors @@ -35,9 +37,11 @@ DOM::Tiny - Minimalistic HTML/XML DOM parser with CSS selectors =head1 DESCRIPTION -L is a minimalistic and relaxed HTML/XML DOM parser with CSS -selector support based on L. It will even try to interpret broken -HTML and XML, so you should not use it for validation. +L is a minimalistic and relaxed pure-perl HTML/XML DOM parser with +support for the L and +L based on L. It +will even try to interpret broken HTML and XML, so you should not use it for +validation. =head1 NODES AND ELEMENTS @@ -673,6 +677,217 @@ Alias for L. Alias for L. +=head1 COLLECTION METHODS + +Some L methods return an array-based collection object, which can +either be accessed directly as an array reference, or with the following +methods. + + # Chain methods + $collection->map(sub { ucfirst })->shuffle->each(sub { + my ($word, $num) = @_; + say "$num: $word"; + }); + + # Access array directly to manipulate collection + $collection->[23] += 100; + say for @$collection; + +=head2 compact + + my $new = $collection->compact; + +Create a new collection with all elements that are defined and not an empty +string. + + # $collection contains (0, 1, undef, 2, '', 3) + $collection->compact->join(', '); # "0, 1, 2, 3" + +=head2 each + + my @elements = $collection->each; + $collection = $collection->each(sub {...}); + +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<$_>. + + # Make a numbered list + $collection->each(sub { + my ($e, $num) = @_; + say "$num: $e"; + }); + +=head2 first + + 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); + +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<$_>. + + # Longer version + my $first = $collection->first(sub { $_->$method(@args) }); + + # Find first value that contains the word "dom" + my $interesting = $collection->first(qr/dom/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 "dom" + my $interesting = $collection->grep(qr/dom/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 "dom" to all values + my $domified = $collection->map(sub { $_ . 'dom' }); + +=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 Report any issues on the public bugtracker.