roxml 1.2 → 2.3.2

data/lib/roxml/extensions/active_support.rb

@@ -0,0 +1,32 @@
+require 'rubygems'
+require 'active_support/core_ext/symbol'
+require 'active_support/core_ext/blank'
+require 'active_support/core_ext/duplicable'
+require 'active_support/core_ext/array/extract_options'
+require 'active_support/core_ext/hash/reverse_merge'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/module/aliasing'
+require 'active_support/core_ext/object/misc' # returning
+require 'active_support/inflector'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/string/starts_ends_with'
+
+require 'extensions/enumerable'
+require 'extensions/array'
+
+class Module
+  include ActiveSupport::CoreExtensions::Module if ActiveSupport::CoreExtensions.const_defined? :Module
+end
+
+class String #:nodoc:
+  include ActiveSupport::CoreExtensions::String::Inflections
+  include ActiveSupport::CoreExtensions::String::StartsEndsWith
+end
+
+class Array #:nodoc:
+  include ActiveSupport::CoreExtensions::Array::ExtractOptions
+end
+
+class Hash #:nodoc:
+  include ActiveSupport::CoreExtensions::Hash::ReverseMerge
+end

data/lib/roxml/extensions/array.rb

@@ -0,0 +1,5 @@
+require File.join(File.dirname(__FILE__), 'array/conversions')
+
+class Array #:nodoc:
+  include ROXML::CoreExtensions::Array::Conversions
+end

data/lib/roxml/extensions/array/conversions.rb

@@ -0,0 +1,25 @@
+module ROXML
+  module CoreExtensions
+    module Array #:nodoc:
+      module Conversions
+        # Translates an array into a hash, where each element of the array is
+        # an array with 2 elements:
+        #
+        #   >> [[:key, :value], [1, 2], ['key', 'value']].to_h
+        #   => {:key => :value, 1 => 2, 'key' => 'value'}
+        #
+        def to_hash
+          inject({}) do |result, (k, v)|
+            result[k] = v
+            result
+          end
+        end
+
+        def to_h #:nodoc:
+          to_hash
+        end
+        deprecate :to_h => :to_hash
+      end
+    end
+  end
+end

data/lib/roxml/extensions/deprecation.rb

@@ -0,0 +1,28 @@
+require 'active_support/core_ext/kernel/reporting'
+require 'active_support/core_ext/module/attribute_accessors'
+require 'active_support/deprecation'
+require 'active_support/version'
+
+module ActiveSupport # :nodoc:all
+  module Deprecation
+    class << self
+      if VERSION::MAJOR <= 2 && VERSION::MINOR <= 1
+        def deprecation_message(callstack, message = nil)
+          message ||= "You are using deprecated behavior which will be removed from the next major or minor release."
+          "DEPRECATION WARNING: #{message}. #{deprecation_caller_message(callstack)}"
+        end
+      end
+    end
+
+    module ClassMethods
+      def deprecated_method_warning(method_name, message=nil)
+        warning = "#{method_name} is deprecated and will be removed from the next major or minor release."
+        case message
+          when Symbol then "#{warning} (use #{message} instead)"
+          when String then "#{warning} (#{message})"
+          else warning
+        end
+      end
+    end
+  end
+end

data/lib/roxml/extensions/string.rb

@@ -0,0 +1,21 @@
+require File.join(File.dirname(__FILE__), 'string/conversions')
+require File.join(File.dirname(__FILE__), 'string/iterators')
+
+class String #:nodoc:
+  include ROXML::CoreExtensions::String::Conversions
+  include ROXML::CoreExtensions::String::Iterators
+end
+
+class Object #:nodoc:
+  # Deprecated in favor of explicit #to_s.to_utf
+  def to_utf
+    ActiveSupport::Deprecation.warn "This method will be removed from Object please use String#to_utf instead via explicit #to_s"
+    to_s.to_utf
+  end
+
+  # Deprecated in favor of explicit #to_s.to_latin
+  def to_latin
+    ActiveSupport::Deprecation.warn "This method will be removed from Object please use String#to_latin instead via explicit #to_s"
+    to_s.to_latin
+  end
+end

