shanna-xml-sax-machines 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 "Shane Hanna"
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,43 @@
+= XML SAX Machines
+
+* http://github.com/shanna/xml-sax-machines/tree/master
+
+== Description
+
+Assorted XML SAX readers, filters and writers for nokogiri.
+
+== Dependencies
+
+Ruby::
+* nokogiri ~> 1.2.2
+
+== Install
+
+* Via git: git clone git://github.com/shanna/xml-sax-machines.git
+* Via gem: gem install shanna-xml-sax-machines -s http://gems.github.com
+
+== Filters
+
+=== XML::SAX::Filter
+Base class for creating chainable SAX filters.
+
+=== XML::SAX::Debug
+Debuging output for SAX events.
+
+=== XML::SAX::Builder
+Build in-memory document trees from SAX streams.
+
+=== XML::SAX::FragmentBuilder
+Process in-memory record based document fragments. Builds well balanced XML chunks matching an XPath into a partial
+in-memory document tree for processing by a callback block.
+
+== TODO
+
+* Pipeline and Tee filters.
+* Json reader/writer?
+* Any other Ruby parsers that can generate a SAX stream?
+* Namespace handling in XML::SAX::Builder and XML::SAX::FragmentBuilder.
+
+== Copyright
+
+Copyright (c) 2009 "Shane Hanna". See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 1

data/lib/xml-sax-machines/builder.rb

@@ -0,0 +1,73 @@
+module XML
+  module SAX
+
+    # Build a Nokogiri::XML::Document from a SAX stream.
+    #
+    # ==== Example
+    #
+    #   builder =  XML::SAX::Builder.new
+    #   parser  =  Nokogiri::XML::SAX::PushParser.new(builder)
+    #   parser  << %q{<root>xml content</root>}
+    #   parser.finish
+    #
+    #   puts builder.document.children.to_s #=> xml content
+    #
+    # ==== See
+    # * XML::SAX::Filter
+    #
+    # --
+    # TODO:
+    # * Namespaces.
+    class Builder < Filter
+
+      # The document object.
+      #
+      # ==== Returns
+      # Nokogiri::XML::Document
+      attr_reader :document
+
+      def start_document #:nodoc:
+        super
+        @document = Nokogiri::XML::Document.new
+        @context  = @document
+      end
+
+      def start_element(name, attributes = []) #:nodoc:
+        super
+
+        el = Nokogiri::XML::Element.new(name, @document)
+        Hash[*attributes].each_pair{|k, v| el[k] = v}
+        @context = @context.add_child(el)
+      end
+
+      def end_element(name) #:nodoc:
+        super
+        raise "Unmatched closing element. Got '#{name}' but expected '#{@context.name}'" \
+          unless name == @context.name
+        @context = @context.parent
+      end
+
+      def characters(string) #:nodoc:
+        super
+        # http://nokogiri.lighthouseapp.com/projects/19607-nokogiri/tickets/68-xpath-incorrect-when-text-siblings-exist#ticket-68-1
+        sibling = @context.children.last
+        if sibling.kind_of?(Nokogiri::XML::Text)
+          sibling.content += string
+        else
+          @context.add_child(Nokogiri::XML::Text.new(string, @document))
+        end
+      end
+
+      def cdata_block(string) #:nodoc:
+        super
+        @context.add_child(Nokogiri::XML::CDATA.new(@document, string))
+      end
+
+      def comment(string) #:nodoc:
+        super
+        @context.add_child(Nokogiri::XML::Comment.new(@document, string))
+      end
+
+    end # Builder
+  end # SAX
+end # XML

data/lib/xml-sax-machines/debug.rb

@@ -0,0 +1,33 @@
+module XML
+  module SAX
+
+    # SAX Debug filter.
+    #
+    # Warn all SAX event methods before calling the next filter in the chain. Handy as it can be placed anywhere in a
+    # pipeline to see what events are being passed to the next filter.
+    #
+    # ==== See
+    # * XML::SAX::Filter
+    #
+    class Debug < Filter
+
+      %w{
+        cdata_block
+        characters
+        comment
+        end_document
+        end_element
+        error
+        start_document
+        start_element
+        warning
+      }.each do |method|
+        define_method(method.to_sym) do |*args|
+          warn "#{method}: #{args.inspect}"
+          super(*args)
+        end
+      end
+
+    end # Debug
+  end # SAX
+end # XML

