<posted & mailed>

Hello,

This release includes a SAX2 parsing API.  I'm pretty excited about this 
addition, not because I like SAX2, but because this new API includes a lot 
of other syntactic sugar I've been meaning to add for a long time.  This 
new API does not affect compatibility with the older REXML streaming API, 
so none of the apps that use REXML for stream parsing need to change.

Pull this release from the usual place:

  http://www.germane-software.com/software/rexml

There are a number of things to note about this new API.  The first is that 
SAX2 will never be as fast as REXML's original streaming API.  This is 
because SAX2 requires a lot of processing before events are propagated, 
such as namespace resolution and so on.  If you have a need for speed, use 
the original API.  That said, check out the new API, because it is pretty 
slick.

Some of the things you can do with the new API:

  parser.listen( :characters, %w{ tag1 tag2 othertag } ) { |text|
    puts text
  }

prints out only the text from all "tag1", "tag2", and "othertag" elements in 
a document.

  parser.listen( listener )

Methods in "listener" are called for every event on the document, like the 
old REXML streaming API.

  parser.listen( %w{ a b c }, listener )

Call methods in "listener" for every event, but only for a, b, and c 
elements.

  parser.listen( %w{ x y } ) { |uri,prefix,qname,attributes|
     some_rexml_doc.add_element qname, attributes
  }
  parser.listen( %w{ a b }, listener )

For x and y elements in a document, add them and their attributes to some 
other document; do something more complex with all of the events of a and 
b.

In addition to the core SAX2 events, events are generated for DocType 
declarations as well.  The SAX2Listener API is comprehensive, and for every 
method in the listener API, a corresponding block event exists.

Also, I think I've discovered a way of drastically improving XPath parsing; 
if it works, a side effect will be that SAX2 will gain some limited XPath 
capabilities, for filtering.

A current limitation is that there is no mechanism for descendant matching; 
that is, in XPath terms, you can match "element", but not "element//*".  It 
is on the todo list.

This is a /really/ beta API, and I'm looking forward to feedback (and unit 
tests) from people who want to test it.  Similarly, I'm also looking for 
feedback to the pull parsing API.  I'd like to stabilize the Pull parser 
fairly quickly, if I can, because I'm considering some refactoring that 
would depend on that.

Next on the list are XPath improvements, bugfixes to these newest APIs, and 
continuing to improve DTD parsing.

Good luck, and have fun

--- SER