data/lib/roxml/extensions/string/conversions.rb

@@ -0,0 +1,44 @@
+module ROXML
+  module CoreExtensions #:nodoc:
+    module String
+      # Extension of String class to handle conversion from/to
+      # UTF-8/ISO-8869-1
+      module Conversions
+        require 'iconv'
+
+        #
+        # Return an utf-8 representation of this string.
+        #
+        def to_utf
+          begin
+            Iconv.new("utf-8", "iso-8859-1").iconv(to_s)
+          rescue Iconv::IllegalSequence
+            STDERR << "!! Failed converting from UTF-8 -> ISO-8859-1 (#{self}). Already the right charset?"
+            self
+          end
+        end
+
+        #
+        # Convert this string to iso-8850-1
+        #
+        def to_latin
+          begin
+            Iconv.new("iso-8859-1", "utf-8").iconv(to_s)
+          rescue Iconv::IllegalSequence
+            STDERR << "!! Failed converting from ISO-8859-1 -> UTF-8 (#{self}). Already the right charset?"
+            self
+          end
+        end
+      end
+    end
+  end
+end
+
+class Object
+end
+
+class String
+  def between(separator, &block)
+    split(separator).collect(&block).join(separator)
+  end
+end

data/lib/roxml/extensions/string/iterators.rb

@@ -0,0 +1,12 @@
+module ROXML
+  module CoreExtensions
+    module String #:nodoc:
+      module Iterators
+        # Allows you to iterate over and modify the sub-strings between _separator_.  Returns the joined result of the modification.
+        def between(separator, &block)
+          split(separator).collect(&block).join(separator)
+        end
+      end
+    end
+  end
+end

data/lib/roxml/options.rb

