opinionated-xml 0.0.1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/History.textile

@@ -0,0 +1 @@
+Note: OX v.1 Does not handle treating attribute values as the changing "value" of a node

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Matt Zumwalt
+
+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,17 @@
+= opinionated-xml
+
+A library to help you tame sprawling XML schemas like MODS.
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Matt Zumwalt. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,52 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "opinionated-xml"
+    gem.summary = %Q{A library to help you tame sprawling XML schemas like MODS.}
+    gem.description = %Q{A library to help you tame sprawling XML schemas like MODS.  Wraps Nokogiri documents in objects with miscellaneous helper methods for doing things like retrieve generated xpath queries or look up properties based on a simplified DSL}
+    gem.email = "matt.zumwalt@yourmediashelf.com"
+    gem.homepage = "http://github.com/mediashelf/opinionated-xml"
+    gem.authors = ["Matt Zumwalt"]
+    
+    gem.add_dependency('nokogiri')
+    gem.add_dependency('facets')
+    
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "mocha", ">= 0.9.8"
+    gem.add_development_dependency "ruby-debug"
+    
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "opinionated-xml #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/opinionated-xml/ox.rb

@@ -0,0 +1,430 @@
+require "open-uri"
+require "logger"
+
+module OX
+  
+  # Class Methods -- These methods will be available on classes that include OX (ie. the OX MODS class)
+  
+  module ClassMethods
+    
+    attr_accessor :root_property_ref, :root_config, :ox_namespaces, :schema_url
+    attr_writer :schema_file
+    attr_reader :properties
+    
+    def root_property( property_ref, path, namespace, opts={})
+      # property property_ref, path, opts.merge({:path=>path, :ref=>property_ref})
+      @root_config = opts.merge({:namespace=>namespace, :path=>path, :ref=>property_ref})
+      @root_property_ref = property_ref
+      @ox_namespaces = {'oxns'=>root_config[:namespace]}
+      @schema_url = opts[:schema]
+    end
+    
+    def property( property_ref, opts={})
+      @properties ||= {}
+      @properties[property_ref] = opts.merge({:ref=>property_ref})
+      configure_property @properties[property_ref]
+      configure_paths @properties[property_ref]
+    end
+    
+    def configure_property(prop_hash=root_config)
+      if prop_hash.has_key?(:variant_of)
+        properties[prop_hash[:ref]] = properties[prop_hash[:variant_of]].deep_copy.merge(prop_hash)
+      end
+      if !prop_hash.has_key?(:convenience_methods)
+        prop_hash[:convenience_methods] = {}
+      end
+    end
+    
+    # Generates appropriate xpath queries for a property described by the given hash
+    # putting the results into the hash under keys like :xpath and :xpath_constrained
+    # This is also done recursively for all subelements and convenience methods described in the hash.
+    def configure_paths(prop_hash=root_config)
+      prop_hash[:path] ||= ""
+      # prop_hash[:path] = Array( prop_hash[:path] )
+      xpath_opts = {}
+      
+      if prop_hash.has_key?(:variant_of)
+        xpath_opts[:variations] = prop_hash
+      end
+      
+      xpath_constrained_opts = xpath_opts.merge({:constraints=>:default})
+      
+      relative_xpath = generate_xpath(prop_hash, xpath_opts.merge(:relative=>true))
+      # prop_hash[:xpath] = generate_xpath(prop_hash, xpath_opts)
+      prop_hash[:xpath] = "//#{relative_xpath}"
+      prop_hash[:xpath_relative] = relative_xpath
+      prop_hash[:xpath_constrained] = generate_xpath(prop_hash, xpath_constrained_opts).gsub('"', '\"')
+      
+      prop_hash[:convenience_methods].each_pair do |cm_name, cm_props|
+        cm_xpath_relative_opts = cm_props.merge(:variations => cm_props, :relative=>true)
+        cm_constrained_opts = xpath_opts.merge(:constraints => cm_props)
+        
+        cm_relative_xpath = generate_xpath(cm_props, cm_xpath_relative_opts)
+        prop_hash[:convenience_methods][cm_name][:xpath_relative] = cm_relative_xpath
+        # prop_hash[:convenience_methods][cm_name][:xpath] = generate_xpath(cm_xpath_hash, cm_xpath_opts)
+        prop_hash[:convenience_methods][cm_name][:xpath] = prop_hash[:xpath] + "/" + cm_relative_xpath
+        prop_hash[:convenience_methods][cm_name][:xpath_constrained] = generate_xpath(prop_hash, cm_constrained_opts).gsub('"', '\"')
+      end
+      
+      if prop_hash.has_key?(:subelements) 
+        prop_hash[:subelements].each do |se|
+          configure_subelement_paths(se, prop_hash, xpath_opts)
+        end
+      end
+      
+      if properties[:unresolved].has_key?(prop_hash[:ref])
+        ref = prop_hash[:ref]
+        properties[:unresolved][ref].each do |parent_prop_hash|
+          logger.debug "Resolving #{ref} subelement for #{parent_prop_hash[:ref]} property"
+          configure_subelement_paths(ref, parent_prop_hash, xpath_opts)
+        end
+        properties[:unresolved].delete(ref)
+      end
+
+    end
+    
+    def configure_subelement_paths(se, parent_prop_hash, parent_xpath_opts)
+      # se_xpath_opts = parent_xpath_opts.merge(:subelement_of => parent_prop_hash[:ref])
+      se_xpath_opts = parent_xpath_opts
+      new_se_props = {}
+      if parent_prop_hash.has_key?(:variant_of)
+        se_xpath_opts[:variations] = parent_prop_hash
+      end
+      
+      if se.instance_of?(String)
+        
+        new_se_props[:path] = se
+        new_se_props[:xpath_relative] = generate_xpath({:path=>se}, :relative=>true)
+        new_se_props[:xpath] = parent_prop_hash[:xpath] + "/" + new_se_props[:xpath_relative]
+        se_xpath_constrained_opts = se_xpath_opts.merge({:constraints=>{:path=>se}})
+        new_se_props[:xpath_constrained] = generate_xpath(parent_prop_hash, se_xpath_constrained_opts)
+        
+      elsif se.instance_of?(Symbol) 
+        
+        if properties.has_key?(se)
+          
+          se_props = properties[se]
+          
+          new_se_props = se_props.deep_copy
+          # new_se_props[:path] = se_props[:path]
+          # new_se_props[:xpath_relative] = se_props[:xpath_relative]
+          new_se_props[:xpath] = parent_prop_hash[:xpath] + "/" + new_se_props[:xpath_relative] 
+          se_xpath_constrained_opts = parent_xpath_opts.merge(:constraints => se_props, :subelement_of => parent_prop_hash[:ref])        
+          new_se_props[:xpath_constrained] = generate_xpath(parent_prop_hash, se_xpath_constrained_opts)
+                
+        else
+          properties[:unresolved] ||= {}
+          properties[:unresolved][se] ||= []
+          properties[:unresolved][se] << parent_prop_hash
+          logger.debug("Added #{se.inspect} to unresolved properties with parent #{parent_prop_hash[:ref]}")
+        end                
+      else
+        logger.info("failed to generate path for #{se.inspect}")
+        se_xpath = ""
+        se_xpath_constrained = ""
+      end
+
+      if new_se_props.has_key?(:xpath_constrained)
+        new_se_props[:xpath_constrained].gsub!('"', '\"')
+      end
+      
+      properties[ parent_prop_hash[:ref] ][:convenience_methods][se.to_sym] = new_se_props  
+
+    end
+    
+    def generate_xpath( property_info, opts={})
+      prefix = "oxns"
+      property_info[:path] ||= "" 
+      path = property_info[:path]
+      path_array = Array( path )
+      template = ""
+      template << "//" unless opts[:relative]
+      template << "#{prefix}:"
+      template << delimited_list(path_array, "/#{prefix}:")
+
+      predicates = []   
+      default_content_path = property_info.has_key?(:default_content_path) ? property_info[:default_content_path] : ""
+      subelement_path_parts = []
+      
+      # Skip everything if a template was provided
+      if opts.has_key?(:template)
+        template = eval('"' + opts[:template] + '"')
+      else
+        # Apply variations
+        if opts.has_key?(:variations)
+          if opts[:variations].has_key?(:attributes)
+            opts[:variations][:attributes].each_pair do |attr_name, attr_value|
+              predicates << "@#{attr_name}=\"#{attr_value}\""
+            end
+          end
+          if opts[:variations].has_key?(:subelement_path) 
+            if opts[:variations][:subelement_path].instance_of?(Array)
+              opts[:variations][:subelement_path].each do |se_path|
+                subelement_path_parts << "#{prefix}:#{se_path}"  
+              end
+            else
+              subelement_path_parts << "#{prefix}:#{opts[:variations][:subelement_path]}"  
+            end
+          end
+        end
+      
+        # Apply constraints
+        if opts.has_key?(:constraints)  
+          arguments_for_contains_function = []
+          if opts[:constraints] == :default
+            if property_info.has_key?(:default_content_path)
+              default_content_path = property_info[:default_content_path]
+              arguments_for_contains_function << "#{prefix}:#{default_content_path}"
+            end
+          elsif opts[:constraints].has_key?(:path)
+            constraint_predicates = []
+            if opts.has_key?(:subelement_of)
+              constraint_path = "#{prefix}:#{opts[:constraints][:path]}"
+              if opts[:constraints].has_key?(:default_content_path)
+                constraint_path << "/#{prefix}:#{opts[:constraints][:default_content_path]}"
+              end 
+            else
+             constraint_path = "#{prefix}:#{opts[:constraints][:path]}"
+            end
+            arguments_for_contains_function << constraint_path
+            
+            if opts[:constraints].has_key?(:attributes) && opts[:constraints][:attributes].kind_of?(Hash)
+              opts[:constraints][:attributes].each_pair do |attr_name, attr_value|
+                constraint_predicates << "@#{attr_name}=\"#{attr_value}\""
+              end
+            end
+          
+            unless constraint_predicates.empty?
+              arguments_for_contains_function.last << "[#{delimited_list(constraint_predicates)}]"
+            end
+          
+          end
+          arguments_for_contains_function << "\":::constraint_value:::\""
+        
+          predicates << "contains(#{delimited_list(arguments_for_contains_function)})"
+        
+        end
+            
+        unless predicates.empty? 
+          template << "["
+          template << delimited_list(predicates, " and ")
+          template << "]"
+        end
+        
+        unless subelement_path_parts.empty?
+          subelement_path_parts.each {|path_part| template << "/#{path_part}"}
+        end
+      end
+      
+      # result = eval( '"' + template + '"' )
+      return template.gsub( /:::(.*?):::/ ) { '#{'+$1+'}' }
+    end
+    
+    #
+    # Convenience Methods for Retrieving Generated Info
+    #
+    
+    def xpath_query_for( property_ref, query_opts={}, opts={} )
+
+      if property_ref.instance_of?(String)
+        xpath_query = property_ref
+      else
+        property_info = property_info_for( property_ref )
+
+        if !property_info.nil?
+          if query_opts.kind_of?(String)
+            constraint_value = query_opts
+            xpath_template = property_info[:xpath_constrained]
+            xpath_query = eval( '"' + xpath_template + '"' )
+          elsif query_opts.kind_of?(Hash) && !query_opts.empty?       
+            key_value_pair = query_opts.first 
+            constraint_value = key_value_pair.last
+            xpath_template = property_info[:convenience_methods][key_value_pair.first][:xpath_constrained]
+            xpath_query = eval( '"' + xpath_template + '"' )          
+          else 
+            xpath_query = property_info[:xpath]
+          end
+        else
+          xpath_query = nil
+        end
+      end
+      return xpath_query
+    end
+
+    def property_info_for(property_ref)
+      if property_ref.instance_of?(Array) && property_ref.length == 1
+        property_ref = property_ref[0]      
+      end
+      if property_ref.instance_of?(Symbol)
+        property_info = properties[property_ref]
+      elsif property_ref.kind_of?(Array)
+        prop_ref = property_ref[0]
+        cm_name = property_ref[1]
+        if properties.has_key?(prop_ref)
+          property_info = properties[prop_ref][:convenience_methods][cm_name]
+        end
+      else
+        property_info = nil
+      end
+      return property_info 
+    end
+    
+    ##
+    # Validation Support
+    ##
+    
+    # Validate the given document against the Schema provided by the root_property for this class
+    def validate(doc)
+      schema.validate(doc).each do |error|
+          puts error.message
+      end
+    end
+    
+    # Retrieve the Nokogiri Schema for this class
+    def schema
+      @schema ||= Nokogiri::XML::Schema(schema_file.read)
+    end
+    
+    # Retrieve the schema file for this class
+    # If the schema file is not already set, it will be loaded from the schema url provided in the root_property configuration for the class
+    def schema_file
+      @schema_file ||= file_from_url(schema_url)
+    end
+    
+    # Retrieve file from a url (used by schema_file method to retrieve schema file from the schema url)
+    def file_from_url( url )
+      # parsed_url = URI.parse( url )
+      # 
+      # if parsed_url.class != URI::HTTP 
+      #   raise "Invalid URL.  Could not parse #{url} as a HTTP url."
+      # end
+      
+      begin
+        file = open( url )
+        return file
+      rescue OpenURI::HTTPError => e
+        raise "Could not retrieve file from #{url}. Error: #{e}"
+      rescue Exception => e  
+        raise "Could not retrieve file from #{url}. Error: #{e}"
+      end
+    end
+    
+    def delimited_list( values_array, delimiter=", ")
+      result = values_array.collect{|a| a + delimiter}.to_s.chomp(delimiter)
+    end
+    
+    
+    #
+    # Builder Support
+    #
+    
+    def builder_template(property_ref, opts={})
+      property_info = property_info_for(property_ref)
+
+      prop_info = property_info.merge(opts) 
+      
+      if prop_info.nil?
+        return nil
+      else
+        node_options = []
+        node_child_template = ""
+        if prop_info.has_key?(:default_content_path)
+          node_child_options = ["\':::builder_new_value:::\'"]
+          node_child_template = " { xml.#{property_info[:default_content_path]}( #{delimited_list(node_child_options)} ) }"
+        else
+          node_options = ["\':::builder_new_value:::\'"]
+        end
+        # if opts.has_key?(:attributes) ...
+        # ...
+        if prop_info.has_key?(:attributes)
+          applicable_attributes( prop_info[:attributes] ).each_pair do |k,v|
+            node_options << ":#{k}=>\'#{v}\'"
+          end
+        end
+        template = "xml.#{prop_info[:path]}( #{delimited_list(node_options)} )" + node_child_template
+        return template.gsub( /:::(.*?):::/ ) { '#{'+$1+'}' }
+      end
+    end
+    
+    # @attributes_spec Array or Hash
+    # Returns a Hash where all of the values are strings
+    # {:type=>"date"} will return {:type=>"date"}
+    # {["authority", {:type=>["text","code"]}] will return {:type=>"text"}
+    def applicable_attributes(attributes)
+      
+      if attributes.kind_of?(Hash)
+        attributes_hash = attributes
+      elsif attributes.kind_of?(Array)
+        attributes_hash = {}
+        attributes.each do |bute|
+          if bute.kind_of?(Hash)
+            attributes_hash.merge!(bute)
+          end
+        end
+      end
+      
+      applicable_attributes = {}
+      attributes_hash.each_pair {|k,v| applicable_attributes[k] = condense_value(v) }
+      
+      
+      return applicable_attributes
+    end
+    
+    def condense_value(value)
+      if value.kind_of?(Array)
+        return value.first
+      else
+        return value
+      end
+    end
+    
+    def logger      
+      @logger ||= defined?(RAILS_DEFAULT_LOGGER) ? RAILS_DEFAULT_LOGGER : Logger.new(STDOUT)
+    end
+    
+    private :file_from_url, :applicable_attributes
+    
+    
+    
+  end
+  
+  # Instance Methods -- These methods will be available on instances of OX classes (ie. the actual xml documents)
+  
+  def self.included(klass)
+    klass.extend(ClassMethods)
+    klass.send(:include, OX::PropertyValuesHelper)
+  end
+  
+  # Applies the property's corresponding xpath query, returning the result Nokogiri::XML::NodeSet
+  def lookup( property_ref, query_opts={}, opts={} )
+    xpath_query = xpath_query_for( property_ref, query_opts, opts )
+    
+    if xpath_query.nil?
+      result = []
+    else
+      result = xpath(xpath_query, ox_namespaces)
+    end
+    
+    return result
+  end  
+  
+  
+  # Returns a hash combining the current documents namespaces (provided by nokogiri) and any namespaces that have been set up by your class definiton.
+  # Most importantly, this matches the 'oxns' namespace to the namespace you provided in your root property config
+  def ox_namespaces
+    @ox_namespaces ||= namespaces.merge(self.class.ox_namespaces)
+  end
+  
+  def validate
+    self.class.validate(self)
+  end
+  
+  def xpath_query_for( property_ref, query_opts={}, opts={} )
+    self.class.xpath_query_for( property_ref, query_opts, opts )
+  end
+  
+  def property_info_for(property_ref)
+    self.class.property_info_for(property_ref)
+  end
+
+end

