Mojo::DOM::CSS(3pm)

1Mojo::DOM::CSS(3)     User Contributed Perl Documentation    Mojo::DOM::CSS(3)
2
3
4

NAME

6       Mojo::DOM::CSS - CSS selector engine
7

SYNOPSIS

9         use Mojo::DOM::CSS;
10
11         # Select elements from DOM tree
12         my $css = Mojo::DOM::CSS->new(tree => $tree);
13         my $elements = $css->select('h1, h2, h3');
14

DESCRIPTION

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

SELECTORS

21       All CSS selectors that make sense for a standalone parser are
22       supported.
23
24   *
25       Any element.
26
27         my $all = $css->select('*');
28
29   E
30       An element of type "E".
31
32         my $title = $css->select('title');
33
34   E[foo]
35       An "E" element with a "foo" attribute.
36
37         my $links = $css->select('a[href]');
38
39   E[foo="bar"]
40       An "E" element whose "foo" attribute value is exactly equal to "bar".
41
42         my $case_sensitive = $css->select('input[type="hidden"]');
43         my $case_sensitive = $css->select('input[type=hidden]');
44
45   E[foo="bar" i]
46       An "E" element whose "foo" attribute value is exactly equal to any
47       (ASCII-range) case-permutation of "bar". Note that this selector is
48       EXPERIMENTAL and might change without warning!
49
50         my $case_insensitive = $css->select('input[type="hidden" i]');
51         my $case_insensitive = $css->select('input[type=hidden i]');
52         my $case_insensitive = $css->select('input[class~="foo" i]');
53
54       This selector is part of Selectors Level 4
55       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
56       progress.
57
58   E[foo="bar" s]
59       An "E" element whose "foo" attribute value is exactly and case-
60       sensitively equal to "bar". Note that this selector is EXPERIMENTAL and
61       might change without warning!
62
63         my $case_sensitive = $css->select('input[type="hidden" s]');
64
65       This selector is part of Selectors Level 4
66       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
67       progress.
68
69   E[foo~="bar"]
70       An "E" element whose "foo" attribute value is a list of whitespace-
71       separated values, one of which is exactly equal to "bar".
72
73         my $foo = $css->select('input[class~="foo"]');
74         my $foo = $css->select('input[class~=foo]');
75
76   E[foo^="bar"]
77       An "E" element whose "foo" attribute value begins exactly with the
78       string "bar".
79
80         my $begins_with = $css->select('input[name^="f"]');
81         my $begins_with = $css->select('input[name^=f]');
82
83   E[foo$="bar"]
84       An "E" element whose "foo" attribute value ends exactly with the string
85       "bar".
86
87         my $ends_with = $css->select('input[name$="o"]');
88         my $ends_with = $css->select('input[name$=o]');
89
90   E[foo*="bar"]
91       An "E" element whose "foo" attribute value contains the substring
92       "bar".
93
94         my $contains = $css->select('input[name*="fo"]');
95         my $contains = $css->select('input[name*=fo]');
96
97   E[foo|="en"]
98       An "E" element whose "foo" attribute has a hyphen-separated list of
99       values beginning (from the left) with "en".
100
101         my $english = $css->select('link[hreflang|=en]');
102
103   E:root
104       An "E" element, root of the document.
105
106         my $root = $css->select(':root');
107
108   E:nth-child(n)
109       An "E" element, the "n-th" child of its parent.
110
111         my $third = $css->select('div:nth-child(3)');
112         my $odd   = $css->select('div:nth-child(odd)');
113         my $even  = $css->select('div:nth-child(even)');
114         my $top3  = $css->select('div:nth-child(-n+3)');
115
116   E:nth-last-child(n)
117       An "E" element, the "n-th" child of its parent, counting from the last
118       one.
119
120         my $third    = $css->select('div:nth-last-child(3)');
121         my $odd      = $css->select('div:nth-last-child(odd)');
122         my $even     = $css->select('div:nth-last-child(even)');
123         my $bottom3  = $css->select('div:nth-last-child(-n+3)');
124
125   E:nth-of-type(n)
126       An "E" element, the "n-th" sibling of its type.
127
128         my $third = $css->select('div:nth-of-type(3)');
129         my $odd   = $css->select('div:nth-of-type(odd)');
130         my $even  = $css->select('div:nth-of-type(even)');
131         my $top3  = $css->select('div:nth-of-type(-n+3)');
132
133   E:nth-last-of-type(n)
134       An "E" element, the "n-th" sibling of its type, counting from the last
135       one.
136
137         my $third    = $css->select('div:nth-last-of-type(3)');
138         my $odd      = $css->select('div:nth-last-of-type(odd)');
139         my $even     = $css->select('div:nth-last-of-type(even)');
140         my $bottom3  = $css->select('div:nth-last-of-type(-n+3)');
141
142   E:first-child
143       An "E" element, first child of its parent.
144
145         my $first = $css->select('div p:first-child');
146
147   E:last-child
148       An "E" element, last child of its parent.
149
150         my $last = $css->select('div p:last-child');
151
152   E:first-of-type
153       An "E" element, first sibling of its type.
154
155         my $first = $css->select('div p:first-of-type');
156
157   E:last-of-type
158       An "E" element, last sibling of its type.
159
160         my $last = $css->select('div p:last-of-type');
161
162   E:only-child
163       An "E" element, only child of its parent.
164
165         my $lonely = $css->select('div p:only-child');
166
167   E:only-of-type
168       An "E" element, only sibling of its type.
169
170         my $lonely = $css->select('div p:only-of-type');
171
172   E:empty
173       An "E" element that has no children (including text nodes).
174
175         my $empty = $css->select(':empty');
176
177   E:any-link
178       Alias for "E:link". Note that this selector is EXPERIMENTAL and might
179       change without warning! This selector is part of Selectors Level 4
180       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
181       progress.
182
183   E:link
184       An "E" element being the source anchor of a hyperlink of which the
185       target is not yet visited (":link") or already visited (":visited").
186       Note that Mojo::DOM::CSS is not stateful, therefore ":any-link",
187       ":link" and ":visited" yield exactly the same results.
188
189         my $links = $css->select(':any-link');
190         my $links = $css->select(':link');
191         my $links = $css->select(':visited');
192
193   E:visited
194       Alias for "E:link".
195
196   E:scope
197       An "E" element being a designated reference element. Note that this
198       selector is EXPERIMENTAL and might change without warning!
199
200         my $scoped = $css->select('a:not(:scope > a)');
201         my $scoped = $css->select('div :scope p');
202         my $scoped = $css->select('~ p');
203
204       This selector is part of Selectors Level 4
205       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
206       progress.
207
208   E:checked
209       A user interface element "E" which is checked (for instance a radio-
210       button or checkbox).
211
212         my $input = $css->select(':checked');
213
214   E.warning
215       An "E" element whose class is "warning".
216
217         my $warning = $css->select('div.warning');
218
219   E#myid
220       An "E" element with "ID" equal to "myid".
221
222         my $foo = $css->select('div#foo');
223
224   E:not(s1, s2)
225       An "E" element that does not match either compound selector "s1" or
226       compound selector "s2". Note that support for compound selectors is
227       EXPERIMENTAL and might change without warning!
228
229         my $others = $css->select('div p:not(:first-child, :last-child)');
230
231       Support for compound selectors was added as part of Selectors Level 4
232       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
233       progress.
234
235   E:is(s1, s2)
236       An "E" element that matches compound selector "s1" and/or compound
237       selector "s2". Note that this selector is EXPERIMENTAL and might change
238       without warning!
239
240         my $headers = $css->select(':is(section, article, aside, nav) h1');
241
242       This selector is part of Selectors Level 4
243       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
244       progress.
245
246   E:has(rs1, rs2)
247       An "E" element, if either of the relative selectors "rs1" or "rs2",
248       when evaluated with "E" as the :scope elements, match an element. Note
249       that this selector is EXPERIMENTAL and might change without warning!
250
251         my $link = $css->select('a:has(> img)');
252
253       This selector is part of Selectors Level 4
254       <http://dev.w3.org/csswg/selectors-4>, which is still a work in
255       progress.  Also be aware that this feature is currently marked
256       "at-risk", so there is a high chance that it will get removed
257       completely.
258
259   A|E
260       An "E" element that belongs to the namespace alias "A" from CSS
261       Namespaces Module Level 3 <https://www.w3.org/TR/css-namespaces-3/>.
262       Key/value pairs passed to selector methods are used to declare
263       namespace aliases.
264
265         my $elem = $css->select('lq|elem', lq => 'http://example.com/q-markup');
266
267       Using an empty alias searches for an element that belongs to no
268       namespace.
269
270         my $div = $c->select('|div');
271
272   E F
273       An "F" element descendant of an "E" element.
274
275         my $headlines = $css->select('div h1');
276
277   E > F
278       An "F" element child of an "E" element.
279
280         my $headlines = $css->select('html > body > div > h1');
281
282   E + F
283       An "F" element immediately preceded by an "E" element.
284
285         my $second = $css->select('h1 + h2');
286
287   E ~ F
288       An "F" element preceded by an "E" element.
289
290         my $second = $css->select('h1 ~ h2');
291
292   E, F, G
293       Elements of type "E", "F" and "G".
294
295         my $headlines = $css->select('h1, h2, h3');
296
297   E[foo=bar][bar=baz]
298       An "E" element whose attributes match all following attribute
299       selectors.
300
301         my $links = $css->select('a[foo^=b][foo$=ar]');
302

