NAME

DOMHandler - Implements a call-back interface to DOM.

SYNOPSIS

  use DOMHandler;
  use XML::LibXML;
  $p = new XML::LibXML;
  $doc = $p->parse_file( 'data.xml' );
  $dh = new DOMHandler( handler_package => new testhandler );
  $dh->traverse( $doc );

  package testhandler;
  sub new {
      return bless {};
  }
  sub A {
      my( $self, $agent, $node ) = @_;
      my $par = $node->parentNode->nodeName;
      print "I'm in an A element and my parent is $par.\n";
  }
  sub generic_element {
      my( $self, $agent, $node ) = @_;
      my $name = $node->nodeName;
      print "I'm in an element named '$name'.\n";
  }
  sub generic_text {
      print "Here's some text.\n";
  }
  sub generic_PI {
      print "Here's a processing instruction.\n";
  }
  sub generic_CDATA {
      print "Here's a CDATA Section.\n";
  }

DESCRIPTION

This module creates a layer on top of DOM that allows you to program in a "push" style rather than "pull". Once the document has been parsed and you have a DOM object, you can call on the DOMHandler's traverse() method to apply a set of call-back routines to all the nodes in a tree. You supply the routines in a handler package when initializing the DOMHandler.

In your handler package, the names of routines determine which will be called for a given node. There are routines for node types, named "generic_" plus the node type. For elements, you can name routines after the element name and these will only be called for that type of element. A list of supported handlers follows:

else_generic_node()

Applied only to nodes that have not been handled by another routine.

generic_CDATA()

Applied to CDATA sections.

generic_comment()

Applied to XML comments.

generic_doctype()

Applied to DOCTYPE declarations.

generic_element()

Applied to all elements.

generic_node()

Applied to all nodes.

generic_PI()

Processing instruction

generic_text()

Applied to text nodes.

A handler routine takes three arguments: the $self reference, a reference to the DOMHandler object, and a reference to a node in the document being traversed. You can use DOM routines on that node to do any processing you want. At the moment, this module only supports XML::LibXML documents.

IMPORTANT NOTE: Some DOM operations may cause unwanted results. For example, if you delete the current node's parent, the program will likely crash.

METHODS

traverse( $doc )

Visits each node in a document, in order, applying the appropriate handler routines.

AUTHOR

Erik Ray (eray@oreilly.com), Production Tools Dept., O'Reilly and Associates Inc.

COPYRIGHT

Copyright (c) 2002 Erik Ray and O'Reilly & Associates.