data/lib/xml-sax-machines/filter.rb

@@ -0,0 +1,85 @@
+module XML
+  module SAX
+
+    # SAX Filter base class.
+    #
+    # Chain SAX filters together by delegating missing SAX event methods to the next filter in the chain. Simply call
+    # super in any SAX event methods you overload to pass the call to the next filter in the chain.
+    #
+    # Extend this Class rather than <tt>Nokogiri::XML::SAX::Document</tt> which acts as a final filter.
+    #
+    # ==== See
+    # * Nokogiri::XML::SAX::Document
+    #
+    #--
+    # TODO:
+    # * Examples.
+    class Filter < Nokogiri::XML::SAX::Document
+
+      # The next filter in the chain.
+      attr_accessor :filter
+
+      # New filter instance.
+      #
+      # ==== Notes
+      # Filter chains are built in reverse, the filter passed during construction is called *after* the current
+      # filter.
+      #
+      # ==== See
+      # * XML::SAX::Pipeline
+      #
+      # ==== Parameters
+      # filter<Nokogiri::XML::SAX::Document>::
+      #   Optional next <tt>XML::SAX::Filter</tt> or <tt>Nokogiri::XML::SAX::Document<tt>(final) in the chain.
+      #   By default a <tt>Nokogiri::XML::SAX::Document</tt> will be used making the chain final.
+      #
+      # options<Hash>::
+      #   Optional per-filter arguments.
+      #
+      #--
+      # TODO:
+      # * Barf if the filter isn't a Nokogiri::XML::SAX::Document or XML::SAX::Filter.
+      def initialize(filter = nil, options = {})
+        @filter = filter
+      end
+
+      def cdata_block(string) #:nodoc:
+        @filter.cdata_block(string) if @filter
+      end
+
+      def characters(string) #:nodoc:
+        @filter.characters(string) if @filter
+      end
+
+      def comment(string) #:nodoc:
+        @filter.comment(string) if @filter
+      end
+
+      def end_document #:nodoc:
+        @filter.end_document if @filter
+      end
+
+      def end_element(name) #:nodoc:
+        @filter.end_element(name) if @filter
+      end
+
+      def error(string) #:nodoc:
+        @filter.error(string) if @filter
+      end
+
+      def start_document #:nodoc:
+        @filter.start_document if @filter
+      end
+
+      def start_element(name, attributes = []) #:nodoc:
+        @filter.start_element(name, attributes = []) if @filter
+      end
+
+      def warning(string) #:nodoc:
+        @filter.warning(string) if @filter
+      end
+
+    end # Filter
+  end # SAX
+end # XML
+

data/lib/xml-sax-machines/fragment_builder.rb

