libxml-ruby 0.9.3 → 0.9.4

data/CHANGES

@@ -1,5 +1,14 @@
 (See log/ChangeLog for more detailed changes derived directly from source control.)
 
+== 0.9.4 / 2008-11-24 Charlie Savage
+
+* Update HTML parser so that it can read files, strings and io
+  streams.
+
+* Update HTML parser to support user specified encodings.
+
+* Additional C code cleanup.
+
 == 0.9.3 / 2008-11-22 Charlie Savage
 
 * Fixed segementation fault caused by documents being freed

data/README

@@ -4,12 +4,11 @@
 The libxml gem provides Ruby language bindings for GNOME's Libxml2
 XML toolkit. It is free software, released under the MIT License.
 
-libxml-ruby provides several advantages over REXML:
-
-* Speed - libxml is many times faster than REXML
-* Features - libxml provides a number of additional features over REXML, including XML Schema Validation, RelaxNg validation, xslt (see libxslt-ruby)
-* Conformance - libxml passes all 1800+ tests from the OASIS XML Tests Suite 
+We think libxml-ruby is the best XML library for Ruby because:
 
+* Speed - Its much faster than REXML and Hpricot
+* Features - It provides an amazing number of featues
+* Conformance - It passes all 1800+ tests from the OASIS XML Tests Suite
 
 == Requirements
 libxml-ruby requires Ruby 1.8.4 or higher.  It is dependent on 
@@ -41,58 +40,56 @@ libxml2 and iconv.  The gem also includes a Microsoft VC++ 2008
 solution.  If you wish to run a debug version of libxml-ruby on
 Windows, then it is highly recommended you use VC++.
 
-== Functionality
-LibXML is a highly conformant XML parser, passing all 1800+ tests 
-from the OASIS XML Tests Suite.  It includes rich functionality such as:
+== Getting Started
+Using libxml is easy. First decide what parser you want to use:
 
