File Coverage

blib/lib/Mojo/DOM58.pm

Criterion	Covered	Total	%
statement	234	234	100.0
branch	123	126	97.6
condition	59	66	89.3
subroutine	78	78	100.0
pod	43	44	97.7
total	537	548	97.9

line	stmt	bran	cond	sub	pod	time	code
1							package Mojo::DOM58;
2
3	2			2		140385	use strict;
	2					13
	2					62
4	2			2		11	use warnings;
	2					4
	2					231
5
6							use overload
7	4			4		13	'@{}' => sub { shift->child_nodes },
8	95			95		241	'%{}' => sub { shift->attr },
9	32			32		3876	bool => sub {1},
10	129			129		16226	'""' => sub { shift->to_string },
11	2			2		2508	fallback => 1;
	2					2081
	2					24
12
13	2			2		217	use Exporter 'import';
	2					4
	2					58
14	2			2		435	use Mojo::DOM58::_Collection;
	2					5
	2					67
15	2			2		1036	use Mojo::DOM58::_CSS;
	2					6
	2					80
16	2			2		982	use Mojo::DOM58::_HTML 'tag_to_html';
	2					6
	2					148
17	2			2		15	use Scalar::Util qw(blessed weaken);
	2					4
	2					99
18	2			2		1615	use Storable 'dclone';
	2					6527
	2					8074
19
20							our $VERSION = '3.000';
21
22							our @EXPORT_OK = 'tag_to_html';
23
24							sub new {
25	2128			2128	1	344339	my $class = shift;
26	2128		66			5373	my $self = bless \Mojo::DOM58::_HTML->new, ref $class \|\| $class;
27	2128	100				6281	return @_ ? $self->parse(@_) : $self;
28							}
29
30							sub new_tag {
31	11			11	1	2924	my $self = shift;
32	11					28	my $new = $self->new;
33	11					46	$$new->tag(@_);
34	11	100				35	$$new->xml($$self->xml) if ref $self;
35	11					37	return $new;
36							}
37
38	1			1	0	92	sub TO_JSON { ${shift()}->render }
	1					6
