HTML::O...eeWalker(3)

📦 version 0.6.0, in alpine 3.24

💖 NAME 💖

HTML::Object::DOM::TreeWalker — HTML Object DOM Tree Walker Class 🎀

✨ SYNOPSIS ✨

Okay bestie, here's the vibe: if you pass just one argument, it defaults to searching for everything ("SHOW_ALL") and uses the default filter, which always returns "FILTER_ACCEPT" 💅

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

Or, you can pass an anonymous subroutine as the filter 🫶

my $nodes = HTML::Object::DOM::TreeWalker->new(
    $root_node,
    $what_to_show_bit,
    sub{ return( FILTER_ACCEPT ); }
) || die( HTML::Object::DOM::TreeWalker->error, "\n" );

Or, pass a hash reference with a property 'acceptNode' whose value is an anonymous subroutine, as the filter 🌸

my $nodes = HTML::Object::DOM::TreeWalker->new(
    $root_node,
    $what_to_show_bit,
    {
        acceptNode => sub{ return( FILTER_ACCEPT ); }
    }
) || die( HTML::Object::DOM::TreeWalker->error, "\n" );

Or, pass an object that implements the method "acceptNode" 🦋

my $nodes = HTML::Object::DOM::TreeWalker->new(
    $root_node,
    $what_to_show_bit,
    # This object must implement the acceptNode method
    My::Customer::NodeFilter->new
) || die( HTML::Object::DOM::TreeWalker->error, "\n" );

There is also HTML::Object::DOM::TreeWalker, which performs a somewhat similar function 👑

Choose HTML::Object::DOM::NodeIterator when you only need a simple iterator to filter and browse the selected nodes, and choose HTML::Object::DOM::TreeWalker when you need to access to the node and its siblings 💫

🌈 VERSION 🌈

v0.2.0 ⭐

🧚 DESCRIPTION 🧚

The "TreeWalker" object represents the nodes of a document subtree and a position within them. Literally its whole personality 💜

👑 PROPERTIES 👑

💅 currentNode

This is the Node on which the "TreeWalker" is currently pointing at. Main character energy, honestly.

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); }
);
my $root = $treeWalker->currentNode; # the root element as it is the first element!

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/currentNode 🦋

🎀 expandEntityReferences

Normally this is read-only, but under perl you can set whatever boolean value you want. No cap.

Under JavaScript, this is a boolean value indicating if, when discarding an "EntityReference", its whole sub-tree must be discarded at the same time.

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
my $expand = $treeWalker->expandEntityReferences;

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/expandEntityReferences 🌸

🌟 filter

Normally this is read-only, but under perl you can set it to a new HTML::Object::DOM::NodeFilter object you want, even after object instantiation. Slay.

Returns a HTML::Object::DOM::NodeFilter used to select the relevant nodes.

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
my $nodeFilter = $treeWalker->filter;

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/filter 🫶

🦋 root

Normally this is read-only, but under perl you can set whatever node value you want.

Returns a Node representing the root node as specified when the "TreeWalker" was created.

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
my $root = $treeWalker->root; # $doc->body in this case

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/root 💖

⭐ whatToShow

Normally this is read-only, but under perl you can set whatever number value you want.

Returns an unsigned long being a bitmask made of constants describing the types of Node that must to be presented. Non-matching nodes are skipped, but their children may be included, if relevant.

Possible constant values (exported by HTML::Object::DOM::NodeFilter) are:

SHOW_ALL (4294967295) — Shows all nodes. 💯
SHOW_ELEMENT (1) — Shows Element nodes. ✨
SHOW_ATTRIBUTE (2) — Shows attribute Attribute nodes. This is meaningful only when creating a "TreeWalker" with an Attribute node as its root; in this case, it means that the attribute node will appear in the first position of the iteration or traversal. Since attributes are never children of other nodes, they do not appear when traversing over the document tree.
SHOW_TEXT (4) — Shows Text nodes. 🍓

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    ( SHOW_ELEMENT | SHOW_COMMENT | SHOW_TEXT ),
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
if( ( $treeWalker->whatToShow & SHOW_ALL ) ||
    ( $treeWalker->whatToShow & SHOW_COMMENT ) )
{
    # $treeWalker will show comments
}

