om 0.1.10 → 1.0.0

data/README.textile

@@ -0,0 +1,27 @@
+h1. opinionated-xml
+
+A library to help you tame sprawling XML schemas like MODS.
+
+h2. 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.
+
+h2. Acknowledgements
+
+Creator: Matt Zumwalt ("MediaShelf":http://yourmediashelf.com)
+
+Thanks to 
+
+Bess Sadler, who enabled us to take knowledge gleaned from developing Blacklight and apply it to OM metadata indexing
+Ross Singer
+Those who participated in the Opinionated MODS breakout session at Code4Lib 2010
+
+h2. Copyright
+
+Copyright (c) 2010 Matt Zumwalt. See LICENSE for details.

data/Rakefile

@@ -11,7 +11,7 @@ begin
     gem.homepage = "http://github.com/mediashelf/om"
     gem.authors = ["Matt Zumwalt"]
     
-    gem.add_dependency('nokogiri')
+    gem.add_dependency('nokogiri', ">= 1.4.2")
     gem.add_dependency('facets')
     
     gem.add_development_dependency "rspec", ">= 1.2.9"

data/VERSION

@@ -1 +1 @@
-0.1.10
+1.0.0

data/lib/om/samples/mods_article.rb

@@ -0,0 +1,64 @@
+class OM::Samples::ModsArticle
+    
+    include OM::XML::Document
+    
+    set_terminology do |t|
+      t.root(:path=>"mods", :xmlns=>"http://www.loc.gov/mods/v3", :schema=>"http://www.loc.gov/standards/mods/v3/mods-3-2.xsd")
+
+      t.title_info(:path=>"titleInfo") {
+        t.main_title(:path=>"title", :label=>"title")
+        t.language(:path=>{:attribute=>"lang"})
+      } 
+      t.abstract     
+      t.topic_tag(:path=>"subject", :default_content_path=>"topic")           
+      # This is a mods:name.  The underscore is purely to avoid namespace conflicts.
+      t.name_ {
+        # this is a namepart
+        t.namePart(:index_as=>[:searchable, :displayable, :facetable, :sortable], :required=>:true, :type=>:string, :label=>"generic name")
+        # affiliations are great
+        t.affiliation
+        t.displayForm
+        t.role(:ref=>[:role])
+        t.description
+        t.date(:path=>"namePart", :attributes=>{:type=>"date"})
+        t.last_name(:path=>"namePart", :attributes=>{:type=>"family"})
+        t.first_name(:path=>"namePart", :attributes=>{:type=>"given"}, :label=>"first name")
+        t.terms_of_address(:path=>"namePart", :attributes=>{:type=>"termsOfAddress"})
+      }
+      # lookup :person, :first_name        
+      t.person(:ref=>:name, :attributes=>{:type=>"personal"})
+      t.organizaton(:ref=>:name, :attributes=>{:type=>"institutional"})
+      t.conference(:ref=>:name, :attributes=>{:type=>"conference"})
+
+      t.role {
+        t.text(:path=>"roleTerm",:attributes=>{:type=>"text"})
+        t.code(:path=>"roleTerm",:attributes=>{:type=>"code"})
+      }
+      t.journal(:path=>'relatedItem', :attributes=>{:type=>"host"}) {
+        t.title_info
+        t.origin_info(:path=>"originInfo") {
+          t.publisher
+          t.date_issued(:path=>"dateIssued")
+        }
+        t.issn(:path=>"identifier", :attributes=>{:type=>"issn"})
+        t.issue(:path=>"part") {
+          t.volume(:path=>"detail", :attributes=>{:type=>"volume"}, :default_content_path=>"number")
+          t.level(:path=>"detail", :attributes=>{:type=>"number"}, :default_content_path=>"number")
+          t.extent
+          t.pages(:path=>"extent", :attributes=>{:unit=>"pages"}) {
+            t.start
+            t.end
+          }
+          t.publication_date(:path=>"date")
+          t.start_page(:proxy=>[:pages, :start])
+          t.end_page(:proxy=>[:pages, :end])
+        }
+      }
+      
+    end
+    
+    # Changes from OM::Properties implementation
+    # renamed family_name => last_name
+    # start_page & end_page now accessible as [:journal, :issue, :pages, :start] (etc.)
+
+end

data/lib/om/samples.rb

@@ -0,0 +1,2 @@
+module OM::Samples;end
+require "om/samples/mods_article"

data/lib/om/tree_node.rb

@@ -0,0 +1,24 @@
+module OM::TreeNode
+  
+  attr_accessor :ancestors
+  
+  #  insert the mapper into the given parent
+  def set_parent(parent_mapper)
+    parent_mapper.children[@name] = self
+    @ancestors << parent_mapper
+  end
+  
+  #  insert the given mapper into the current mappers children
+  def add_child(child_mapper)
+    child_mapper.ancestors << self
+    @children[child_mapper.name.to_sym] = child_mapper    
+  end
+  
+  def retrieve_child(child_name)
+    child = @children.fetch(child_name, nil)
+  end
+  
+  def parent
+    ancestors.last
+  end
+end

data/lib/om/xml/document.rb

@@ -0,0 +1,68 @@
+module OM::XML::Document
+    
+  
+  # Class Methods -- These methods will be available on classes that include this Module 
+  
+  module ClassMethods
+    
+    attr_accessor :terminology
+  
+    # Sets the OM::XML::Terminology for the Document
+    # Expects +&block+ that will be passed into OM::XML::Terminology::Builder.new
+    def set_terminology &block
+      @terminology = OM::XML::Terminology::Builder.new( &block ).build
+    end
+    
+    # Returns any namespaces defined by the Class' Terminology
+    def ox_namespaces
+      if @terminology.nil?
+        return {}
+      else
+        return @terminology.namespaces
+      end
+    end
+    
+  end
+  
+  # Instance Methods -- These methods will be available on instances of classes that include this module
+  
+  attr_accessor :ox_namespaces
+  
+  def self.included(klass)
+    klass.extend(ClassMethods)
+  
+    klass.send(:include, OM::XML::Container)
+    klass.send(:include, OM::XML::TermValueOperators)
+  end
+  
+  # Applies the property's corresponding xpath query, returning the result Nokogiri::XML::NodeSet
+  def find_by_terms_and_value(*term_pointer)
+    xpath = self.class.terminology.xpath_for(*term_pointer)    
+    if xpath.nil?
+      return nil
+    else
+      return ng_xml.xpath(xpath, ox_namespaces) 
+    end
+  end
+  
+
+  # +term_pointer+ Variable length array of values in format [:accessor_name, :accessor_name ...] or [{:accessor_name=>index}, :accessor_name ...]
+  # example: {:person => 1}, :first_name
+  # example: [:person, 1, :first_name]
+  # Currently, indexes must be integers.
+  def find_by_terms(*term_pointer)
+    xpath = self.class.terminology.xpath_with_indexes(*term_pointer)   
+    if xpath.nil?
+      return nil
+    else
+      return ng_xml.xpath(xpath, ox_namespaces) 
+    end   
+  end
+  
+  # Returns a hash combining the current documents namespaces (provided by nokogiri) and any namespaces that have been set up by your Terminology.
+  # Most importantly, this matches the 'oxns' namespace to the namespace you provided in your Terminology's root term config
+  def ox_namespaces
+    @ox_namespaces ||= ng_xml.namespaces.merge(self.class.ox_namespaces)
+  end
+  
+end

data/lib/om/xml/named_term_proxy.rb

@@ -0,0 +1,37 @@
+class OM::XML::NamedTermProxy
+  
+  attr_accessor :proxy_pointer, :name
+  
+  include OM::TreeNode
+  
+  def initialize(name, proxy_pointer, opts={})
+    opts = {:namespace_prefix=>"oxns", :ancestors=>[], :children=>{}}.merge(opts)
+    [:children, :ancestors].each do |accessor_name|
+      instance_variable_set("@#{accessor_name}", opts.fetch(accessor_name, nil) )     
+    end
+    @name = name
+    @proxy_pointer = proxy_pointer
+  end
+  
+  def proxied_term
+    self.parent.retrieve_term(*self.proxy_pointer)
+  end
+  
+  # do nothing -- this is to prevent errors when the parent term calls generate_xpath_queries! on its children
+  def generate_xpath_queries!
+    # do nothing
+  end
+  
+  def method_missing
+  end
+  
+  # Any unknown method calls will be proxied to the proxied term
+  def method_missing method, *args, &block 
+    if args.empty?
+      return self.proxied_term.send(method)
+    else
+      return self.proxied_term.send(method, args)
+    end
+  end
+  
+end

data/lib/om/xml/node_generator.rb

@@ -0,0 +1,14 @@
+module OM::XML::NodeGenerator
+    
+  # Module Methods -- These methods can be called directly on the Module itself
+  def self.generate(term, builder_new_value, opts={})
+    template = term.xml_builder_template(opts)
+    builder_call_body = eval('"' + template + '"')
+    builder = Nokogiri::XML::Builder.new do |xml|
+      eval( builder_call_body )
+    end
+    
+    return builder.doc
+  end
+
+end

data/lib/om/xml/term.rb

@@ -0,0 +1,223 @@
+class OM::XML::Term
+  
+  # Term::Builder Class Definition
+  
+  class Builder
+    attr_accessor :name, :settings, :children, :terminology_builder
+    
+    def initialize(name, terminology_builder=nil)
+      @name = name.to_sym
+      @terminology_builder = terminology_builder
+      @settings = {:required=>false, :data_type=>:string}
+      @children = {}
+    end
+    
+    def add_child(child)
+      @children[child.name] = child
+    end
+    
+    def retrieve_child(child_name)
+      child = @children.fetch(child_name, nil)
+    end
+    
+    def lookup_refs(nodes_visited=[])
+      result = []
+      if @settings[:ref]
+        # Fail if we do not have terminology builder
+        if self.terminology_builder.nil?
+          raise "Cannot perform lookup_ref for the #{self.name} builder.  It doesn't have a reference to any terminology builder"
+        end
+        begin
+          target = self.terminology_builder.retrieve_term_builder(*@settings[:ref])
+        rescue OM::XML::Terminology::BadPointerError
+          # Clarify message on BadPointerErrors
+          raise OM::XML::Terminology::BadPointerError, "#{self.name} refers to a Term Builder that doesn't exist.  The bad pointer is #{@settings[:ref].inspect}"
+        end
+        
+        # Fail on circular references and return an intelligible error message
+        if nodes_visited.contains?(target)
+          nodes_visited << self
+          nodes_visited << target
+          trail = ""
+          nodes_visited.each_with_index do |node, z|
+            trail << node.name.inspect
+            unless z == nodes_visited.length-1
+              trail << " => "
+            end
+          end
+          raise OM::XML::Terminology::CircularReferenceError, "Circular reference in Terminology: #{trail}"
+        end
+        result << target
+        result.concat( target.lookup_refs(nodes_visited << self) )
+      end
+      return result
+    end
+    
+    # If a :ref value has been set, looks up the target of that ref and merges the target's settings & children with the current builder's settings & children
+    # operates recursively, so it is possible to apply refs that in turn refer to other nodes.
+    def resolve_refs!
+      name_of_last_ref = nil
+      lookup_refs.each_with_index do |ref,z|        
+        @settings = two_layer_merge(@settings, ref.settings)
+        @children.merge!(ref.children)
+        name_of_last_ref = ref.name
+      end
+      if @settings[:path].nil? && !name_of_last_ref.nil?
+        @settings[:path] = name_of_last_ref.to_s
+      end
+      @settings.delete :ref
+      return self
+    end
+    
+    # Returns a new Hash that merges +downstream_hash+ with +upstream_hash+
+    # similar to calling +upstream_hash+.merge(+downstream_hash+) only it also merges 
+    # any internal values that are themselves Hashes.
+    def two_layer_merge(downstream_hash, upstream_hash)
+      up = upstream_hash.dup
+      dn = downstream_hash.dup
+      up.each_pair do |setting_name, value|
+        if value.kind_of?(Hash) && downstream_hash.has_key?(setting_name)  
+          dn[setting_name] = value.merge(downstream_hash[setting_name])
+          up.delete(setting_name)
+        end
+      end
+      return up.merge(dn)
+    end
+    
+    # Builds a new OM::XML::Term based on the Builder object's current settings
+    # If no path has been provided, uses the Builder object's name as the term's path
+    # Recursively builds any children, appending the results as children of the Term that's being built.
+    def build
+      self.resolve_refs!
+      if term.self.settings.has_key?(:proxy)
+        term = OM::XML::NamedTermProxy.new(self.name, self.settings[:proxy])
+      else
+        term = OM::XML::Term.new(self.name)
+      
+        self.settings.each do |name, values|  
+          if term.respond_to?(name.to_s+"=")
+            term.instance_variable_set("@#{name}", values)
+          end
+        end
+        @children.each_value do |child|
+          term.add_child child.build
+        end
+        term.generate_xpath_queries!
+      end
+      
+      return term
+    end
+    
+    # Any unknown method calls will add an entry to the settings hash and return the current object
+    def method_missing method, *args, &block 
+      if args.length == 1
+        args = args.first
+      end
+      @settings[method] = args
+      return self
+    end
+  end
+  
+  # Term Class Definition
+  
+  attr_accessor :name, :xpath, :xpath_constrained, :xpath_relative, :path, :index_as, :required, :data_type, :variant_of, :path, :attributes, :default_content_path, :namespace_prefix, :is_root_term
+  attr_accessor :children, :internal_xml, :terminology
+  
+  include OM::TreeNode
+  
+  def initialize(name, opts={})
+    opts = {:namespace_prefix=>"oxns", :ancestors=>[], :children=>{}}.merge(opts)
+    [:children, :ancestors,:path, :index_as, :required, :type, :variant_of, :path, :attributes, :default_content_path, :namespace_prefix].each do |accessor_name|
+      instance_variable_set("@#{accessor_name}", opts.fetch(accessor_name, nil) )     
+    end
+    @name = name
+    if @path.nil? || @path.empty?
+      @path = name.to_s
+    end
+  end
+  
+  def self.from_node(mapper_xml)    
+    name = mapper_xml.attribute("name").text.to_sym
+    attributes = {}
+    mapper_xml.xpath("./attribute").each do |a|
+      attributes[a.attribute("name").text.to_sym] = a.attribute("value").text
+    end
+    new_mapper = self.new(name, :attributes=>attributes)
+    [:index_as, :required, :type, :variant_of, :path, :default_content_path, :namespace_prefix].each do |accessor_name|
+      attribute =  mapper_xml.attribute(accessor_name.to_s)
+      unless attribute.nil?
+        new_mapper.instance_variable_set("@#{accessor_name}", attribute.text )      
+      end     
+    end
+    new_mapper.internal_xml = mapper_xml
+    
+    mapper_xml.xpath("./mapper").each do |child_node|
+      child = self.from_node(child_node)
+      new_mapper.add_child(child)
+    end
+    
+    return new_mapper
+  end
+  
+  # crawl down into mapper's children hash to find the desired mapper
+  # ie. @test_mapper.retrieve_mapper(:conference, :role, :text)
+  def retrieve_term(*pointers)
+    children_hash = self.children
+    pointers.each do |p|
+      if children_hash.has_key?(p)
+        target = children_hash[p]
+        if pointers.index(p) == pointers.length-1
+          return target
+        else
+          children_hash = target.children
+        end
+      else
+        return nil
+      end
+    end
+    return target
+  end
+  
+  def is_root_term?
+    @is_root_term == true
+  end
+  
+  def xpath_absolute
+    @xpath
+  end
+  
+  # +term_pointers+ reference to the property you want to generate a builder template for
+  # @opts
+  def xml_builder_template(extra_opts = {})
+    extra_attributes = extra_opts.fetch(:attributes, {})  
+
+    node_options = []
+    node_child_template = ""
+    if !self.default_content_path.nil?
+      node_child_options = ["\':::builder_new_value:::\'"]
+      node_child_template = " { xml.#{self.default_content_path}( #{OM::XML.delimited_list(node_child_options)} ) }"
+    else
+      node_options = ["\':::builder_new_value:::\'"]
+    end
+    if !self.attributes.nil?
+      self.attributes.merge(extra_attributes).each_pair do |k,v|
+        node_options << ":#{k}=>\'#{v}\'"
+      end
+    end
+    template = "xml.#{self.path}( #{OM::XML.delimited_list(node_options)} )" + node_child_template
+    return template.gsub( /:::(.*?):::/ ) { '#{'+$1+'}' }
+  end
+  
+  # Generates absolute, relative, and constrained xpaths for the term, setting xpath, xpath_relative, and xpath_constrained accordingly.
+  # Also triggers update_xpath_values! on all child nodes, as their absolute paths rely on those of their parent nodes.
+  def generate_xpath_queries!
+    self.xpath = OM::XML::TermXpathGenerator.generate_absolute_xpath(self)
+    self.xpath_constrained = OM::XML::TermXpathGenerator.generate_constrained_xpath(self)
+    self.xpath_relative = OM::XML::TermXpathGenerator.generate_relative_xpath(self)
+    self.children.each_value {|child| child.generate_xpath_queries! }
+    return self
+  end
+  
+  # private :update_xpath_values
+  
+end

data/lib/om/xml/term_value_operators.rb

@@ -0,0 +1,182 @@
+require "open-uri"
+require "logger"
+
+class OM::XML::ParentNodeNotFoundError < RuntimeError; end
+module OM::XML::TermValueOperators
+  
+  # Retrieves all of the nodes from the current document that match +term_pointer+ and returns an array of their values
+  def term_values(*term_pointer)
+    result = []
+    find_by_terms(*term_pointer).each {|node| result << node.text }
+    # find_by_terms(*OM.destringify(term_pointer)).each {|node| result << node.text }
+    return result
+  end
+  
+  # alias for term_values
+  def property_values(*lookup_args)
+    term_values(*lookup_args)
+  end
+  
+  # 
+  # example term values hash: {[{":person"=>"0"}, "role", "text"]=>{"0"=>"role1", "1"=>"role2", "2"=>"role3"}, [{:person=>1}, :family_name]=>"Andronicus", [{"person"=>"1"},:given_name]=>["Titus"],[{:person=>1},:role,:text]=>["otherrole1","otherrole2"] }
+  def update_values(params={})
+    # remove any terms from params that this datastream doesn't recognize    
+    
+    params.delete_if do |term_pointer,new_values| 
+      if term_pointer.kind_of?(String)
+        true
+      else
+        !self.class.terminology.has_term?(*OM.destringify(term_pointer))
+      end
+    end
+    
+    result = params.dup
+    
+    params.each_pair do |term_pointer,new_values|
+      pointer = OM.destringify(term_pointer)
+      template = OM.pointers_to_flat_array(pointer,false)
+      hn = OM::XML::Terminology.term_hierarchical_name(*pointer)
+      
+      # Sanitize new_values to always be a hash with indexes
+      case new_values
+      when Hash
+      when Array
+        nv = new_values.dup
+        new_values = {}
+        nv.each {|v| new_values[nv.index(v).to_s] = v}
+      else
+        new_values = {"0"=>new_values}
+      end
+      
+      # Populate the response hash appropriately, using hierarchical names for terms as keys rather than the given pointers.
+      result.delete(term_pointer)
+      result[hn] = new_values.dup
+      
+      # Skip any submitted values if the new value matches the current values
+      current_values = term_values(*pointer)
+      new_values.delete_if do |y,z| 
+        if current_values[y.to_i]==z and y.to_i > -1
+          true
+        else
+          false
+        end
+      end 
+      
+      # Fill out the pointer completely if the final term is a NamedTermProxy
+      term = self.class.terminology.retrieve_term( *OM.pointers_to_flat_array(pointer,false) )
+      if term.kind_of? OM::XML::NamedTermProxy
+        pointer.pop
+        pointer = pointer.concat(term.proxy_pointer)
+      end
+      
+      xpath = self.class.terminology.xpath_with_indexes(*pointer)
+      parent_pointer = pointer.dup
+      parent_pointer.pop
+      parent_xpath = self.class.terminology.xpath_with_indexes(*parent_pointer)
+      
+      # If the value doesn't exist yet, append it.  Otherwise, update the existing value.
+      new_values.each do |y,z|   
+        if find_by_terms(*pointer)[y.to_i].nil? || y.to_i == -1
+          result[hn].delete(y)
+          term_values_append(:parent_select=>parent_xpath,:child_index=>0,:template=>template,:values=>z)
+          new_array_index = find_by_terms(*pointer).length - 1
+          result[hn][new_array_index.to_s] = z
+        else
+          term_value_update(xpath, y.to_i, z)
+        end
+      end
+    end
+    return result
+  end
+  
+  def term_values_append(opts={})
+    parent_select = Array( opts[:parent_select] )
+    child_index = opts[:child_index]
+    template = opts[:template]
+    new_values = Array( opts[:values] )
+  
+    # If template is a string, use it as the template, otherwise use it as arguments to xml_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)
+        template_args << template_opts
+      end
+      template = self.class.terminology.xml_builder_template( *template_args )
+    end    
+    
+    parent_nodeset = find_by_terms(*parent_select)
+    parent_node = node_from_set(parent_nodeset, child_index)
+    
+    if parent_node.nil?
+      raise OM::XML::ParentNodeNotFoundError, "Failed to find a parent node to insert values into based on :parent_select #{parent_select.inspect} with :child_index #{child_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 term_value_update(node_select,child_index,new_value,opts={})
+    # template = opts.fetch(:template,nil)
+    
+    node = find_by_terms_and_value(*node_select)[child_index]
+    if new_value == "" || new_value == :delete
+      node.remove
+    else
+      node.content = new_value
+    end
+  end
+  
+  # def term_value_set(term_ref, query_opts, node_index, new_value)
+  # end
+  
+  def term_value_delete(opts={})
+    parent_select = Array( opts[:parent_select] )
+    parent_index = opts[:parent_index]
+    child_index = opts[:child_index]
+    xpath_select = opts[:select]
+    
+    if !xpath_select.nil?
+      node = find_by_terms_and_value(xpath_select).first
+    else
+      # parent_nodeset = find_by_terms_and_value(parent_select, parent_select)
+      parent_nodeset = find_by_terms_and_value(*parent_select)
+      
+      if parent_index.nil?
+        node = node_from_set(parent_nodeset, child_index)
+      else
+        parent = node_from_set(parent_nodeset, parent_index)
+        # this next line is a hack around the fact that element_children() sometimes doesn't work.
+        node = node_from_set(parent.xpath("*"), child_index)
+      end
+    end
+    
+    node.remove
+  end
+   
+  
+  # Allows you to provide an array index _or_ a symbol representing the function to call on the nodeset in order to retrieve the node.
+  def node_from_set(nodeset, index)
+    if index.kind_of?(Integer)
+      node = nodeset[index]
+    elsif index.kind_of?(Symbol) && nodeset.respond_to?(index) 
+      node = nodeset.send(index)
+    else
+      raise "Could not retrieve node using index #{index}."
+    end
+    
+    return node
+  end
+  
+  private :node_from_set
+  
+end