.\" 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 "2013-04-23" "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 HTML/XML DOM parser with CSS selectors
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Mojo::DOM;
\&
\& # Parse
\& my $dom = Mojo::DOM\->new(\*(Aq\*(Aq);
\&
\& # Find
\& say $dom\->at(\*(Aq#b\*(Aq)\->text;
\& say $dom\->find(\*(Aqp\*(Aq)\->pluck(\*(Aqtext\*(Aq);
\&
\& # 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(\*(AqC
\*(Aq);
\&
\& # Render
\& say $dom;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mojo::DOM is a minimalistic and relaxed \s-1HTML/XML\s0 \s-1DOM\s0 parser with \s-1CSS\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-1HTML\s0 semantics, that means all tags and attributes
are lowercased and selectors need to be lower case as well.
.PP
.Vb 3
\& my $dom = Mojo::DOM\->new(\*(AqHi!
\*(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(\*(AqHi!
\*(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 HTML semantics
\& $dom\->xml(0);
.Ve
.SH "METHODS"
.IX Header "METHODS"
Mojo::DOM inherits all methods from Mojo::Base and implements the
following new ones.
.SS "new"
.IX Subsection "new"
.Vb 2
\& my $dom = Mojo::DOM\->new;
\& my $dom = Mojo::DOM\->new(\*(Aqtest\*(Aq);
.Ve
.PP
Construct a new array-based Mojo::DOM object and \f(CW\*(C`parse\*(C'\fR \s-1HTML/XML\s0 document
if necessary.
.SS "all_text"
.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\->all_text;
\&
\& # "foo\enbarbaz\en"
\& $dom\->parse("")\->div\->all_text(0);
.Ve
.SS "append"
.IX Subsection "append"
.Vb 1
\& $dom = $dom\->append(\*(AqHi!
\*(Aq);
.Ve
.PP
Append to element.
.PP
.Vb 2
\& # "A
B
"
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->append(\*(AqB
\*(Aq)\->root;
.Ve
.SS "append_content"
.IX Subsection "append_content"
.Vb 1
\& $dom = $dom\->append_content(\*(AqHi!
\*(Aq);
.Ve
.PP
Append to element content.
.PP
.Vb 2
\& # "AB
"
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->append_content(\*(AqB\*(Aq)\->root;
.Ve
.SS "at"
.IX Subsection "at"
.Vb 1
\& my $result = $dom\->at(\*(Aqhtml title\*(Aq);
.Ve
.PP
Find first element matching the \s-1CSS\s0 selector and return it as a Mojo::DOM
object or return \f(CW\*(C`undef\*(C'\fR if none could be found. 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
.SS "attrs"
.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.
.SS "charset"
.IX Subsection "charset"
.Vb 2
\& my $charset = $dom\->charset;
\& $dom = $dom\->charset(\*(AqUTF\-8\*(Aq);
.Ve
.PP
Charset used for decoding and encoding \s-1HTML/XML\s0.
.SS "children"
.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 as
Mojo::DOM objects, similar to \f(CW\*(C`find\*(C'\fR.
.PP
.Vb 2
\& # Show type of random child element
\& say $dom\->children\->shuffle\->first\->type;
.Ve
.SS "content_xml"
.IX Subsection "content_xml"
.Vb 1
\& my $xml = $dom\->content_xml;
.Ve
.PP
Render content of this element to \s-1XML\s0. Note that the \s-1XML\s0 will be encoded if a
\&\f(CW\*(C`charset\*(C'\fR has been defined.
.PP
.Vb 2
\& # "test"
\& $dom\->parse(\*(Aqtest
\*(Aq)\->div\->content_xml;
.Ve
.SS "find"
.IX Subsection "find"
.Vb 1
\& my $collection = $dom\->find(\*(Aqhtml title\*(Aq);
.Ve
.PP
Find all elements matching the \s-1CSS\s0 selector and return a Mojo::Collection
object containing these elements as Mojo::DOM objects. 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)\->pluck(\*(Aqtext\*(Aq)\->each;
.Ve
.SS "namespace"
.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
.SS "next"
.IX Subsection "next"
.Vb 1
\& my $sibling = $dom\->next;
.Ve
.PP
Return Mojo::DOM object for next sibling of element or \f(CW\*(C`undef\*(C'\fR if there
are no more siblings.
.PP
.Vb 2
\& # "B
"
\& $dom\->parse(\*(AqA
B
\*(Aq)\->at(\*(Aqh1\*(Aq)\->next;
.Ve
.SS "parent"
.IX Subsection "parent"
.Vb 1
\& my $parent = $dom\->parent;
.Ve
.PP
Return Mojo::DOM object for parent of element or \f(CW\*(C`undef\*(C'\fR if this element
has no parent.
.SS "parse"
.IX Subsection "parse"
.Vb 1
\& $dom = $dom\->parse(\*(Aqtest\*(Aq);
.Ve
.PP
Parse \s-1HTML/XML\s0 document with 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
.SS "prepend"
.IX Subsection "prepend"
.Vb 1
\& $dom = $dom\->prepend(\*(AqHi!
\*(Aq);
.Ve
.PP
Prepend to element.
.PP
.Vb 2
\& # "A
B
"
\& $dom\->parse(\*(AqB
\*(Aq)\->at(\*(Aqh2\*(Aq)\->prepend(\*(AqA
\*(Aq)\->root;
.Ve
.SS "prepend_content"
.IX Subsection "prepend_content"
.Vb 1
\& $dom = $dom\->prepend_content(\*(AqHi!
\*(Aq);
.Ve
.PP
Prepend to element content.
.PP
.Vb 2
\& # "AB
"
\& $dom\->parse(\*(AqB
\*(Aq)\->at(\*(Aqh2\*(Aq)\->prepend_content(\*(AqA\*(Aq)\->root;
.Ve
.SS "previous"
.IX Subsection "previous"
.Vb 1
\& my $sibling = $dom\->previous;
.Ve
.PP
Return Mojo::DOM object for previous sibling of element or \f(CW\*(C`undef\*(C'\fR if
there are no more siblings.
.PP
.Vb 2
\& # "A
"
\& $dom\->parse(\*(AqA
B
\*(Aq)\->at(\*(Aqh2\*(Aq)\->previous;
.Ve
.SS "remove"
.IX Subsection "remove"
.Vb 1
\& my $old = $dom\->remove;
.Ve
.PP
Remove element and return it as a Mojo::DOM object.
.PP
.Vb 2
\& # ""
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->remove\->root;
.Ve
.SS "replace"
.IX Subsection "replace"
.Vb 1
\& my $old = $dom\->replace(\*(Aqtest
\*(Aq);
.Ve
.PP
Replace element and return the replaced element as a Mojo::DOM object.
.PP
.Vb 2
\& # "B
"
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace(\*(AqB
\*(Aq)\->root;
\&
\& # ""
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace(\*(Aq\*(Aq)\->root;
.Ve
.SS "replace_content"
.IX Subsection "replace_content"
.Vb 1
\& $dom = $dom\->replace_content(\*(Aqtest\*(Aq);
.Ve
.PP
Replace element content.
.PP
.Vb 2
\& # "B
"
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace_content(\*(AqB\*(Aq)\->root;
\&
\& # ""
\& $dom\->parse(\*(AqA
\*(Aq)\->at(\*(Aqh1\*(Aq)\->replace_content(\*(Aq\*(Aq)\->root;
.Ve
.SS "root"
.IX Subsection "root"
.Vb 1
\& my $root = $dom\->root;
.Ve
.PP
Return Mojo::DOM object for root node.
.SS "text"
.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\->text;
\&
\& # "foo\enbaz\en"
\& $dom\->parse("")\->div\->text(0);
.Ve
.SS "text_after"
.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\->p\->text_after;
\&
\& # "baz\en"
\& $dom\->parse("")\->div\->p\->text_after(0);
.Ve
.SS "text_before"
.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\->p\->text_before;
\&
\& # "foo\en"
\& $dom\->parse("")\->div\->p\->text_before(0);
.Ve
.SS "to_xml"
.IX Subsection "to_xml"
.Vb 2
\& my $xml = $dom\->to_xml;
\& my $xml = "$dom";
.Ve
.PP
Render this element and its content to \s-1XML\s0. Note that the \s-1XML\s0 will be encoded
if a \f(CW\*(C`charset\*(C'\fR has been defined.
.PP
.Vb 2
\& # "test"
\& $dom\->parse(\*(Aqtest
\*(Aq)\->div\->b\->to_xml;
.Ve
.SS "tree"
.IX Subsection "tree"
.Vb 2
\& my $tree = $dom\->tree;
\& $dom = $dom\->tree([\*(Aqroot\*(Aq, [qw(text lalala)]]);
.Ve
.PP
Document Object Model. Note that this structure should only be used very
carefully since it is very dynamic.
.SS "type"
.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
\& say $dom\->children\->pluck(\*(Aqtype\*(Aq);
.Ve
.SS "xml"
.IX Subsection "xml"
.Vb 2
\& my $xml = $dom\->xml;
\& $dom = $dom\->xml(1);
.Ve
.PP
Disable \s-1HTML\s0 semantics in parser and activate case sensitivity, defaults to
auto detection based on processing instructions.
.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;
\& say $dom\->div\->pluck(\*(Aqtext\*(Aq);
.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, .