HTML::O...orShared(3)

📦 version 0.6.0, in alpine 3.24

💖 NAME 💖

okay so bestie, welcome to HTML::O...orShared(3) — the shared class page ✨ The actual star of the show is HTML::Object::DOM::NodeIterator, a.k.a. the HTML Object DOM Node Iterator Shared Class. She's the chill parent class that HTML::Object::DOM::NodeIterator and HTML::Object::DOM::TreeWalker both inherit from, and she does the tree-crawling heavy lifting. 🌳💅

🎀 SYNOPSIS 🎀

bestie it's literally so simple. if you pass just one argument, it defaults to searching for everything ("SHOW_ALL") and uses the default filter, which always returns "FILTER_ACCEPT". slay. 🫶

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

or, passing an anonymous subroutine as the filter:

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

or, passing a hash reference with a property 'acceptNode' whose value is an anonymous subroutine, as the filter:

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

or, passing an object that implements the method "acceptNode":

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

there's also HTML::Object::DOM::TreeWalker, which performs a somewhat similar function 👀

so like, choose "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 the node and its siblings. iykyk 🌈

⭐ VERSION ⭐

v0.2.0

🦋 DESCRIPTION 🦋

this class is to be inherited by either HTML::Object::DOM::NodeIterator or HTML::Object::DOM::TreeWalker, and she implements the basic tree crawling mechanism. not me being the blueprint 💅

✨ PROPERTIES ✨

🌸 `expandEntityReferences`

normally this is read-only, but under perl you can set whatever boolean value you want. main character energy fr.

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 $nodeIterator = $doc->createNodeIterator(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
my $expand = $nodeIterator->expandEntityReferences;

see also the Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/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. glow-up mid-life, we love to see it ✨

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

Example:

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

see also the Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/filter

🍓 `pos`

read-only. periodt.

this is a non-standard property, which returns the 0-based position in the array of the anchor element's children. you can poll this to know where the iterator is at. it's giving live location sharing 🔥

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
# You need to first declare $nodeIterator to be able to use it in the callback
my $nodeIterator;
$nodeIterator = $doc->createNodeIterator(
    $doc->body,
    SHOW_ELEMENT,
    sub
    {
        say "Current position is: ", $nodeIterator->pos );
        return( $_->getName eq 'div' ? FILTER_ACCEPT : FILTER_SKIP );
    },
);

🧚 `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 "NodeIterator" was created.

Example:

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

see for more information: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/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. no cap. 💅

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

`SHOW_ALL` (`4294967295`)

shows all nodes. everything. the whole vibe check passed 🌈

`SHOW_ELEMENT` (`1`)

shows Element nodes.

`SHOW_ATTRIBUTE` (`2`)

shows attribute Attribute nodes. this is meaningful only when creating a NodeIterator 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 $nodeIterator = $doc->createNodeIterator(
    $doc->body,
    ( SHOW_ELEMENT | SHOW_COMMENT | SHOW_TEXT ),
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
);
if( ( $nodeIterator->whatToShow & SHOW_ALL ) ||
    ( $nodeIterator->whatToShow & SHOW_COMMENT ) )
{
    # $nodeIterator will show comments
}

`SHOW_CDATA_SECTION` (`8`)

will always returns nothing, because there is no support for xml documents. 💀 that's it, that's the whole function.

`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 for more information: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/whatToShow

🎀 CONSTRUCTOR 🎀

`${new}` — sorry, `new` 💖

provided with a root node, an optional bitwise value representing what to show, and an optional filter callback, and this will return a new node iterator or tree walker depending on the class used. pick your fighter 💅

🔥 METHODS 🔥

`nextNode`

returns the next Node in the document, or "undef" if there are none. 😭

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $nodeIterator = $doc->createNodeIterator(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
    0 # false; this optional argument is not used any more
);
my $currentNode = $nodeIterator->nextNode(); # returns the next node

see also the Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/nextNode

`previousNode`

returns the previous Node in the document, or "undef" if there are none.

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $nodeIterator = $doc->createNodeIterator(
    $doc->body,
    SHOW_ELEMENT,
    sub{ return( FILTER_ACCEPT ); },
    # or
    # { acceptNode => sub{ return( FILTER_ACCEPT ); } },
    0 # false; this optional argument is not used any more
);
my $currentNode = $nodeIterator->nextNode(); # returns the next node
my $previousNode = $nodeIterator->previousNode(); # same result, since we backtracked to the previous node

see also the Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator/previousNode

🫶 AUTHOR 🫶

Jacques Deguest <jack@deguest.jp> — icon, legend, the moment ✨

🌈 SEE ALSO 🌈

HTML::Object::DOM::NodeIterator
HTML::Object::DOM::TreeWalker
Mozilla documentation: https://developer.mozilla.org/en-US/docs/Web/API/NodeIterator
StackOverflow topic on NodeIterator: https://stackoverflow.com/questions/7941288/when-to-use-nodeiterator
W3C specifications: https://dom.spec.whatwg.org/#interface-nodeiterator

💜 COPYRIGHT & LICENSE 💜

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

ok that's the whole page bestie, you ate that 🍓 this was perl v5.42.2, dated 2026-02-15, from the HTML::O...orShared(3) manual — now go iterate some nodes, 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...orShared(3)

💖 NAME 💖

🎀 SYNOPSIS 🎀

⭐ VERSION ⭐

🦋 DESCRIPTION 🦋

✨ PROPERTIES ✨

🌸 expandEntityReferences

💜 filter

🍓 pos

🧚 root

👑 whatToShow

SHOW_ALL (4294967295)

SHOW_ELEMENT (1)

SHOW_ATTRIBUTE (2)

SHOW_TEXT (4)

SHOW_CDATA_SECTION (8)

SHOW_ENTITY_REFERENCE (16)

SHOW_ENTITY (32)

SHOW_PROCESSING_INSTRUCTION (64)

SHOW_COMMENT (128)

SHOW_DOCUMENT (256)

SHOW_DOCUMENT_TYPE (512)

SHOW_DOCUMENT_FRAGMENT (1024)

SHOW_NOTATION (2048)

SHOW_SPACE (4096)

🎀 CONSTRUCTOR 🎀

${new} — sorry, new 💖

🔥 METHODS 🔥

nextNode

previousNode

🫶 AUTHOR 🫶

🌈 SEE ALSO 🌈

💜 COPYRIGHT & LICENSE 💜

🌸 `expandEntityReferences`

💜 `filter`

🍓 `pos`

🧚 `root`

👑 `whatToShow`

`SHOW_ALL` (`4294967295`)

`SHOW_ELEMENT` (`1`)

`SHOW_ATTRIBUTE` (`2`)

`SHOW_TEXT` (`4`)

`SHOW_CDATA_SECTION` (`8`)

`SHOW_ENTITY_REFERENCE` (`16`)

`SHOW_ENTITY` (`32`)

`SHOW_PROCESSING_INSTRUCTION` (`64`)

`SHOW_COMMENT` (`128`)

`SHOW_DOCUMENT` (`256`)

`SHOW_DOCUMENT_TYPE` (`512`)

`SHOW_DOCUMENT_FRAGMENT` (`1024`)

`SHOW_NOTATION` (`2048`)

`SHOW_SPACE` (`4096`)

`${new}` — sorry, `new` 💖

`nextNode`

`previousNode`