<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/css"
href="http://www.germane-software.com/svn/repos/documentation/documentation.css"
?>
<?xml-stylesheet type="text/xsl"
href="http://www.germane-software.com/svn/repos/documentation/documentation.xsl"
?>
<!DOCTYPE documentation SYSTEM "http://www.germane-software.com/svn/repos/documentation/documentation.dtd">
<documentation>
  <head>
    <title>REXML</title>

    <banner href="img/rexml.png" />

    <version>2.3.5</version>

    <date>*2002-159</date>

    <home>http://www.germane-software.com/software/rexml</home>

    <base>rexml</base>

    <archive type="unix" version="2.2.2">Stable release</archive>

    <archive type="dos" version="2.2.2">Stable release</archive>

    <archive type="unix">Current release</archive>

    <archive type="dos">Current release</archive>

    <language>ruby</language>

    <author jabber="ser@jabber.com"
    href="http://www.germane-software.com/~ser"
    email="ser@germane-software.com">Sean Russell</author>
  </head>

  <overview>
    <purpose lang="en">
      <p>REXML is an XML processor for the language Ruby. REXML is conformant
      (passes 100% of the Oasis non-validating tests), and includes full XPath
      support. It is reasonably fast, and is implemented in pure Ruby. Best of
      all, it has a clean, intuitive API.</p>

      <p>This software is distribute under the <link href="LICENSE.txt">Ruby
      license</link>.</p>
    </purpose>

    <general>
      <p>Why REXML? There, at the time of this writing, already two XML
      parsers for Ruby. The first is a Ruby binding to a native XML parser.
      This is a fast parser, using proven technology. However, it isn&#39;t
      very portable. The second is a native Ruby implementation, and as useful
      as it is, it has (IMO) a difficult API.</p>

      <p>I have this problem: I dislike obfuscated APIs. There are several XML
      parser APIs for Java. Most of them follow DOM or SAX, and are very
      similar in philosophy with an increasing number of Java APIs. Namely,
      they look like they were designed by theorists who never had to use
      their own APIs. The extant XML APIs, in general, suck. They take a
      markup language which was specifically designed to be very simple,
      elegant, and powerful, and wrap an obnoxious, bloated, and large API
      around it. I was always having to refer to the API documentation to do
      even the most basic XML tree manipulations; nothing was intuitive, and
      almost every operation was complex.</p>

      <p>Then along came Electric XML.</p>

      <p>Ah, bliss. Look at the Electric XML API. First, the library is small;
      less than 500K. Next, the API is intuitive. You want to parse a
      document? <code>doc = new Document( some_file )</code>. Create and add a
      new element? <code>element = parent.addElement( tag_name )</code>. Write
      out a subtree?? <code>element.write( writer )</code>. Now how about DOM?
      To parse some file: <pre>parser = new DOMParser();