SHOW_CDATA_SECTION (8) — Will always returns 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. 👑

See also Mozilla documentation at https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/whatToShow 🌈

💅 METHODS 💅

okay bestie, this is the part where the walker actually does stuff. every single one of these moves the current node around the tree and hands you back what it found. and whenever it can't find anything? it gives you undef and politely leaves the current node exactly where it was. no chaos, no side effects. we love a respectful icon. ✨

🎀 `firstChild`

Moves the current Node to the first visible child of the current node, and returns the found child. It also moves the current node to this child. If no such child exists, returns undef and the current node is not changed.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->firstChild(); # returns the first child of the root element, or null if none

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/firstChild

🦋 `lastChild`

Moves the current Node to the last visible child of the current node, and returns the found child. It also moves the current node to this child. If no such child exists, undef is returned and the current node is not changed.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->lastChild(); # returns the last visible child of the root element

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/lastChild

🌸 `nextNode`

Moves the current Node to the next visible node in document order, and returns the found node. It also moves the current node to this one. If no such node exists, returns undef and the current node is not changed.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->nextNode(); # returns the first child of root, as it is the next $node in document order

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/nextNode

💜 `nextSibling`

Moves the current Node to its next sibling, if any, and returns the found sibling. If there is no such node, undef is returned and the current node is not changed.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
$treeWalker->firstChild();
my $node = $treeWalker->nextSibling(); # returns null if the first child of the root element has no sibling

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/nextSibling

🧚 `parentNode`

Moves the current Node to the first visible ancestor node in document order, and returns the found node. It also moves the current node to this one. If no such node exists, or if it is before that the root node defined at the object construction, returns undef and the current node is not changed.

heads up bestie: the walker will not climb above the root node you gave it when you built the object. that's the ceiling. periodt.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->parentNode(); # returns null as there is no parent

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/parentNode

🍓 `previousNode`

Moves the current Node to the previous visible node in document order, and returns the found node. It also moves the current node to this one. If no such node exists, or if it is before that the root node defined at the object construction, returns undef and the current node is not changed.

same deal as parentNode: the root node you set at construction is the hard limit. it will not go past it, no cap.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->previousNode(); # returns null as there is no parent

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/previousNode

🌈 `previousSibling`

Moves the current Node to its previous sibling, if any, and returns the found sibling. If there is no such node, return undef and the current node is not changed.

Example:

my $treeWalker = $doc->createTreeWalker(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
);
my $node = $treeWalker->previousSibling(); # returns null as there is no previous sibiling

See also Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/TreeWalker/previousSibling

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp>

💖 COPYRIGHT & LICENSE 💖

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

and that's the whole page, bestie, you ate that 💅✨ this lil doc shipped as perl v5.42.2 dated 2026-02-15 — go forth and walk some trees, ily, bye 🦋💜

📦 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

HTML::O...eeWalker(3)

💖 NAME 💖

✨ SYNOPSIS ✨

🌈 VERSION 🌈

🧚 DESCRIPTION 🧚

👑 PROPERTIES 👑

💅 currentNode

🎀 expandEntityReferences

🌟 filter

🦋 root

⭐ whatToShow

💅 METHODS 💅

🎀 firstChild

🦋 lastChild

🌸 nextNode

💜 nextSibling

🧚 parentNode

🍓 previousNode

🌈 previousSibling

👑 AUTHOR 👑

🫶 SEE ALSO 🫶

💖 COPYRIGHT & LICENSE 💖

🎀 `firstChild`

🦋 `lastChild`

🌸 `nextNode`

💜 `nextSibling`

🧚 `parentNode`

🍓 `previousNode`

🌈 `previousSibling`