data/lib/opinionated-xml/ox_property_values_helper.rb

@@ -0,0 +1,62 @@
+require "open-uri"
+require "logger"
+
+class OX::ParentNodeNotFoundError < RuntimeError; end
+module OX::PropertyValuesHelper
+  
+  def property_values(lookup_args)
+    result = []
+    lookup(lookup_args).each {|node| result << node.text }
+    return result
+  end
+  
+  def property_values_append(opts={})
+    parent_select = opts[:parent_select] 
+    parent_index = opts[:parent_index]
+    template = opts[:template]
+    new_values = opts[:values]
+    
+    # If template is a string, use it as the template, otherwise use it as arguments to builder_template
+    unless template.instance_of?(String)
+      template_args = Array(template)
+      if template_args.last.kind_of?(Hash)
+        template_opts = template_args.delete_at(template_args.length - 1)
+      else
+        template_opts = {}
+      end
+      template = self.class.builder_template( template_args, template_opts )
+    end
+    
+    new_values = Array(new_values)
+    # template = self.class.builder_template(property_ref) 
+    
+    parent_select = Array(parent_select)
+    parent_nodeset = lookup(parent_select[0], parent_select[1])
+    
+    if parent_index.kind_of?(Integer)
+      parent_node = parent_nodeset[parent_index]
+    elsif parent_index.kind_of?(Symbol) && parent_nodeset.respond_to?(parent_index) 
+      parent_node = parent_nodeset.send(parent_index)
+    end
+    
+    if parent_node.nil?
+      raise OX::ParentNodeNotFoundError, "Failed to find a parent node to insert values into based on :parent_select #{parent_select.inspect} with :parent_index #{parent_index.inspect}"
+    end
+    
+    builder = Nokogiri::XML::Builder.with(parent_node) do |xml|
+      new_values.each do |builder_new_value|
+        builder_arg = eval('"'+ template + '"') # this inserts builder_new_value into the builder template
+        eval(builder_arg)
+      end
+    end
+        
+    # Nokogiri::XML::Node.new(builder.to_xml, foo)
+    
+    return parent_node
+    
+  end
+  
+  def property_value_set(property_ref, query_opts, node_index, new_value)
+  end
+  
+end

data/lib/opinionated-xml.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+
+require 'nokogiri'
+require "facets"
+
+module OX; end
+
+require "opinionated-xml/ox_property_values_helper"
+require File.join(File.dirname(__FILE__), 'opinionated-xml', 'ox.rb')