shanna-xml-sax-machines 0.2.0 → 0.2.1

data/README.rdoc

@@ -16,10 +16,18 @@ Ruby::
 * 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
+== Flow
 
 === XML::SAX::Filter
-Base class for creating chainable SAX filters.
+Pass through filter. Base class for creating chainable SAX filters.
+
+=== XML::SAX::Pipeline
+A linear sequence of SAX filters.
+
+== Filters
+
+=== XML::SAX::Handler
+Base class for creating chainable SAX handlers.
 
 === XML::SAX::Debug
 Debuging output for SAX events.
@@ -31,9 +39,16 @@ Build in-memory document trees from SAX streams.
 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.
 
+== Recognition
+
+This library is my interpretation of patterns introduced to me through Perl's <tt>XML::SAX::Machines</tt>. All credit
+to Barrie Slaymaker and contributors.
+
+* http://search.cpan.org/dist/XML-SAX-Machines
+
 == TODO
 
-* Pipeline and Tee filters.
+* Tee filter.
 * Json reader/writer?
 * Any other Ruby parsers that can generate a SAX stream?
 * Namespace handling in XML::SAX::Builder and XML::SAX::FragmentBuilder.

data/VERSION.yml

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

data/lib/xml-sax-machines.rb

@@ -12,4 +12,4 @@ 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)}
+%w{filter pipeline debug builder fragment_builder}.each{|r| require File.join(base, r)}

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

@@ -8,7 +8,13 @@ module XML
     #
     # Extend this Class rather than <tt>Nokogiri::XML::SAX::Document</tt> which acts as a final filter.
     #
+    # ==== Notes
+    # Filter chains are built in reverse by setting the filter attribute. Use <tt>XML::SAX::Pipeline</tt> to
+    # construct filter chains in a more logical order. This keeps the filter constructor clear of any prerequisite
+    # API in subclasses.
+    #
     # ==== See
+    # * XML::SAX::Pipeline
     # * Nokogiri::XML::SAX::Document
     #
     #--
@@ -16,33 +22,10 @@ module XML
     # * Examples.
     class Filter < Nokogiri::XML::SAX::Document
 
+      # Barf if the filter isn't a Nokogiri::XML::SAX::Document or XML::SAX::Filter.
       # 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

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

@@ -47,8 +47,8 @@ module XML
       # 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)
+      def initialize(options = {})
+        super()
         @find   = options
         @found  = {}
         @buffer = 0

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

@@ -0,0 +1,16 @@
+module XML
+  module SAX
+
+    # Define a filter chain top to bottom.
+    #
+    #--
+    # TODO:
+    # * More enumerable methods so you can alter pipelines.
+    class Pipeline < Filter
+      def initialize(*filters)
+        self.filter = filters.each_with_index{|f, i| f.filter = filters[i + 1]}.first
+      end
+    end # Pipeline
+
+  end # SAX
+end # XML

data/test/fragment_builder_test.rb

@@ -4,21 +4,21 @@ class FragmentBuilderTest < Test::Unit::TestCase
   context 'XML::SAX::FragmentBuilder' do
 
     should 'call callback for record' do
-      builder = XML::SAX::FragmentBuilder.new(nil, {
+      builder = XML::SAX::FragmentBuilder.new(
         '//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, {
+      builder = XML::SAX::FragmentBuilder.new(
         '//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

data/test/pipeline_test.rb

@@ -0,0 +1,22 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class PipelineTest < Test::Unit::TestCase
+  context 'XML::SAX::Filter' do
+
+    should 'chain filters first to last' do
+      class Debug1 < XML::SAX::Debug; end
+      class Debug2 < XML::SAX::Debug; end
+      class Debug3 < XML::SAX::Debug; end
+
+      pipe = XML::SAX::Pipeline.new(
+        Debug1.new,
+        Debug2.new,
+        Debug3.new
+      )
+      assert_kind_of Debug1, pipe.filter
+      assert_kind_of Debug2, pipe.filter.filter
+      assert_kind_of Debug3, pipe.filter.filter.filter
+    end
+
+  end
+end # FilterTest

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: shanna-xml-sax-machines
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors: 
 - Shane Hanna