NAME

XML::Filter::Dispatcher - Path based event dispatching with DOM support

SYNOPSIS

use XML::Filter::Dispatcher ;

## Using callbacks:
my $h = XML::Filter::Dispatcher->new(
    Rules => {   ## use [...] instead of {...} if order is important
        ## A small subset of XPath expressions can be used here
       '//foo'  => \&handle_foo_start_tag,
       '//@bar' => \&handle_bar_attr_at_start_tag,
   },
#       DOMBuilder => XML::LibXML::Filter::Builder->new() ;
);

DESCRIPTION

WARNING: Alpha code alert.

Allows a reasonable (IMHO) subset of XPath expressions to be mapped to handlers, Provides a stack mechanism for building output data structures. data structures easy. Inherits from the XML::SAX::Base module so it can be used as filter quite easily.

TODO: Provide an "auto-forward" feature that can be used to gate the output events so as to prune the tree.

WARNING: The documentation sucks and the API is likely to change.

Incremental XPath Dialect

Some of the features of XPath require that the source document be fully translated in to a tree of "nodes" before the features can be evaluated. (Nodes are things like elements, attributes, text, comments, processing instructions, namespace mappings etc).

These features are not supported and are not likely to be, you might want to use XML::Filter::XSLT for "full" XPath support (tho it be in an XSLT framework) or wait for XML::TWIG to be SAXed up.

Rather than build a DOM, XML::Filter::Dispatcher only keeps a bare minimum of nodes: the current node and it's parent, grandparent, and so on, up to the document ("root") node (basically the /ancestor-or-self:: axis). This is called the "context stack", although you may not need to know that term unless you delve in to the guts.

All of this means that only a portion of XPath is available. Luckily, that portion is also quite useful. Here are examples of working XPath expressions, followed by known unimplemented features.

TODO: There is also an extension function available to differentiate between start_... and end_... events. By default

Examples

Expression     Event Type      Description (event type)
==========     ==========      ========================
/              start_document  Selects the document node
/a             start_element   Root elt, if it's "<a ...>"
//a            start_element   All "a" elements
//b//c         start_element   All "c" descendants of "b" elt.s

Notes for XPath Afficianados

This section assumes familiarity with XPath in order to explain some of the particulars and side effects of the incremental XPath engine.

• Much of XPath's power comes from the concept of a "node set". A node set is a set of nodes returned by many XPath expressions. XML::Filter::Dispatcher treats node set expressions as boolean expressions: if the current event (node) would be in the node set returned by an expression in a "real" XPath processor, the expression is true and the handler runs.

• SAX does not define events for attributes; these are passed in to the start_element and (usually) end_element methods as part of the element node. XML::Filter::Dispatcher does allow selecting attribute nodes and passes in just the selected attribute node, see the examples above.

• Axes in path steps (/foo::...)

  Axes can be reasonably supported within a SAX framework to a varying degree without buffering of document nodes or queueing SAX events for in-document-order delivery.

  Axes

  self (yes)

  descendant (yes)

  descendant-or-self (yes)

  child (yes)

  attribute (yes)

  namespace (todo)

  ancestor (todo, will be limited)

  ancestor-or-self (todo, will be limited)

  parent (todo, will be limited)

  parent/ancestor paths will not allow you to descend the tree, that would require DOM building and SAX event queueing.

  preceding (no: reverse axis, would require DOM building)

  preceding-sibling (no: reverse axis, would require DOM building)

  following (no: forward axis, would require DOM building and rule activation queueing)

  following-sibling (no: forward axis, would require DOM building and rule activation queueing)

as_graphviz

binmode STDOUT,
print STDOUT $d->as_graphviz->as_png;

Charts the dispatcher's rule base. Creates huge graphs for all but trivial rule bases.

as_png

$d->as_png( "file.png" );
$d->as_png( ">file.png" );
$d->as_png( "| viewer_program" );
$d->as_png( "| cat > foo.png && png_viewer foo.png" );

Shorthand for printing as_graphviz_as_png to the file.

AUTHOR

Barrie Slaymaker <barries@slaysys.com>

COPYRIGHT

Copyright 2002, Barrie Slaymaker, All Rights Reserved.

You may use this module under the terms of the Artistic or GNU Pulic licenses your choice. Also, a portion of XML::Filter::Dispatcher::Parser is covered by:

The Parse::Yapp module and its related modules and shell scripts are
copyright (c) 1998-1999 Francois Desarmenien, France. All rights
reserved.

You may use and distribute them under the terms of either the GNU
General Public License or the Artistic License, as specified in the
Perl README file.

Note: Parse::Yapp is only needed if you want to modify lib/XML/Filter/Dispatcher/Grammar.pm