X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.pod;h=2bf0aa84e609eaea917aa784e837b9a4f900e070;hb=3187745294af04bb4f3ece751c5d947f373039e5;hp=a2937c47e19af75aed2f864b3174582086c49db4;hpb=9a5f1e3f0633370ed08c12af1542a9e38870c84a;p=catagits%2FDOM-Tiny.git

diff --git a/README.pod b/README.pod
index a2937c4..2bf0aa8 100644
--- a/README.pod
+++ b/README.pod
@@ -94,6 +94,226 @@ XML detection can also be disabled with the L</"xml"> method.
   my $dom = DOM::Tiny->new->xml(0)->parse('<P ID="greeting">Hi!</P>');
   say $dom->at('p[id]')->text;
 
+=head1 SELECTORS
+
+L<DOM::Tiny> uses a CSS selector engine based on L<Mojo::DOM::CSS>. All CSS
+selectors that make sense for a standalone parser are supported.
+
+=head2 *
+
+Any element.
+
+  my $all = $dom->find('*');
+
+=head2 E
+
+An element of type C<E>.
+
+  my $title = $dom->at('title');
+
+=head2 E[foo]
+
+An C<E> element with a C<foo> attribute.
+
+  my $links = $dom->find('a[href]');
+
+=head2 E[foo="bar"]
+
+An C<E> element whose C<foo> attribute value is exactly equal to C<bar>.
+
+  my $case_sensitive = $dom->find('input[type="hidden"]');
+  my $case_sensitive = $dom->find('input[type=hidden]');
+
+=head2 E[foo="bar" i]
+
+An C<E> element whose C<foo> attribute value is exactly equal to any
+(ASCII-range) case-permutation of C<bar>. Note that this selector is
+EXPERIMENTAL and might change without warning!
+
+  my $case_insensitive = $dom->find('input[type="hidden" i]');
+  my $case_insensitive = $dom->find('input[type=hidden i]');
+  my $case_insensitive = $dom->find('input[class~="foo" i]');
+
+This selector is part of
+L<Selectors Level 4|http://dev.w3.org/csswg/selectors-4>, which is still a work
+in progress.
+
+=head2 E[foo~="bar"]
+
+An C<E> element whose C<foo> attribute value is a list of whitespace-separated
+values, one of which is exactly equal to C<bar>.
+
+  my $foo = $dom->find('input[class~="foo"]');
+  my $foo = $dom->find('input[class~=foo]');
+
+=head2 E[foo^="bar"]
+
+An C<E> element whose C<foo> attribute value begins exactly with the string
+C<bar>.
+
+  my $begins_with = $dom->find('input[name^="f"]');
+  my $begins_with = $dom->find('input[name^=f]');
+
+=head2 E[foo$="bar"]
+
+An C<E> element whose C<foo> attribute value ends exactly with the string
+C<bar>.
+
+  my $ends_with = $dom->find('input[name$="o"]');
+  my $ends_with = $dom->find('input[name$=o]');
+
+=head2 E[foo*="bar"]
+
+An C<E> element whose C<foo> attribute value contains the substring C<bar>.
+
+  my $contains = $dom->find('input[name*="fo"]');
+  my $contains = $dom->find('input[name*=fo]');
+
+=head2 E:root
+
+An C<E> element, root of the document.
+
+  my $root = $dom->at(':root');
+
+=head2 E:nth-child(n)
+
+An C<E> element, the C<n-th> child of its parent.
+
+  my $third = $dom->find('div:nth-child(3)');
+  my $odd   = $dom->find('div:nth-child(odd)');
+  my $even  = $dom->find('div:nth-child(even)');
+  my $top3  = $dom->find('div:nth-child(-n+3)');
+
+=head2 E:nth-last-child(n)
+
+An C<E> element, the C<n-th> child of its parent, counting from the last one.
+
+  my $third    = $dom->find('div:nth-last-child(3)');
+  my $odd      = $dom->find('div:nth-last-child(odd)');
+  my $even     = $dom->find('div:nth-last-child(even)');
+  my $bottom3  = $dom->find('div:nth-last-child(-n+3)');
+
+=head2 E:nth-of-type(n)
+
+An C<E> element, the C<n-th> sibling of its type.
+
+  my $third = $dom->find('div:nth-of-type(3)');
+  my $odd   = $dom->find('div:nth-of-type(odd)');
+  my $even  = $dom->find('div:nth-of-type(even)');
+  my $top3  = $dom->find('div:nth-of-type(-n+3)');
+
+=head2 E:nth-last-of-type(n)
+
+An C<E> element, the C<n-th> sibling of its type, counting from the last one.
+
+  my $third    = $dom->find('div:nth-last-of-type(3)');
+  my $odd      = $dom->find('div:nth-last-of-type(odd)');
+  my $even     = $dom->find('div:nth-last-of-type(even)');
+  my $bottom3  = $dom->find('div:nth-last-of-type(-n+3)');
+
+=head2 E:first-child
+
+An C<E> element, first child of its parent.
+
+  my $first = $dom->find('div p:first-child');
+
+=head2 E:last-child
+
+An C<E> element, last child of its parent.
+
+  my $last = $dom->find('div p:last-child');
+
+=head2 E:first-of-type
+
+An C<E> element, first sibling of its type.
+
+  my $first = $dom->find('div p:first-of-type');
+
+=head2 E:last-of-type
+
+An C<E> element, last sibling of its type.
+
+  my $last = $dom->find('div p:last-of-type');
+
+=head2 E:only-child
+
+An C<E> element, only child of its parent.
+
+  my $lonely = $dom->find('div p:only-child');
+
+=head2 E:only-of-type
+
+An C<E> element, only sibling of its type.
+
+  my $lonely = $dom->find('div p:only-of-type');
+
+=head2 E:empty
+
+An C<E> element that has no children (including text nodes).
+
+  my $empty = $dom->find(':empty');
+
+=head2 E:checked
+
+A user interface element C<E> which is checked (for instance a radio-button or
+checkbox).
+
+  my $input = $dom->find(':checked');
+
+=head2 E.warning
+
+An C<E> element whose class is "warning".
+
+  my $warning = $dom->find('div.warning');
+
+=head2 E#myid
+
+An C<E> element with C<ID> equal to "myid".
+
+  my $foo = $dom->at('div#foo');
+
+=head2 E:not(s)
+
+An C<E> element that does not match simple selector C<s>.
+
+  my $others = $dom->find('div p:not(:first-child)');
+
+=head2 E F
+
+An C<F> element descendant of an C<E> element.
+
+  my $headlines = $dom->find('div h1');
+
+=head2 E E<gt> F
+
+An C<F> element child of an C<E> element.
+
+  my $headlines = $dom->find('html > body > div > h1');
+
+=head2 E + F
+
+An C<F> element immediately preceded by an C<E> element.
+
+  my $second = $dom->find('h1 + h2');
+
+=head2 E ~ F
+
+An C<F> element preceded by an C<E> element.
+
+  my $second = $dom->find('h1 ~ h2');
+
+=head2 E, F, G
+
+Elements of type C<E>, C<F> and C<G>.
+
+  my $headlines = $dom->find('h1, h2, h3');
+
+=head2 E[foo=bar][bar=baz]
+
+An C<E> element whose attributes match all following attribute selectors.
+
+  my $links = $dom->find('a[foo^=b][foo$=ar]');
+
 =head1 OPERATORS
 
 L<DOM::Tiny> overloads the following operators.