@@ -0,0 +1,266 @@
+module ROXML
+  HASH_KEYS = [:attrs, :key, :value].freeze
+  TYPE_KEYS = [:attr, :text, :hash, :content].freeze
+
+  class HashDesc # :nodoc:
+    attr_reader :key, :value, :wrapper
+
+    def initialize(opts, wrapper)
+      unless (invalid_keys = opts.keys - HASH_KEYS).empty?
+        raise ArgumentError, "Invalid Hash description keys: #{invalid_keys.join(', ')}"
+      end
+
+      @wrapper = wrapper
+      if opts.has_key? :attrs
+        @key   = to_ref(opts, :attr, opts[:attrs][0])
+        @value = to_ref(opts, :attr, opts[:attrs][1])
+      else
+        @key = to_ref opts, *fetch_element(opts, :key)
+        @value = to_ref opts, *fetch_element(opts, :value)
+      end
+    end
+
+    def types
+      [@key.class, @value.class]
+    end
+
+    def names
+      [@key.name, @value.name]
+    end
+
+  private
+    def fetch_element(opts, what)
+      case opts[what]
+      when Hash
+        raise ArgumentError, "Hash #{what} is over-specified: #{opts[what].pp_s}" unless opts[what].keys.one?
+        type = opts[what].keys.first
+        [type, opts[what][type]]
+      when :content
+        [:content, opts[:name]]
+      when :name
+        [:name, '*']
+      when String
+        [:text, opts[what]]
+      when Symbol
+        [:text, opts[what]]
+      else
+        raise ArgumentError, "unrecognized hash parameter: #{what} => #{opts[what]}"
+      end
+    end
+
+    def to_ref(args, type, name)
+      case type
+      when :attr
+        XMLAttributeRef.new(to_hash_args(args, type, name))
+      when :text
+        XMLTextRef.new(to_hash_args(args, type, name))
+      when Symbol
+        XMLTextRef.new(to_hash_args(args, type, name))
+      else
+        raise ArgumentError, "Missing key description #{{:type => type, :name => name}.pp_s}"
+      end
+    end
+
+    def to_hash_args(args, type, name)
+      args = [args] unless args.is_a? Array
+
+      if args.one? && !(args.only.keys & HASH_KEYS).empty?
+        opts = {type => name}
+        if type == :content
+          opts[:type] = :text
+          (opts[:as] ||= []) << :content
+        end
+        Opts.new(name, opts)
+      else
+        opts = args.extract_options!
+        raise opts.to_s
+      end
+    end
+  end
+
+  class Opts # :nodoc:
+    attr_reader :name, :type, :hash, :blocks, :default, :accessor
+
+    class << self
+      def silence_xml_name_warning?
+        @silence_xml_name_warning || (ROXML.const_defined?('SILENCE_XML_NAME_WARNING') && ROXML::SILENCE_XML_NAME_WARNING)
+      end
+
+      def silence_xml_name_warning!
+        @silence_xml_name_warning = true
+      end
+    end
+
+    def initialize(sym, *args, &block)
+      @accessor = sym
+      @opts = extract_options!(args)
+      @default = @opts.delete(:else)
+
+      @opts.reverse_merge!(:as => [], :in => nil)
+      @opts[:as] = [*@opts[:as]]
+
+      @type = extract_type(args)
+      @opts[:as] << :bool if @accessor.to_s.ends_with?('?')
+
+      if @type.respond_to?(:xml_name?) && @type.xml_name?
+        unless self.class.silence_xml_name_warning?
+          warn "WARNING: As of 2.3, a breaking change has been in the naming of sub-objects. " +
+               "ROXML now considers the xml_name of the sub-object before falling back to the accessor name of the parent. " +
+               "Use :from on the parent declaration to override this behavior. Set ROXML::SILENCE_XML_NAME_WARNING to avoid this message."
+          self.class.silence_xml_name_warning!
+        end
+        @opts[:from] ||= @type.tag_name
+      else
+        @opts[:from] ||= variable_name
+      end
+
+      @blocks = collect_blocks(block, @opts[:as])
+
+      @name = @opts[:from].to_s
+      @name = @name.singularize if hash? || array?
+      if hash? && (hash.key.name? || hash.value.name?)
+        @name = '*'
+      end
+
+      raise ArgumentError, "Can't specify both :else default and :required" if required? && default
+    end
+
+    def variable_name
+      accessor.to_s.ends_with?('?') ? accessor.to_s.chomp('?') : accessor.to_s
+    end
+
+    def hash
+      @hash ||= HashDesc.new(@opts.delete(:hash), name) if hash?
+    end
+
+    def hash?
+      @type == :hash
+    end
+
+    def content?
+      @type == :content
+    end
+
+    def array?
+      @opts[:as].include? :array
+    end
+
+    def cdata?
+      @opts[:as].include? :cdata
+    end
+
+    def wrapper
+      @opts[:in]
+    end
+
+    def required?
+      @opts[:required]
+    end
+
+  private
+    BLOCK_TO_FLOAT = lambda do |val|
+      if val.is_a? Array
+        val.collect do |v|
+          Float(v)
+        end
+      else
+        Float(val)
+      end
+    end
+
+    BLOCK_TO_INT = lambda do |val|
+      if val.is_a? Array
+        val.collect do |v|
+          Integer(v)
+        end
+      else
+        Integer(val)
+      end
+    end
+
+    TRUE_VALS = %w{TRUE True true 1}
+    FALSE_VALS = %w{FALSE False false 0}
+
+    BLOCK_SHORTHANDS = {
+      :integer => BLOCK_TO_INT,
+      Integer  => BLOCK_TO_INT,
+      :float   => BLOCK_TO_FLOAT,
+      Float    => BLOCK_TO_FLOAT,
+      :bool    => nil,
+      :bool_standalone => lambda do |val|
+        if TRUE_VALS.include? val
+          true
+        elsif FALSE_VALS.include? val
+          false
+        else
+          nil
+        end
+      end,
+
+      :bool_combined => lambda do |val|
+        if TRUE_VALS.include? val
+          true
+        elsif FALSE_VALS.include? val
+          false
+        else
+          val
+        end
+      end
+    }
+
+    def collect_blocks(block, as)
+      shorthands = as & BLOCK_SHORTHANDS.keys
+      if shorthands.size > 1
+        raise ArgumentError, "multiple block shorthands supplied #{shorthands.map(&:to_s).join(', ')}"
+      end
+
+      shorthand = shorthands.first
+      if shorthand == :bool
+        # if a second block is present, and we can't coerce the xml value
+        # to bool, we need to be able to pass it to the user-provided block
+        shorthand = block ? :bool_combined : :bool_standalone
+      end
+      [BLOCK_SHORTHANDS[shorthand], block].compact
+    end
+
+    def extract_options!(args)
+      opts = args.extract_options!
+      unless (opts.keys & HASH_KEYS).empty?
+        args.push(opts)
+        opts = {}
+      end
+      opts
+    end
+
+    def extract_type(args)
+      types = (@opts.keys & TYPE_KEYS)
+      # type arg
+      if args.one? && types.empty?
+        if args.only.is_a? Array
+          @opts[:as] << :array
+          return args.only.only
+        elsif args.only.is_a? Hash
+          @opts[:hash] = args.only
+          return :hash
+        else
+          return args.only
+        end
+      end
+
+      unless args.empty?
+        raise ArgumentError, "too many arguments (#{(args + types).join(', ')}).  Should be name, type, and " +
+                             "an options hash, with the type and options optional"
+      end
+
+      # type options
+      if types.one?
+        @opts[:from] = @opts.delete(types.only)
+        types.only
+      elsif types.empty?
+        :text
+      else
+        raise ArgumentError, "more than one type option specified: #{types.join(', ')}"
+      end
+    end
+  end
+end

