Mojo::DOM - Minimalistic HTML/XML DOM parser with CSS selectors
use Mojo::DOM; # Parse my $dom = Mojo::DOM->new('<div><p id="a">Test</p><p id="b">123</p></div>'); # Find say $dom->at('#b')->text; say $dom->find('p')->map('text')->join("\n"); say $dom->find('[id]')->map(attr => 'id')->join("\n"); # Iterate $dom->find('p[id]')->reverse->each(sub { say $_->{id} }); # Loop for my $e ($dom->find('p[id]')->each) { say $e->{id}, ':', $e->text; } # Modify $dom->find('div p')->last->append('<p id="c">456</p>'); $dom->at('#c')->prepend($dom->new_tag('p', id => 'd', '789')); $dom->find(':not(p)')->map('strip'); # Render say "$dom";
Mojo::DOM is a minimalistic and relaxed HTML/XML DOM parser with CSS selector support. It will even try to interpret broken HTML and XML, so you should not use it for validation.
When we parse an HTML/XML fragment, it gets turned into a tree of nodes.
<!DOCTYPE html> <html> <head><title>Hello</title></head> <body>World!</body> </html>
There are currently eight different kinds of nodes, cdata, comment, doctype, pi, raw, root, tag and text. Elements are nodes of the type tag.
cdata
comment
doctype
pi
raw
root
tag
text
root |- doctype (html) +- tag (html) |- tag (head) | +- tag (title) | +- raw (Hello) +- tag (body) +- text (World!)
While all node types are represented as Mojo::DOM objects, some methods like "attr" and "namespace" only apply to elements.
Mojo::DOM defaults to HTML semantics, that means all tags and attribute names are lowercased and selectors need to be lowercase as well.
# HTML semantics my $dom = Mojo::DOM->new('<P ID="greeting">Hi!</P>'); say $dom->at('p[id]')->text;
If an XML declaration is found, the parser will automatically switch into XML mode and everything becomes case-sensitive.
# XML semantics my $dom = Mojo::DOM->new('<?xml version="1.0"?><P ID="greeting">Hi!</P>'); say $dom->at('P[ID]')->text;
HTML or XML semantics can also be forced with the "xml" method.
# Force HTML semantics my $dom = Mojo::DOM->new->xml(0)->parse('<P ID="greeting">Hi!</P>'); say $dom->at('p[id]')->text; # Force XML semantics my $dom = Mojo::DOM->new->xml(1)->parse('<P ID="greeting">Hi!</P>'); say $dom->at('P[ID]')->text;
Mojo::DOM implements the following methods.
my $text = $dom->all_text;
Extract text content from all descendant nodes of this element.
# "foo\nbarbaz\n" $dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->at('div')->all_text;
my $collection = $dom->ancestors; my $collection = $dom->ancestors('div ~ p');
Find all ancestor elements of this node matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# List tag names of ancestor elements say $dom->ancestors->map('tag')->join("\n");
$dom = $dom->append('<p>I ♥ Mojolicious!</p>'); $dom = $dom->append(Mojo::DOM->new);
Append HTML/XML fragment to this node (for all node types other than root).
# "<div><h1>Test</h1><h2>123</h2></div>" $dom->parse('<div><h1>Test</h1></div>') ->at('h1')->append('<h2>123</h2>')->root; # "<p>Test 123</p>" $dom->parse('<p>Test</p>')->at('p') ->child_nodes->first->append(' 123')->root;
$dom = $dom->append_content('<p>I ♥ Mojolicious!</p>'); $dom = $dom->append_content(Mojo::DOM->new);
Append HTML/XML fragment (for root and tag nodes) or raw content to this node's content.
# "<div><h1>Test123</h1></div>" $dom->parse('<div><h1>Test</h1></div>') ->at('h1')->append_content('123')->root; # "<!-- Test 123 --><br>" $dom->parse('<!-- Test --><br>') ->child_nodes->first->append_content('123 ')->root; # "<p>Test<i>123</i></p>" $dom->parse('<p>Test</p>')->at('p')->append_content('<i>123</i>')->root;
my $result = $dom->at('div ~ p'); my $result = $dom->at('svg|line', svg => 'http://www.w3.org/2000/svg');
Find first descendant element of this element matching the CSS selector and return it as a Mojo::DOM object, or undef if none could be found. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
undef
# Find first element with "svg" namespace definition my $namespace = $dom->at('[xmlns\:svg]')->{'xmlns:svg'};
Trailing key/value pairs can be used to declare xml namespace aliases.
# "<rect />" $dom->parse('<svg xmlns="http://www.w3.org/2000/svg"><rect /></svg>') ->at('svg|rect', svg => 'http://www.w3.org/2000/svg');
my $hash = $dom->attr; my $foo = $dom->attr('foo'); $dom = $dom->attr({foo => 'bar'}); $dom = $dom->attr(foo => 'bar');
This element's attributes.
# Remove an attribute delete $dom->attr->{id}; # Attribute without value $dom->attr(selected => undef); # List id attributes say $dom->find('*')->map(attr => 'id')->compact->join("\n");
my $collection = $dom->child_nodes;
Return a Mojo::Collection object containing all child nodes of this element as Mojo::DOM objects.
# "<p><b>123</b></p>" $dom->parse('<p>Test<b>123</b></p>')->at('p')->child_nodes->first->remove; # "<!DOCTYPE html>" $dom->parse('<!DOCTYPE html><b>123</b>')->child_nodes->first; # " Test " $dom->parse('<b>123</b><!-- Test -->')->child_nodes->last->content;
my $collection = $dom->children; my $collection = $dom->children('div ~ p');
Find all child elements of this element matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# Show tag name of random child element say $dom->children->shuffle->first->tag;
my $str = $dom->content; $dom = $dom->content('<p>I ♥ Mojolicious!</p>'); $dom = $dom->content(Mojo::DOM->new);
Return this node's content or replace it with HTML/XML fragment (for root and tag nodes) or raw content.
# "<b>Test</b>" $dom->parse('<div><b>Test</b></div>')->at('div')->content; # "<div><h1>123</h1></div>" $dom->parse('<div><h1>Test</h1></div>')->at('h1')->content('123')->root; # "<p><i>123</i></p>" $dom->parse('<p>Test</p>')->at('p')->content('<i>123</i>')->root; # "<div><h1></h1></div>" $dom->parse('<div><h1>Test</h1></div>')->at('h1')->content('')->root; # " Test " $dom->parse('<!-- Test --><br>')->child_nodes->first->content; # "<div><!-- 123 -->456</div>" $dom->parse('<div><!-- Test -->456</div>') ->at('div')->child_nodes->first->content(' 123 ')->root;
my $collection = $dom->descendant_nodes;
Return a Mojo::Collection object containing all descendant nodes of this element as Mojo::DOM objects.
# "<p><b>123</b></p>" $dom->parse('<p><!-- Test --><b>123<!-- 456 --></b></p>') ->descendant_nodes->grep(sub { $_->type eq 'comment' }) ->map('remove')->first; # "<p><b>test</b>test</p>" $dom->parse('<p><b>123</b>456</p>') ->at('p')->descendant_nodes->grep(sub { $_->type eq 'text' }) ->map(content => 'test')->first->root;
my $collection = $dom->find('div ~ p'); my $collection = $dom->find('svg|line', svg => 'http://www.w3.org/2000/svg');
Find all descendant elements of this element matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# Find a specific element and extract information my $id = $dom->find('div')->[23]{id}; # Extract information from multiple elements my @headers = $dom->find('h1, h2, h3')->map('text')->each; # Count all the different tags my $hash = $dom->find('*')->reduce(sub { $a->{$b->tag}++; $a }, {}); # Find elements with a class that contains dots my @divs = $dom->find('div.foo\.bar')->each;
# "<rect />" $dom->parse('<svg xmlns="http://www.w3.org/2000/svg"><rect /></svg>') ->find('svg|rect', svg => 'http://www.w3.org/2000/svg')->first;
my $collection = $dom->following; my $collection = $dom->following('div ~ p');
Find all sibling elements after this node matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# List tags of sibling elements after this node say $dom->following->map('tag')->join("\n");
my $collection = $dom->following_nodes;
Return a Mojo::Collection object containing all sibling nodes after this node as Mojo::DOM objects.
# "C" $dom->parse('<p>A</p><!-- B -->C')->at('p')->following_nodes->last->content;
my $bool = $dom->matches('div ~ p'); my $bool = $dom->matches('svg|line', svg => 'http://www.w3.org/2000/svg');
Check if this element matches the CSS selector. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# True $dom->parse('<p class="a">A</p>')->at('p')->matches('.a'); $dom->parse('<p class="a">A</p>')->at('p')->matches('p[class]'); # False $dom->parse('<p class="a">A</p>')->at('p')->matches('.b'); $dom->parse('<p class="a">A</p>')->at('p')->matches('p[id]');
# True $dom->parse('<svg xmlns="http://www.w3.org/2000/svg"><rect /></svg>') ->matches('svg|rect', svg => 'http://www.w3.org/2000/svg');
my $namespace = $dom->namespace;
Find this element's namespace, or return undef if none could be found.
# Find namespace for an element with namespace prefix my $namespace = $dom->at('svg > svg\:circle')->namespace; # Find namespace for an element that may or may not have a namespace prefix my $namespace = $dom->at('svg > circle')->namespace;
my $dom = Mojo::DOM->new; my $dom = Mojo::DOM->new('<foo bar="baz">I ♥ Mojolicious!</foo>');
Construct a new scalar-based Mojo::DOM object and "parse" HTML/XML fragment if necessary.
my $tag = Mojo::DOM->new_tag('div'); my $tag = $dom->new_tag('div'); my $tag = $dom->new_tag('div', id => 'foo', hidden => undef); my $tag = $dom->new_tag('div', 'safe content'); my $tag = $dom->new_tag('div', id => 'foo', 'safe content'); my $tag = $dom->new_tag('div', data => {mojo => 'rocks'}, 'safe content'); my $tag = $dom->new_tag('div', id => 'foo', sub { 'unsafe content' });
Construct a new Mojo::DOM object for an HTML/XML tag with or without attributes and content. The data attribute may contain a hash reference with key/value pairs to generate attributes from.
data
# "<br>" $dom->new_tag('br'); # "<div></div>" $dom->new_tag('div'); # "<div id="foo" hidden></div>" $dom->new_tag('div', id => 'foo', hidden => undef); # "<div>test & 123</div>" $dom->new_tag('div', 'test & 123'); # "<div id="foo">test & 123</div>" $dom->new_tag('div', id => 'foo', 'test & 123'); # "<div data-foo="1" data-bar="test">test & 123</div>"" $dom->new_tag('div', data => {foo => 1, Bar => 'test'}, 'test & 123'); # "<div id="foo">test & 123</div>" $dom->new_tag('div', id => 'foo', sub { 'test & 123' }); # "<div>Hello<b>Mojo!</b></div>" $dom->parse('<div>Hello</div>')->at('div') ->append_content($dom->new_tag('b', 'Mojo!'))->root;
my $sibling = $dom->next;
Return Mojo::DOM object for next sibling element, or undef if there are no more siblings.
# "<h2>123</h2>" $dom->parse('<div><h1>Test</h1><h2>123</h2></div>')->at('h1')->next;
my $sibling = $dom->next_node;
Return Mojo::DOM object for next sibling node, or undef if there are no more siblings.
# "456" $dom->parse('<p><b>123</b><!-- Test -->456</p>') ->at('b')->next_node->next_node; # " Test " $dom->parse('<p><b>123</b><!-- Test -->456</p>') ->at('b')->next_node->content;
my $parent = $dom->parent;
Return Mojo::DOM object for parent of this node, or undef if this node has no parent.
# "<b><i>Test</i></b>" $dom->parse('<p><b><i>Test</i></b></p>')->at('i')->parent;
$dom = $dom->parse('<foo bar="baz">I ♥ Mojolicious!</foo>');
Parse HTML/XML fragment with Mojo::DOM::HTML.
# Parse XML my $dom = Mojo::DOM->new->xml(1)->parse('<foo>I ♥ Mojolicious!</foo>');
my $collection = $dom->preceding; my $collection = $dom->preceding('div ~ p');
Find all sibling elements before this node matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
# List tags of sibling elements before this node say $dom->preceding->map('tag')->join("\n");
my $collection = $dom->preceding_nodes;
Return a Mojo::Collection object containing all sibling nodes before this node as Mojo::DOM objects.
# "A" $dom->parse('A<!-- B --><p>C</p>')->at('p')->preceding_nodes->first->content;
$dom = $dom->prepend('<p>I ♥ Mojolicious!</p>'); $dom = $dom->prepend(Mojo::DOM->new);
Prepend HTML/XML fragment to this node (for all node types other than root).
# "<div><h1>Test</h1><h2>123</h2></div>" $dom->parse('<div><h2>123</h2></div>') ->at('h2')->prepend('<h1>Test</h1>')->root; # "<p>Test 123</p>" $dom->parse('<p>123</p>') ->at('p')->child_nodes->first->prepend('Test ')->root;
$dom = $dom->prepend_content('<p>I ♥ Mojolicious!</p>'); $dom = $dom->prepend_content(Mojo::DOM->new);
Prepend HTML/XML fragment (for root and tag nodes) or raw content to this node's content.
# "<div><h2>Test123</h2></div>" $dom->parse('<div><h2>123</h2></div>') ->at('h2')->prepend_content('Test')->root; # "<!-- Test 123 --><br>" $dom->parse('<!-- 123 --><br>') ->child_nodes->first->prepend_content(' Test')->root; # "<p><i>123</i>Test</p>" $dom->parse('<p>Test</p>')->at('p')->prepend_content('<i>123</i>')->root;
my $sibling = $dom->previous;
Return Mojo::DOM object for previous sibling element, or undef if there are no more siblings.
# "<h1>Test</h1>" $dom->parse('<div><h1>Test</h1><h2>123</h2></div>')->at('h2')->previous;
my $sibling = $dom->previous_node;
Return Mojo::DOM object for previous sibling node, or undef if there are no more siblings.
# "123" $dom->parse('<p>123<!-- Test --><b>456</b></p>') ->at('b')->previous_node->previous_node; # " Test " $dom->parse('<p>123<!-- Test --><b>456</b></p>') ->at('b')->previous_node->content;
my $parent = $dom->remove;
Remove this node and return "root" (for root nodes) or "parent".
# "<div></div>" $dom->parse('<div><h1>Test</h1></div>')->at('h1')->remove; # "<p><b>456</b></p>" $dom->parse('<p>123<b>456</b></p>') ->at('p')->child_nodes->first->remove->root;
my $parent = $dom->replace('<div>I ♥ Mojolicious!</div>'); my $parent = $dom->replace(Mojo::DOM->new);
Replace this node with HTML/XML fragment and return "root" (for root nodes) or "parent".
# "<div><h2>123</h2></div>" $dom->parse('<div><h1>Test</h1></div>')->at('h1')->replace('<h2>123</h2>'); # "<p><b>123</b></p>" $dom->parse('<p>Test</p>') ->at('p')->child_nodes->[0]->replace('<b>123</b>')->root;
my $root = $dom->root;
Return Mojo::DOM object for root node.
my $selector = $dom->selector;
Get a unique CSS selector for this element.
# "ul:nth-child(1) > li:nth-child(2)" $dom->parse('<ul><li>Test</li><li>123</li></ul>')->find('li')->last->selector; # "p:nth-child(1) > b:nth-child(1) > i:nth-child(1)" $dom->parse('<p><b><i>Test</i></b></p>')->at('i')->selector;
my $parent = $dom->strip;
Remove this element while preserving its content and return "parent".
# "<div>Test</div>" $dom->parse('<div><h1>Test</h1></div>')->at('h1')->strip;
my $tag = $dom->tag; $dom = $dom->tag('div');
This element's tag name.
# List tag names of child elements say $dom->children->map('tag')->join("\n");
$dom = $dom->tap(sub {...});
Alias for "tap" in Mojo::Base.
my $text = $dom->text;
Extract text content from this element only (not including child elements).
# "bar" $dom->parse("<div>foo<p>bar</p>baz</div>")->at('p')->text; # "foo\nbaz\n" $dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->at('div')->text;
my $str = $dom->to_string;
Render this node and its content to HTML/XML.
# "<b>Test</b>" $dom->parse('<div><b>Test</b></div>')->at('div b')->to_string;
my $tree = $dom->tree; $dom = $dom->tree(['root']);
Document Object Model. Note that this structure should only be used very carefully since it is very dynamic.
my $type = $dom->type;
This node's type, usually cdata, comment, doctype, pi, raw, root, tag or text.
# "cdata" $dom->parse('<![CDATA[Test]]>')->child_nodes->first->type; # "comment" $dom->parse('<!-- Test -->')->child_nodes->first->type; # "doctype" $dom->parse('<!DOCTYPE html>')->child_nodes->first->type; # "pi" $dom->parse('<?xml version="1.0"?>')->child_nodes->first->type; # "raw" $dom->parse('<title>Test</title>')->at('title')->child_nodes->first->type; # "root" $dom->parse('<p>Test</p>')->type; # "tag" $dom->parse('<p>Test</p>')->at('p')->type; # "text" $dom->parse('<p>Test</p>')->at('p')->child_nodes->first->type;
my $value = $dom->val;
Extract value from form element (such as button, input, option, select and textarea), or return undef if this element has no value. In the case of select with multiple attribute, find option elements with selected attribute and return an array reference with all values, or undef if none could be found.
button
input
option
select
textarea
multiple
selected
# "a" $dom->parse('<input name=test value=a>')->at('input')->val; # "b" $dom->parse('<textarea>b</textarea>')->at('textarea')->val; # "c" $dom->parse('<option value="c">Test</option>')->at('option')->val; # "d" $dom->parse('<select><option selected>d</option></select>') ->at('select')->val; # "e" $dom->parse('<select multiple><option selected>e</option></select>') ->at('select')->val->[0]; # "on" $dom->parse('<input name=test type=checkbox>')->at('input')->val;
my $new_class = Mojo::DOM->with_roles('Mojo::DOM::Role::One'); my $new_class = Mojo::DOM->with_roles('+One', '+Two'); $dom = $dom->with_roles('+One', '+Two');
Alias for "with_roles" in Mojo::Base.
$dom = $dom->wrap('<div></div>'); $dom = $dom->wrap(Mojo::DOM->new);
Wrap HTML/XML fragment around this node (for all node types other than root), placing it as the last child of the first innermost element.
# "<p>123<b>Test</b></p>" $dom->parse('<b>Test</b>')->at('b')->wrap('<p>123</p>')->root; # "<div><p><b>Test</b></p>123</div>" $dom->parse('<b>Test</b>')->at('b')->wrap('<div><p></p>123</div>')->root; # "<p><b>Test</b></p><p>123</p>" $dom->parse('<b>Test</b>')->at('b')->wrap('<p></p><p>123</p>')->root; # "<p><b>Test</b></p>" $dom->parse('<p>Test</p>')->at('p')->child_nodes->first->wrap('<b>')->root;
$dom = $dom->wrap_content('<div></div>'); $dom = $dom->wrap_content(Mojo::DOM->new);
Wrap HTML/XML fragment around this node's content (for root and tag nodes), placing it as the last children of the first innermost element.
# "<p><b>123Test</b></p>" $dom->parse('<p>Test<p>')->at('p')->wrap_content('<b>123</b>')->root; # "<p><b>Test</b></p><p>123</p>" $dom->parse('<b>Test</b>')->wrap_content('<p></p><p>123</p>');
my $bool = $dom->xml; $dom = $dom->xml($bool);
Disable HTML semantics in parser and activate case-sensitivity, defaults to auto-detection based on XML declarations.
Mojo::DOM overloads the following operators.
my @nodes = @$dom;
Alias for "child_nodes".
# "<!-- Test -->" $dom->parse('<!-- Test --><b>123</b>')->[0];
my $bool = !!$dom;
Always true.
my %attrs = %$dom;
Alias for "attr".
# "test" $dom->parse('<div id="test">Test</div>')->at('div')->{id};
my $str = "$dom";
Alias for "to_string".
Mojolicious, Mojolicious::Guides, https://mojolicious.org.
To install Mojolicious, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious
CPAN shell
perl -MCPAN -e shell install Mojolicious
For more information on module installation, please visit the detailed CPAN module installation guide.