39
40	25			25	1	82	sub all_text { _text(_nodes($_[0]->tree), $_[0]->xml, 1) }
41
42	15			15	1	53	sub ancestors { _select($_[0]->_collect([_ancestors($_[0]->tree)]), $_[1]) }
43
44	9			9	1	40	sub append { shift->_add(1, @_) }
45	13			13	1	45	sub append_content { shift->_content(1, 0, @_) }
46
47							sub at {
48	612			612	1	2064	my $self = shift;
49	612	100				1719	return undef unless my $result = $self->_css->select_one(@_);
50	564					3357	return $self->_build($result, $self->xml);
51							}
52
53							sub attr {
54	168			168	1	285	my $self = shift;
55
56							# Hash
57	168					331	my $tree = $self->tree;
58	168	100				438	my $attrs = $tree->[0] ne 'tag' ? {} : $tree->[2];
59	168	100				859	return $attrs unless @_;
60
61							# Get
62	40	100	100			268	return $attrs->{$_[0]} unless @_ > 1 \|\| ref $_[0];
63
64							# Set
65	4	100				15	my $values = ref $_[0] ? $_[0] : {@_};
66	4					18	@$attrs{keys %$values} = values %$values;
67
68	4					17	return $self;
69							}
70
71	59			59	1	152	sub child_nodes { $_[0]->_collect(_nodes($_[0]->tree)) }
72
73	13			13	1	61	sub children { _select($_[0]->_collect(_nodes($_[0]->tree, 1)), $_[1]) }
74
75							sub content {
76	55			55	1	107	my $self = shift;
77
78	55					132	my $type = $self->type;
79	55	100	100			239	if ($type eq 'root' \|\| $type eq 'tag') {
80	24	100				89	return $self->_content(0, 1, @_) if @_;
81	7					15	my $html = Mojo::DOM58::_HTML->new(xml => $self->xml);
82	7					19	return join '', map { $html->tree($_)->render } @{_nodes($self->tree)};
	12					28
	7					15
83							}
84
85	31	100				80	return $self->tree->[1] unless @_;
86	3					9	$self->tree->[1] = shift;
87	3					11	return $self;
88							}
89
90	13			13	1	37	sub descendant_nodes { $_[0]->_collect(_all(_nodes($_[0]->tree))) }
91
92							sub find {
93	427			427	1	2767	my $self = shift;
94	427					1205	return $self->_collect($self->_css->select(@_));
95							}
96
97	8			8	1	28	sub following { _select($_[0]->_collect(_siblings($_[0]->tree, 1, 1)), $_[1]) }
98	7			7	1	21	sub following_nodes { $_[0]->_collect(_siblings($_[0]->tree, 0, 1)) }
99
100	44			44	1	106	sub matches { shift->_css->matches(@_) }
101
102							sub namespace {
103	18			18	1	40	my $self = shift;
104
105	18	100				39	return undef if (my $tree = $self->tree)->[0] ne 'tag';
106
107							# Extract namespace prefix and search parents
108	16	100				188	my $ns = $tree->[1] =~ /^(.*?):/ ? "xmlns:$1" : undef;
109	16					43	for my $node ($tree, _ancestors($tree)) {
110
111							# Namespace for prefix
112	35					50	my $attrs = $node->[2];
113	35	100	100			87	if ($ns) { $_ eq $ns and return $attrs->{$_} for keys %$attrs }
	13	100				75
114
115							# Namespace attribute
116	10					54	elsif (defined $attrs->{xmlns}) { return $attrs->{xmlns} }
117							}
118
119	1					5	return undef;
120							}
121
122	13			13	1	32	sub next { $_[0]->_maybe(_siblings($_[0]->tree, 1, 1, 0)) }
123	5			5	1	13	sub next_node { $_[0]->_maybe(_siblings($_[0]->tree, 0, 1, 0)) }
124
125							sub parent {
126	48			48	1	93	my $self = shift;
127	48	50				98	return undef if (my $tree = $self->tree)->[0] eq 'root';
128	48					119	return $self->_build(_parent($tree), $self->xml);
129							}
130
131	166	50		166	1	401	sub parse { ${$_[0]}->parse($_[1]) and return $_[0] }
	166					879
132
133	5			5	1	14	sub preceding { _select($_[0]->_collect(_siblings($_[0]->tree, 1, 0)), $_[1]) }
134	7			7	1	17	sub preceding_nodes { $_[0]->_collect(_siblings($_[0]->tree, 0)) }
135
136	11			11	1	37	sub prepend { shift->_add(0, @_) }
137	6			6	1	22	sub prepend_content { shift->_content(0, 0, @_) }
138
139	7			7	1	22	sub previous { $_[0]->_maybe(_siblings($_[0]->tree, 1, 0, -1)) }
140	5			5	1	13	sub previous_node { $_[0]->_maybe(_siblings($_[0]->tree, 0, 0, -1)) }
141
142	6			6	1	21	sub remove { shift->replace('') }
143
144							sub replace {
145	24			24	1	65	my ($self, $new) = @_;
146	24	100				51	return $self->parse($new) if (my $tree = $self->tree)->[0] eq 'root';
147	16					50	return $self->_replace(_parent($tree), $tree, _nodes($self->_parse($new)));
148							}
149
150							sub root {
151	12			12	1	28	my $self = shift;
152	12	100				28	return $self unless my $tree = _ancestors($self->tree, 1);
153	9					41	return $self->_build($tree, $self->xml);
154							}
155
156							sub selector {
157	13	100		13	1	39	return undef unless (my $tree = shift->tree)->[0] eq 'tag';
158							return join ' > ',
159	11					47	reverse map { $_->[1] . ':nth-child(' . (@{_siblings($_, 1)} + 1) . ')' }
	31					68
	31					73
160							$tree, _ancestors($tree);
161							}
162
163							sub strip {
164	9			9	1	18	my $self = shift;
165	9	100				21	return $self if (my $tree = $self->tree)->[0] ne 'tag';
166	7					25	return $self->_replace($tree->[3], $tree, _nodes($tree));
167							}
168
169							sub tag {
170	96			96	1	227	my ($self, $tag) = @_;
171	96	100				178	return undef if (my $tree = $self->tree)->[0] ne 'tag';
172	94	100				480	return $tree->[1] unless $tag;
173	1					5	$tree->[1] = $tag;
174	1					4	return $self;
175							}
176
177	1			1	1	7	sub tap { Mojo::DOM58::_Collection::tap(@_) }
178
179	722			722	1	1933	sub text { _text(_nodes(shift->tree), 0, 0) }
180
181	139			139	1	237	sub to_string { ${shift()}->render }
	139					564
