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')->text;
say $dom->find('[id]')->attr('id');
# 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)')->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 implements the following methods.
all_contents
my $collection = $dom->all_contents;Return a Mojo::Collection object containing all nodes in DOM structure as Mojo::DOM and Mojo::DOM::Node objects.
"<p><b>123</b></p>"
$dom->parse('<p><!-- test --><b>123<!-- 456 --></b></p>')
->all_contents->grep(sub { $_->node eq 'comment' })->remove->first;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);ancestors
my $collection = $dom->ancestors;
my $collection = $dom->ancestors('div > p');Find all ancestors 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.
# List types of ancestor elements
say $dom->ancestors->type;append
$dom = $dom->append('<p>I ♥ Mojolicious!</p>');Append HTML/XML fragment to this 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>I ♥ Mojolicious!</p>');Append HTML/XML fragment to this element's 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 in DOM structure matching the CSS selector and return it as a Mojo::DOM object or return undef if none could be found. All selectors from "SELECTORS" in 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');This element's attributes.
# List id attributes
say $dom->find('*')->attr('id')->compact;children
my $collection = $dom->children;
my $collection = $dom->children('div > p');Find all children 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 type of random child element
say $dom->children->shuffle->first->type;content
my $str = $dom->content;
$dom = $dom->content('<p>I ♥ Mojolicious!</p>');Render this element's content to HTML/XML or replace it with HTML/XML fragment.
# "<b>test</b>"
$dom->parse('<div><b>test</b></div>')->div->content;
# "<div><h1>B</h1></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->content('B')->root;
# "<div><h1></h1></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->content('')->root;contents
my $collection = $dom->contents;Return a Mojo::Collection object containing the child nodes of this element as Mojo::DOM and Mojo::DOM::Node objects.
"<p><b>123</b></p>"
$dom->parse('<p>test<b>123</b></p>')->at('p')->contents->first->remove;find
my $collection = $dom->find('html title');Find all elements in DOM structure 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')->text->each;
my @links = $dom->find('a[href]')->attr('href')->each;match
my $result = $dom->match('html title');Match the CSS selector against this element and return it as a Mojo::DOM object or return undef if it didn't match. All selectors from "SELECTORS" in Mojo::DOM::CSS are supported.
namespace
my $namespace = $dom->namespace;Find this element's 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;new
my $dom = Mojo::DOM->new;
my $dom = Mojo::DOM->new('<foo bar="baz">I ♥ Mojolicious!</foo>');Construct a new array-based Mojo::DOM object and "parse" HTML/XML fragment if necessary.
next
my $sibling = $dom->next;Return Mojo::DOM object for next sibling of this 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;node
my $type = $dom->node;This element's node type, usually root or tag.
parent
my $parent = $dom->parent;Return Mojo::DOM object for parent of this element or undef if this element has no parent.
parse
$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($xml);prepend
$dom = $dom->prepend('<p>I ♥ Mojolicious!</p>');Prepend HTML/XML fragment to this 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>I ♥ Mojolicious!</p>');Prepend HTML/XML fragment to this element's 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 this 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 this element and return "parent".
# "<div></div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->remove;replace
my $parent = $dom->replace('<div>I ♥ Mojolicious!</div>');Replace this element with HTML/XML fragment and return "parent".
# "<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
my $root = $dom->root;Return Mojo::DOM object for root node.
siblings
my $collection = $dom->siblings;
my $collection = $dom->siblings('div > p');Find all siblings 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.
# List types of sibling elements
say $dom->siblings->type;strip
my $parent = $dom->strip;Remove this element while preserving its content and return "parent".
# "<div>A</div>"
$dom->parse('<div><h1>A</h1></div>')->at('h1')->strip;tap
$dom = $dom->tap(sub {...});Alias for "tap" in Mojo::Base.
text
my $trimmed = $dom->text;
my $untrimmed = $dom->text(0);Extract text content from this 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);to_string
my $str = $dom->to_string;Render this element and its content to HTML/XML.
# "<b>test</b>"
$dom->parse('<div><b>test</b></div>')->div->b->to_string;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');This element's type.
# List types of child elements
say $dom->children->type;wrap
$dom = $dom->wrap('<div></div>');Wrap HTML/XML fragment around this element, placing it as the last child of the first innermost element.
# "<p>B<b>A</b></p>"
$dom->parse('<b>A</b>')->at('b')->wrap('<p>B</p>')->root;
# "<div><p><b>A</b></p>B</div>"
$dom->parse('<b>A</b>')->at('b')->wrap('<div><p></p>B</div>')->root;
# "<p><b>A</b></p><p>B</p>"
$dom->parse('<b>A</b>')->at('b')->wrap('<p></p><p>B</p>')->root;wrap_content
$dom = $dom->wrap_content('<div></div>');Wrap HTML/XML fragment around this element's content, placing it as the last children of the first innermost element.
# "<p><b>BA</b></p>"
$dom->parse('<p>A<p>')->at('p')->wrap_content('<b>B</b>')->root;
# "<p><b>A</b></p><p>B</p>"
$dom->parse('<b>A</b>')->wrap_content('<p></p><p>B</p>');xml
my $bool = $dom->xml;
$dom = $dom->xml($bool);Disable HTML semantics in parser and activate case sensitivity, defaults to auto detection based on processing instructions.
AUTOLOAD
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->text;OPERATORS
Mojo::DOM overloads the following operators.
bool
my $bool = !!$dom;Always true.
hash
my %attrs = %$dom;Alias for "attr".
say $dom->{foo};
say $dom->div->{id};stringify
my $str = "$dom";Alias for "to_string".