parser.parse( new InputSource( new FileInputStream( some_file ) ) )</pre>
      Create a new element? First you have to know the owning document of the
      to-be-created node (can anyone say &#34;global variables, or obtuse,
      multi-argument methods&#34;?) and call <pre>element = doc.createElement( tag_name )
parent.appendChild( element )</pre> &#34;appendChild&#34;? Where did they get
      that from? How many different methods do we have in Java in how many
      different classes for adding children to parents? <code>addElement()</code>?
      <code>add()</code>? <code>put()</code>? <code>appendChild()</code>?
      Heaven forbid that you want to create an Element elsewhere in the code
      without having access to the owning document. I&#39;m not even going to
      go into what travesty of code you have to go through to write out an XML
      sub-tree in DOM.</p>

      <p>So, I use Electric XML extensively. It is small, fast, and intuitive.
      IE, the API doesn&#39;t add a bunch of work to the task of writing
      software. When I started to write more software in Ruby, I needed an XML
      parser. I wasn&#39;t keen on the native library binding,
      &#34;XMLParser&#34;, because I try to avoid complex library dependancies
      in my software, when I can. For a long time, I used NQXML, because it
      was the only other parser out there. However, the NQXML API can be even
      more painful than the Java DOM API. Almost all element operations
      requires accessing some indirect node access... you had to do something
      like element.node.attr[&#39;key&#39;], and it is never obvious to me
      when you access the element directly, or the node.. or, really, why
      they&#39;re two different objects, anyway. This is even more unfortunate
      since Ruby is so elegent and intuitive, and bad APIs really stand out.
      I&#39;m not, by the way, trying to insult NQXML; I just don&#39;t like
      the API.</p>

      <p>I wrote the people at TheMind (Electric XML... get it?) and asked
      them if I could do a translation to Ruby. They said yes. After a few
      weeks of hacking on it for a couple of hours each week, and after having
      gone down a few blind alleys in the translation, I had a working beta.
      IE, it parsed, but hadn&#39;t gone through a lot of strenuous testing.
      Along the way, I had made a few changes to the API, and a lot of changes
      to the code. First off, Ruby does iterators differently than Java. Java
      uses a lot of helper classes. Helper classes are exactly the kinds of
      things that theorists come up with... they look good on paper, but using
      them is like chewing glass. You find that you spend 50% of your time
      writing helper classes just to support the other 50% of the code that
      actually does the job you were trying to solve in the first place. In
      this case, the Java helper classes are either Enumerations or Iterators.
      Ruby, on the other hand, uses blocks, which is much more elegant. Rather
      than:</p>

      <example>for (Enumeration e=parent.getChildren(); e.hasMoreElements(); ) {
   Element child = (Element)e.nextElement();
   // Do something with child
}</example>

      <p>you get:</p>

      <example>parent.each_child{ |child| # Do something with child }</example>

      <p>Can&#39;t you feel the peace and contentment in this block of code?
      Ruby is the language Buddha would have programmed in.</p>

      <p>Anyhoo, I chose to use blocks in REXML directly, since this is more
      common to Ruby code than <code>for x in y ... end</code>, which is as
      orthoganal to the original Java as possible.</p>

      <p>Also, I changed the naming conventions to more Ruby-esque method
      names. For example, the Java method <code>getAttributeValue()</code>
      becomes in Ruby <code>get_attribute_value()</code>. This is a toss-up. I
      actually like the Java naming convention more<footnote>This is no longer
      true. I&#39;m a convert to the Ruby naming scheme, for Ruby. The reason
      being that Ruby does a superb job of hiding the difference between
      attributes and methods; in fact, for all intents and purposes, you
      <em>can&#39;t</em> access attributes directly; all attribute accessors
      are methods. What this means in the long run is that there is no reason
      to have different naming conventions for attributes and methods.</footnote>,
      but the latter is more common in Ruby code, and I&#39;m trying to make
      things easy for Ruby programmers, not Java programmers.</p>

      <p>The biggest change was in the code. The Java version of Electric XML
      did a lot of efficient String-array parsing, character by character.
      Ruby, however, has ubiquitous, efficient, and powerful regular
      expression support. All regex functions are done in native code, so it
      is very fast, and the power of Ruby regex rivals that of Perl.
      Therefore, a direct conversion of the Java code to Ruby would have been
      more difficult, and much slower, than using Ruby regexps. I therefore
      used regexs. In doing so, I cut the number of lines of sourcecode by
      half.</p>

      <p>Finally, by this point the API looks almost nothing like the original
      Electric XML API, and practically none of the code is even vaguely
      similar. However, even though the actual code is completely different, I
      did borrow the same process of processing XML as Electric, and am deeply
      indebted to the Electric XML code for inspiration.</p>

      <p>One last thing. If you use and like this software, and you feel
      compelled to make some contribution to the author by way of saying
      &#34;thanks&#34;, and you happen to know what a tea cozy is and where to
      get them, then you can send me one. Send those puppies to: <pre>Sean Russell
60252 Rimfire Rd.
Bend, OR 97702
USA</pre> If you&#39;re outside of the US, make sure you write &#34;gift&#34;
      on it to avoid the taxes. If you don&#39;t want to send a tea cozy, you
      can also send money. Or don&#39;t send anything. Offer me a job I
      can&#39;t refuse, in Western Europe somewhere.</p>
    </general>

    <features lang="en">
      <item>Four intuitive parsing APIs.</item>

      <item>Intuitive, powerful, and reasonably fast tree parsing API (a-la
      DOM<footnote>Be aware, however, that REXML does not have a DOM API.</footnote></item>

      <item>Fast stream parsing API (a-la SAX)<footnote>This is not a SAX API.</footnote></item>

      <item>SAX2-based API<footnote>In addition to the native REXML streaming
      API. This is slower than the native REXML API, but does a lot more work
      for you.</footnote></item>

      <item>Pull parsing API.</item>

      <item>Small</item>

      <item>Reasonably fast</item>

      <item>Native Ruby</item>

      <item>Full XPath support<footnote>Currently only available for the tree
      API</footnote></item>

      <item>XML 1.0 conformant<footnote>REXML passes all of the non-validating
      OASIS tests. There are probably places where REXML isn&#39;t conformant,
      but I try to fix them as they&#39;re reported.</footnote></item>

      <item>ISO-8859-1, UNILE, UTF-16 and UTF-8 input and output</item>

      <item>Documentation</item>
    </features>
  </overview>

  <operation lang="en">
    <subsection title="Installation">
      <p>Run <code>ruby bin/install.rb</code>. By the way, you really should
      look at these sorts of files before you run them as root. They could
      contain anything, and since (in Ruby, at least) they tend to be
      mercifully short, it doesn&#39;t hurt to glance over them. If you want
      to uninstall REXML, run <code>ruby bin/install.rb -u</code>.</p>
    </subsection>

    <subsection title="Unit tests">
      <p>If you have Test::Unit installed, you can run the unit test cases.
      You can run both installed and not installed tests; to run the tests
      before installing REXML, run <code>ruby -I. bin/suite.rb</code>. To run
      them with an installed REXML, use <code>ruby bin/suite.rb</code>.</p>
    </subsection>

    <subsection title="Benchmarks">
      <p>There is a benchmark suite in <code>benchmarks/</code>. To run the
      benchmarks, change into that directory and run <code>ruby comparison.rb</code>.
      If you have nothing else installed, only the benchmarks for REXML will
      be run. However, if you have any of the following installed, benchmarks
      for those tools will also be run:</p>

      <list>
        <item>NQXML</item>

        <item>XMLParser</item>

        <item>Electric XML (you must copy <code>EXML.jar</code> into the
        <code>benchmarks</code> directory and compile <code>flatbench.java</code>
        before running the test)</item>
      </list>

      <p>The results will be written to <code>index.html</code>.</p>
    </subsection>

    <subsection title="General Usage">
      <p>Please see <link href="docs/tutorial.html">the Tutorial</link>.</p>

      <p>The API documentation is available <link
      href="http://www.germane-software.com/software/rexml_doc">on-line</link>,
      or it can be downloaded as an archive <link
      href="http://www.germane-software.com/software/archives/rexml_api_2.3.5.tbz2">in
      tbz2 format (~40Kb)</link>, <link
      href="http://www.germane-software.com/software/archives/rexml_api_2.3.5.tgz">in
      tgz format (~70Kb)</link>, or (if you&#39;re a masochist) <link
      href="http://www.germane-software.com/software/archives/rexml_api_2.3.5.zip">in
      zip format (~280Kb)</link>. The best solution is to download and install
      Dave Thomas&#39; most excellent <link href="http://rdoc.sourceforge.net">rdoc</link>
      and generate the API docs yourself; then you&#39;ll be sure to have the
      latest API docs and won&#39;t have to keep downloading the doc archive.</p>

      <p>The unit tests in <code>test/</code> and the benchmarking code in
      <code>benchmark/</code> provide additional examples of using REXML. The
      Tutorial provides examples with commentary. The documentation unpacks
      into <link href="doc/index.html"><code>rexml/doc</code></link>.</p>

      <p>Kouhei Sutou maintains a <link
      href="http://www.germane-software.com/software/rexml_doc_ja/current/index.html">Japanese
      version</link> of the REXML 2.2.2 API docs. The Japanese API
      documentation is also available for download as a <link
      href="http://www.germane-software.com/software/archives/rexml_api_ja_2_2_2.tar.gz">gzipped
      tarball</link>, a <link
      href="http://www.germane-software.com/software/archives/rexml_api_ja_2_2_2.tar.bz2">bzipped
      tarball (smallest)</link>, or a <link
      href="http://www.germane-software.com/software/archives/rexml_api_ja_2_2_2.zip">zip
      file (largest)</link>.</p>
    </subsection>
  </operation>

  <status>
    <subsection title="Speed and Completeness">
      <p>Unfortunately, NQXML is the only package REXML can be compared
      against; XMLParser uses expat, which is a native library, and really is
      a different beast altogether. So in comparing NQXML and REXML you can
      look at four things: speed, size, completeness, and API.</p>

      <p><link href="benchmarks/index.html">Benchmarks</link></p>

      <p>REXML is faster than NQXML in some things, and slower than NQXML in a
      couple of things. You can see this for yourself by running the supplied
      benchmarks. Most of the places where REXML are slower are because of the
      convenience methods<footnote>For example, <code>element.elements[index]</code>
      isn&#39;t really an array operation; index can be an Integer or an
      XPath, and this feature is relatively time expensive.</footnote>. On the
      positive side, most of the convenience methods can be bypassed if you
      know what you are doing. Check the <link href="benchmarks/index.html">
      benchmark comparison page</link> for a <em>general</em> comparison. You
      can look at the benchmark code yourself to decide how much salt to take
      with them.</p>

      <p>The sizes of the XML parsers are close<footnote>As measured with
      <code>ruby -nle &#39;print unless /^\s*(#.*|)$/&#39; *.rb | wc -l</code>
      </footnote>. NQXML 1.1.3 has 1580 non-blank, non-comment lines of code;
      REXML 2.0 has 2340<footnote>REXML started out with about 1200, but that
      number has been steadily increasing as features are added. XPath
      accounts for 541 lines of that code, so the core REXML has about 1800
      LOC.</footnote>.</p>

      <p>REXML is a conformant XML 1.0 parser. It supports multiple language
      encodings, and internal processing uses the required UTF-8 and UTF-16
      encodings. It passes 100% of the Oasis non-validating tests.
      Furthermore, it provides a full implementation of XPath, a SAX2 and a
      PullParser API.</p>

      <p>The last thing is the API, and this is where I think REXML wins. The
      core API is clean and intuitive, and things work the way you would
      expect them to. Convenience methods abound, and you can code for either
      convenience or speed. REXML code is terse, and readable, like Ruby code
      should be. The best way to decide which you like more is to write a
      couple of small applications in each, then use the one you&#39;re more
      comfortable with.</p>
    </subsection>

    <subsection title="XPath">
      <p>As of release 2.0, XPath 1.0 is fully implemented.</p>

      <p>I fully expect bugs to crop up from time to time, so if you see any
      bogus XPath results, please let me know. That said, since I&#39;m now
      following the XPath grammar and spec fairly closely, I suspect that you
      won&#39;t be surprised by REXML&#39;s XPath very often, and it should
      become rock solid fairly quickly.</p>

      <p>Check the &#34;bugs&#34; section for known problems; there are little
      bits of XPath here and there that are not yet implemented, but I&#39;ll
      get to them soon.</p>

      <p>Namespace support is rather odd, but it isn&#39;t my fault. I can
      only do so much and still conform to the specs. In particular, XPath
      attempts to help as much as possible. Therefore, in the trivial cases,
      you can pass namespace prefixes to Element.elements[...] and so on -- in
      these cases, XPath will use the namespace environment of the base
      element you&#39;re starting your XPath search from. However, if you want
      to do something more complex, like pass in your own namespace
      environment, you have to use the XPath first(), each(), and match()
      methods. Also, default namespaces <em>force</em> you to use the XPath
      methods, rather than the convenience methods, because there is no way
      for XPath to know what the mappings for the default namespaces should
      be. This is exactly why I loath namespaces -- a pox on the person(s) who
      thought them up!</p>
    </subsection>

    <subsection title="Namespaces">
      <p>Namespace support is now fairly stable. One thing to be aware of is
      that REXML is not (yet) a validating parser. This means that some
      invalid namespace declarations are not caught.</p>
    </subsection>

    <subsection title="Mailing list">
      <p>There is a low-volume mailing list dedicated to REXML. To subscribe,
      send an empty email to <link
      href="mailto:ser-rexml-subscribe@germane-software.com">ser-rexml-subscribe@germane-software.com</link>.
      This list is more or less spam proof. To unsubscribe, similarly send a
      message to <link
      href="mailto:ser-rexml-unsubscribe@germane-software.com">ser-rexml-unsubscribe@germane-software.com</link>.</p>
    </subsection>

    <subsection title="RSS">
      <p>An <link
      href="http://www.germane-software.com/software/rexml/rss.xml">RSS file</link>
      for REXML is now being generated from the change log. This allows you to
      be alerted of upgrades via &#39;pull&#39; as they become available, if
      you have an RSS browser. This is an abuse of the RSS mechanism, which
      was intended to be a distribution system for headlines linked back to
      full articles, but it works. The headline for REXML is the version
      number, and the description is the change log. The links all link back
      to the REXML home page. The URL for the RSS itself is
      http://www.germane-software.com/software/rexml/rss.xml</p>

      <p>For those who are interested, there&#39;s a <link
      href="docs/sloccount.txt">SLOCCount</link> (by David A. Wheeler) file
      with stats on the REXML sourcecode. Note that the SLOCCount output
      includes the files in the test/, benchmarks/, and bin/ directories, as
      well as the main sourcecode for REXML itself.</p>
    </subsection>

    <subsection title="Applications that use REXML">
      <list>
        <item>Hiroshi NAKAMURA&#39;s <link
        href="http://www.ruby-lang.org/en/raa-list.rhtml?name=SOAP4R">SOAP4R</link>
        package can use REXML as the XML processor.</item>

        <item>Chris Morris&#39; <link href="http://clabs.org/clxmlserial.htm">XML
        Serializer</link>. XML Serializer provides a serialization mechanism
        for Ruby that provides a bidirectional mapping between Ruby classes
        and XML documents.</item>

        <item>Much of the <link href="http://www.rubyxml.com">RubyXML</link>
        site is generated with scripts that use REXML. RubyXML is a great
        place to find information about th intersection between Ruby and XML.</item>

        <item><link href="http://www.pinkjuice.com/ruby/jelly/">Jelly</link>
        is a generic utility for generating Ruby libs (XML writers) from W3C
        XML schemas.</item>
      </list>
    </subsection>

    <changelog>
      <item version="2.3.5"><list><item>Fixed a bug that caused text
      containing &#62; to be split into two text nodes. This incurred a speed
      penalty, but I&#39;ll try to improve that later.</item><item>Added a bug
      tracking system.</item><item>Fixed a comment parsing bug.</item><item>Mike
      Stok fixed Functions#translate and cleaned up some cruft that slipped
      through in Functions#substring.</item><item>Fixed a bug in
      Element#prefixes, and fixed Attributes#prefixes to use DOCTYPE declared
      namespaces. Added DocType#attributes_of(Element).</item><item>Fixed a
      bug in writing Attlist declarations.</item><item>Added AttlistDecl#each;
      AttlistDecl now includes Enumerable</item><item>Fixed Functions#name and
      Functions#local_name; fixed unit test.</item><item>Fixed a bug re.
      functions w/in predicates in XPath</item><item>Fixes for Child#parent=()</item><item>Fixes
      and speed improvement for creating Text nodes</item><item>SAX2Parser bug
      fixes</item><item>Added dist.xml and an ant build file</item><item>Tom
      sent a new version of his pretty printer</item><item>Kouhei has a new
      version of his Japanese API documentation translation online</item></list></item>

      <item version="2.3.4">Fixed a bug in XPath that kept non-Element nodes
      from being returned from recursive paths. This had a side effect of
      speeding up XPath recursions. Fixed a bug in Document WRT text outside
      of the document. Added peek and unshift methods to the PullParser API.
      XPath methods now accept an array of nodes in addition to a single node.
      Fixed a bug in Functions::string(). Changed the unit tests to the
      Test::Unit platform. This allows the unit tests to be run under a GUI.
      More Function fixes (substring) by Mike Stok. There was a major bug in
      XPath handling of math operations, which is fixed. Strings pulled from
      IO streams are now tainted. Lots of bug fixes in PullParser -- it now
      passes 100% of the Oasis tests. Bug fix for stream parsing in Entity.
      Bug fixes in DocType -- SAX2Parser now passes 100% of Oasis tests. REXML
      now processes internal ATTLIST declarations in the doctype. This
      includes processing of XML namespaces in the doctype. Changed pretty
      printing. Whitespace is now never added around Text nodes, and
      there&#39;s a new context property, :ignore_whitespace_nodes.
      There&#39;s also a new transitive pretty printer, obtained by passing
      &#39;true&#39; as the third argument to write().</item>

      <item version="2.3.3">Added an alternate pretty printer by Thomas
      Sawyer; it is in the contrib/ directory. Speed optimizations; REXML is
      noticably faster now. In particular, PullParser is now just as fast as
      Stream parsing (10x speed increase over first version). Fixed a bug in
      Element.add_namespace. Fixed a problem that occurred on some systems
      with Entities. <em>News:</em> Kouhei Sutou has done a Japanese
      translation of the REXML API docs. See the section in the main REXML
      page about the API documentation for links. Mike Stock fixed a bug in
      the starts_with XPath function. Added, on request, methods to Element to
      filter children on type. cdatas(), instructions(), comments(), and
      texts() now return immutable arrays of only those child nodes.</item>

      <item version="2.3.2">Added a (more or less) SAX2 conforming parser.
      Really, this and the pull parser are just a thin layer over the legacy
      REXML stream parser, and you&#39;ll get better results with the original
      API. The best thing about this (and the primary reason I did it this
      way) is that REXML maintains backward compatibility with the old Stream
      API. After I play with pure pull parsing some more, I may decide to
      reimplement stream parsing on top of pull parsing, but it shouldn&#39;t
      affect SAX2 in any way. The SAX2 parser is slower primarily because SAX2
      requires the parser to do a lot more work -- resolving namespaces and so
      on -- so while I know I can improve the speed some, SAX2 will <em>never</em>
      be as fast as REXML vanilla stream parsing. That said, the SAX2 API is
      pretty nice, and includes all of those stream API changes I wanted to
      get in, except for filter parsing. Check out the tutorial for usage
      information.</item>

      <item version="2.3.1">Added a pull parser. This is VERY experimental,
      and the API is likely to change.</item>

      <item version="2.3.0">Internal entities are now handled<footnote>Please
      note that entity handling complicates text manipulation. See the note in
      the tutorial</footnote>. Speed has been further improved for most
      operations, but especially for stream parsing, writing, and large
      document parsing.</item>

      <item version="2.2.1">Fixed a bug in benchmark/bench.rb that kept it
      from running. Added stand_alone?() to XMLDecl as an alias for the
      standalone accessor. Improvements to the streaming API; in particular,
      pulling data from non-closing streams doesn&#39;t require passing a
      block size of 1 to the IOSource class any longer; in fact, the block
      size is ignored. Added a user-supplied patch to fix the fact that not
      all of the DTD events were getting passed to the listener. Improved
      entity parsing. Better test suite; you can now pass <code>--help</code>
      to the main test suite to get a list of the new options, which include
      listing the available suites and listing methods in the suites, as well
      as instructions on how to run only certain suites or methods in suites.</item>

      <item version="2.1.3">Fixed broken links in documentation. Added new
      documentation layout; the old format -- everything on one page -- was
      getting a bit overwhelming. Added RSS for changelog. Bugfix for element
      cloning namespace loss. The Streaming API wasn&#39;t normalizing input
      strings; this has been fixed. Added support for deep cloning via
      Parent.deep_clone(). Fixed some streaming issues for SOAP4RUBY. In
      particular, text normalization is now also done for the Streaming API.
      &#39;\r&#39; handling is now correct, as per the XML spec, and entities
      are handled better. &#38;#13; is now converted to &#39;\r&#39;
      internally, and then translated back to &#39;\r&#39; on output. All
      other numeric entities (&#38;#nnn; and &#38;#xnnn;) are now converted to
      unicode on input, but are only converted back to entities if they
      don&#39;t fit in the requested encoding.</item>

      <item version="2.1.2">Fixed a bug with reading ISO-8859-1 encoded
      documents, and Document now includes Output, which it always should
      have.</item>

      <item version="2.1.1">Forgot to add output.rb to the repository.</item>

      <item version="2.1.0">IO optimizations, and support for ISO-8859-1
      output. Fixed up pretty-printing a little. Now, if pretty-printing is
      turned on, text nodes are stripped before printing. This, obviously, can
      mess up what you&#39;d expect from :respect_whitespace, but pretty
      printing, by definition, must change your formatting. Updated the
      tutorial a bit. Please see the section on adding text for a warning, if
      you&#39;re using a non-UTF-8 compatable encoding. Changed behavior of
      <code>Element.attributes.each</code>. It now itterates over key, value
      pairs, rather than attributes. This was a feature request. Expanded the
      unit tests and subsequently fixed a number of obscure bugs. I&#39;m
      distributing the API documentation seperately from the main distribution
      now, because the API docs constitute nearly 50% of the total
      distribution size. FIxed a bug in namespace handling in attributes.
      Completely updated the API documentation for Element, Element.Elements,
      and Element.Attributes; the rest of the classes to follow. I&#39;m
      seriously contemplating removing the examples from the API
      documentation, because most of them are practically duplicates of the
      unit tests in <code>test/</code>.</item>

      <item version="2.0.4">2.0 munged the encoding value in output. This is
      fixed. I left debugging turned on in XPath in 2.0.2 :-/</item>

      <item version="2.0.2">Added grouping &#39;(...)&#39; and preceding:: and
      following:: axis. This means that, aside from functional bugs, XPath
      should have no missing functionality bugs. Keep in mind that not all
      Functions are tested, though.</item>

      <item version="2.0.1">Added some unit tests, and fixed a namespace XPath
      bug WRT attribute default NS&#39;s. Unicode support was screwing up the
      upper end of ASCII support; chars between 0xF0 and 0xFD were getting
      munged. This has been fixed, at the cost of a small amount of speed.
      Optimized the descendant axes of XPath; it should be significantly
      faster for &#39;//&#39; and other descendant operations. Added several
      user contributed unit tests. Re-added QuickPath, the old,
      non-fully-XPath compliant, yet much faster, XPath processor. Everything
      is being converted to UTF8 now, and the XML declaration reflects this.
      See the bugs for more information.</item>

      <item version="2.0">True XPath support. Finally. XPath is fully
      implemented now, and passes all of the tests I can throw at it,
      including complex XPaths such as <code>&#39;*[* and not(*/node()) and
      not(*[not(@style)]) and not(*/@style != */@style)]&#39;</code>. It may
      be slower than it was, but it should be reasonably efficient for what it
      is doing. The XPath spec doesn&#39;t help, and thwarts most attempts at
      optimization. Please see the notes on XPath for more information. Oh,
      and some minor bugs were fixed in the XML parser.</item>

      <item version="1.2.8">Fixed a bug pointed out by Peter Verhage where the
      element names weren&#39;t being properly parsed if a namespace was
      involved.</item>

      <item version="1.2.7">Fixing problems with the 1.2.6 distribution :-/.
      Added an &#34;applications using REXML&#34; section in this document --
      send me those links! Added rdoc documentation. I&#39;m not using API2XML
      anymore. I think API2XML was the right model, generating XML rather than
      HTML (which is what rdoc does), but rdoc does a much better job at
      parsing Ruby source, and I really didn&#39;t want to go there in the
      first place. Also, I had forgotten to generate the Tutorial HTML.</item>

      <item version="1.2.6">Documentation fix (TR). Fixed a bug in Element.add
      (and, therefore, Element.add_element). Added Robert Feldt&#39;s terse
      xml constructor to contrib/ (check it out; it&#39;s handy). Tobias
      discovered a terrible bug, whereby ENTITY wasn&#39;t printing out a
      final &#39;&#62;&#39;. After a long discussion with a couple of users,
      and some review of the XML spec, I decided to reverse the default
      handling of whitespace and pretty printing. REXML now no longer defaults
      to pretty printing, and preserves whitespace unless otherwise directed.
      Added provisional namespace support to XPath. XPath is going to require
      another rewrite.</item>

      <item version="1.2.5">Bug fixes: doctypes that had spaces between the
      closing ] and &#62; generated errors. There was a small bug that caused
      too many newlines to be generated in some output. Eelis van der Weegen
      (what a great name!) pointed out one of the numerous API errors. Julian
      requested that add_attributes take both Hash (original) and array of
      arrays (as produced by StreamListener). I killed the mailing list,
      accidentally, and fixed it again. Fixed a bug in next_sibling, caused by
      a combination of mixing overriding &#60;=&#62;() and using
      Array.index().</item>

      <item version="1.2.4">Changes since 1.1b: 100% OASIS valid tests passed.
      UTF-8/16 support. Many bug fixes. to_a() added to Parent and
      Element.elements. Updated tutorial. Added variable IOSource buffer size,
      for stream parsing. delete() now fails silently rather than throwing an
      exception if it can&#39;t find the elemnt to delete. Added a patch to
      support REXMLBuilder. Reorganized file layout in distribution; added a
      repackaging program; added the logo.</item>

      <item version="1.1b">Changes since 1.1a: Stream parsing added. Bug fixes
      in entity parsing. New XPath implementation, fixing many bugs and making
      feature complete. Completed whitespace handling, adding much
      functionality and fixing several bugs. Added convenience methods for
      inserting elememnts. Improved error reporting. Fixed attribute content
      to correctly handle quotes and apostrophes. Added mechanisms for
      handling raw text. Cleaned up utility programs (profile.rb,
      comparison.rb, etc.). Improved speed a little. Brought REXML up to 98.9%
      OASIS valid source compliance.</item>
    </changelog>

    <bugs lang="en">
      <p>You can submit bug reports and feature requests, and view the list of
      known bugs, at the <link
      href="http://www.germane-software.com/cgi-bin/rexml">REXML bug report
      page.</link> Please do submit bug reports. If you really want your bug
      fixed fast, include an runit or Test::Unit method (or methods) that
      illustrates the problem. At the very least, send me some XML that REXML
      doesn&#39;t process properly.</p>

      <p>You don&#39;t have to send an entire test suite -- just the unit test
      methods. If you don&#39;t send me a unit test, I&#39;ll have to write
      one myself, which will mean that your bug will take longer to fix.</p>

      <p>When submitting bug reports, please include the version of Ruby and
      of REXML that you&#39;re using, and the operating system you&#39;re
      running on. Just run: <code>ruby -vrrexml/rexml -e &#39;p
      REXML::Version,PLATFORM&#39;</code> and paste the results in your bug
      report.</p>

      <item>Some of the XPath <em>functions</em> are untested<footnote>Mike
      Stok has been testing, debugging, and implementing some of these
      Functions (and he&#39;s been doing a good job) so there&#39;s steady
      improvement in this area.</footnote>. Any XPath functions that don&#39;t
      work are also bugs... please report them. If you send a unit test that
      illustrates the problem, I&#39;ll try to fix the problem within a couple
      of days (if I can) and send you a patch, personally.</item>

      <item>Accessing prefixes for which there is no defined namespace in an
      XPath should throw an exception. It currently doesn&#39;t -- it just
      fails to match.</item>
    </bugs>

    <todo lang="en">
      <item>Absolute XPaths attribute for nodes</item>

      <item status="request">XQuery support</item>

      <item status="request">Japanese encoding support for REXML</item>

      <item>Make sure namespaces are supported in pull parser</item>

      <item status="request">Add document start and entity replacement events
      in pull parser</item>

      <item>RPM-ify REXML</item>

      <item>Add XPath support for streaming APIs (depends on absolute XPaths)</item>

      <item>Better stream parsing exception handling</item>

      <item>I had a dream the other night about how to speed up XPath
      considerably; I&#39;ll have to do some testing to see if it would
      actually work, but I have high hopes. (depends on absolute XPaths)</item>

      <item>True DTD handling (in progress)</item>

      <item>I&#39;d like to hack XMLRPC4R to use REXML, for my own purposes.</item>

      <item status="fixed">Bug report submission mechanism</item>

      <item status="fixed">RFC/RCR on the REXML page</item>

      <item status="fixed">Allow the user to add entity conversions</item>

      <item status="fixed">Support internal DocType ATTLIST processing
      (required)</item>

      <item status="fixed">Run the streaming and pull parsing APIs against the
      OASIS tests</item>

      <item status="fixed">Link to Kouhei&#39;s translated documentation.</item>

      <item status="fixed">Extend pretty printing. First, make transitive
      pretty printing an option. Second, make sure that whitespace isn&#39;t
      added around/to Text nodes. Third, add :ignore_whitespace_nodes.</item>

      <item status="fixed">Taint the strings pulled from files.</item>

      <item status="fixed">Process entity declarations in DocType.</item>
    </todo>
  </status>

  <faq>
    <q>I&#39;m using the XPath &#39;//foo&#39; on an XML branch node X, and
    keep getting all of the &#39;foo&#39; elements in the entire document.
    Why? Shouldn&#39;t it return only the &#39;foo&#39; element descendants of
    X?</q>

    <a>No. XPath specifies that &#39;/&#39; returns the document root,
    regardless of the context node. &#39;//&#39; also starts at the document
    root. If you want to limit your search to a branch, you need to use the
    self:: axe. EG, &#39;self::node()//foo&#39;, or the shorthand
    &#39;.//foo&#39;.</a>

    <q>I want to parse a document both as a tree, and as a stream. Can I do
    this?</q>

    <a>Yes, and no. There is no mechanism that directly supports this in
    REXML. However, aside from writing your own traversal layer, there is a
    way of doing this. To turn a tree into a stream, just turn the branch you
    want to process as a stream back into a string, and re-parse it with your
    preferred API. EG: pp = PullParser.new( some_element.to_s ). The other
    direction is more difficult; you basically have to build a tree from the
    events. REXML will have one of these builders, eventually, but it
    doesn&#39;t currently exist.</a>

    <q>Why is Element.elements indexed off of &#39;1&#39; instead of
    &#39;0&#39;?</q>

    <a>Because of XPath. The XPath specification states that the index of the
    first child node is &#39;1&#39;. Although it may be counter-intuitive to
    base elements on 1, it is more undesireable to have element.elements[0] ==
    element.elements[ &#39;node()[1]&#39; ]. Since I can&#39;t change the
    XPath specification, the result is that Element.elements[1] is the first
    child element.</a>

    <q>Why isn&#39;t REXML a validating parser?</q>

    <a>Because validating parsers must include code that parses and interprets
    DTDs. I hate DTDs. REXML supports the barest minimum of DTD parsing, and
    even that isn&#39;t complete. There is DTD parsing code in the works, but
    I only work on it when I&#39;m really, really bored. Rumor has it that a
    contributor is working on a DTD parser for REXML; rest assured that any
    such contribution will be included with REXML as soon as it is available.</a>

    <q>I&#39;m trying to create an ISO-8859-1 document, but when I add text to
    the document it isn&#39;t being properly encoded.</q>

    <a>Regardless of what the encoding of your document is, when you add text
    programmatically to a REXML document you <em>must</em> ensure that you are
    only adding UTF-8 to the tree. In particular, you can&#39;t add ISO-8859-1
    encoded text that contains characters above 0x80 to REXML trees -- you
    must convert it to UTF-8 before doing so. Luckily, this is easy:
    <code>text.unpack(&#39;C*&#39;).pack(&#39;U*&#39;)</code> will do the
    trick. 7-bit ASCII is identical to UTF-8, so you probably won&#39;t need
    to worry about this.</a>

    <q>How do I get the tag name of an Element?</q>

    <a>You take a look at the APIs, and notice that <code>Element</code>
    includes <code>Namespace</code>. Then you click on the <code>Namespace</code>
    link and look at the methods that <code>Element</code> includes from
    <code>Namespace</code>. One of these is <code>name()</code>. Another is
    <code>expanded_name()</code>. Yet another is <code>prefix()</code>. Then,
    you email the author of rdoc and ask him to extend rdoc so that it lists
    methods in the API that are included from other files, so that you
    don&#39;t have to do all of that looking around for your method.</a>
  </faq>

  <credits>
    <p>I&#39;ve had help from a number of resources; if I haven&#39;t listed
    you here, it means that I just haven&#39;t gotten around to adding you, or
    that I&#39;m a dork and have forgotten. In either case, feel free to write
    me and complain. I may ignore you, but at least you tried. (Actually, I
    don&#39;t conciously ignore anybody except spammers.)</p>

    <list>
      <item>Mike Stok has been very active, sending not only fixes for bugs
      (especially in Functions), but also by providing unit tests and making
      sure REXML runs under Ruby 1.7.</item>

      <item>Kouhei Sutou translated the REXML API documentation to Japanese!
      Links are in the API docs section of the main documentation.</item>

      <item>Erik Terpstra heard my pleas and submitted several logos for
      REXML. After sagely avoiding choosing one for several weeks, I finally
      forced my poor slave of a wife to pick one (this is what we call
      &#34;delegation&#34;). She did, with caveats; Erik quickly made the
      changes, and the result is what you now see at the top of this page. He
      also supplied a <link href="img/rexml_50p.png">smaller version</link>
      that you can include with your projects that use REXML, if you&#39;d
      like.</item>

      <item>Ernest Ellingson contributed the sourcecode for turning UTF16 and
      UNILE encodings into UTF8, which allowed REXML to get the 100% OASIS
      valid tests rating.</item>

      <item>Ian Macdonald provided me with a comprehensive, well written RPM
      spec file.</item>

      <item>Oliver M . Bolzer is maintaining a Debian package distribution of
      REXML. He also has provided good feedback and bug reports about
      namespace support.</item>

      <item>Michael Granger supplied a patch for REXML that make the unit
      tests pass under Ruby 1.7.</item>

      <item>James Britt contributed code that makes using
      Document.parse_stream easier to use by allowing it to be passed either a
      Source, File, or String.</item>

      <item>Tobias Reif: Numerous bug reports, and suggestions for
      improvement.</item>

      <item>Stefan Scholl, who provided a lot of feedback and bug reports
      while I was trying to get ISO-8859-1 support working.</item>

      <item>Steven E Lumos for volunteering information about XPath
      particulars.</item>

      <item>Fumitoshi UKAI provided some bug fixes for CData metacharacter
      quoting.</item>

      <item>TAKAHASHI Masayoshi, for information on UTF</item>

      <item>Robert Feldt: Bug reports and suggestions/recommendations about
      improving REXML. Testing is one of the most important aspects of
      software development.</item>

      <item><link href="http://www.themindelectric.com/exml/index.html">Electric
      XML</link>: This was, after all, the inspiration for REXML. Originally,
      I was just going to do a straight port, and although REXML doesn&#39;t
      in any way, shape or form resemble Electric XML, still the basic
      framework and philosophy was inspired by E-XML. And I still use E-XML in
      my Java projects.</item>

      <item><link href="http://www.io.com/~jimm/downloads/nqxml/index.html">NQXML</link>:
      While I may complain about the NQXML API, I wrote a few applications
      using it that wouldn&#39;t have been written otherwise, and it was very
      useful to me. It also encouraged me to write REXML. Never complain about
      free software *slap*.</item>

      <item>See my <link
      href="http://www.germane-software.com/~ser/technology.html">technologies
      page</link> for a more comprehensive list of computer technologies that
      I depend on for my day-to-day work.</item>

      <item>rdoc, an excellent JavaDoc analog<footnote>When I was first
      working on REXML, rdoc wasn&#39;t, IMO, very good, so I wrote API2XML.
      API2XML was good enough for a while, and then there was a flurry of work
      on rdoc, and it quickly surpassed API2XML in features. Since I was never
      really interested in maintaining a JavaDoc analog, I stopped support of
      API2XML, and am now recommending that people use rdoc.</footnote>.</item>

      <item>Many, many other people who&#39;ve submitted bug reports,
      suggestions, and positive feedback. You&#39;re all co-developers!</item>
    </list>
  </credits>
</documentation>