@@ -0,0 +1,86 @@
+module XML
+  module SAX
+
+    # Build a Nokogiri::XML::Document fragments that match an XPath.
+    #
+    # Stream large (or small) record based XML documents building each matching XPath into a document fragment making
+    # futher manipulation of each record easier.
+    #
+    # ==== Notes
+    # * In order to save memory well balanced elements that do not match any XPath are unlinked. This means you *cannot*
+    #   match records by position in relation to siblings.
+    # * Because we are parsing a SAX stream there is no read ahead. You *cannot* match records by any children the
+    #   element may have once further events are pushed.
+    # * You can match by attributes of an element.
+    #
+    # ==== Example
+    #
+    #   builder =  XML::SAX::FragmentBuilder.new(nil, {
+    #     '//record' => lambda{|record| puts el.to_s} # Process each matched record element.
+    #   })
+    #   parser  =  Nokogiri::XML::SAX::PushParser.new(builder)
+    #   parser  << %q{
+    #     <root>
+    #       <record id="1">record one</record>
+    #       <record id="2">record two</record>
+    #     </root>
+    #   }
+    #   #=> <record id="1">record one</record>
+    #   #=> <record id="2">record two</record>
+    #   parser.finish
+    #
+    # ==== See
+    # * XML::SAX::Builder
+    # * XML::SAX::Filter
+    #
+    # --
+    # TODO:
+    # * Namespaces.
+    class FragmentBuilder < Builder
+      private :document # Would return an empty/partial document you really shouldn't mess with.
+
+      # ==== Parameters
+      # handler<Nokogiri::XML::SAX::Document>::
+      #   Optional next <tt>XML::SAX::Filter</tt> or <tt>Nokogiri::XML::SAX::Document<tt>(final) in the chain.
+      #   By default a <tt>Nokogiri::XML::SAX::Document</tt> will be used making the chain final.
+      #
+      # options<Hash>::
+      #   {xpath<String> => &block<Proc>} pairs. The first element passed to the block will be the matching
+      #   Nokogiri::XML::Node. Keep in mind the node will be unlinked after your block returns.
+      def initialize(filter = nil, options = {})
+        super(filter)
+        @find   = options
+        @found  = {}
+        @buffer = 0
+      end
+
+      def start_element(name, attributes = []) #:nodoc:
+        super
+        @find.each_pair do |xpath, block|
+          if match = @document.at(xpath)
+            unless @found[match.path]
+              @buffer += 1
+              @found[match.path] = block
+            end
+          end
+        end
+      end
+
+      def end_element(name) #:nodoc:
+        path = @context.path
+        if @buffer > 0 && block = @found.delete(path)
+          @buffer -= 1
+          block.call(@context) # Copy @context fragment tree to actual fragment?
+        end
+        super
+
+        if @buffer == 0 && !(path == '/')
+          # Unlink children if position context []
+          # @doc.at(path).children.unlink unless path == '/'
+          @document.at(path).unlink
+        end
+      end
+
+    end # FragmentBuilder
+  end # SAX
+end # XML

data/lib/xml-sax-machines.rb

@@ -0,0 +1,15 @@
+begin
+  require 'nokogiri'
+rescue LoadError
+  require 'rubygems'
+  require 'nokogiri'
+end
+
+module XML
+  module SAX
+  end # SAX
+end # XML
+
+# TODO: Conditionally load some machines?
+base = File.join(File.dirname(__FILE__), 'xml-sax-machines')
+%w{filter debug builder fragment_builder}.each{|r| require File.join(base, r)}

data/test/builder_test.rb

@@ -0,0 +1,54 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class BuilderTest < Test::Unit::TestCase
+  context 'XML::SAX::Builder' do
+
+    should 'create root' do
+      assert_equal 'r', build('<r/>').root.name
+    end
+
+    should 'create comments' do
+      assert_equal '<!-- woot -->', build('<r><!-- woot --></r>').root.children.to_s
+    end
+
+    should 'create cdata_blocks' do
+      assert_equal '<![CDATA[ woot ]]>', build('<r><![CDATA[ woot ]]></r>').root.children.to_s
+    end
+
+    should 'create characters' do
+      assert_equal 'woot', build('<r>woot</r>').root.children.to_s
+    end
+
+    should 'create empty element' do
+      assert build('<r><foo/></r>').at('/r/foo')
+    end
+
+    should 'create element with attributes' do
+      el = build('<r><foo id="1"/></r>').at('/r/foo')
+      assert_equal '1', el['id']
+    end
+
+    should 'create element with child element' do
+      assert build('<r><foo><bar/></foo></r>').at('/r/foo/bar')
+    end
+
+    should 'create element with mixed content' do
+      el = build('<r><foo>text<bar/></foo></r>').at('/r/foo')
+      assert_equal 'text<bar/>', el.children.to_s
+    end
+
+    should 'create element siblings' do
+      el = build('<r><foo/><bar/></r>').root
+      assert_equal 2, el.children.length
+    end
+  end
+
+  protected
+    def build(string)
+      builder = XML::SAX::Builder.new
+      parser  = Nokogiri::XML::SAX::PushParser.new(builder)
+      parser << string
+      parser.finish
+      builder.document
+    end
+end # BuilderTest

data/test/debug_test.rb

