.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mojo::DOM 3pm"
.TH Mojo::DOM 3pm "2012-09-05" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mojo::DOM \- Minimalistic HTML5/XML DOM parser with CSS3 selectors
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Mojo::DOM;
\&
\&  # Parse
\&  my $dom = Mojo::DOM\->new(\*(Aq<div><p id="a">A</p><p id="b">B</p></div>\*(Aq);
\&
\&  # Find
\&  my $b = $dom\->at(\*(Aq#b\*(Aq);
\&  say $b\->text;
\&
\&  # Walk
\&  say $dom\->div\->p\->[0]\->text;
\&  say $dom\->div\->children(\*(Aqp\*(Aq)\->first\->{id};
\&
\&  # Iterate
\&  $dom\->find(\*(Aqp[id]\*(Aq)\->each(sub { say shift\->{id} });
\&
\&  # Loop
\&  for my $e ($dom\->find(\*(Aqp[id]\*(Aq)\->each) {
\&    say $e\->text;
\&  }
\&
\&  # Modify
\&  $dom\->div\->p\->[1]\->append(\*(Aq<p id="c">C</p>\*(Aq);
\&
\&  # Render
\&  say $dom;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::DOM is a minimalistic and relaxed \s-1HTML5/XML\s0 \s-1DOM\s0 parser with \s-1CSS3\s0
selector support. It will even try to interpret broken \s-1XML\s0, so you should not
use it for validation.
.SH "CASE SENSITIVITY"
.IX Header "CASE SENSITIVITY"
Mojo::DOM defaults to \s-1HTML5\s0 semantics, that means all tags and attributes
are lowercased and selectors need to be lowercase as well.
.PP
.Vb 3
\&  my $dom = Mojo::DOM\->new(\*(Aq<P ID="greeting">Hi!</P>\*(Aq);
\&  say $dom\->at(\*(Aqp\*(Aq)\->text;
\&  say $dom\->p\->{id};
.Ve
.PP
If \s-1XML\s0 processing instructions are found, the parser will automatically switch
into \s-1XML\s0 mode and everything becomes case sensitive.
.PP
.Vb 3
\&  my $dom = Mojo::DOM\->new(\*(Aq<?xml version="1.0"?><P ID="greeting">Hi!</P>\*(Aq);
\&  say $dom\->at(\*(AqP\*(Aq)\->text;
\&  say $dom\->P\->{ID};
.Ve
.PP
\&\s-1XML\s0 detection can also be disabled with the \f(CW\*(C`xml\*(C'\fR method.
.PP
.Vb 2
\&  # Force XML semantics
\&  $dom\->xml(1);
\&
\&  # Force HTML5 semantics
\&  $dom\->xml(0);
.Ve
.SH "METHODS"
.IX Header "METHODS"
Mojo::DOM implements the following methods.
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
.Vb 2
\&  my $dom = Mojo::DOM\->new;
\&  my $dom = Mojo::DOM\->new(\*(Aq<foo bar="baz">test</foo>\*(Aq);
.Ve
.PP
Construct a new Mojo::DOM object.
.ie n .SS """all_text"""
.el .SS "\f(CWall_text\fP"
.IX Subsection "all_text"
.Vb 2
\&  my $trimmed   = $dom\->all_text;
\&  my $untrimmed = $dom\->all_text(0);
.Ve
.PP
Extract all text content from \s-1DOM\s0 structure, smart whitespace trimming is
enabled by default.
.PP
.Vb 2
\&  # "foo bar baz"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->all_text;
\&
\&  # "foo\enbarbaz\en"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->all_text(0);
.Ve
.ie n .SS """append"""
.el .SS "\f(CWappend\fP"
.IX Subsection "append"
.Vb 1
\&  $dom = $dom\->append(\*(Aq<p>Hi!</p>\*(Aq);
.Ve
.PP
Append to element.
.PP
.Vb 2
\&  # "<div><h1>A</h1><h2>B</h2></div>"
\&  $dom\->parse(\*(Aq<div><h1>A</h1></div>\*(Aq)\->at(\*(Aqh1\*(Aq)\->append(\*(Aq<h2>B</h2>\*(Aq);
.Ve
.ie n .SS """append_content"""
.el .SS "\f(CWappend_content\fP"
.IX Subsection "append_content"
.Vb 1
\&  $dom = $dom\->append_content(\*(Aq<p>Hi!</p>\*(Aq);
.Ve
.PP
Append to element content.
.PP
.Vb 2
\&  # "<div><h1>AB</h1></div>"
\&  $dom\->parse(\*(Aq<div><h1>A</h1></div>\*(Aq)\->at(\*(Aqh1\*(Aq)\->append_content(\*(AqB\*(Aq);
.Ve
.ie n .SS """at"""
.el .SS "\f(CWat\fP"
.IX Subsection "at"
.Vb 1
\&  my $result = $dom\->at(\*(Aqhtml title\*(Aq);
.Ve
.PP
Find a single element with \s-1CSS3\s0 selectors. All selectors from
Mojo::DOM::CSS are supported.
.PP
.Vb 2
\&  # Find first element with "svg" namespace definition
\&  my $namespace = $dom\->at(\*(Aq[xmlns\e:svg]\*(Aq)\->{\*(Aqxmlns:svg\*(Aq};
.Ve
.ie n .SS """attrs"""
.el .SS "\f(CWattrs\fP"
.IX Subsection "attrs"
.Vb 4
\&  my $attrs = $dom\->attrs;
\&  my $foo   = $dom\->attrs(\*(Aqfoo\*(Aq);
\&  $dom      = $dom\->attrs({foo => \*(Aqbar\*(Aq});
\&  $dom      = $dom\->attrs(foo => \*(Aqbar\*(Aq);
.Ve
.PP
Element attributes.
.ie n .SS """charset"""
.el .SS "\f(CWcharset\fP"
.IX Subsection "charset"
.Vb 2
\&  my $charset = $dom\->charset;
\&  $dom        = $dom\->charset(\*(AqUTF\-8\*(Aq);
.Ve
.PP
Alias for \*(L"charset\*(R" in Mojo::DOM::HTML.
.ie n .SS """children"""
.el .SS "\f(CWchildren\fP"
.IX Subsection "children"
.Vb 2
\&  my $collection = $dom\->children;
\&  my $collection = $dom\->children(\*(Aqdiv\*(Aq);
.Ve
.PP
Return a Mojo::Collection object containing the children of this element,
similar to \f(CW\*(C`find\*(C'\fR.
.PP
.Vb 2
\&  # Show type of random child element
\&  say $dom\->children\->shuffle\->first\->type;
.Ve
.ie n .SS """content_xml"""
.el .SS "\f(CWcontent_xml\fP"
.IX Subsection "content_xml"
.Vb 1
\&  my $xml = $dom\->content_xml;
.Ve
.PP
Render content of this element to \s-1XML\s0.
.PP
.Vb 2
\&  # "<b>test</b>"
\&  $dom\->parse(\*(Aq<div><b>test</b></div>\*(Aq)\->div\->content_xml;
.Ve
.ie n .SS """find"""
.el .SS "\f(CWfind\fP"
.IX Subsection "find"
.Vb 1
\&  my $collection = $dom\->find(\*(Aqhtml title\*(Aq);
.Ve
.PP
Find elements with \s-1CSS3\s0 selectors and return a Mojo::Collection object. All
selectors from Mojo::DOM::CSS are supported.
.PP
.Vb 2
\&  # Find a specific element and extract information
\&  my $id = $dom\->find(\*(Aqdiv\*(Aq)\->[23]{id};
\&
\&  # Extract information from multiple elements
\&  my @headers = $dom\->find(\*(Aqh1, h2, h3\*(Aq)\->map(sub { shift\->text })\->each;
.Ve
.ie n .SS """namespace"""
.el .SS "\f(CWnamespace\fP"
.IX Subsection "namespace"
.Vb 1
\&  my $namespace = $dom\->namespace;
.Ve
.PP
Find element namespace.
.PP
.Vb 2
\&   # Find namespace for an element with namespace prefix
\&   my $namespace = $dom\->at(\*(Aqsvg > svg\e:circle\*(Aq)\->namespace;
\&
\&   # Find namespace for an element that may or may not have a namespace prefix
\&   my $namespace = $dom\->at(\*(Aqsvg > circle\*(Aq)\->namespace;
.Ve
.ie n .SS """parent"""
.el .SS "\f(CWparent\fP"
.IX Subsection "parent"
.Vb 1
\&  my $parent = $dom\->parent;
.Ve
.PP
Parent of element.
.ie n .SS """parse"""
.el .SS "\f(CWparse\fP"
.IX Subsection "parse"
.Vb 1
\&  $dom = $dom\->parse(\*(Aq<foo bar="baz">test</foo>\*(Aq);
.Ve
.PP
Alias for \*(L"parse\*(R" in Mojo::DOM::HTML.
.PP
.Vb 2
\&  # Parse UTF\-8 encoded XML
\&  my $dom = Mojo::DOM\->new\->charset(\*(AqUTF\-8\*(Aq)\->xml(1)\->parse($xml);
.Ve
.ie n .SS """prepend"""
.el .SS "\f(CWprepend\fP"
.IX Subsection "prepend"
.Vb 1
\&  $dom = $dom\->prepend(\*(Aq<p>Hi!</p>\*(Aq);
.Ve
.PP
Prepend to element.
.PP
.Vb 2
\&  # "<div><h1>A</h1><h2>B</h2></div>"
\&  $dom\->parse(\*(Aq<div><h2>B</h2></div>\*(Aq)\->at(\*(Aqh2\*(Aq)\->prepend(\*(Aq<h1>A</h1>\*(Aq);
.Ve
.ie n .SS """prepend_content"""
.el .SS "\f(CWprepend_content\fP"
.IX Subsection "prepend_content"
.Vb 1
\&  $dom = $dom\->prepend_content(\*(Aq<p>Hi!</p>\*(Aq);
.Ve
.PP
Prepend to element content.
.PP
.Vb 2
\&  # "<div><h2>AB</h2></div>"
\&  $dom\->parse(\*(Aq<div><h2>B</h2></div>\*(Aq)\->at(\*(Aqh2\*(Aq)\->prepend_content(\*(AqA\*(Aq);
.Ve
.ie n .SS """replace"""
.el .SS "\f(CWreplace\fP"
.IX Subsection "replace"
.Vb 1
\&  $dom = $dom\->replace(\*(Aq<div>test</div>\*(Aq);
.Ve
.PP
Replace elements.
.PP
.Vb 2
\&  # "<div><h2>B</h2></div>"
\&  $dom\->parse(\*(Aq<div><h1>A</h1></div>\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace(\*(Aq<h2>B</h2>\*(Aq);
.Ve
.ie n .SS """replace_content"""
.el .SS "\f(CWreplace_content\fP"
.IX Subsection "replace_content"
.Vb 1
\&  $dom = $dom\->replace_content(\*(Aqtest\*(Aq);
.Ve
.PP
Replace element content.
.PP
.Vb 2
\&  # "<div><h1>B</h1></div>"
\&  $dom\->parse(\*(Aq<div><h1>A</h1></div>\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace_content(\*(AqB\*(Aq);
.Ve
.ie n .SS """root"""
.el .SS "\f(CWroot\fP"
.IX Subsection "root"
.Vb 1
\&  my $root = $dom\->root;
.Ve
.PP
Find root node.
.ie n .SS """text"""
.el .SS "\f(CWtext\fP"
.IX Subsection "text"
.Vb 2
\&  my $trimmed   = $dom\->text;
\&  my $untrimmed = $dom\->text(0);
.Ve
.PP
Extract text content from element only (not including child elements), smart
whitespace trimming is enabled by default.
.PP
.Vb 2
\&  # "foo baz"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->text;
\&
\&  # "foo\enbaz\en"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->text(0);
.Ve
.ie n .SS """text_after"""
.el .SS "\f(CWtext_after\fP"
.IX Subsection "text_after"
.Vb 2
\&  my $trimmed   = $dom\->text_after;
\&  my $untrimmed = $dom\->text_after(0);
.Ve
.PP
Extract text content immediately following element, smart whitespace trimming
is enabled by default.
.PP
.Vb 2
\&  # "baz"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->p\->text_after;
\&
\&  # "baz\en"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->p\->text_after(0);
.Ve
.ie n .SS """text_before"""
.el .SS "\f(CWtext_before\fP"
.IX Subsection "text_before"
.Vb 2
\&  my $trimmed   = $dom\->text_before;
\&  my $untrimmed = $dom\->text_before(0);
.Ve
.PP
Extract text content immediately preceding element, smart whitespace trimming
is enabled by default.
.PP
.Vb 2
\&  # "foo"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->p\->text_before;
\&
\&  # "foo\en"
\&  $dom\->parse("<div>foo\en<p>bar</p>baz\en</div>")\->div\->p\->text_before(0);
.Ve
.ie n .SS """to_xml"""
.el .SS "\f(CWto_xml\fP"
.IX Subsection "to_xml"
.Vb 1
\&  my $xml = $dom\->to_xml;
.Ve
.PP
Render this element and its content to \s-1XML\s0.
.PP
.Vb 2
\&  # "<div><b>test</b></div>"
\&  $dom\->parse(\*(Aq<div><b>test</b></div>\*(Aq)\->div\->to_xml;
.Ve
.ie n .SS """tree"""
.el .SS "\f(CWtree\fP"
.IX Subsection "tree"
.Vb 2
\&  my $tree = $dom\->tree;
\&  $dom     = $dom\->tree([\*(Aqroot\*(Aq, [qw(text lalala)]]);
.Ve
.PP
Alias for \*(L"tree\*(R" in Mojo::DOM::HTML.
.ie n .SS """type"""
.el .SS "\f(CWtype\fP"
.IX Subsection "type"
.Vb 2
\&  my $type = $dom\->type;
\&  $dom     = $dom\->type(\*(Aqdiv\*(Aq);
.Ve
.PP
Element type.
.PP
.Vb 2
\&  # List types of child elements
\&  $dom\->children\->each(sub { say $_\->type });
.Ve
.ie n .SS """xml"""
.el .SS "\f(CWxml\fP"
.IX Subsection "xml"
.Vb 2
\&  my $xml = $dom\->xml;
\&  $dom    = $dom\->xml(1);
.Ve
.PP
Alias for \*(L"xml\*(R" in Mojo::DOM::HTML.
.SH "CHILD ELEMENTS"
.IX Header "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.
.PP
.Vb 3
\&  say $dom\->p\->text;
\&  say $dom\->div\->[23]\->text;
\&  $dom\->div\->each(sub { say $_\->text });
.Ve
.SH "ELEMENT ATTRIBUTES"
.IX Header "ELEMENT ATTRIBUTES"
Direct hash reference access to element attributes is also possible.
.PP
.Vb 2
\&  say $dom\->{foo};
\&  say $dom\->div\->{id};
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.