XML::NodeFilter 0.01 review

XML::NodeFilter is a generic XML::NodeFilter Class. SYNOPSIS use XML::NodeFilter; my $filter = XML::NodeFilter->new();

License: Perl Artistic License File size: 6K Developer: Christian Glahn

0

XML::NodeFilter is a generic XML::NodeFilter Class.

SYNOPSIS

use XML::NodeFilter;

my $filter = XML::NodeFilter->new();

$your_iterator->set_filter( $filter );

"Filters are objects that know how to "filter out" nodes. If a NodeIterator or a TreeWalker is given a NodeFilter, it applies the filter before it returns the next node. If the filter says to accept the node, the traversal logic returns it; otherwise, traversal looks for the next node and pretends that the node was rejected was not there."

This definition is given by the DOM Traversal and Range Specification. It explains pretty well, what this class is for: A XML::NodeFilter will recieve a node from a traversal object, such as XML::LibXML::Iterator is one and tells if the given node should be returned to the caller or not.
Although I refere only to XML::LibXML here, XML::NodeFilter is implemented more open, so it can be used with other DOM implementations as well.

The Spec And The Implementation

The DOM Traversal and Range Specification just defines the contstants and accept_node() for a node filter. The XML::NodeFilter implementation also adds the what_to_show() function to the class definition, since I think that it is a filters job to decide which node-types should be shown and which not.

Also XML::NodeFilter adds two constants which are not part of the specification. The first one is FILTER_DECLINED. It tells the traversal logic, that it should apply another filter in order to decide if the node should be visible or not. While the spec only defines the traversal logic to have either one or no filter applied, it showed that it leads to cleaner code if more filter could be used in conjunktion. If a traversal logic finds a single filter that returns FILTER_DECLINED, it should be handled as a synonym of FILTER_ACCEPT. While FILTER_ACCEPT is finite and would cause all other not to be executed, FILTER_DECLINED gives one more flexibility.

The second extension of the specification is the SHOW_NONE symbol. It was added for operational completeness, so one can explicitly switch the node type filter off (means all node types are rejected). This will cause the two calls of what_to_show have a different result:

$filter->what_to_show( undef ); # will set SHOW_ALL
$filter->what_to_show( SHOW_NONE ); # will not set SHOW_ALL

Infact SHOW_NONE is a NULL flag, that means it can be added to any list of flags without altering it.

$filter->what_to_show( SHOW_ELEMENT | SHOW_TEXT | SHOW_NONE );

is therefore identical to

$filter->what_to_show( SHOW_ELEMENT | SHOW_TEXT );

SHOW_NONE is espacially usefull to avoid numerically or even more ugly unintialized values while building such flag lists dynamically.

Requirements:
Perl