HTML::Object::DOM(3)

📦 version 0.6.0, in alpine 3.24

okay bestie, this is the User Contributed Perl Documentation page for HTML::Object::DOM(3) — yes, the HTML::Object::DOM manual, and we are doing part 1 with every single detail intact 💖

✨ NAME ✨

HTML::Object::DOM — HTML Object DOM Class 💅

🌸 SYNOPSIS 🌸

bestie, you load it like this:

use HTML::Object::DOM;
my $this = HTML::Object::DOM->new || die( HTML::Object::DOM->error, "\n" );

⭐ VERSION ⭐

v0.5.0

🦋 DESCRIPTION 🦋

Okay so this module implements a DOM-like interface to HTML objects and inherits from HTML::Object, so you can call this module instead to parse HTML data, and the resulting tree of objects will have DOM capabilities. Slay.

DOM stands for Document Object Model. Periodt.

There are 2 divergences from the standard:

nodeName — nodeName returns the tag name in lower case instead of the upper case. lowercase era, iykyk.
Space and text — this interface makes the difference between text and space-only text, whereas the DOM standard specification treats both as a text node.

This leads to a new non-standard constant nodeType for space having a value "SPACE_NODE" (13) and the non-standard constant "SHOW_SPACE" in HTML::Object::DOM::NodeFilter. no cap, that's the lore.

🧚 INHERITANCE 🧚

the family tree is giving:

+--------------+     +-------------------+
| HTML::Object | --> | HTML::Object::DOM |
+--------------+     +-------------------+

🛠️ CONSTRUCTOR 🛠️

🆕 new

Provided with a hash or hash reference of options, and this returns a new HTML::Object::DOM object. Options available are the same as the methods available. lowkey convenient 💅

💜 METHODS 💜

current_parent

This represents the parent for the current element being processed by the parser. main character energy for the parser's current fave.

document

Set or get the element object for the document. vibe check on the document element ✨

get_definition

Provided with a tag name, and this will return its corresponding hash reference or undef if there is no such tag or an error occurred somehow. fr fr, that's the whole deal.

get_dom

Get the value for the global variable $GLOBAL_DOM, which should be a HTML::Object::DOM::Document object.

new_closing

Instantiates a new closing element, passing it any arguments received, and returns the new object.

new_comment

Instantiates a new comment element, passing it any arguments received, and returns the new object.

new_declaration

Instantiates a new declaration element, passing it any arguments received, and returns the new object.

new_document

Instantiates a new document element, passing it any arguments received, and returns the new object.

The new document object has its property "defaultView" set to a new window object. it ate, honestly 🎀

new_element

Instantiates a new element, passing it any arguments received, and returns the new object.

new_space

Instantiates a new space element, passing it any arguments received, and returns the new object.

new_text

Instantiates a new text element, passing it any arguments received, and returns the new object.

new_window

Instantiates a new window object, passing it any arguments received, and returns the new object. iconic behavior 👑

onload

Set or get the code reference to be executed when the parsing of the html data has been completed.

The value of this code reference is provided to the new document when it is instantiated.

Upon execution, $_ is set to the HTML document object, and a new event is passed of type "readstate" and with the "detail" property having the following data available:

document — the document object
state — the state of the document parsing

The event "target" property is also set to the document object.

onreadystatechange

Set or get the code reference to be executed whenever there is a change of state to the document. 3 states are available: "loading", "interactive" and "complete". ngl, that's the whole state machine vibe.

The value of this code reference is provided to the new document when it is instantiated.

Upon execution, $_ is set to the HTML document object, and a new event is passed of type "readstate" and with the "detail" property having the following data available:

document — the document object
state — the state of the document parsing

The event "target" property is also set to the document object.

parseFromString

Provided with some HTML data, and this will parse it and return a new document object or undef if an error occurred. literally the parse-and-hope bestie 💖

screen

Returns the HTML::Object::DOM::Screen object. obsessed.

set_dom

Set the global variable $GLOBAL_DOM which must be a HTML::Object::DOM::Document. fr fr, it must be that.

window

Set or get the window object for this new parser and the document it creates. window behavior, but make it parser lore 🦋