182
183	4596	100	50	4596	1	8886	sub tree { @_ > 1 ? (${$_[0]}->tree($_[1]) and return $_[0]) : ${$_[0]}->tree }
	2641					8807
184
185	78			78	1	153	sub type { shift->tree->[0] }
186
187							sub val {
188	27			27	1	42	my $self = shift;
189
190							# "option"
191	27	100				59	return defined($self->{value}) ? $self->{value} : $self->text
		100
192							if (my $tag = $self->tag) eq 'option';
193
194							# "input" ("type=checkbox" and "type=radio")
195	17		100			50	my $type = $self->{type} \|\| '';
196	17	100	100			69	return defined $self->{value} ? $self->{value} : 'on'
		100	100
197							if $tag eq 'input' && ($type eq 'radio' \|\| $type eq 'checkbox');
198
199							# "textarea", "input" or "button"
200	12	100				36	return $tag eq 'textarea' ? $self->text : $self->{value} if $tag ne 'select';
		100
201
202							# "select"
203							my $v = $self->find('option:checked:not([disabled])')
204	5			6		14	->grep(sub { !$_->ancestors('optgroup[disabled]')->size })->map('val');
	6					17
205	5	100				33	return exists $self->{multiple} ? $v->size ? $v->to_array : undef : $v->last;
		100
206							}
207
208	1			1	1	1289	sub with_roles { Mojo::DOM58::_Collection::with_roles(@_) }
209
210	9			9	1	38	sub wrap { shift->_wrap(0, @_) }
211	7			7	1	27	sub wrap_content { shift->_wrap(1, @_) }
212
213	3275	100	50	3275	1	6796	sub xml { @_ > 1 ? (${$_[0]}->xml($_[1]) and return $_[0]) : ${$_[0]}->xml }
	1309					4419
