NAME

       Mojo::DOM::CSS - CSS selector engine

SYNOPSIS

         use Mojo::DOM::CSS;

         # Select elements from DOM tree
         my $css = Mojo::DOM::CSS->new(tree => $tree);
         my $elements = $css->select('h1, h2, h3');

DESCRIPTION

       Mojo::DOM::CSS is the CSS selector engine used by Mojo::DOM, based on the HTML Living
       Standard <https://html.spec.whatwg.org> and Selectors Level 3
       <http://www.w3.org/TR/css3-selectors/>.

SELECTORS

       All CSS selectors that make sense for a standalone parser are supported.

   *
       Any element.

         my $all = $css->select('*');

   E
       An element of type "E".

         my $title = $css->select('title');

   E[foo]
       An "E" element with a "foo" attribute.

         my $links = $css->select('a[href]');

   E[foo="bar"]
       An "E" element whose "foo" attribute value is exactly equal to "bar".

         my $case_sensitive = $css->select('input[type="hidden"]');
         my $case_sensitive = $css->select('input[type=hidden]');

   E[foo="bar" i]
       An "E" element whose "foo" attribute value is exactly equal to any (ASCII-range) case-
       permutation of "bar". Note that this selector is EXPERIMENTAL and might change without
       warning!

         my $case_insensitive = $css->select('input[type="hidden" i]');
         my $case_insensitive = $css->select('input[type=hidden i]');
         my $case_insensitive = $css->select('input[class~="foo" i]');

       This selector is part of Selectors Level 4 <http://dev.w3.org/csswg/selectors-4>, which is
       still a work in progress.

   E[foo~="bar"]
       An "E" element whose "foo" attribute value is a list of whitespace-separated values, one
       of which is exactly equal to "bar".

         my $foo = $css->select('input[class~="foo"]');
         my $foo = $css->select('input[class~=foo]');

   E[foo^="bar"]
       An "E" element whose "foo" attribute value begins exactly with the string "bar".

         my $begins_with = $css->select('input[name^="f"]');
         my $begins_with = $css->select('input[name^=f]');

   E[foo$="bar"]
       An "E" element whose "foo" attribute value ends exactly with the string "bar".

         my $ends_with = $css->select('input[name$="o"]');
         my $ends_with = $css->select('input[name$=o]');

   E[foo*="bar"]
       An "E" element whose "foo" attribute value contains the substring "bar".

         my $contains = $css->select('input[name*="fo"]');
         my $contains = $css->select('input[name*=fo]');

   E:root
       An "E" element, root of the document.

         my $root = $css->select(':root');

   E:nth-child(n)
       An "E" element, the "n-th" child of its parent.

         my $third = $css->select('div:nth-child(3)');
         my $odd   = $css->select('div:nth-child(odd)');
         my $even  = $css->select('div:nth-child(even)');
         my $top3  = $css->select('div:nth-child(-n+3)');

   E:nth-last-child(n)
       An "E" element, the "n-th" child of its parent, counting from the last one.

         my $third    = $css->select('div:nth-last-child(3)');
         my $odd      = $css->select('div:nth-last-child(odd)');
         my $even     = $css->select('div:nth-last-child(even)');
         my $bottom3  = $css->select('div:nth-last-child(-n+3)');

   E:nth-of-type(n)
       An "E" element, the "n-th" sibling of its type.

         my $third = $css->select('div:nth-of-type(3)');
         my $odd   = $css->select('div:nth-of-type(odd)');
         my $even  = $css->select('div:nth-of-type(even)');
         my $top3  = $css->select('div:nth-of-type(-n+3)');

   E:nth-last-of-type(n)
       An "E" element, the "n-th" sibling of its type, counting from the last one.

         my $third    = $css->select('div:nth-last-of-type(3)');
         my $odd      = $css->select('div:nth-last-of-type(odd)');
         my $even     = $css->select('div:nth-last-of-type(even)');
         my $bottom3  = $css->select('div:nth-last-of-type(-n+3)');

   E:first-child
       An "E" element, first child of its parent.

         my $first = $css->select('div p:first-child');

   E:last-child
       An "E" element, last child of its parent.

         my $last = $css->select('div p:last-child');

   E:first-of-type
       An "E" element, first sibling of its type.

         my $first = $css->select('div p:first-of-type');

   E:last-of-type
       An "E" element, last sibling of its type.

         my $last = $css->select('div p:last-of-type');

   E:only-child
       An "E" element, only child of its parent.

         my $lonely = $css->select('div p:only-child');

   E:only-of-type
       An "E" element, only sibling of its type.

         my $lonely = $css->select('div p:only-of-type');

   E:empty
       An "E" element that has no children (including text nodes).

         my $empty = $css->select(':empty');

   E:checked
       A user interface element "E" which is checked (for instance a radio-button or checkbox).

         my $input = $css->select(':checked');

   E.warning
       An "E" element whose class is "warning".

         my $warning = $css->select('div.warning');

   E#myid
       An "E" element with "ID" equal to "myid".

         my $foo = $css->select('div#foo');

   E:not(s1, s2)
       An "E" element that does not match either compound selector "s1" or compound selector
       "s2". Note that support for compound selectors is EXPERIMENTAL and might change without
       warning!

         my $others = $css->select('div p:not(:first-child, :last-child)');

       Support for compound selectors was added as part of Selectors Level 4
       <http://dev.w3.org/csswg/selectors-4>, which is still a work in progress.

   E:matches(s1, s2)
       An "E" element that matches compound selector "s1" and/or compound selector "s2". Note
       that this selector is EXPERIMENTAL and might change without warning!

         my $headers = $css->select(':matches(section, article, aside, nav) h1');

       This selector is part of Selectors Level 4 <http://dev.w3.org/csswg/selectors-4>, which is
       still a work in progress.

   E F
       An "F" element descendant of an "E" element.

         my $headlines = $css->select('div h1');

   E > F
       An "F" element child of an "E" element.

         my $headlines = $css->select('html > body > div > h1');

   E + F
       An "F" element immediately preceded by an "E" element.

         my $second = $css->select('h1 + h2');

   E ~ F
       An "F" element preceded by an "E" element.

         my $second = $css->select('h1 ~ h2');

   E, F, G
       Elements of type "E", "F" and "G".

         my $headlines = $css->select('h1, h2, h3');

   E[foo=bar][bar=baz]
       An "E" element whose attributes match all following attribute selectors.

         my $links = $css->select('a[foo^=b][foo$=ar]');

ATTRIBUTES

       Mojo::DOM::CSS implements the following attributes.

   tree
         my $tree = $css->tree;
         $css     = $css->tree(['root']);

       Document Object Model. Note that this structure should only be used very carefully since
       it is very dynamic.

METHODS

       Mojo::DOM::CSS inherits all methods from Mojo::Base and implements the following new ones.

   matches
         my $bool = $css->matches('head > title');

       Check if first node in "tree" matches the CSS selector.

   select
         my $results = $css->select('head > title');

       Run CSS selector against "tree".

   select_one
         my $result = $css->select_one('head > title');

       Run CSS selector against "tree" and stop as soon as the first node matched.

SEE ALSO

       Mojolicious, Mojolicious::Guides, <http://mojolicious.org>.