@@ -886,226 +1106,6 @@ callback/method.
   # $collection contains ([1, 2], [2, 1], [3, 2])
   $collection->uniq(sub{ $_->[1] })->to_array; # "[[1, 2], [2, 1]]"
 
-=head1 SELECTORS
-
-L<DOM::Tiny> uses a CSS selector engine based on L<Mojo::DOM::CSS>. All CSS
-selectors that make sense for a standalone parser are supported.
-
-=head2 *
-
-Any element.
-
-  my $all = $dom->find('*');
-
-=head2 E
-
-An element of type C<E>.
-
-  my $title = $dom->at('title');
-
-=head2 E[foo]
-
-An C<E> element with a C<foo> attribute.
-
-  my $links = $dom->find('a[href]');
-
-=head2 E[foo="bar"]
-
-An C<E> element whose C<foo> attribute value is exactly equal to C<bar>.
-
-  my $case_sensitive = $dom->find('input[type="hidden"]');
-  my $case_sensitive = $dom->find('input[type=hidden]');
-
-=head2 E[foo="bar" i]
-
-An C<E> element whose C<foo> attribute value is exactly equal to any
-(ASCII-range) case-permutation of C<bar>. Note that this selector is
-EXPERIMENTAL and might change without warning!
-
-  my $case_insensitive = $dom->find('input[type="hidden" i]');
-  my $case_insensitive = $dom->find('input[type=hidden i]');
-  my $case_insensitive = $dom->find('input[class~="foo" i]');
-
-This selector is part of
-L<Selectors Level 4|http://dev.w3.org/csswg/selectors-4>, which is still a work
-in progress.
-
-=head2 E[foo~="bar"]
-
-An C<E> element whose C<foo> attribute value is a list of whitespace-separated
-values, one of which is exactly equal to C<bar>.
-
-  my $foo = $dom->find('input[class~="foo"]');
-  my $foo = $dom->find('input[class~=foo]');
-
-=head2 E[foo^="bar"]
-
-An C<E> element whose C<foo> attribute value begins exactly with the string
-C<bar>.
-
-  my $begins_with = $dom->find('input[name^="f"]');
-  my $begins_with = $dom->find('input[name^=f]');
-
-=head2 E[foo$="bar"]
-
-An C<E> element whose C<foo> attribute value ends exactly with the string
-C<bar>.
-
-  my $ends_with = $dom->find('input[name$="o"]');
-  my $ends_with = $dom->find('input[name$=o]');
-
-=head2 E[foo*="bar"]
-
-An C<E> element whose C<foo> attribute value contains the substring C<bar>.
-
-  my $contains = $dom->find('input[name*="fo"]');
-  my $contains = $dom->find('input[name*=fo]');
-
-=head2 E:root
-
-An C<E> element, root of the document.
-
-  my $root = $dom->at(':root');
-
-=head2 E:nth-child(n)
-
-An C<E> element, the C<n-th> child of its parent.
-
-  my $third = $dom->find('div:nth-child(3)');
-  my $odd   = $dom->find('div:nth-child(odd)');
-  my $even  = $dom->find('div:nth-child(even)');
-  my $top3  = $dom->find('div:nth-child(-n+3)');
-
-=head2 E:nth-last-child(n)
-
-An C<E> element, the C<n-th> child of its parent, counting from the last one.
-
-  my $third    = $dom->find('div:nth-last-child(3)');
-  my $odd      = $dom->find('div:nth-last-child(odd)');
-  my $even     = $dom->find('div:nth-last-child(even)');
-  my $bottom3  = $dom->find('div:nth-last-child(-n+3)');
-
-=head2 E:nth-of-type(n)
-
-An C<E> element, the C<n-th> sibling of its type.
-
-  my $third = $dom->find('div:nth-of-type(3)');
-  my $odd   = $dom->find('div:nth-of-type(odd)');
-  my $even  = $dom->find('div:nth-of-type(even)');
-  my $top3  = $dom->find('div:nth-of-type(-n+3)');
-
-=head2 E:nth-last-of-type(n)
-
-An C<E> element, the C<n-th> sibling of its type, counting from the last one.
-
-  my $third    = $dom->find('div:nth-last-of-type(3)');
-  my $odd      = $dom->find('div:nth-last-of-type(odd)');
-  my $even     = $dom->find('div:nth-last-of-type(even)');
-  my $bottom3  = $dom->find('div:nth-last-of-type(-n+3)');
-
-=head2 E:first-child
-
-An C<E> element, first child of its parent.
-
-  my $first = $dom->find('div p:first-child');
-
-=head2 E:last-child
-
-An C<E> element, last child of its parent.
-
-  my $last = $dom->find('div p:last-child');
-
-=head2 E:first-of-type
-
-An C<E> element, first sibling of its type.
-
-  my $first = $dom->find('div p:first-of-type');
-
-=head2 E:last-of-type
-
-An C<E> element, last sibling of its type.
-
-  my $last = $dom->find('div p:last-of-type');
-
-=head2 E:only-child
-
-An C<E> element, only child of its parent.
-
-  my $lonely = $dom->find('div p:only-child');
-
-=head2 E:only-of-type
-
-An C<E> element, only sibling of its type.
-
-  my $lonely = $dom->find('div p:only-of-type');
-
-=head2 E:empty
-
-An C<E> element that has no children (including text nodes).
-
-  my $empty = $dom->find(':empty');
-
-=head2 E:checked
-
-A user interface element C<E> which is checked (for instance a radio-button or
-checkbox).
-
-  my $input = $dom->find(':checked');
-
-=head2 E.warning
-
-An C<E> element whose class is "warning".
-
-  my $warning = $dom->find('div.warning');
-
-=head2 E#myid
-
-An C<E> element with C<ID> equal to "myid".
-
-  my $foo = $dom->at('div#foo');
-
-=head2 E:not(s)
-
-An C<E> element that does not match simple selector C<s>.
-
-  my $others = $dom->find('div p:not(:first-child)');
-
-=head2 E F
-
-An C<F> element descendant of an C<E> element.
-
-  my $headlines = $dom->find('div h1');
-
-=head2 E E<gt> F
-
-An C<F> element child of an C<E> element.
-
-  my $headlines = $dom->find('html > body > div > h1');
-
-=head2 E + F
-
-An C<F> element immediately preceded by an C<E> element.
-
-  my $second = $dom->find('h1 + h2');
-
-=head2 E ~ F
-
-An C<F> element preceded by an C<E> element.
-
-  my $second = $dom->find('h1 ~ h2');
-
-=head2 E, F, G
-
-Elements of type C<E>, C<F> and C<G>.
-
-  my $headlines = $dom->find('h1, h2, h3');
-
-=head2 E[foo=bar][bar=baz]
-
-An C<E> element whose attributes match all following attribute selectors.
-
-  my $links = $dom->find('a[foo^=b][foo$=ar]');
-
 =head1 BUGS
 
 Report any issues on the public bugtracker.
@@ -1124,7 +1124,7 @@ This is free software, licensed under:
 
 =head1 SEE ALSO
 
-L<Mojo::DOM>, L<XML::LibXML>, L<XML::Twig>, L<HTML::TreeBuilder>, L<XML::Smart>
+L<Mojo::DOM>, L<HTML::TreeBuilder>, L<XML::LibXML>, L<XML::Twig>, L<XML::Smart>
 
 =for Pod::Coverage TO_JSON