om 3.1.0 → 3.1.1

data/LICENSE

@@ -1,20 +1,15 @@
-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.
+##########################################################################
+# Copyright (c) 2009 Matt Zumwalt
+# Additional copyright may be held by others, as reflected in the commit log
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

data/QUERYING_DOCUMENTS.md

@@ -0,0 +1,162 @@
+# Querying OM Documents
+
+This document will help you understand how to access the information
+associated with an [OM::XML::Document](OM/XML/Document.html) object. We
+will explain some of the methods provided by the
+[OM::XML::Document](OM/XML/Document.html) module and its related modules
+[OM::XML::TermXPathGenerator](OM/XML/TermXPathGenerator.html) &
+[OM::XML::TermValueOperators](OM/XML/TermValueOperators.html)
+
+*Note: In your code, don’t worry about including
+`OM::XML::TermXPathGenerator` and `OM::XML::TermValueOperators` into your
+classes. `OM::XML::Document` handles that for you.*
+
+### Load the Sample XML and Sample Terminology
+
+These examples use the Document class defined in
+[OM::Samples::ModsArticle](https://github.com/projecthydra/om/blob/master/lib/om/samples/mods_article.rb)
+
+Download
+[hydrangea\_article1.xml](https://github.com/projecthydra/om/blob/master/spec/fixtures/mods_articles/hydrangea_article1.xml)
+(sample xml) into your working directory, then run this in irb:
+
+```ruby
+require "om/samples"
+sample_xml = File.new("hydrangea_article1.xml")
+doc = OM::Samples::ModsArticle.from_xml(sample_xml)
+```
+
+## Querying the [OM::XML::Document](OM/XML/Document.html)
+
+The [OM::XML::Terminology](OM/XML/Terminology.html") declared by
+[OM::Samples::ModsArticle](https://github.com/projecthydra/om/blob/master/lib/om/samples/mods_article.rb)
+maps the defined Terminology structure to xpath queries. It will also run the queries for you in most cases.
+
+#### xpath\_for method of [OM::XML::Terminology](OM/XML/Terminology.html") retrieves xpath expressions for OM terms
+
+The `xpath_for` method retrieves the xpath used by the
+[OM::XML::Terminology](OM/XML/Terminology.html")
+
+Examples of xpaths for `:name` and two variants of `:name` that were created
+using the `:ref` argument in the Terminology builder:
+
+```ruby
+OM::Samples::ModsArticle.terminology.xpath_for(:name)
+=> "//oxns:name"
+OM::Samples::ModsArticle.terminology.xpath_for(:person)
+=> "//oxns:name[@type=\"personal\"]" 
+OM::Samples::ModsArticle.terminology.xpath_for(:organization)
+=> "//oxns:name[@type=\"corporate\"]"
+```
+
+#### Working with Terms
+
+To retrieve the values of xml nodes, use the `term_values` method:
+
+```ruby
+doc.term_values(:person, :first_name) 
+doc.term_values(:person, :last_name) 
+```
+
+The `term_values` method is defined in the
+[OM::XML::TermValueOperators](OM/XML/TermValueOperators.html) module,
+which is included in [OM::XML::Document](OM/XML/Document.html)
+
+Not that if a term’s xpath mapping points to XML nodes that contain
+other nodes, the response to term\_values will be `Nokogiri::XML::Node`
+objects instead of text values:
+
+    doc.term_values(:name)
+
+More examples of using term\_values and find\_by\_terms (defined in
+[OM::XML::Document](OM/XML/Document.html)):
+
+```ruby
+doc.find_by_terms(:organization).to_xml
+doc.term_values(:organization, :role)
+=> ["\n      Funder\n    "] 
+doc.term_values(:organization, :namePart)
+=> ["NSF"]
+```
+
+To retrieve the values of nested terms, create a sequence of terms, from
+outermost to innermost:
+
+```ruby
+OM::Samples::ModsArticle.terminology.xpath_for(:journal, :issue, :pages, :start)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:part/oxns:extent[@unit=\"pages\"]/oxns:start" 
+doc.term_values(:journal, :issue, :pages, :start)
+=> ["195"] 
+```
+
+If you get one of the term names wrong in the sequence, OM will tell you
+which one is causing problems. See what happens when you put :page
+instead of :pages in your argument to term\_values.
+
+```ruby
+doc.term_values(:journal, :issue, :page, :start)
+ # OM::XML::Terminology::BadPointerError: You attempted to retrieve a Term using this pointer: [:journal, :issue, :page] but no Term exists at that location. Everything is fine until ":page", which doesn't exist.
+```
+
+### When XML Elements are Reused in a Document
+
+Another way to put this: the xpath statement for a term can be ambiguous.
+
+In our MODS document, we have two distinct uses of the title XML element:
+
+1. title of the published article,
+2. title of the journal it was published in.
+
+How can we distinguish between these two uses?
+
+```ruby
+doc.term_values(:title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE", "TITLE OF HOST JOURNAL"] 
+doc.term_values(:mods, :title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE"]
+OM::Samples::ModsArticle.terminology.xpath_for(:title_info, :main_title)
+=> "//oxns:titleInfo/oxns:title" 
+```
+
+The solution: include the root node in your term pointer.
+
+```ruby
+OM::Samples::ModsArticle.terminology.xpath_for(:mods, :title_info, :main_title)
+=> "//oxns:mods/oxns:titleInfo/oxns:title"
+doc.term_values(:mods, :title_info, :main_title)
+=> ["ARTICLE TITLE", "VARYING FORM OF TITLE"] 
+```
+
+We can still access the Journal title by its own pointers:
+
+```ruby
+doc.term_values(:journal, :title_info, :main_title)
+ => ["TITLE OF HOST JOURNAL"] 
+```
+
+### Making life easier with Proxy Terms
+
+If you use a nested term often, you may want to avoid typing the whole
+sequence of term names by defining a *proxy* term.
+
+As you can see in
+[OM::Samples::ModsArticle](https://github.com/projecthydra/om/blob/master/lib/om/samples/mods_article.rb),
+we have defined a few proxy terms for convenience.
+
+```ruby
+t.publication_url(:proxy=>[:location,:url])
+t.peer_reviewed(:proxy=>[:journal,:origin_info,:issuance], :index_as=>[:facetable])
+t.title(:proxy=>[:mods,:title_info, :main_title])
+t.journal_title(:proxy=>[:journal, :title_info, :main_title])
+```
+
+You can use proxy terms just like any other term when querying the document.
+```ruby
+OM::Samples::ModsArticle.terminology.xpath_for(:peer_reviewed)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:originInfo/oxns:issuance"
+OM::Samples::ModsArticle.terminology.xpath_for(:title)
+=> "//oxns:mods/oxns:titleInfo/oxns:title" 
+OM::Samples::ModsArticle.terminology.xpath_for(:journal_title)
+=> "//oxns:relatedItem[@type=\"host\"]/oxns:titleInfo/oxns:title"
+```
+

data/README.md

@@ -12,7 +12,7 @@ OM "terms" are ruby symbols you define (in the terminology) that map specific XM
 ## Tutorials & Reference
 
 * [Tame Your XML with OM](https://github.com/projecthydra/om/wiki/Tame-your-XML-with-OM)
-* [Common OM Patterns](https://github.com/projecthydra/om/blob/master/COMMON_OM_PATTERNS.textile)
+* [Common OM Patterns](https://github.com/projecthydra/om/blob/master/COMMON_OM_PATTERNS.md)
 
 ### Solrizing Documents
 
@@ -28,7 +28,7 @@ We have a page on the Hydra wiki with a list of OM Terminologies in active use:
 
 ### Creator
 
-Matt Zumwalt ([MediaShelf](http://yourmediashelf.com)
+Matt Zumwalt ([MediaShelf](http://yourmediashelf.com))
 
 ### Thanks To
 

data/UPDATING_DOCUMENTS.md

@@ -0,0 +1,6 @@
+### Updating, Inserting & Deleting Elements ([TermValueOperators](http://ruby-doc.org/gems/docs/o/om-1.8.0/OM/XML/TermValueOperators.html))
+
+### Inserting Entire Hierarchies of Elements
+
+TODO: write docs here.
+

data/gemfiles/gemfile.rails3

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gemspec :path=>"../"
 

data/gemfiles/gemfile.rails4

@@ -1,4 +1,4 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gemspec :path=>"../"
 

data/lib/om/version.rb

@@ -1,3 +1,3 @@
 module Om
-  VERSION = "3.1.0"
+  VERSION = "3.1.1"
 end

data/lib/om/xml/dynamic_node.rb

@@ -3,8 +3,8 @@ module OM
     #
     # Provides a natural syntax for using OM Terminologies to access values from xml Documents
     #
-    # *Note*: All of these examples assume that @article is an instance of OM::Samples::ModsArticle.  Look at that file to see the Terminology. 
-    # 
+    # *Note*: All of these examples assume that @article is an instance of OM::Samples::ModsArticle.  Look at that file to see the Terminology.
+    #
     # @example Return an array of the value(s) "start page" node(s) from the second issue node within the first journal node
     #   # Using DynamicNode syntax:
     #   @article.journal(0).issue(1).pages.start
@@ -38,37 +38,23 @@ module OM
         self.parent = parent
       end
 
-      def method_missing (name, *args, &block)
-        if /=$/.match(name.to_s)
-          new_update_node(name, args)
-        elsif args.length > 1
-          new_update_node_with_index(name, args)
-        else
-          child = term_child_by_name(term.nil? ? parent.term : term, name)
-          if child
-            OM::XML::DynamicNode.new(name, args.first, @document, child, self)
-          else 
-            val.send(name, *args, &block)
-          end
-        end
+      # In practice, method_missing will respond 4 different ways:
+      # (1) ALL assignment operations are accepted/attempted as new nodes,
+      # (2) ANY operation with multiple arguments is accepted/attempted as a new node (w/ index),
+      # (3) With an auto-constructed sub DynamicNode object,
+      # (4) By handing off to val.  This is the only route that will return NoMethodError.
+      #
+      # Here we don't have args, so we cannot handle cases 2 and 3.  But we can at least do 1 and 4.
+      def respond_to_missing?(name, include_private = false)
+        /=$/.match(name.to_s) || val.respond_to?(name, include_private) || super
       end
 
-      def respond_to?(method)
-        super || val.respond_to?(method)
-      end
-
-      def new_update_node(name, args)
-        modified_name = name.to_s.chop.to_sym
-        child = term.retrieve_term(modified_name)
-        node = OM::XML::DynamicNode.new(modified_name, nil, @document, child, self)
-        node.val=args
-      end
-
-      def new_update_node_with_index(name, args)
-        index = args.shift
-        child = term.retrieve_term(name)
-        node = OM::XML::DynamicNode.new(name, index, @document, child, self)
-        node.val=args
+      def method_missing(name, *args, &block)
+        return new_update_node(name.to_s.chop.to_sym, nil, args) if /=$/.match(name.to_s)
+        return new_update_node(name, args.shift, args) if args.length > 1
+        child = term_child_by_name(term.nil? ? parent.term : term, name)
+        return OM::XML::DynamicNode.new(name, args.first, @document, child, self) if child
+        val.send(name, *args, &block)
       end
 
       def val=(args)
@@ -96,18 +82,9 @@ module OM
         end
       end
 
-
-      def term_child_by_name(term, name)
-        if (term.kind_of? NamedTermProxy)
-           @document.class.terminology.retrieve_node(*(term.proxy_pointer.dup << name)) 
-        else
-          term.retrieve_term(name)
-        end
-      end
-
       # This resolves the target of this dynamic node into a reified Array
       # @return [Array]
-      def val 
+      def val
         query = xpath
         trim_text = !query.index("text()").nil?
         val = @document.find_by_xpath(query).collect {|node| (trim_text ? node.text.strip : node.text) }
@@ -123,7 +100,7 @@ module OM
       def delete
         nodeset.delete
       end
-      
+
       def inspect
         val.inspect
       end
@@ -146,7 +123,7 @@ module OM
         else ### A pointer
           parent.nil? ? [key] : parent.to_pointer << key
         end
-      end 
+      end
 
       def xpath
         if parent.nil?
@@ -155,10 +132,8 @@ module OM
           chain = retrieve_addressed_node( )
           '//' + chain.map { |n| n.xpath}.join('/')
         end
-        
       end
 
-
       class AddressedNode
         attr_accessor :xpath, :key, :pointer
         def initialize (pointer, xpath, key)
@@ -167,15 +142,12 @@ module OM
           self.pointer = pointer
         end
       end
-     
+
       ##
       # This is very similar to Terminology#retrieve_term, however it expands proxy paths out into their cannonical paths
       def retrieve_addressed_node()
          chain = []
-            
-         if parent
-           chain += parent.retrieve_addressed_node()
-         end
+         chain += parent.retrieve_addressed_node() if parent
          if (self.index)
            ### This is an index
            node = AddressedNode.new(key, term.xpath_relative, self)
@@ -191,12 +163,31 @@ module OM
               p = p.retrieve_term(first)
               chain << AddressedNode.new(p, p.xpath_relative, self)
             end
-         else 
+         else
            chain << AddressedNode.new(key, term.xpath_relative, self)
          end
          chain
       end
 
+      private
+
+      # Only to be called by method_missing, hence the NoMethodError.
+      # We know term.sanitize_new_values would fail in .val= if we pass a nil term.
+      def new_update_node(name, index, args)
+        child = term.retrieve_term(name)
+        raise NoMethodError, "undefined method `#{name}' in OM::XML::DynamicNode for #{self}:#{self.class}" if child.nil?
+        node = OM::XML::DynamicNode.new(name, index, @document, child, self)
+        node.val = args
+      end
+
+      # Only to be called by method_missing
+      def term_child_by_name(term, name)
+        if (term.kind_of? NamedTermProxy)
+          @document.class.terminology.retrieve_node(*(term.proxy_pointer.dup << name))
+        else
+          term.retrieve_term(name)
+        end
+      end
 
     end
   end

data/lib/tasks/om.rake

@@ -33,7 +33,7 @@ namespace :om do
     doc_destination = File.join(project_root, 'doc')
 
     YARD::Rake::YardocTask.new(:doc) do |yt|
-      readme_filename = 'README.textile'
+      readme_filename = 'README.md'
       #yt.options = ['--private', '--protected', '--output-dir', doc_destination, '--readme', readme_filename]
     end
   rescue LoadError

data/om.gemspec

@@ -9,6 +9,7 @@ Gem::Specification.new do |s|
   s.authors     = ["Matt Zumwalt", "Justin Coyne"]
   s.email       = %q{matt.zumwalt@yourmediashelf.com justin.coyne@mediashelf.com}
   s.homepage    = %q{http://github.com/projecthydra/om}
+  s.license     = 'APACHE2'
   s.summary     = %q{OM (Opinionated Metadata): A library to help you tame sprawling XML schemas like MODS.}
   s.description = %q{OM (Opinionated Metadata): 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}
 
@@ -21,8 +22,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency "rspec", "~> 2.0"
   s.add_development_dependency "rake"
   s.add_development_dependency "yard"
-  s.add_development_dependency "rdoc"
-  s.add_development_dependency "RedCloth" # for textile formatting in rdoc
   s.add_development_dependency "awesome_print"
   s.add_development_dependency "equivalent-xml", ">= 0.2.4"
 

data/spec/integration/differentiated_elements_spec.rb

@@ -30,10 +30,10 @@ describe "use the root element as a member of the proxy address" do
   end
 
   it "should pull out all occurences of the_thing_we_want in the relevant_container" do
-    subject.relevant_container.the_thing_we_want.should == ["1", "2"]
+    expect(subject.relevant_container.the_thing_we_want).to eq ["1", "2"]
   end
 
   it "should only pull out the_thing_we_want at the root level" do
-    subject.the_thing_we_want.should == ["2"]
+    expect(subject.the_thing_we_want).to eq ["2"]
   end
 end

data/spec/integration/element_value_spec.rb

@@ -53,39 +53,39 @@ EOF
 end
 
   it "should handle single-element terms correctly" do
-    subject.elementA.should == ["valA"]
+    expect(subject.elementA).to eq ["valA"]
   end
 
   it "should handle term paths" do
-    subject.elC.should == ["valC"]
+    expect(subject.elC).to eq ["valC"]
   end
 
   it "should handle multiple-element, terms with paths correctly" do
-    subject.elB.should == ["valB1", "valB2"]
+    expect(subject.elB).to eq ["valB1", "valB2"]
   end
 
   it "should handle terms that require specific attributes" do
-    subject.elementC.should == ["valC"]
+    expect(subject.elementC).to eq ["valC"]
   end
 
   it "should handle" do
-    subject.here.length.should == 1
-    subject.here.first.split(/\W/).should include('123', '456')
+    expect(subject.here.length).to eq 1
+    expect(subject.here.first.split(/\W/)).to include('123', '456')
   end
 
   it "should handle missing terms" do
-    subject.there.should be_empty
+    expect(subject.there).to be_empty
   end
 
   it "should handle element  value given the absence of a specific attribute" do
-    subject.elementD.should == ["valD1"]
-    subject.no_attrib.should == ["valB1"]
+    expect(subject.elementD).to eq ["valD1"]
+    expect(subject.no_attrib).to eq ["valB1"]
   end
 
   it "should handle OM terms for an attribute value" do
-    subject.elementB.my_attr.should == ["vole"]
-    subject.alternate.should == ["vole"]
-    subject.another.should == ["vole"]
-    subject.animal_attrib.should include("vole", "seagull")
+    expect(subject.elementB.my_attr).to eq ["vole"]
+    expect(subject.alternate).to eq ["vole"]
+    expect(subject.another).to eq ["vole"]
+    expect(subject.animal_attrib).to include("vole", "seagull")
   end
 end