ATTRIBUTES

304       Mojo::DOM::CSS implements the following attributes.
305
306   tree
307         my $tree = $css->tree;
308         $css     = $css->tree(['root']);
309
310       Document Object Model. Note that this structure should only be used
311       very carefully since it is very dynamic.
312

METHODS

314       Mojo::DOM::CSS inherits all methods from Mojo::Base and implements the
315       following new ones.
316
317   matches
318         my $bool = $css->matches('head > title');
319         my $bool = $css->matches('svg|line', svg => 'http://www.w3.org/2000/svg');
320
321       Check if first node in "tree" matches the CSS selector. Trailing
322       key/value pairs can be used to declare xml namespace aliases.
323
324   select
325         my $results = $css->select('head > title');
326         my $results = $css->select('svg|line', svg => 'http://www.w3.org/2000/svg');
327
328       Run CSS selector against "tree". Trailing key/value pairs can be used
329       to declare xml namespace aliases.
330
331   select_one
332         my $result = $css->select_one('head > title');
333         my $result =
334           $css->select_one('svg|line', svg => 'http://www.w3.org/2000/svg');
335
336       Run CSS selector against "tree" and stop as soon as the first node
337       matched. Trailing key/value pairs can be used to declare xml namespace
338       aliases.
339

DEBUGGING

341       You can set the "MOJO_DOM_CSS_DEBUG" environment variable to get some
342       advanced diagnostics information printed to "STDERR".
343
344         MOJO_DOM_CSS_DEBUG=1
345