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 $_->{id} });

  # Loop
  for my $e ($dom->find('p[id]')->each) {
    say $e->{id}, ':', $e->text;
  }

  # Modify
  $dom->div->p->last->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 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 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 types of ancestor elements
  say $dom->ancestors->type;

append

  $dom = $dom->append('<p>I ♥ Mojolicious!</p>');

Append HTML/XML fragment to this node.

  # "<div><h1>A</h1><h2>B</h2></div>"
  $dom->parse('<div><h1>A</h1></div>')->at('h1')->append('<h2>B</h2>')->root;

  # "<p>test 123</p>"
  $dom->parse('<p>test</p>')->at('p')->contents->first->append(' 123')->root;

append_content

  $dom = $dom->append_content('<p>I ♥ Mojolicious!</p>');

Append HTML/XML fragment or raw content (depending on node type) to this node's content.

  # "<div><h1>AB</h1></div>"
  $dom->parse('<div><h1>A</h1></div>')->at('h1')->append_content('B')->root;

  # "<!-- A B --><br>"
  $dom->parse('<!-- A --><br>')->contents->first->append_content('B ')->root;

  # "<p>A<i>B</i></p>"
  $dom->parse('<p>A</p>')->at('p')->append_content('<i>B</i>')->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 $hash = $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>');

Return this node's content or replace it with HTML/XML fragment or raw content (depending on node type).

  # "<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;

  # " A "
  $dom->parse('<!-- A --><br>')->contents->first->content;

  # "<!-- B --><br>"
  $dom->parse('<!-- A --><br>')->contents->first->content(' B ')->root;

  # "<p><i>B</i></p>"
  $dom->parse('<p>A</p>')->at('p')->content('<i>B</i>')->root;

  my $collection = $dom->contents;

Return a Mojo::Collection object containing the child nodes of this element as Mojo::DOM objects.

  # "<p><b>123</b></p>"
  $dom->parse('<p>test<b>123</b></p>')->at('p')->contents->first->remove;

  # "<!-- test -->"
  $dom->parse('<!-- test --><b>123</b>')->contents->first;

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;

  # Count all the different tags
  my $hash = $dom->find('*')->type->reduce(sub { $a->{$b}++; $a }, {});

  # Find elements with a class that contains dots
  my @divs = $dom->find('div.foo\.bar')->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 scalar-based Mojo::DOM object and "parse" HTML/XML fragment if necessary.

  my $sibling = $dom->next;

Return Mojo::DOM object for next sibling 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;

next_sibling

  my $sibling = $dom->next_sibling;

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_sibling->next_sibling;

node

  my $type = $dom->node;

This node's type, usually cdata, comment, doctype, pi, raw, root, tag or text.

parent

  my $parent = $dom->parent;

Return Mojo::DOM object for parent of this node or undef if this node 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 node.

  # "<div><h1>A</h1><h2>B</h2></div>"
  $dom->parse('<div><h2>B</h2></div>')->at('h2')->prepend('<h1>A</h1>')->root;

  # "<p>test 123</p>"
  $dom->parse('<p>123</p>')->at('p')->contents->first->prepend('test ')->root;

prepend_content

  $dom = $dom->prepend_content('<p>I ♥ Mojolicious!</p>');

Prepend HTML/XML fragment or raw content (depending on node type) to this node's content.

  # "<div><h2>AB</h2></div>"
  $dom->parse('<div><h2>B</h2></div>')->at('h2')->prepend_content('A')->root;

  # "<!-- A B --><br>"
  $dom->parse('<!-- B --><br>')->contents->first->prepend_content(' A')->root;

  # "<p><i>B</i>A</p>"
  $dom->parse('<p>A</p>')->at('p')->prepend_content('<i>B</i>')->root;

  my $sibling = $dom->previous;

Return Mojo::DOM object for previous sibling 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;

previous_sibling

  my $sibling = $dom->previous_sibling;

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_sibling->previous_sibling;

remove

  my $parent = $dom->remove;

Remove this node and return "parent".

  # "<div></div>"
  $dom->parse('<div><h1>A</h1></div>')->at('h1')->remove;

  # "<p><b>456</b></p>"
  $dom->parse('<p>123<b>456</b></p>')->at('p')->contents->first->remove->root;

replace

  my $parent = $dom->replace('<div>I ♥ Mojolicious!</div>');

Replace this node 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>');

  # "<p><b>B</b></p>"
  $dom->parse('<p>A</p>')->at('p')->contents->[0]->replace('<b>B</b>')->root;

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 sibling 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 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 node 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']);

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;

val

  my $collection = $dom->val;

Extract values from button, input, option, select or textarea element and return a Mojo::Collection object containing these values. In the case of select, find all option elements it contains that have a selected attribute and extract their values.

  # "b"
  $dom->parse('<input name="a" value="b">')->at('input')->val;

  # "c"
  $dom->parse('<option value="c">C</option>')->at('option')->val;

  # "d"
  $dom->parse('<option>d</option>')->at('option')->val;

wrap

  $dom = $dom->wrap('<div></div>');

Wrap HTML/XML fragment around this node, 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;

  # "<p><b>A</b></p>"
  $dom->parse('<p>A</p>')->at('p')->contents->first->wrap('<b>')->root;

wrap_content

  $dom = $dom->wrap_content('<div></div>');

Wrap HTML/XML fragment around this node'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. For more power and consistent results you can also use "children".

  say $dom->p->text;
  say $dom->div->[23]->text;
  say $dom->div->text;

OPERATORS

Mojo::DOM overloads the following operators.

array

  my @nodes = @$dom;

Alias for "contents".

  # "<!-- test -->"
  $dom->parse('<!-- test --><b>123</b>')->[0];

bool

  my $bool = !!$dom;

Always true.

hash

  my %attrs = %$dom;

Alias for "attr".

  # "test"
  $dom->parse('<div id="test">A</div>')->at('div')->{id};

stringify

  my $str = "$dom";

Alias for "to_string".

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)