sax_stream 0.3.2 → 1.0.0

data/README.markdown

@@ -9,7 +9,7 @@ The two main goals of this process are:
 1. To avoid loading the entire XML file stream into memory at once.
 2. To avoid loading all the mapped objects into memory simultaneously.
 
-This is currently only for XML importing. Supporting exporting too would be nice if I need it.
+This library handles both importing and exporting, but at present no steps have been taken to conserve memory when exporting XML. Using this library for export is comparable to ROXML or Happymapper (and is heavily based on ROXML's implementation).
 
 ## Status
 
@@ -68,7 +68,7 @@ class UnusualDate
 end
 ```
 
-### Run the parser
+### Importing XML: Run the parser
 
 The parser object must be supplied with a collector and an array of mapping classes to use.
 
@@ -90,6 +90,10 @@ To get the full benefits of this library, supply a collector which does somethin
 
 I plan to supply a batching collector which will collect a certain number of objects before passing them off to another collector you supply, so you can save objects in batches of 100 or whatever is optimal for your application.
 
+### Exporting XML: Call to_xml
+
+No parser or collector object is used to export XML. Simply call to_xml on the root object. The exporter will expect data to be in the same place it was imported to. It will look in attributes for data for this object, and relations to find associated objects. If you defined custom setters on your object to manipulate the values, then you may need to also supply custom getters.
+
 ## Credits
 
 Author: [Craig Ambrose](http://www.craigambrose.com)

data/lib/sax_stream/core_extensions/ordered_hash.rb

@@ -0,0 +1,101 @@
+# Taken from the "Thor" gem.
+
+module SaxStream
+  module CoreExtensions
+    if RUBY_VERSION >= '1.9'
+      class OrderedHash < ::Hash
+      end
+    else
+      # This class is based on the Ruby 1.9 ordered hashes.
+      #
+      # It keeps the semantics and most of the efficiency of normal hashes
+      # while also keeping track of the order in which elements were set.
+      #
+      class OrderedHash #:nodoc:
+        include Enumerable
+
+        Node = Struct.new(:key, :value, :next, :prev)
+
+        def initialize
+          @hash = {}
+        end
+
+        def [](key)
+          @hash[key] && @hash[key].value
+        end
+
+        def []=(key, value)
+          if node = @hash[key]
+            node.value = value
+          else
+            node = Node.new(key, value)
+
+            if @first.nil?
+              @first = @last = node
+            else
+              node.prev = @last
+              @last.next = node
+              @last = node
+            end
+          end
+
+          @hash[key] = node
+          value
+        end
+
+        def delete(key)
+          if node = @hash[key]
+            prev_node = node.prev
+            next_node = node.next
+
+            next_node.prev = prev_node if next_node
+            prev_node.next = next_node if prev_node
+
+            @first = next_node if @first == node
+            @last = prev_node  if @last  == node
+
+            value = node.value
+          end
+
+          @hash.delete(key)
+          value
+        end
+
+        def keys
+          self.map { |k, v| k }
+        end
+
+        def values
+          self.map { |k, v| v }
+        end
+
+        def each
+          return unless @first
+          yield [@first.key, @first.value]
+          node = @first
+          yield [node.key, node.value] while node = node.next
+          self
+        end
+
+        def merge(other)
+          hash = self.class.new
+
+          self.each do |key, value|
+            hash[key] = value
+          end
+
+          other.each do |key, value|
+            hash[key] = value
+          end
+
+          hash
+        end
+
+        def empty?
+          @hash.empty?
+        end
+      end
+    end
+
+  end
+end

data/lib/sax_stream/internal/mapping_factory.rb

@@ -0,0 +1,19 @@
+require 'sax_stream/internal/mappings/element_content'
+require 'sax_stream/internal/mappings/element_attribute'
+require 'sax_stream/internal/mappings/child'
+
+module SaxStream
+  module Internal
+    class MappingFactory
+      def self.build_mapping(name, options)
+        last_part = options[:to].split('/').last
+        klass = (last_part =~ /^@/ ? Mappings::ElementAttribute : Mappings::ElementContent)
+        klass.new(name, options)
+      end
+
+      def self.build_relation(name, options)
+        Mappings::Child.new(name, options)
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/mappings/base.rb

@@ -0,0 +1,56 @@
+module SaxStream
+  module Internal
+    module Mappings
+      class Base
+        attr_reader :name
+
+        def initialize(name, options = {})
+          @name = name.to_s
+          @path = options[:to]
+          process_conversion_type(options[:as])
+        end
+
+        def handler_for(name, collector, handler_stack, parent_object)
+        end
+
+        def path_parts
+          @path.split('/')
+        rescue => e
+          raise "could not split #{@path.inspect} for #{@name.inspect}"
+        end
+
+        def map_value_onto_object(object, value)
+        end
+
+        def find_or_insert_parent_node(doc, base)
+          find_or_insert_nested_node(doc, base, path_parts.tap(&:pop))
+        end
+
+        def update_parent_node(builder, doc, parent, object)
+          raise NotImplementedError
+        end
+
+        private
+
+          def find_or_insert_nested_node(doc, base, remaining_parts)
+            part = remaining_parts.shift
+            return base unless part
+            node = find_or_insert_child_element(doc, base, part)
+            find_or_insert_nested_node(doc, node, remaining_parts)
+          end
+
+          def find_or_insert_child_element(doc, base, part)
+            base.search(part).first || insert_child_element(doc, base, part)
+          end
+
+          def insert_child_element(doc, base, part)
+            doc.create_element(part).tap do |element|
+              base << element
+            end
+          end
+
+
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/mappings/child.rb

@@ -0,0 +1,74 @@
+require 'sax_stream/internal/mapper_handler'
+require 'sax_stream/internal/singular_relationship_collector'
+require 'sax_stream/internal/mappings/base'
+
+module SaxStream
+  module Internal
+    module Mappings
+      class Child < Base
+        # Supported options are :to, :as & :parent_collects. See Mapper.relate documentation for more details.
+        def initialize(name, options)
+          @parent_collects = options[:parent_collects]
+          super
+        end
+
+        def handler_for(node_path, collector, handler_stack, parent_object)
+          node_name = node_path.split('/').last
+          @mapper_classes.each do |mapper_class|
+            if mapper_class.maps_node?(node_name)
+              return MapperHandler.new(mapper_class, child_collector(parent_object, collector), handler_stack)
+            end
+          end
+          nil
+        end
+
+        def build_empty_relation
+          [] if @plural
+        end
+
+        def update_parent_node(builder, doc, parent, object)
+          value_from_object(object).each do |child_object|
+            parent << builder.build_xml_for(child_object, parent)
+          end
+        end
+
+        private
+
+          def value_from_object(object)
+            result = object.relations[@name]
+            result = [result] unless @plural
+            result
+          end
+
+          def child_collector(parent_object, collector)
+            if @parent_collects
+              if @plural
+                parent_object.relations[name]
+              else
+                SingularRelationshipCollector.new(parent_object, @name)
+              end
+            else
+              collector
+            end
+          end
+
+          def arrayify(value)
+            value.is_a?(Enumerable) ? value : [value]
+          end
+
+          def process_conversion_type(as)
+            @plural = as.is_a?(Enumerable)
+            @mapper_classes = arrayify(as).compact
+            if @mapper_classes.empty?
+              raise ":as options for #{@name} field is empty, for child nodes it must be a mapper class or array of mapper classes"
+            end
+            @mapper_classes.each do |mapper_class|
+              unless mapper_class.respond_to?(:map_key_onto_object)
+                raise ":as options for #{@name} field contains #{mapper_class.inspect} which does not appear to be a valid mapper class"
+              end
+            end
+          end
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/mappings/element.rb

@@ -0,0 +1,53 @@
+require 'sax_stream/internal/mappings/base'
+
+module SaxStream
+  module Internal
+    module Mappings
+      class Element < Base
+        def map_value_onto_object(object, value)
+          if value && @parser
+            value = @parser.parse(value)
+          end
+          if object.respond_to?(setter_method)
+            object.send(setter_method, value)
+          else
+            object[@name] = value
+          end
+        end
+
+        def string_value_from_object(object)
+          result = raw_value_from_object(object)
+          result = @parser.format(result) if @parser && @parser.respond_to?(:format)
+          result.to_s
+        end
+
+        def find_or_insert_node(doc, base)
+          find_or_insert_nested_node(doc, base, path_parts)
+        end
+
+        private
+          def raw_value_from_object(object)
+            if object.respond_to?(@name) && !Object.new.respond_to?(@name)
+              object.send(@name)
+            else
+              object[@name]
+            end
+          end
+
+          def setter_method
+            "#{@name}=".to_sym
+          end
+
+          def process_conversion_type(as)
+            if as
+              if as.respond_to?(:parse)
+                @parser = as
+              else
+                raise ArgumentError, ":as options for #{@name} field is a #{as.inspect} which must respond to parse"
+              end
+            end
+          end
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/mappings/element_attribute.rb

@@ -0,0 +1,20 @@
+require 'sax_stream/internal/mappings/element'
+
+module SaxStream
+  module Internal
+    module Mappings
+      class ElementAttribute < Element
+        def update_parent_node(builder, doc, parent, object)
+          parent[base_attribute_name] = string_value_from_object(object)
+          parent
+        end
+
+        private
+
+          def base_attribute_name
+            path_parts.last.sub(/^@/, '')
+          end
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/mappings/element_content.rb

@@ -0,0 +1,25 @@
+require 'sax_stream/internal/mappings/element'
+
+module SaxStream
+  module Internal
+    module Mappings
+      class ElementContent < Element
+        def initialize(name, options = {})
+          @cdata = options[:cdata]
+          super
+        end
+
+        def update_parent_node(builder, doc, parent, object)
+          node = find_or_insert_child_element(doc, parent, path_parts.last)
+          value = string_value_from_object(object)
+          if @cdata
+            node.add_child(Nokogiri::XML::CDATA.new(doc, value))
+          else
+            node.content = value
+          end
+          node
+        end
+      end
+    end
+  end
+end

data/lib/sax_stream/internal/xml_builder.rb

@@ -0,0 +1,49 @@
+require 'nokogiri'
+
+module SaxStream
+  module Internal
+    class XmlBuilder
+      def initialize(options = {})
+        @encoding = options[:encoding] || 'UTF-8'
+      end
+
+      def build_xml_for(object, parent = nil)
+        mappings = object.mappings
+
+        in_sub_object = has_doc?
+        @doc ||= build_doc
+
+        base = add_base_element(@doc, parent || @doc, object)
+
+        object.mappings.each do |mapping|
+          add_mapping(@doc, base, object, mapping)
+        end
+
+        in_sub_object ? base : @doc.to_xml
+      end
+
+      private
+
+        def has_doc?
+          !!@doc
+        end
+
+        def build_doc
+          @doc = Nokogiri::XML::Document.new
+          @doc.encoding = @encoding
+          @doc
+        end
+
+        def add_base_element(doc, parent, object)
+          base = doc.create_element(object.node_name)
+          parent << base
+          base
+        end
+
+        def add_mapping(doc, base, object, mapping)
+          parent = mapping.find_or_insert_parent_node(doc, base)
+          mapping.update_parent_node(self, doc, parent, object)
+        end
+    end
+  end
+end

data/lib/sax_stream/mapper.rb

@@ -1,5 +1,6 @@
-require 'sax_stream/internal/field_mapping'
-require 'sax_stream/internal/child_mapping'
+require 'sax_stream/internal/mapping_factory'
+require 'sax_stream/internal/xml_builder'
+require 'sax_stream/core_extensions/ordered_hash'
 
 module SaxStream
   # Include this module to make your class map an XML node. For usage examples, see the READEME.
@@ -15,7 +16,7 @@ module SaxStream
       end
 
       def map(attribute_name, options = {})
-        store_field_mapping(options[:to], Internal::FieldMapping.new(attribute_name, options))
+        store_field_mapping(options[:to], Internal::MappingFactory.build_mapping(attribute_name, options))
       end
 
       # Define a relation to another object which is built from an XML node using another class
@@ -49,7 +50,8 @@ module SaxStream
       #                          or at least what is known about it, but the parent will not be finished being
       #                          parsed. The parent will have already parsed all XML attributes though.
       def relate(attribute_name, options = {})
-        store_relation_mapping(options[:to] || '*', Internal::ChildMapping.new(attribute_name, options))
+        options[:to] ||= '*'
+        store_relation_mapping(options[:to], Internal::MappingFactory.build_relation(attribute_name, options))
       end
 
       def node_name
@@ -92,11 +94,13 @@ module SaxStream
       end
 
       def mappings
-        parent_class_values(:mappings, {}).merge(class_mappings).freeze
+        parent_class_values(:mappings, CoreExtensions::OrderedHash.new).merge(class_mappings).freeze
       end
 
       def regex_mappings
-        (class_regex_mappings + parent_class_values(:regex_mappings, [])).freeze
+        mappings.reject do |key, mapping|
+          !key.is_a?(Regexp)
+        end
       end
 
       def should_collect?
@@ -111,11 +115,8 @@ module SaxStream
         end
 
         def store_field_mapping(key, mapping)
-          if key.include?('*')
-            class_regex_mappings << [Regexp.new(key.gsub('*', '[^/]+')), mapping]
-          else
-            class_mappings[key] = mapping
-          end
+          key = Regexp.new(key.gsub('*', '[^/]+')) if key.include?('*')
+          class_mappings[key] = mapping
         end
 
         def field_mapping(key)
@@ -133,12 +134,8 @@ module SaxStream
           @relation_mappings ||= []
         end
 
-        def class_regex_mappings
-          @regex_mappings ||= []
-        end
-
         def class_mappings
-          @mappings ||= {}
+          @mappings ||= CoreExtensions::OrderedHash.new
         end
 
         def parent_class_values(method_name, default)
@@ -159,13 +156,21 @@ module SaxStream
     end
 
     def attributes
-      @attributes ||= {}
+      @attributes ||= CoreExtensions::OrderedHash.new
+    end
+
+    def attributes=(value)
+      @attributes = value
     end
 
     def relations
       @relations ||= build_empty_relations
     end
 
+    def mappings
+      self.class.mappings.values
+    end
+
     def node_name
       self.class.node_name
     end
@@ -174,10 +179,15 @@ module SaxStream
       self.class.should_collect?
     end
 
+    def to_xml(encoding = 'UTF-8', builder = nil)
+      builder ||= Internal::XmlBuilder.new(:encoding => encoding)
+      builder.build_xml_for(self)
+    end
+
     private
 
       def build_empty_relations
-        result = {}
+        result = CoreExtensions::OrderedHash.new
         self.class.relation_mappings.each do |relation_mapping|
           result[relation_mapping.name] = relation_mapping.build_empty_relation
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sax_stream
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-26 00:00:00.000000000 Z
+date: 2012-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &70295398456460 !ruby/object:Gem::Requirement
+  requirement: &70160590504180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: 1.5.2
   type: :runtime
   prerelease: false
-  version_requirements: *70295398456460
+  version_requirements: *70160590504180
 description: A streaming XML parser which builds objects and passes them to a collecter
   as they are ready. Based upon Nokogiri SAX parsing functionality.
 email:
@@ -32,15 +32,21 @@ extra_rdoc_files: []
 files:
 - lib/sax_stream/collectors/block_collector.rb
 - lib/sax_stream/collectors/naive_collector.rb
+- lib/sax_stream/core_extensions/ordered_hash.rb
 - lib/sax_stream/errors.rb
-- lib/sax_stream/internal/child_mapping.rb
 - lib/sax_stream/internal/combined_handler.rb
 - lib/sax_stream/internal/element_stack.rb
-- lib/sax_stream/internal/field_mapping.rb
 - lib/sax_stream/internal/handler_stack.rb
 - lib/sax_stream/internal/mapper_handler.rb
+- lib/sax_stream/internal/mapping_factory.rb
+- lib/sax_stream/internal/mappings/base.rb
+- lib/sax_stream/internal/mappings/child.rb
+- lib/sax_stream/internal/mappings/element.rb
+- lib/sax_stream/internal/mappings/element_attribute.rb
+- lib/sax_stream/internal/mappings/element_content.rb
 - lib/sax_stream/internal/sax_handler.rb
 - lib/sax_stream/internal/singular_relationship_collector.rb
+- lib/sax_stream/internal/xml_builder.rb
 - lib/sax_stream/mapper.rb
 - lib/sax_stream/parser.rb
 - lib/sax_stream/types/boolean.rb

data/lib/sax_stream/internal/child_mapping.rb

@@ -1,65 +0,0 @@
-require 'sax_stream/internal/mapper_handler'
-require 'sax_stream/internal/singular_relationship_collector'
-
-module SaxStream
-  module Internal
-    class ChildMapping
-      attr_reader :name
-
-      # Supported options are :to, :as & :parent_collects. See Mapper.relate documentation for more details.
-      def initialize(name, options)
-        @name = name.to_s
-        @parent_collects = options[:parent_collects]
-        process_conversion_type(options[:as])
-      end
-
-      def handler_for(node_path, collector, handler_stack, parent_object)
-        node_name = node_path.split('/').last
-        @mapper_classes.each do |mapper_class|
-          if mapper_class.maps_node?(node_name)
-            return MapperHandler.new(mapper_class, child_collector(parent_object, collector), handler_stack)
-          end
-        end
-        nil
-      end
-
-      def map_value_onto_object(object, value)
-      end
-
-      def build_empty_relation
-        [] if @plural
-      end
-
-      private
-
-        def child_collector(parent_object, collector)
-          if @parent_collects
-            if @plural
-              parent_object.relations[name]
-            else
-              SingularRelationshipCollector.new(parent_object, @name)
-            end
-          else
-            collector
-          end
-        end
-
-        def arrayify(value)
-          value.is_a?(Enumerable) ? value : [value]
-        end
-
-        def process_conversion_type(as)
-          @plural = as.is_a?(Enumerable)
-          @mapper_classes = arrayify(as).compact
-          if @mapper_classes.empty?
-            raise ":as options for #{@name} field is empty, for child nodes it must be a mapper class or array of mapper classes"
-          end
-          @mapper_classes.each do |mapper_class|
-            unless mapper_class.respond_to?(:map_key_onto_object)
-              raise ":as options for #{@name} field contains #{mapper_class.inspect} which does not appear to be a valid mapper class"
-            end
-          end
-        end
-    end
-  end
-end

data/lib/sax_stream/internal/field_mapping.rb

@@ -1,40 +0,0 @@
-module SaxStream
-  module Internal
-    class FieldMapping
-      def initialize(name, options = {})
-        @name = name.to_s
-        @path = options[:to]
-        process_conversion_type(options[:as])
-      end
-
-      def map_value_onto_object(object, value)
-        if value && @parser
-          value = @parser.parse(value)
-        end
-        if object.respond_to?(setter_method)
-          object.send(setter_method, value)
-        else
-          object[@name] = value
-        end
-      end
-
-      def handler_for(name, collector, handler_stack, parent_object)
-      end
-
-      private
-        def setter_method
-          "#{@name}=".to_sym
-        end
-
-        def process_conversion_type(as)
-          if as
-            if as.respond_to?(:parse)
-              @parser = as
-            else
-              raise ArgumentError, ":as options for #{@name} field is a #{as.inspect} which must respond to parse"
-            end
-          end
-        end
-    end
-  end
-end