data/lib/roxml/xml.rb

@@ -0,0 +1,223 @@
+module ROXML
+  unless const_defined? 'XML_PARSER'
+    begin
+      require 'libxml'
+      XML_PARSER = 'libxml' # :nodoc:
+    rescue LoadError
+      XML_PARSER = 'rexml' # :nodoc:
+    end
+  end
+  require File.join(File.dirname(__FILE__), 'xml', XML_PARSER)
+
+  class RequiredElementMissing < Exception # :nodoc:
+  end
+
+  #
+  # Internal base class that represents an XML - Class binding.
+  #
+  class XMLRef # :nodoc:
+    delegate :name, :required?, :array?, :wrapper, :blocks, :accessor, :variable_name, :to => :opts
+    alias_method :xpath_name, :name
+
+    def initialize(opts)
+      @opts = opts
+    end
+
+    # Reads data from the XML element and populates the instance
+    # accordingly.
+    def populate(xml, instance)
+      data = value(xml)
+      instance.instance_variable_set("@#{variable_name}", data)
+      instance
+    end
+
+    def name?
+      false
+    end
+
+    def update_xml(xml, value)
+      returning wrap(xml) do |xml|
+        write_xml(xml, value)
+      end
+    end
+
+    def default
+      @default ||= @opts.default || (@opts.array? ? Array.new : nil)
+      @default.duplicable? ? @default.dup : @default
+    end
+
+    def value(xml)
+      value = fetch_value(xml)
+      if value.blank?
+        raise RequiredElementMissing, accessor.to_s if required?
+        value = default
+      end
+      apply_blocks(value)
+    end
+
+  private
+    attr_reader :opts
+
+    def apply_blocks(val)
+      blocks.inject(val) {|val, block| block[val] }
+    end
+
+    def xpath
+      wrapper ? "#{wrapper}/#{xpath_name}" : xpath_name.to_s
+    end
+
+    def wrap(xml)
+      (wrapper && xml.name != wrapper) ? xml.child_add(XML::Node.new_element(wrapper)) : xml
+    end
+  end
+
+  # Interal class representing an XML attribute binding
+  #
+  # In context:
+  #  <element attribute="XMLAttributeRef">
+  #   XMLTextRef
+  #  </element>
+  class XMLAttributeRef < XMLRef # :nodoc:
+  private
+    # Updates the attribute in the given XML block to
+    # the value provided.
+    def write_xml(xml, value)
+      xml.attributes[name] = value.to_s.to_utf
+    end
+
+    def fetch_value(xml)
+      attr = xml.search(xpath).first
+      attr && attr.value
+    end
+
+    def xpath_name
+      "@#{name}"
+    end
+  end
+
+  # Interal class representing XML content text binding
+  #
+  # In context:
+  #  <element attribute="XMLAttributeRef">
+  #   XMLTextRef
+  #  </element>
+  class XMLTextRef < XMLRef # :nodoc:
+    delegate :cdata?, :content?, :to => :opts
+
+    def name?
+      name == '*'
+    end
+
+  private
+    # Updates the text in the given _xml_ block to
+    # the _value_ provided.
+    def write_xml(xml, value)
+      if content?
+        add(xml, value)
+      elsif name?
+        xml.name = value
+      elsif array?
+        value.each do |v|
+          add(xml.child_add(XML::Node.new_element(name)), v)
+        end
+      else
+        add(xml.child_add(XML::Node.new_element(name)), value)
+      end
+    end
+
+    def fetch_value(xml)
+      if content?
+        xml.content.strip
+      elsif name?
+        xml.name
+      elsif array?
+        xml.search(xpath).collect do |e|
+          e.content.strip.to_latin if e.content
+        end
+      else
+        child = xml.search(xpath).first
+        child.content if child
+      end
+    end
+
+    def add(dest, value)
+      if cdata?
+        dest.child_add(XML::Node.new_cdata(value.to_s.to_utf))
+      else
+        dest.content = value.to_s.to_utf
+      end
+    end
+  end
+
+  class XMLHashRef < XMLTextRef # :nodoc:
+    delegate :hash, :to => :opts
+
+    def default
+      result = super
+      result.nil? ? {} : result
+    end
+
+  private
+    # Updates the composed XML object in the given XML block to
+    # the value provided.
+    def write_xml(xml, value)
+      value.each_pair do |k, v|
+        node = xml.child_add(XML::Node.new_element(hash.wrapper))
+        hash.key.update_xml(node, k)
+        hash.value.update_xml(node, v)
+      end
+    end
+
+    def fetch_value(xml)
+      xml.search(xpath).collect do |e|
+        [hash.key.value(e), hash.value.value(e)]
+      end
+    end
+
+    def apply_blocks(vals)
+      unless blocks.empty?
+        vals.collect! do |kvp|
+          super(kvp)
+        end
+      end
+      vals.to_hash if vals
+    end
+  end
+
+  class XMLObjectRef < XMLTextRef # :nodoc:
+    delegate :type, :to => :opts
+
+  private
+    # Updates the composed XML object in the given XML block to
+    # the value provided.
+    def write_xml(xml, value)
+      unless array?
+        xml.child_add(value.to_xml(name))
+      else
+        value.each do |v|
+          xml.child_add(v.to_xml(name))
+        end
+      end
+    end
+
+    def fetch_value(xml)
+      unless array?
+        if child = xml.search(xpath).first
+          instantiate(child)
+        end
+      else
+        xml.search(xpath).collect do |e|
+          instantiate(e)
+        end
+      end
+    end
+
+    def instantiate(elem)
+      if type.respond_to? :from_xml
+        type.from_xml(elem)
+      else
+        type.new(elem)
+      end
+    end
+  end
+end