@@ -0,0 +1,59 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class DebugTest < Test::Unit::TestCase
+  context 'XML::SAX::Debug event method warning' do
+
+    should 'warn #start_document' do
+      assert_match regexp('start_document: []'), parse('<r/>')
+    end
+
+    should 'warn #end_document' do
+      assert_match regexp('end_document: []'), parse('<r/>')
+    end
+
+    should 'warn #start_element' do
+      assert_match regexp('start_element: ["r", []]'), parse('<r/>')
+    end
+
+    should 'warn #start_element with attributes' do
+      assert_match regexp('start_element: ["r", ["id", "1"]]'), parse('<r id="1"/>')
+    end
+
+    should 'warn #end_element' do
+      assert_match regexp('end_element: ["r"]'), parse('<r/>')
+    end
+
+    should 'warn #characters' do
+      assert_match regexp('characters: ["woot"]'), parse('<r>woot</r>')
+    end
+
+    should 'warn #comment' do
+      assert_match regexp('comment: [" woot "]'), parse('<r><!-- woot --></r>')
+    end
+
+    should 'warn #cdata_block' do
+      assert_match regexp('cdata_block: [" woot "]'), parse('<r><![CDATA[ woot ]]></r>')
+    end
+  end
+
+  protected
+    def parse(xml)
+      parser = Nokogiri::XML::SAX::PushParser.new(XML::SAX::Debug.new)
+      capture_stderr do
+        parser << xml
+        parser.finish
+      end
+    end
+
+    def regexp(string)
+      Regexp.compile('^' + Regexp.escape(string))
+    end
+
+    def capture_stderr(&block)
+      $stderr = StringIO.new
+      yield
+      result  = $stderr.rewind && $stderr.read
+      $stderr = STDERR
+      result
+    end
+end # DebugTest

data/test/filter_test.rb

@@ -0,0 +1,15 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class FilterTest < Test::Unit::TestCase
+  context 'XML::SAX::Filter' do
+
+    should 'run base filter without error' do
+      assert_nothing_thrown do
+        parser = Nokogiri::XML::SAX::PushParser.new(XML::SAX::Filter.new)
+        parser << '<r/>'
+        parser.finish
+      end
+    end
+
+  end
+end # FilterTest

data/test/fragment_builder_test.rb

@@ -0,0 +1,28 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class FragmentBuilderTest < Test::Unit::TestCase
+  context 'XML::SAX::FragmentBuilder' do
+
+    should 'call callback for record' do
+      builder = XML::SAX::FragmentBuilder.new(nil, {
+        '//foo' => lambda do |el|
+          assert_equal 'foo', el.name, 'foo element'
+          assert_equal 1, el.parent.children.length, 'no siblings'
+        end
+      })
+      parser = Nokogiri::XML::SAX::PushParser.new(builder)
+      parser << '<r><foo/><foo/><foo/></r>'
+      parser.finish
+    end
+
+    should 'have buffered children for record' do
+      builder = XML::SAX::FragmentBuilder.new(nil, {
+        '//foo' => lambda{|el| assert_equal 2, el.children.length}
+      })
+      parser = Nokogiri::XML::SAX::PushParser.new(builder)
+      parser << '<r><foo>text<el>el</el></foo></r>'
+      parser.finish
+    end
+
+  end
+end # FragmentBuilderTest

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'xml-sax-machines'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: shanna-xml-sax-machines
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Shane Hanna
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-17 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: nokogiri
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.2.2
+    version: 
+description: XML SAX Machines
+email: shane.hanna@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- README.rdoc
+- VERSION.yml
+- lib/xml-sax-machines
+- lib/xml-sax-machines/builder.rb
+- lib/xml-sax-machines/debug.rb
+- lib/xml-sax-machines/filter.rb
+- lib/xml-sax-machines/fragment_builder.rb
+- lib/xml-sax-machines.rb
+- test/builder_test.rb
+- test/debug_test.rb
+- test/filter_test.rb
+- test/fragment_builder_test.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://github.com/shanna/xml-sax-machines
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Assorted XML SAX readers, filters and writers.
+test_files: []
+