-* DOM (LibXML::XML::Parser)
-* SAX (LibXML::XML::SaxParser)
-* HTML Parsing (LibXML::XML::HTMLParser)
-* Reader (LibXML::XML::Reader)
-* XPath (LibXML::XML::XPath)
-* XPointer (LibXML::XML::XPointer)
-* DTDs (LibXML::XML::Dtd)
-* RelaxNG Schemas (LibXML::XML::RelaxNG)
-* XML Schema (LibXML::XML::Schema)
-* XSLT (http://rubyforge.org/projects/libxsl/)
+ * Generally you'll want to use the XML::Parser which provides
+   a tree based API
+ * For large documents that won't fit into memory, or if you
+   prefer an input based API, then use XML::Reader
+ * If you are parsing HTML files, then use XML::HTMLParser
+ * If you are masochistic or old stream, then use the XML::SaxParser
+   which provides a callback API.
 
-libxml-ruby provides impressive coverage of libxml's functionality 
-through an easy-to-use C api.  
+Once you choose a parser, then choose a datasource and its
+encoding.  Libxml can parse files, strings, URIs and IO stream.
+For more information, see XML::Input.
 
-== Performance
-In addition to being feature rich and conformation, the main reason
-people use libxml-ruby is for performance.  Here are the results 
-of a couple simple benchmarks recently blogged about on the
-Web (you can find them in the benchmark directory of the 
-libxml distribution).
+== Advanced Functionality
+Beyond the basics of parsing and processing XML and HTML documents,
+lLibxml provides a wealth of additional functionality.
 
-From http://depixelate.com/2008/4/23/ruby-xml-parsing-benchmarks
+Most commonly, you'll want to use its XML::XPath support, which makes
+it easy to search for data inside and XML document.  Although not as
+popular, XML::XPointer provides another API for finding data inside
+an XML document.
 
-               user     system      total        real
- libxml    0.032000   0.000000   0.032000 (  0.031000)
- Hpricot   0.640000   0.031000   0.671000 (  0.890000)
- REXML     1.813000   0.047000   1.860000 (  2.031000)
+Often times you'll need to validate data before processing it. For example,
+if you accept user generated content submitted over the Web, you'll
+want to first verify it does not contain malicious code such as embedded scripts.
+This can be done using libxml's powerful set of validators:
 
-From https://svn.concord.org/svn/projects/trunk/common/ruby/xml_benchmarks/
+* DTDs (LibXML::XML::Dtd)
+* Relax Schemas (LibXML::XML::RelaxNG)
+* XML Schema (LibXML::XML::Schema)
 
-               user     system      total        real
- libxml    0.641000   0.031000   0.672000 (  0.672000)
- hpricot   5.359000   0.062000   5.421000 (  5.516000)
- rexml    22.859000   0.047000  22.906000 ( 23.203000) 
+Finally, if you'd like to use XSL Transformations to process data,
+then also install the libxslt gem which is available at
+http://rubyforge.org/projects/libxsl/.
 
-== USAGE
+== Usage
 For in-depth information about using libxml-ruby please refer
-to its online Rdoc documentation.  
+to its online Rdoc documentation.
 
-All libxml classes are in the LibXML::XML module. The most
-expedient way to use libxml is to require 'xml'.  This will mixin
-the LibXML module into the global namespace, allowing you to 
-write code like this: 
+All libxml classes are in the LibXML::XML module. The easiest
+way to use libxml is to require 'xml'.  This will mixin
+the LibXML module into the global namespace, allowing you to
+write code like this:
 
   require 'xml'
   document = XML::Document.new
 
-However, when creating an application or library you plan to 
+However, when creating an application or library you plan to
 redistribute, it is best to not add the LibXML module to the global
 namespace, in which case you can either write your code like this:
 
@@ -114,104 +111,40 @@ and include LibXML into it. For example:
     end
   end
 
-For simplicity's sake we will use require 'xml in the basic examples
-shown below.
+For simplicity's sake, the documentation uses the xml module in its examples.
 
-=== READING
-There are several ways to read xml documents.
+== Performance
+In addition to being feature rich and conformation, the main reason
+people use libxml-ruby is for performance.  Here are the results 
+of a couple simple benchmarks recently blogged about on the
+Web (you can find them in the benchmark directory of the 
+libxml distribution).
 
-  require 'xml'
-  doc = XML::Document.file('output.xml')
-  root = doc.root
-  
-  puts "Root element name: #{root.name}"
-  
-  elem3 = root.find('elem3').to_a.first
-  puts "Elem3: #{elem3['attr']}"
-  
-  doc.find('//root_node/foo/bar').each do |node|
-    puts "Node path: #{node.path} \t Contents: #{node.content}"
-  end
+From http://depixelate.com/2008/4/23/ruby-xml-parsing-benchmarks
 
-And your terminal should look like this:
+               user     system      total        real
+ libxml    0.032000   0.000000   0.032000 (  0.031000)
+ Hpricot   0.640000   0.031000   0.671000 (  0.890000)
+ REXML     1.813000   0.047000   1.860000 (  2.031000)
 
-  Root element name: root_node
-  Elem3: baz
-  Node path: /root_node/foo/bar[1]         Contents: 1
-  Node path: /root_node/foo/bar[2]         Contents: 2
-  Node path: /root_node/foo/bar[3]         Contents: 3
-  Node path: /root_node/foo/bar[4]         Contents: 4
-  Node path: /root_node/foo/bar[5]         Contents: 5
-  Node path: /root_node/foo/bar[6]         Contents: 6
-  Node path: /root_node/foo/bar[7]         Contents: 7
-  Node path: /root_node/foo/bar[8]         Contents: 8
-  Node path: /root_node/foo/bar[9]         Contents: 9
-  Node path: /root_node/foo/bar[10]        Contents: 10
+From https://svn.concord.org/svn/projects/trunk/common/ruby/xml_benchmarks/
 
-=== WRITING
-To write a simple document:
+               user     system      total        real
+ libxml    0.641000   0.031000   0.672000 (  0.672000)
+ hpricot   5.359000   0.062000   5.421000 (  5.516000)
+ rexml    22.859000   0.047000  22.906000 ( 23.203000) 
 
-  require 'xml'
-  
-  doc = XML::Document.new()
-  doc.root = XML::Node.new('root_node')
-  root = doc.root
-  
-  root << elem1 = XML::Node.new('elem1')
-  elem1['attr1'] = 'val1'
-  elem1['attr2'] = 'val2'
-  
-  root << elem2 = XML::Node.new('elem2')
-  elem2['attr1'] = 'val1'
-  elem2['attr2'] = 'val2'
-  
-  root << elem3 = XML::Node.new('elem3')
-  elem3 << elem4 = XML::Node.new('elem4')
-  elem3 << elem5 = XML::Node.new('elem5')
-  
-  elem5 << elem6 = XML::Node.new('elem6')
-  elem6 << 'Content for element 6'
-  
-  elem3['attr'] = 'baz'
-  
-  format = true
-  doc.save('output.xml', format)
-
-The file output.xml contains:
-
-  <?xml version="1.0"?>
-  <root_node>
-    <elem1 attr1="val1" attr2="val2"/>
-    <elem2 attr1="val1" attr2="val2"/>
-    <elem3 attr="baz">
-      <elem4/>
-      <elem5>
-        <elem6>Content for element 6</elem6>
-      </elem5>
-    </elem3>
-    <foo>
-      <bar>1</bar>
-      <bar>2</bar>
-      <bar>3</bar>
-      <bar>4</bar>
-      <bar>5</bar>
-      <bar>6</bar>
-      <bar>7</bar>
-      <bar>8</bar>
-      <bar>9</bar>
-      <bar>10</bar>
-    </foo>
-  </root_node>
 
 == DOCUMENTATION
+For more information please refer to the documentation.
+
 RDoc comments are included - run 'rake doc' to generate documentation.
 You can find the latest documentation at:
 
 * http://libxml.rubyforge.org/rdoc/
 
+If you have any questions, please send email to libxml-devel@rubyforge.org.
+
 == License
 See LICENSE for license information.
 
-== MORE INFORMATION
-For more information please refer to the documentation.  If you have any
-questions, please send email to libxml-devel@rubyforge.org.

data/doc/css/normal.css

@@ -0,0 +1,182 @@
+/*
+ * Uncopyrighted 2005 Ross Bamford.
+ *
+ * rosco at roscopeco dot co dot uk
+ */
+body {
+	background: #ffffff;
+	color: #000000;
+	font-family: Microsoft sans-serif, sans-serif, arial, helvetica;
+	font-size: 12px;
+	padding: 0px;
+	margin: 0px 0px 0px 0px;
+}
+
+.container {
+  width: 800px;
+  margin: 0 auto;
+}
+
+/* ** links ** */
+a {
+	color: red;
+	text-decoration: none;
+}
+
+a:hover {
+	color: red;
+	text-decoration: underline;
+}
+
+a:active {
+	color: red;
+	text-decoration: underline;
+}
+
+.navlinks a {
+	color: red;
+	text-decoration: none;
+	font-weight: bold;
+}
+
+.navlinks a:hover {
+	color: red;
+	text-decoration: underline;
+	font-weight: bold;
+}
+
+.navlinks {
+	padding: 10px; 
+	background: white;
+	white-space: nowrap
+}
+
+div.copyright {
+	/* Copyright bit on pages */
+	color: #909090;
+	position: relative;	
+	top: 5em;
+	right: 2%;
+	text-align: right;
+	font-size: 8pt;	
+}
+
+/* * page styles *** */
+
+h1.title {
+  font-size: 48px;
+  padding-left: 0;
+}
+
+h1 {
+  padding: 10px;
+}
+
+h2 {
+	border-bottom: thin #959595 solid;
+}
+
+h3 {
+	border-bottom: thin #b8c8c8 solid;
+}
+
+h5 {
+	border-bottom: thin #c0c0d8 solid;
+}
+
+div.note {
+	background: #e8e8fa;
+	border: thin dashed #3e5972;
+	position: relative;
+	width: 90%;
+	left: 5%;
+	right: 5%;
+	text-align: right;
+	font-size: 10pt;	
+	padding: 5px;
+	margin-bottom: 5px;
+}
+
+/* * syntax ******** */
+pre.ruby {
+	background: #f5f5f5;
+	border: thin dashed #3e5972;
+	padding: 10px;
+	margin-left: 2em;
+}
+
+pre.ruby span.normal {
+	color: #000000;
+}
+
+pre.ruby span.comment {
+	color: #789a86;
+	text-decoration: oblique;
+}
+
+pre.ruby span.ident {
+	color: #0b0202;
+}
+
+pre.ruby span.punct {
+	color: #8a7070;
+}
+
+pre.ruby span.symbol {
+	color: #aa1010;
+	font-weight: bold;
+}
+
+pre.ruby span.keyword {
+	color: #903030;
+	font-weight: bold;
+}
+
+pre.ruby span.constant {
+	color: #3e5972;
+	font-weight: bold;
+}
+
+pre.ruby span.string {
+	color: #2020f0;	
+}
+
+pre.ruby span.char {
+	color: #2020f0;	
+	font-weight: bold;
+}
+
+pre.ruby span.number {
+	color: #aa1010;	
+}
+
+pre.ruby span.regex {
+	color: #552090;	
+}
+
+pre.ruby span.expr {
+	color: #101080;
+	font-weight: bold;
+}
+
+pre.ruby span.global {
+	color: #557462;
+}
+
+pre.ruby span.class {
+	color: #3e5972;
+	font-weight: bold;
+}
+
+pre.ruby span.method {
+	color: #aa1010;
+}
+
+pre.ruby span.attribute {
+	color: #3e5972;
+}
+
+pre.ruby span.escape { 
+	color: #2020f0;	
+	font-weight: bold;
+}

data/doc/index.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<?xml-stylesheet href="layout.xsl" type="text/xsl" ?>
+
+<content>
+
+  <h2> Welcome to LibXml Ruby </h2>
+
+  <p>The <span style="color: red;">Libxml-Ruby</span> project provides Ruby
+  language bindings for the <a href="http://xmlsoft.org">GNOME Libxml2 XML toolkit</a>.
+  It is free software, released under the <a href="license.xml">MIT License</a>.</p>
+
+  <p>Libxml-ruby's primary advantage over REXML is performance - if speed is your need,
+  these are good libraries to consider, as demonstrated by the informal benchmark below.</p>
+
+  <table border="1" style="border: 1px solid red; margin: 30px;">
+  <tr><td colspan="3"><b>Speed Comparison libxml vs. rexml</b></td></tr>
+  <tr><th> in seconds    </th><th> libxml   </th><th> rexml    </th></tr>
+  <tr><td> opening       </td><td> 0.003954 </td><td> 0.104750 </td></tr>
+  <tr><td> attribute_add </td><td> 0.001895 </td><td> 0.011114 </td></tr>
+  <tr><td> subelems      </td><td> 0.000585 </td><td> 0.004729 </td></tr>
+  <tr><td> xpath         </td><td> 0.013269 </td><td> 2.981499 </td></tr>
+  </table>
+
+  <h2>Download</h2>
+
+  <p>You can find the latest release at:</p>
+
+  <pre>
+	  <a href="http://rubyforge.org/frs/?group_id=494">http://rubyforge.org/frs/?group_id=494</a>
+  </pre>
+
+  <p>Libxml-Ruby is also available for installation via <a href="http://rubygems.rubyforge.org">Rubygems</a>
+  -- see the <a href="install.xml">installation page</a>	for details.</p>
+
+  <h2> Project Status </h2>
+
+  <p>The code has now been updated to work with Ruby 1.8, and is compiling cleanly
+  and working well with GCC 4.x. We still have a number of open bugs to address,
+  which is being done as we work toward a 0.4.0 release and the library is
+  generally fairly stable in use.</p>
+
+</content>
+