NAME
Mojo::DOM - Minimalistic HTML/XML DOM parser with CSS selectors
SYNOPSIS
use Mojo::DOM;
# Parse
my $dom = Mojo::DOM->new('<div><p id="a">A</p><p id="b">B</p></div>');
# Find
say $dom->at('#b')->text;
say $dom->find('p')->pluck('text');
# Walk
say $dom->div->p->[0]->text;
say $dom->div->children('p')->first->{id};
# Iterate
$dom->find('p[id]')->each(sub { say shift->{id} });
# Loop
for my $e ($dom->find('p[id]')->each) {
say $e->text;
}
# Modify
$dom->div->p->[1]->append('<p id="c">C</p>');
$dom->find(':not(p)')->pluck('strip');
# Render
say "$dom";DESCRIPTION
Mojo::DOM is a minimalistic and relaxed HTML/XML DOM parser with CSS selector support. It will even try to interpret broken XML, so you should not use it for validation.
CASE SENSITIVITY
Mojo::DOM defaults to HTML semantics, that means all tags and attributes are lowercased and selectors need to be lowercase as well.
my $dom = Mojo::DOM->new('<P ID="greeting">Hi!</P>');
say $dom->at('p')->text;
say $dom->p->{id};If XML processing instructions are found, the parser will automatically switch into XML mode and everything becomes case sensitive.
my $dom = Mojo::DOM->new('<?xml version="1.0"?><P ID="greeting">Hi!</P>');
say $dom->at('P')->text;
say $dom->P->{ID};XML detection can also be disabled with the xml method.
# Force XML semantics
$dom->xml(1);
# Force HTML semantics
$dom->xml(0);METHODS
Mojo::DOM inherits all methods from Mojo::Base and implements the following new ones.
new
my $dom = Mojo::DOM->new;
my $dom = Mojo::DOM->new('<foo bar="baz">test</foo>');Construct a new array-based Mojo::DOM object and parse HTML/XML document if necessary.
all_text
my $trimmed = $dom->all_text;
my $untrimmed = $dom->all_text(0);Extract all text content from DOM structure, smart whitespace trimming is enabled by default.
# "foo bar baz"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->all_text;
# "foo\nbarbaz\n"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->all_text(0);append
$dom = $dom->append('<p>Hi!</p>');Append HTML/XML to element.
# "<div><h1>A</h1><h2>B</h2></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->append('<h2>B</h2>')->root;append_content
$dom = $dom->append_content('<p>Hi!</p>');Append HTML/XML to element content.
# "<div><h1>AB</h1></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->append_content('B')->root;at
my $result = $dom->at('html title');Find first element matching the CSS selector and return it as a Mojo::DOM object or return undef if none could be found. All selectors from Mojo::DOM::CSS are supported.
# Find first element with "svg" namespace definition
my $namespace = $dom->at('[xmlns\:svg]')->{'xmlns:svg'};attr
my $attrs = $dom->attr;
my $foo = $dom->attr('foo');
$dom = $dom->attr({foo => 'bar'});
$dom = $dom->attr(foo => 'bar');Element attributes.
children
my $collection = $dom->children;
my $collection = $dom->children('div');Return a Mojo::Collection object containing the children of this element as Mojo::DOM objects, similar to find.
# Show type of random child element
say $dom->children->shuffle->first->type;content_xml
my $xml = $dom->content_xml;Render content of this element to XML.
# "<b>test</b>"
$dom->parse('<div><b>test</b></div>')->div->content_xml;find
my $collection = $dom->find('html title');Find all elements matching the CSS selector and return a Mojo::Collection object containing these elements as Mojo::DOM objects. All selectors from 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')->pluck('text')->each;
my @links = $dom->find('a[href]')->pluck(attr => 'href')->each;namespace
my $namespace = $dom->namespace;Find element namespace.
# 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;next
my $sibling = $dom->next;Return Mojo::DOM object for next sibling of element or undef if there are no more siblings.
# "<h2>B</h2>"
$dom->parse('<div><h1>A</h1><h2>B</h2></div>')->at('h1')->next;parent
my $parent = $dom->parent;Return Mojo::DOM object for parent of element or undef if this element has no parent.
parse
$dom = $dom->parse('<foo bar="baz">test</foo>');Parse HTML/XML document with Mojo::DOM::HTML.
# Parse XML
my $dom = Mojo::DOM->new->xml(1)->parse($xml);prepend
$dom = $dom->prepend('<p>Hi!</p>');Prepend HTML/XML to element.
# "<div><h1>A</h1><h2>B</h2></div>"
$dom->parse('<div><h2>B</h2></div>')->at('h2')->prepend('<h1>A</h1>')->root;prepend_content
$dom = $dom->prepend_content('<p>Hi!</p>');Prepend HTML/XML to element content.
# "<div><h2>AB</h2></div>"
$dom->parse('<div><h2>B</h2></div>')->at('h2')->prepend_content('A')->root;previous
my $sibling = $dom->previous;Return Mojo::DOM object for previous sibling of element or undef if there are no more siblings.
# "<h1>A</h1>"
$dom->parse('<div><h1>A</h1><h2>B</h2></div>')->at('h2')->previous;remove
my $parent = $dom->remove;Remove element and return Mojo::DOM object for parent of element.
# "<div></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->remove;replace
my $parent = $dom->replace('<div>test</div>');Replace element with HTML/XML and return Mojo::DOM object for parent of element.
# "<div><h2>B</h2></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->replace('<h2>B</h2>');
# "<div></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->replace('')->root;replace_content
$dom = $dom->replace_content('<p>test</p>');Replace element content with HTML/XML.
# "<div><h1>B</h1></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->replace_content('B')->root;
# "<div><h1></h1></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->replace_content('')->root;root
my $root = $dom->root;Return Mojo::DOM object for root node.
strip
my $parent = $dom->strip;Remove element while preserving its content and return Mojo::DOM object for parent of element.
# "<div>A</div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->strip;text
my $trimmed = $dom->text;
my $untrimmed = $dom->text(0);Extract text content from element only (not including child elements), smart whitespace trimming is enabled by default.
# "foo baz"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->text;
# "foo\nbaz\n"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->text(0);text_after
my $trimmed = $dom->text_after;
my $untrimmed = $dom->text_after(0);Extract text content immediately following element, smart whitespace trimming is enabled by default.
# "baz"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->p->text_after;
# "baz\n"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->p->text_after(0);text_before
my $trimmed = $dom->text_before;
my $untrimmed = $dom->text_before(0);Extract text content immediately preceding element, smart whitespace trimming is enabled by default.
# "foo"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->p->text_before;
# "foo\n"
$dom->parse("<div>foo\n<p>bar</p>baz\n</div>")->div->p->text_before(0);to_xml
my $xml = $dom->to_xml;
my $xml = "$dom";Render this element and its content to XML.
# "<b>test</b>"
$dom->parse('<div><b>test</b></div>')->div->b->to_xml;tree
my $tree = $dom->tree;
$dom = $dom->tree(['root', ['text', 'foo']]);Document Object Model. Note that this structure should only be used very carefully since it is very dynamic.
type
my $type = $dom->type;
$dom = $dom->type('div');Element type.
# List types of child elements
say $dom->children->pluck('type');xml
my $xml = $dom->xml;
$dom = $dom->xml(1);Disable HTML semantics in parser and activate case sensitivity, defaults to auto detection based on processing instructions.
CHILD ELEMENTS
In addition to the methods above, many child elements are also automatically available as object methods, which return a Mojo::DOM or Mojo::Collection object, depending on number of children.
say $dom->p->text;
say $dom->div->[23]->text;
say $dom->div->pluck('text');ELEMENT ATTRIBUTES
Direct hash reference access to element attributes is also possible.
say $dom->{foo};
say $dom->div->{id};