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 <https://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       <https://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       <https://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       <https://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       <https://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       <https://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       <https://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       <https://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   E:text(string_or_regex)
260       An "E" element containing text content that substring matches
261       "string_or_regex" case-insensitively or that regex matches
262       "string_or_regex". For regular expressions use the format :text(/.../).
263       Note that this selector is EXPERIMENTAL and might change without
264       warning!
265
266         # Substring match
267         my $login = $css->select(':text(Log in)');
268
269         # Regex match
270         my $login = $css->select(':text(/Log ?in/)');
271
272         # Regex match (case-insensitive)
273         my $login = $css->select(':text(/(?i:Log ?in)/)');
274
275       This is a custom selector for Mojo::DOM and not part of any spec.
276
277   A|E
278       An "E" element that belongs to the namespace alias "A" from CSS
279       Namespaces Module Level 3 <https://www.w3.org/TR/css-namespaces-3/>.
280       Key/value pairs passed to selector methods are used to declare
281       namespace aliases.
282
283         my $elem = $css->select('lq|elem', lq => 'http://example.com/q-markup');
284
285       Using an empty alias searches for an element that belongs to no
286       namespace.
287
288         my $div = $c->select('|div');
289
290   E F
291       An "F" element descendant of an "E" element.
292
293         my $headlines = $css->select('div h1');
294
295   E > F
296       An "F" element child of an "E" element.
297
298         my $headlines = $css->select('html > body > div > h1');
299
300   E + F
301       An "F" element immediately preceded by an "E" element.
302
303         my $second = $css->select('h1 + h2');
304
305   E ~ F
306       An "F" element preceded by an "E" element.
307
308         my $second = $css->select('h1 ~ h2');
309
310   E, F, G
311       Elements of type "E", "F" and "G".
312
313         my $headlines = $css->select('h1, h2, h3');
314
315   E[foo=bar][bar=baz]
316       An "E" element whose attributes match all following attribute
317       selectors.
318
319         my $links = $css->select('a[foo^=b][foo$=ar]');
320

ATTRIBUTES

322       Mojo::DOM::CSS implements the following attributes.
323
324   tree
325         my $tree = $css->tree;
326         $css     = $css->tree(['root']);
327
328       Document Object Model. Note that this structure should only be used
329       very carefully since it is very dynamic.
330

METHODS

332       Mojo::DOM::CSS inherits all methods from Mojo::Base and implements the
333       following new ones.
334
335   matches
336         my $bool = $css->matches('head > title');
337         my $bool = $css->matches('svg|line', svg => 'http://www.w3.org/2000/svg');
338
339       Check if first node in "tree" matches the CSS selector. Trailing
340       key/value pairs can be used to declare xml namespace aliases.
341
342   select
343         my $results = $css->select('head > title');
344         my $results = $css->select('svg|line', svg => 'http://www.w3.org/2000/svg');
345
346       Run CSS selector against "tree". Trailing key/value pairs can be used
347       to declare xml namespace aliases.
348
349   select_one
350         my $result = $css->select_one('head > title');
351         my $result =
352           $css->select_one('svg|line', svg => 'http://www.w3.org/2000/svg');
353
354       Run CSS selector against "tree" and stop as soon as the first node
355       matched. Trailing key/value pairs can be used to declare xml namespace
356       aliases.
357

DEBUGGING

359       You can set the "MOJO_DOM_CSS_DEBUG" environment variable to get some
360       advanced diagnostics information printed to "STDERR".
361
362         MOJO_DOM_CSS_DEBUG=1
363