214
215							sub _add {
216	20			20		51	my ($self, $offset, $new) = @_;
217
218	20	100				46	return $self if (my $tree = $self->tree)->[0] eq 'root';
219
220	16					55	my $parent = _parent($tree);
221							splice @$parent, _offset($parent, $tree) + $offset, 0,
222	16					48	@{_link($parent, _nodes($self->_parse($new)))};
	16					51
223
224	16					85	return $self;
225							}
226
227							sub _all {
228	21			21		31	my $nodes = shift;
229	21	100				38	@$nodes = map { $_->[0] eq 'tag' ? ($_, @{_all(_nodes($_))}) : ($_) } @$nodes;
	60					125
	8					13
230	21					52	return $nodes;
231							}
232
233							sub _ancestors {
234	54			54		136	my ($tree, $root) = @_;
235
236	54	100				131	return () unless $tree = _parent($tree);
237	51					92	my @ancestors;
238	51		66			84	do { push @ancestors, $tree }
	137					488
239							while ($tree->[0] eq 'tag') && ($tree = $tree->[3]);
240	51	100				591	return $root ? $ancestors[-1] : @ancestors[0 .. $#ancestors - 1];
241							}
242
243	1955			1955		4217	sub _build { shift->new->tree(shift)->xml(shift) }
244
245							sub _collect {
246	553		50	553		1760	my ($self, $nodes) = (shift, shift \|\| []);
247	553					1251	my $xml = $self->xml;
248	553					1302	return Mojo::DOM58::_Collection->new(map { $self->_build($_, $xml) } @$nodes);
	1314					2460
249							}
250
251							sub _content {
252	36			36		89	my ($self, $start, $offset, $new) = @_;
253
254	36					80	my $tree = $self->tree;
255	36	100	100			171	unless ($tree->[0] eq 'root' \|\| $tree->[0] eq 'tag') {
256	2					7	my $old = $self->content;
257	2	100				10	return $self->content($start ? $old . $new : $new . $old);
258							}
259
260	34	100				116	$start = $start ? ($#$tree + 1) : _start($tree);
261	34	100				81	$offset = $offset ? $#$tree : 0;
262	34					57	splice @$tree, $start, $offset, @{_link($tree, _nodes($self->_parse($new)))};
	34					89
263
264	34					156	return $self;
265							}
266
267	1083			1083		2412	sub _css { Mojo::DOM58::_CSS->new(tree => shift->tree) }
268
269	1			1		9	sub _fragment { _link(my $r = ['root', @_], [@_]); $r }
	1					5
270
271							sub _link {
272	98			98		210	my ($parent, $children) = @_;
273
274							# Link parent to children
275	98					187	for my $node (@$children) {
276	102	100				232	my $offset = $node->[0] eq 'tag' ? 3 : 2;
277	102					196	$node->[$offset] = $parent;
278	102					293	weaken $node->[$offset];
279							}
280
281	98					321	return $children;
282							}
283
284	30	100		30		99	sub _maybe { $_[1] ? $_[0]->_build($_[1], $_[0]->xml) : undef }
285
286							sub _nodes {
287	1191	50		1191		2625	return () unless my $tree = shift;
288	1191					2628	my @nodes = @$tree[_start($tree) .. $#$tree];
289	1191	100				3667	return shift() ? [grep { $_->[0] eq 'tag' } @nodes] : \@nodes;
	84					308
290							}
291
292							sub _offset {
293	46			46		100	my ($parent, $child) = @_;
294	46					97	my $i = _start($parent);
295	46	100				300	$_ eq $child ? last : $i++ for @$parent[$i .. $#$parent];
296	46					118	return $i;
297							}
298
299	223	100		223		779	sub _parent { $_[0]->[$_[0][0] eq 'tag' ? 3 : 2] }
300
301							sub _parse {
302	80			80		187	my ($self, $input) = @_;
303	80	100	66			489	return Mojo::DOM58::_HTML->new(xml => $self->xml)->parse($input)->tree
304							unless blessed $input && $input->isa('Mojo::DOM58');
305	21					117	my $tree = dclone $input->tree;
306	21	100				132	return $tree->[0] eq 'root' ? $tree : _fragment($tree);
307							}
308
309							sub _replace {
310	30			30		75	my ($self, $parent, $child, $nodes) = @_;
311	30					85	splice @$parent, _offset($parent, $child), 1, @{_link($parent, $nodes)};
	30					81
312	30					95	return $self->parent;
313							}
314
315	41	100		41		297	sub _select { $_[1] ? $_[0]->grep(matches => $_[1]) : $_[0] }
316
317							sub _siblings {
318	88			88		184	my ($tree, $tags, $tail, $i) = @_;
319
320	88	100				211	return defined $i ? undef : [] if $tree->[0] eq 'root';
		100
321
322	82					146	my $nodes = _nodes(_parent($tree));
323	82					129	my $match = -1;
324	82		66			649	defined($match++) and $_ eq $tree and last for @$nodes;
			100
325
326	82	100				161	if ($tail) { splice @$nodes, 0, $match + 1 }
	30					61
327	52					125	else { splice @$nodes, $match, ($#$nodes + 1) - $match }
328
329	82	100				205	@$nodes = grep { $_->[0] eq 'tag' } @$nodes if $tags;
	171					350
330
331	82	100	100			368	return defined $i ? $i == -1 && !@$nodes ? undef : $nodes->[$i] : $nodes;
		100
332							}
333
334	1264	100		1264		4422	sub _start { $_[0][0] eq 'root' ? 1 : 4 }
335
336							sub _text {
337	747			747		1433	my ($nodes, $xml, $all) = @_;
338
339	747					1305	my $text = '';
340	747					1925	while (my $node = shift @$nodes) {
341	1076					1756	my $type = $node->[0];
342
343							# Text
344	1076	100	100			3887	if ($type eq 'text' \|\| $type eq 'cdata' \|\| $type eq 'raw') {
		100	100
			100
345	867					2537	$text .= $node->[1];
346							}
347
348							# Nested tag
349							elsif ($type eq 'tag' && $all) {
350	152	100	100			573	unshift @$nodes, @{_nodes($node)} if $xml \|\| ($node->[1] ne 'script' && $node->[1] ne 'style');
	140		100			217
351							}
352							}
353
354	747					3648	return $text;
355							}
356
357							sub _wrap {
358	16			16		43	my ($self, $content, $new) = @_;
359
360	16	100	100			33	return $self if (my $tree = $self->tree)->[0] eq 'root' && !$content;
361	15	100	100			98	return $self if $tree->[0] ne 'root' && $tree->[0] ne 'tag' && $content;
			100
362
363							# Find innermost tag
364	14					22	my $current;
365	14					44	my $first = $new = $self->_parse($new);
366	14					49	$current = $first while $first = _nodes($first, 1)->[0];
367	14	100				48	return $self unless $current;
368
369							# Wrap content
370	12	100				32	if ($content) {
371	5					9	push @$current, @{_link($current, _nodes($tree))};
	5					14
372	5					16	splice @$tree, _start($tree), $#$tree, @{_link($tree, _nodes($new))};
	5					14
373	5					26	return $self;
374							}
375
376							# Wrap element
377	7					29	$self->_replace(_parent($tree), $tree, _nodes($new));
378	7					23	push @$current, @{_link($current, [$tree])};
	7					22
379	7					37	return $self;
380							}
381
382							1;
383
384							=encoding utf8
385
386							=head1 NAME
387
388							Mojo::DOM58 - Minimalistic HTML/XML DOM parser with CSS selectors
389
390							=head1 SYNOPSIS
391
392							use Mojo::DOM58;
393
394							# Parse
395							my $dom = Mojo::DOM58->new(' Test 123 ');
396
397							# Find
398							say $dom->at('#b')->text;
399							say $dom->find('p')->map('text')->join("\n");
400							say $dom->find('[id]')->map(attr => 'id')->join("\n");
401
402							# Iterate
403							$dom->find('p[id]')->reverse->each(sub { say $_->{id} });
404
405							# Loop
406							for my $e ($dom->find('p[id]')->each) {
407							say $e->{id}, ':', $e->text;
408							}
409
410							# Modify
411							$dom->find('div p')->last->append(' 456 ');
412							$dom->at('#c')->prepend($dom->new_tag('p', id => 'd', '789'));
413							$dom->find(':not(p)')->map('strip');
414
415							# Render
416							say "$dom";
417
418							=head1 DESCRIPTION
419
420							L is a minimalistic and relaxed pure-perl HTML/XML DOM parser based
421							on L. It supports the L
422							and L, and
423							matching based on L. It will
424							even try to interpret broken HTML and XML, so you should not use it for
425							validation.
426
427							=head1 FORK INFO
428
429							L is a fork of L and tracks features and fixes to stay
430							closely compatible with upstream. It differs only in the standalone format and
431							compatibility with Perl 5.8. Any bugs or patches not related to these changes
432							should be reported directly to the L issue tracker.
433
434							This release of L is up to date with version C<9.0> of
435							L.
436
437							=head1 NODES AND ELEMENTS
438
439							When we parse an HTML/XML fragment, it gets turned into a tree of nodes.
440
441
442
443							Hello
444							World!
445
446
447							There are currently eight different kinds of nodes, C, C,
448							C, C, C, C, C and C. Elements are nodes of
449							the type C.
450
451							root
452							\|- doctype (html)
453							+- tag (html)
454							\|- tag (head)
455							\| +- tag (title)
456							\| +- raw (Hello)
457							+- tag (body)
458							+- text (World!)
459
460							While all node types are represented as L objects, some methods like
461							L and L only apply to elements.
462
463							=head1 CASE-SENSITIVITY
464
465							L defaults to HTML semantics, that means all tags and attribute
466							names are lowercased and selectors need to be lowercase as well.
467
468							# HTML semantics
469							my $dom = Mojo::DOM58->new(' Hi! ');
470							say $dom->at('p[id]')->text;
471
472							If an XML declaration is found, the parser will automatically switch into XML
473							mode and everything becomes case-sensitive.
474
475							# XML semantics
476							my $dom = Mojo::DOM58->new(' Hi! ');
477							say $dom->at('P[ID]')->text;
478
479							HTML or XML semantics can also be forced with the L method.
480
481							# Force HTML semantics
482							my $dom = Mojo::DOM58->new->xml(0)->parse(' Hi! ');
483							say $dom->at('p[id]')->text;
484
485							# Force XML semantics
486							my $dom = Mojo::DOM58->new->xml(1)->parse(' Hi! ');
487							say $dom->at('P[ID]')->text;
488
489							=head1 SELECTORS
490
491							L uses a CSS selector engine based on L. All CSS
492							selectors that make sense for a standalone parser are supported.
493
494							=over
495
496							=item Z<>*
497
498							Any element.
499
500							my $all = $dom->find('*');
501
502							=item E
503
504							An element of type C.
505
506							my $title = $dom->at('title');
507
508							=item E[foo]
509
510							An C element with a C attribute.
511
512							my $links = $dom->find('a[href]');
513
514							=item E[foo="bar"]
515
516							An C element whose C attribute value is exactly equal to C.
517
518							my $case_sensitive = $dom->find('input[type="hidden"]');
519							my $case_sensitive = $dom->find('input[type=hidden]');
520
521							=item E[foo="bar" i]
522
523							An C element whose C attribute value is exactly equal to any
524							(ASCII-range) case-permutation of C. Note that this selector is
525							B and might change without warning!
526
527							my $case_insensitive = $dom->find('input[type="hidden" i]');
528							my $case_insensitive = $dom->find('input[type=hidden i]');
529							my $case_insensitive = $dom->find('input[class~="foo" i]');
530
531							This selector is part of
532							L, which is still a work
533							in progress.
534
535							=item E[foo="bar" s]
536
537							An C element whose C attribute value is exactly and case-sensitively
538							equal to C. Note that this selector is B and might change
539							without warning!
540
541							my $case_sensitive = $dom->find('input[type="hidden" s]');
542
543							This selector is part of
544							L, which is still a work
545							in progress.
546
547							=item E[foo~="bar"]
548
549							An C element whose C attribute value is a list of whitespace-separated
550							values, one of which is exactly equal to C.
551
552							my $foo = $dom->find('input[class~="foo"]');
553							my $foo = $dom->find('input[class~=foo]');
554
555							=item E[foo^="bar"]
556
557							An C element whose C attribute value begins exactly with the string
558							C.
559
560							my $begins_with = $dom->find('input[name^="f"]');
561							my $begins_with = $dom->find('input[name^=f]');
562
563							=item E[foo$="bar"]
564
565							An C element whose C attribute value ends exactly with the string
566							C.
567
568							my $ends_with = $dom->find('input[name$="o"]');
569							my $ends_with = $dom->find('input[name$=o]');
570
571							=item E[foo*="bar"]
572
573							An C element whose C attribute value contains the substring C.
574
575							my $contains = $dom->find('input[name*="fo"]');
576							my $contains = $dom->find('input[name*=fo]');
577
578							=item E[foo\|="en"]
579
580							An C element whose C attribute has a hyphen-separated list of values
581							beginning (from the left) with C.
582
583							my $english = $dom->find('link[hreflang\|=en]');
584
585							=item E:root
586
587							An C element, root of the document.
588
589							my $root = $dom->at(':root');
590
591							=item E:nth-child(n)
592
593							An C element, the C child of its parent.
594
595							my $third = $dom->find('div:nth-child(3)');
596							my $odd = $dom->find('div:nth-child(odd)');
597							my $even = $dom->find('div:nth-child(even)');
598							my $top3 = $dom->find('div:nth-child(-n+3)');
599
600							=item E:nth-last-child(n)
601
602							An C element, the C child of its parent, counting from the last one.
603
604							my $third = $dom->find('div:nth-last-child(3)');
605							my $odd = $dom->find('div:nth-last-child(odd)');
606							my $even = $dom->find('div:nth-last-child(even)');
607							my $bottom3 = $dom->find('div:nth-last-child(-n+3)');
608
609							=item E:nth-of-type(n)
610
611							An C element, the C sibling of its type.
612
613							my $third = $dom->find('div:nth-of-type(3)');
614							my $odd = $dom->find('div:nth-of-type(odd)');
615							my $even = $dom->find('div:nth-of-type(even)');
616							my $top3 = $dom->find('div:nth-of-type(-n+3)');
617
618							=item E:nth-last-of-type(n)
619
620							An C element, the C sibling of its type, counting from the last one.
621
622							my $third = $dom->find('div:nth-last-of-type(3)');
623							my $odd = $dom->find('div:nth-last-of-type(odd)');
624							my $even = $dom->find('div:nth-last-of-type(even)');
625							my $bottom3 = $dom->find('div:nth-last-of-type(-n+3)');
626
627							=item E:first-child
628
629							An C element, first child of its parent.
630
631							my $first = $dom->find('div p:first-child');
632
633							=item E:last-child
634
635							An C element, last child of its parent.
636
637							my $last = $dom->find('div p:last-child');
638
639							=item E:first-of-type
640
641							An C element, first sibling of its type.
642
643							my $first = $dom->find('div p:first-of-type');
644
645							=item E:last-of-type
646
647							An C element, last sibling of its type.
648
649							my $last = $dom->find('div p:last-of-type');
650
651							=item E:only-child
652
653							An C element, only child of its parent.
654
655							my $lonely = $dom->find('div p:only-child');
656
657							=item E:only-of-type
658
659							An C element, only sibling of its type.
660
661							my $lonely = $dom->find('div p:only-of-type');
662
663							=item E:empty
664
665							An C element that has no children (including text nodes).
666
667							my $empty = $dom->find(':empty');
668
669							=item E:any-link
670
671							Alias for L. Note that this selector is B and might
672							change without warning! This selector is part of
673							L, which is still a
674							work in progress.
675
676							=item E:link
677
678							An C element being the source anchor of a hyperlink of which the target is
679							not yet visited (C<:link>) or already visited (C<:visited>). Note that
680							L is not stateful, therefore C<:any-link>, C<:link> and
681							C<:visited> yield exactly the same results.
682
683							my $links = $dom->find(':any-link');
684							my $links = $dom->find(':link');
685							my $links = $dom->find(':visited');
686
687							=item E:visited
688
689							Alias for L.
690
691							=item E:scope
692
693							An C element being a designated reference element. Note that this selector is B and might change
694							without warning!
695
696							my $scoped = $dom->find('a:not(:scope > a)');
697							my $scoped = $dom->find('div :scope p');
698							my $scoped = $dom->find('~ p');
699
700							This selector is part of L, which is still a work in progress.
701
702							=item E:checked
703
704							A user interface element C which is checked (for instance a radio-button or
705							checkbox).
706
707							my $input = $dom->find(':checked');
708
709							=item E.warning
710
711							An C element whose class is "warning".
712
713							my $warning = $dom->find('div.warning');
714
715							=item E#myid
716
717							An C element with C equal to "myid".
718
719							my $foo = $dom->at('div#foo');
720
721							=item E:not(s1, s2)
722
723							An C element that does not match either compound selector C or compound
724							selector C. Note that support for compound selectors is B and
725							might change without warning!
726
727							my $others = $dom->find('div p:not(:first-child, :last-child)');
728
729							Support for compound selectors was added as part of
730							L, which is still a work
731							in progress.
732
733							=item E:is(s1, s2)
734
735							An C element that matches compound selector C and/or compound selector
736							C. Note that this selector is B and might change without warning!
737
738							my $headers = $dom->find(':is(section, article, aside, nav) h1');
739
740							This selector is part of
741							L, which is still a work
742							in progress.
743
744							=item E:has(rs1, rs2)
745
746							An C element, if either of the relative selectors C or C, when evaluated with C as the :scope elements,
747							match an element. Note that this selector is B and might change without warning!
748
749							my $link = $dom->find('a:has(> img)');
750
751							This selector is part of L, which is still a work in progress.
752							Also be aware that this feature is currently marked C, so there is a high chance that it will get removed
753							completely.
754
755							=item A\|E
756
757							An C element that belongs to the namespace alias C from
758							L.
759							Key/value pairs passed to selector methods are used to declare namespace
760							aliases.
761
762							my $elem = $dom->find('lq\|elem', lq => 'http://example.com/q-markup');
763
764							Using an empty alias searches for an element that belongs to no namespace.
765
766							my $div = $dom->find('\|div');
767
768							=item E F
769
770							An C element descendant of an C element.
771
772							my $headlines = $dom->find('div h1');
773
774							=item E E F
775
776							An C element child of an C element.
777
778							my $headlines = $dom->find('html > body > div > h1');
779
780							=item E + F
781
782							An C element immediately preceded by an C element.
783
784							my $second = $dom->find('h1 + h2');
785
786							=item E ~ F
787
788							An C element preceded by an C element.
789
790							my $second = $dom->find('h1 ~ h2');
791
792							=item E, F, G
793
794							Elements of type C, C and C.
795
796							my $headlines = $dom->find('h1, h2, h3');
797
798							=item E[foo=bar][bar=baz]
799
800							An C element whose attributes match all following attribute selectors.
801
802							my $links = $dom->find('a[foo^=b][foo$=ar]');
803
804							=back
805
806							=head1 OPERATORS
807
808							L overloads the following operators.
809
810							=head2 array
811
812							my @nodes = @$dom;
813
814							Alias for L.
815
816							# ""
817							$dom->parse('123')->[0];
818
819							=head2 bool
820
821							my $bool = !!$dom;
822
823							Always true.
824
825							=head2 hash
826
827							my %attrs = %$dom;
828
829							Alias for L.
830
831							# "test"
832							$dom->parse(' Test ')->at('div')->{id};
833
834							=head2 stringify
835
836							my $str = "$dom";
837
838							Alias for L.
839
840							=head1 FUNCTIONS
841
842							L implements the following functions, which can be imported
843							individually.
844
845							=head2 tag_to_html
846
847							my $str = tag_to_html 'div', id => 'foo', 'safe content';
848
849							Generate HTML/XML tag and render it right away. This is a significantly faster
850							alternative to L for template systems that have to generate a lot
851							of tags.
852
853							=head1 METHODS
854
855							L implements the following methods.
856
857							=head2 new
858
859							my $dom = Mojo::DOM58->new;
860							my $dom = Mojo::DOM58->new('I ♥ Mojo::DOM58!');
861
862							Construct a new scalar-based L object and L HTML/XML
863							fragment if necessary.
864
865							=head2 new_tag
866
867							my $tag = Mojo::DOM58->new_tag('div');
868							my $tag = $dom->new_tag('div');
869							my $tag = $dom->new_tag('div', id => 'foo', hidden => undef);
870							my $tag = $dom->new_tag('div', 'safe content');
871							my $tag = $dom->new_tag('div', id => 'foo', 'safe content');
872							my $tag = $dom->new_tag('div', data => {mojo => 'rocks'}, 'safe content');
873							my $tag = $dom->new_tag('div', id => 'foo', sub { 'unsafe content' });
874
875							Construct a new L object for an HTML/XML tag with or without
876							attributes and content. The C attribute may contain a hash reference with
877							key/value pairs to generate attributes from.
878
879							# " "
880							$dom->new_tag('br');
881
882							# " "
883							$dom->new_tag('div');
884
885							# ""
886							$dom->new_tag('div', id => 'foo', hidden => undef);
887
888							# " test & 123 "
889							$dom->new_tag('div', 'test & 123');
890
891							# " test & 123 "
892							$dom->new_tag('div', id => 'foo', 'test & 123');
893
894							# " test & 123 ""
895							$dom->new_tag('div', data => {foo => 1, Bar => 'test'}, 'test & 123');
896
897							# " test & 123 "
898							$dom->new_tag('div', id => 'foo', sub { 'test & 123' });
899
900							# " HelloMojo! "
901							$dom->parse(' Hello ')->at('div')
902							->append_content($dom->new_tag('b', 'Mojo!'))->root;
903
904							=head2 all_text
905
906							my $text = $dom->all_text;
907
908							Extract text content from all descendant nodes of this element. For HTML documents C