part 2 is next, bestie — this page is long and we are not skipping a single section 💅

✨ CONSTANTS ✨

okay so these constants can be exported and used, bestie — like this:

use HTML::Object::DOM qw( :event );
# or directly
use HTML::Object::Event qw( :all );

💖 HTML::Object::Event

NONE (0) — the event is not being processed at this time.
CAPTURING_PHASE (1) — the event is being propagated through the target's ancestor objects. This process starts with the Document, then the HTML html element, and so on through the elements until the target's parent is reached. Event listeners registered for capture mode when addEventListener in HTML::Object::EventTarget was called are triggered during this phase.
AT_TARGET (2) — the event has arrived at the event's target. Event listeners registered for this phase are called at this time. If bubbles is false, processing the event is finished after this phase is complete.
BUBBLING_PHASE (3) — the event is propagating back up through the target's ancestors in reverse order, starting with the parent, and eventually reaching the containing document. This is known as bubbling, and occurs only if bubbles is true. Event listeners registered for this phase are triggered during this process.
CANCEL_PROPAGATION (1) — state of the propagation being cancelled.

$event->stopPropagation();
$event->cancelled == CANCEL_PROPAGATION;

CANCEL_IMMEDIATE_PROPAGATION (2) — state of immediate propagation being cancelled.

$event->stopImmediatePropagation();
$event->cancelled == CANCEL_IMMEDIATE_PROPAGATION;

🌸 HTML::Object::DOM::Element::Media

for HTML::Object::DOM::Element::Media, you can use:

use HTML::Object::DOM qw( :media );
# or directly from HTML::Object::DOM::Element::Media
use HTML::Object::DOM::Element::Media qw( :all );

NETWORK_EMPTY (0) — there is no data yet. Also, readyState is HAVE_NOTHING.
NETWORK_IDLE (1) — the media element is active and has selected a resource, but is not using the network.
NETWORK_LOADING (2) — the browser is downloading HTML::Object::DOM::Element::Media data.
NETWORK_NO_SOURCE (3) — no HTML::Object::DOM::Element::Media src found.

🦋 HTML::Object::DOM::Element::Track

for HTML::Object::DOM::Element::Track, you can use:

use HTML::Object::DOM qw( :track );
# or directly from HTML::Object::DOM::Element::Track
use HTML::Object::DOM::Element::Track qw( :all );

NONE (0) — indicates that the text track's cues have not been obtained. Also used in HTML::Object::Event to indicate the event is not being processed at this time.
LOADING (1) — indicates that the text track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track by the parser.
LOADED (2) — indicates that the text track has been loaded with no fatal errors.
ERROR (3) — indicates that the text track was enabled, but when the user agent attempted to obtain it, this failed in some way. Some or all of the cues are likely missing and will not be obtained.

⭐ HTML::Object::DOM::Node

for HTML::Object::DOM::Node, you can use:

use HTML::Object::DOM qw( :node );
# or directly from HTML::Object::DOM::Node
# Automatically exported
use HTML::Object::DOM::Node;

DOCUMENT_POSITION_IDENTICAL (0 or in bits: 000000) — elements are identical.
DOCUMENT_POSITION_DISCONNECTED (1 or in bits: 000001) — no relationship, both nodes are in different documents or different trees in the same document.
DOCUMENT_POSITION_PRECEDING (2 or in bits: 000010) — the specified node precedes the current node.
DOCUMENT_POSITION_FOLLOWING (4 or in bits: 000100) — the specified node follows the current node.
DOCUMENT_POSITION_CONTAINS (8 or in bits: 001000) — the otherNode is an ancestor of / contains the current node.
DOCUMENT_POSITION_CONTAINED_BY (16 or in bits: 010000) — the otherNode is a descendant of / contained by the node.
DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32 or in bits: 100000) — the specified node and the current node have no common container node, or the two nodes are different attributes of the same node.

and also these constants, bestie:

ELEMENT_NODE (1)
ATTRIBUTE_NODE (2)
TEXT_NODE (3)
CDATA_SECTION_NODE (4)
ENTITY_REFERENCE_NODE (5)
ENTITY_NODE (6)
PROCESSING_INSTRUCTION_NODE (7)
COMMENT_NODE (8)
DOCUMENT_NODE (9)
DOCUMENT_TYPE_NODE (10)
DOCUMENT_FRAGMENT_NODE (11)
NOTATION_NODE (12)
SPACE_NODE (13)

🎀 HTML::Object::DOM::NodeFilter

for HTML::Object::DOM::NodeFilter, you can use:

use HTML::Object::DOM qw( :filter );
# or directly from HTML::Object::DOM::NodeFilter
# Exportable constants
use HTML::Object::DOM::NodeFilter qw( :all );

SHOW_ALL (4294967295) — shows all nodes.
SHOW_ELEMENT (1) — shows Element nodes.
SHOW_ATTRIBUTE (2) — shows attribute Attribute nodes.
SHOW_TEXT (4) — shows Text nodes.
SHOW_CDATA_SECTION (8) — will always return nothing, because there is no support for XML documents.
SHOW_ENTITY_REFERENCE (16) — legacy, no more used.
SHOW_ENTITY (32) — legacy, no more used.
SHOW_PROCESSING_INSTRUCTION (64) — shows ProcessingInstruction nodes.
SHOW_COMMENT (128) — shows Comment nodes.
SHOW_DOCUMENT (256) — shows Document nodes.
SHOW_DOCUMENT_TYPE (512) — shows DocumentType nodes.
SHOW_DOCUMENT_FRAGMENT (1024) — shows HTML::Object::DOM::DocumentFragment nodes.
SHOW_NOTATION (2048) — legacy, no more used.
SHOW_SPACE (4096) — show Space nodes. This is a non-standard extension under this perl framework.

🔥 HTML::Object::DOM::XPathResult

for HTML::Object::DOM::XPathResult, you can use:

use HTML::Object::DOM qw( :xpath );
# or directly from HTML::Object::DOM::Element::Track
# Automatically exported
use HTML::Object::DOM::XPathResult;

ANY_TYPE (0) — a result set containing whatever type naturally results from evaluation of the expression. Note that if the result is a node-set then UNORDERED_NODE_ITERATOR_TYPE is always the resulting type.
NUMBER_TYPE (1) — a result containing a single number. This is useful, for example, in an XPath expression using the count() function.
STRING_TYPE (2) — a result containing a single string.
BOOLEAN_TYPE (3) — a result containing a single boolean value. This is useful, for example, in an XPath expression using the not() function.
UNORDERED_NODE_ITERATOR_TYPE (4) — a result node-set containing all the nodes matching the expression. The nodes may not necessarily be in the same order that they appear in the document.
ORDERED_NODE_ITERATOR_TYPE (5) — a result node-set containing all the nodes matching the expression. The nodes in the result set are in the same order that they appear in the document.
UNORDERED_NODE_SNAPSHOT_TYPE (6) — a result node-set containing snapshots of all the nodes matching the expression. The nodes may not necessarily be in the same order that they appear in the document.
ORDERED_NODE_SNAPSHOT_TYPE (7) — a result node-set containing snapshots of all the nodes matching the expression. The nodes in the result set are in the same order that they appear in the document.
ANY_UNORDERED_NODE_TYPE (8) — a result node-set containing any single node that matches the expression. The node is not necessarily the first node in the document that matches the expression.
FIRST_ORDERED_NODE_TYPE (9) — a result node-set containing the first node in the document that matches the expression.

👑 AUTHOR 👑

Jacques Deguest — jack@deguest.jp

🌈 SEE ALSO 🌈

go read these, bestie, they're the receipts:

Mozilla documentation — https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model
Mozilla documentation on HTML DOM API — https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API
W3C standard — https://html.spec.whatwg.org/multipage/dom.html, HTML elements specifications — https://html.spec.whatwg.org/

🎀 COPYRIGHT & LICENSE 🎀

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

mwah 💖 this gorgeous page is from perl v5.42.2, dated 2026-02-15, and it's HTML::Object::DOM(3) — byeee bestie 🎀✨

📦 where this page comes from

alpine 3.24: perl-html-object-doc 0.6.0-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms