HTML::Object::DOM::NodeIterator - HTML Object DOM Node Iterator Class
With just one argument, this default to search for everything (SHOW_ALL) and to use the default filter, which always returns FILTER_ACCEPT
SHOW_ALL
FILTER_ACCEPT
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 an 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 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.
v0.2.0
The NodeIterator interface represents an iterator over the members of a list of the nodes in a subtree of the DOM. The nodes will be returned in document order.
NodeIterator
A NodeIterator can be created using the "createNodeIterator" in HTML::Object::DOM::Document method, as follows:
use HTML::Object::DOM; my $parser = HTML::Object::DOM->new; my $doc = $parser->parse_data( $some_html_data ) || die( $parser->error ); my $nodeIterator = $doc->createNodeIterator( $root, $whatToShow, $filter ) || die( $doc->error );
Normally this is read-only, but under perl you can set whatever boolean value you want.
Under JavaScript, this is a boolean value indicating if, when discarding an EntityReference its whole sub-tree must be discarded at the same time.
EntityReference
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 Mozilla documentation
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.
Returns a HTML::Object::DOM::NodeFilter used to select the relevant nodes.
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;
Normally this is read-only, but under perl you can set whatever boolean value you want. Defaults to true.
Returns a boolean flag that indicates whether the NodeIterator is anchored before, the flag being true, or after, the flag being false, the anchor node.
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 $flag = $nodeIterator->pointerBeforeReferenceNode;
Read-only.
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.
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 ); }, );
Returns the Node to which the iterator is anchored.
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 $node = $nodeIterator->referenceNode;
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.
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
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:
Shows all nodes.
Shows Element nodes.
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.
Shows Text nodes.
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 }
Will always returns nothing, because there is no support for xml documents.
Legacy, no more used.
Shows ProcessingInstruction nodes.
Shows Comment nodes.
Shows Document nodes
Shows DocumentType nodes
DocumentType
Shows HTML::Object::DOM::DocumentFragment nodes.
Show Space nodes. This is a non-standard extension under this perl framework.
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.
This operation is a no-op. It does not do anything. Previously it was telling the web browser engine that the NodeIterator was no more used, but this is now useless.
Returns the next Node in the document, or undef if there are none.
undef
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
Returns the previous Node in the document, or undef if there are none.
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
Jacques Deguest <jack@deguest.jp>
Mozilla documentation, StackOverflow topic on NodeIterator, W3C specifications
Copyright(c) 2021 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.
To install HTML::Object, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::Object
CPAN shell
perl -MCPAN -e shell install HTML::Object
For more information on module installation, please visit the detailed CPAN module installation guide.