HTML::O...deFilter(3)

📦 version 0.6.0, in alpine 3.24

🌸 NAME 🌸

Okay so this is HTML::Object::DOM::NodeFilter — HTML Object DOM Node Filter. It's from the User Contributed Perl Documentation, and it's giving iconic reference-page energy. 💅

✨ SYNOPSIS ✨

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

🎀 VERSION 🎀

v0.2.0 — literally the version, bestie. 🫶

💖 DESCRIPTION 💖

A NodeFilter interface represents an object used to filter the nodes in a HTML::Object::DOM::NodeIterator or a HTML::Object::DOM::::TreeWalker. (Yep, that's four colons in the original — I'm keeping it character-for-character, no cap. 💀) A NodeFilter knows nothing about the document or traversing nodes; it only knows how to evaluate a single node against the provided filter. It's giving single-responsibility icon. Periodt. ✨

🦋 PROPERTIES 🦋

There are no properties. That's it. Zero. Nada. The vibe check is empty, and honestly? Obsessed with the simplicity. 🦋

🔥 METHODS 🔥

💅 acceptNode 💅

Returns an unsigned short that will be used to tell if a given Node must be accepted or not by the HTML::Object::DOM::NodeIterator or HTML::Object::DOM::TreeWalker iteration algorithm.

This method is expected to be written by the user of a NodeFilter. (You're the main character here, bestie. 👑) Possible return values are:

  • FILTER_ACCEPT — value returned by the acceptNode method when a node should be accepted. Slay.
  • FILTER_REJECT — value to be returned by the acceptNode method when a node should be rejected. For HTML::Object::DOM::TreeWalker, child nodes are also rejected. For NodeIterator, this flag is synonymous with FILTER_SKIP.
  • FILTER_SKIP — value to be returned by acceptNode for nodes to be skipped by the HTML::Object::DOM::NodeIterator or HTML::Object::DOM::TreeWalker object. The children of skipped nodes are still considered. This is treated as "skip this node but not its children".

Example:

use HTML::Object::DOM::NodeFilter qw( :all );
my $nodeIterator = $doc->createNodeIterator(
    # Node to use as root
    $doc->getElementById('someId'),

    # Only consider nodes that are text nodes (nodeType 3)
    SHOW_TEXT,

    # Object containing the sub to use for the acceptNode method
    # of the NodeFilter
    { acceptNode => sub
        {
            my $node = shift( @_ ); # also available as $_
            # Logic to determine whether to accept, reject or skip node
            # In this case, only accept nodes that have content other than whitespace
            if( $node->data !~ /^\s*$/ )
            {
                return( FILTER_ACCEPT );
            }
        }
    },
    0 # false
);

# Show the content of every non-empty text node that is a child of root
my $node;
while( ( $node = $nodeIterator->nextNode() ) )
{
    say( $node->data );
}

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

🌈 CONSTANTS 🌈

  • SHOW_ALL (4294967295) — shows all nodes. All of them. Ate.
  • 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,
    { acceptNode => sub{ return( FILTER_ACCEPT ); } },
    0 # false
);
if( ( $nodeIterator->whatToShow & SHOW_ALL ) ||
    ( $nodeIterator->whatToShow & SHOW_COMMENT ) )
{
    # $nodeIterator will show comments
}
  • SHOW_CDATA_SECTION (8) — will always return nothing, because there is no support for xml documents.
  • SHOW_ENTITY_REFERENCE (16) — legacy, no more used. It's giving retired icon. 💀
  • 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.

And for the callback control:

  • FILTER_ACCEPT (1)
  • FILTER_REJECT (2)
  • FILTER_SKIP (3)

👑 AUTHOR 👑

Jacques Deguest <jack@deguest.jp> — author icon. 💖

⭐ SEE ALSO ⭐

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved

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

💖 That's the whole page, bestie. Source/version and date on deck: perl v5.42.2, 2026-02-15, and the manual is HTML::O...deFilter(3). Periodt. 🎀

📦 where this page comes from