om 3.1.0 → 3.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 774ca56c42282c5d31bef07b86d7f6e5e54d74b7
-  data.tar.gz: bcf4d74285aa0283c8c4a926e988b5444f0706ae
+  metadata.gz: 47b327a1e5c5c97aaced259dfada9e0272a7e011
+  data.tar.gz: 43198216111873a28f12a414d420bccf3f1453f6
 SHA512:
-  metadata.gz: 8c277df99dae62c250a6747bd05f68aa058477ccec12c03861818880e2ce828f20e21a1203bda0204d088830ecf59b9769caba20929fd0643bd3d28362c38091
-  data.tar.gz: d145e98cd6c1387c58b6c98715d502b5bdb30e970050f0ab75c52c1c7fdb00b23ee83f09fdcf1c70565bd5fb6aecd3ab1794bc86b59d83dc0a2aaa1ed7a0d1a4
+  metadata.gz: 509267f8bedd654a287e8c97dbd55076f6c21beb31e6af88b0910a5b33c505e2e1efff7f36ae5b831731e58fe4d9723c9e6e56da568bdc12e56f7321bb87fab5
+  data.tar.gz: 717a6650a821571adac1077be22ef1e56d4c56d74821601c3372f48caa29ce2217a1c2d47fdb9c2be2356f3c09cd3225db80037f9a36065f057f4a1ec3aa1b12

data/{COMMON_OM_PATTERNS.textile → COMMON_OM_PATTERNS.md}

@@ -1,10 +1,10 @@
-h1. Common Patterns You'll Use with OM
+# Common Patterns You’ll Use with OM
 
-h2. Common Terminology Patterns
+## Common Terminology Patterns
 
-Let's say we have xml like this:
+Let’s say we have xml like this:
 
-<pre>
+```text/xml
 <outer outerId="hypatia:outer" type="outer type">
   <elementA>valA</elementA>
   <elementB>valB1</elementB>
@@ -23,16 +23,15 @@ Let's say we have xml like this:
     </file>
   </resource>
 </outer>
-</pre>
+```
 
-h4. element value
+#### element value
 
-We want an OM term for the value of an element. 
+We want an OM term for the value of an element.
 
 In the Datastream Model:
 
-<pre>  
-# defines the expected OM terminology for example xml
+```ruby
 class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
   # OM (Opinionated Metadata) terminology mapping 
   set_terminology do |t|
@@ -42,18 +41,19 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
     t.elC(:path => "elementC", :namespace_prefix => nil)
   end  
 end
-</pre>
+```
 
-This results in :elementA having a value of "valA" and :elB having two values of "valB1" and "valB2", and :elC having a value of "valC"
+This results in :elementA having a value of “valA” and :elB having two
+values of “valB1” and “valB2”, and :elC having a value of “valC”
 
-h4. element value given a specific attribute value
+#### Element value given a specific attribute value
 
-We want an OM term for the value of an element, but only if the element has a specific attribute value.
+We want an OM term for the value of an element, but only if the element
+has a specific attribute value.
 
 In the Datastream Model:
 
-<pre>  
-# defines the expected OM terminology for example xml
+```ruby
 class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
   # OM (Opinionated Metadata) terminology mapping 
   set_terminology do |t|
@@ -63,16 +63,17 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
     t.there(:path=>"resource", :attributes=>{:type=>"nowhere"}, :namespace_prefix => nil)
   end  
 end 
-</pre>
+```
 
-This results in :elementC having a value of "valC" and :here having a value of "123 456", and :there having a value of nil (or is it ""?)
+This results in :elementC having a value of “valC” and :here having a
+value of “123 456”, and :there having a value of nil (or is it “”?)
 
-h4. element value given absence of a specific attribute
+#### element value given absence of a specific attribute
 
-We want an OM term for an element's value, but only if the element does not have a specific attribute.
+We want an OM term for an element’s value, but only if the element does
+not have a specific attribute.
 
-<pre>  
-# defines the expected OM terminology for example xml
+```ruby
 class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
   # OM (Opinionated Metadata) terminology mapping 
   set_terminology do |t|
@@ -81,19 +82,18 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
     t.no_attrib(:path => "elementB", :attributes=>{:animal=>:none}, :namespace_prefix => nil)
   end  
 end 
-</pre>
+```
 
-This results in both :elementB and :no_attib having the single value "valB1"
+This results in both :elementB and :no\_attib having the single value
+“valB1”
 
-
-h4. attribute value
+#### attribute value
 
 We want an OM term for an attribute value
 
-<pre>  
-# defines the expected OM terminology for example xml
-class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
-  # OM (Opinionated Metadata) terminology mapping 
+```ruby
+class ExampleXMLDS < ActiveFedora::NokogiriDatastream
+  # OM (Opinionated Metadata) terminology mapping
   set_terminology do |t|
     t.root(:path => "outer", :xmlns => '', :namespace_prefix => nil)
     t.elementB {
@@ -102,17 +102,17 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
     t.alternate(:path => "elementB/@animal", :namespace_prefix => nil)
     t.another(:proxy=>[:elementB, :my_attr_])
     t.animal_attrib(:path => {:attribute=>"animal"}, :namespace_prefix => nil)
-  end  
+  end
 end
-</pre>
-
-This results in :my_attr, :alternate and :another all having the single value of "vole", and :animal_attrib having the values "vole" and "seagull"
+```
 
+This results in :my\_attr, :alternate and :another all having the single
+value of “vole”, and :animal\_attrib having the values “vole” and
+“seagull”
 
-h4. an example with :proxy and :ref
+#### an example with :proxy and :ref
 
-<pre>  
-# defines the expected OM terminology for example xml
+```ruby
 class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
   # OM (Opinionated Metadata) terminology mapping 
   set_terminology do |t|
@@ -145,27 +145,25 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
     t.image_sha1(:proxy=>[:image, :file, :sha1])
   end  
 end
-</pre>
+```
 
-This results in 
-:ead_fedora_pid has value "hypatia:ead_file_asset_fixture"
-:ead_ds_label has value "my_ead.xml"
-:ead_size has value "47570"
-:ead_md5 has value"123"
-:ead_sha1 has value "456"
+This results in:
+- :ead_fedora_pid has value “hypatia:ead\_file\_asset\_fixture”
+- :ead_ds_label has value “my\_ead.xml”
+- :ead_size has value “47570”
+- :ead_md5 has value “123”
+- :ead_sha1 has value “456”
+- :image_fedora_pid has value “hypatia:coll_img_file_asset_fixture”
+- :image_ds_label has value “my_image.jpg”
+- :image_size has value “302080”
+- :image_md5 has value “789”
+- :image_sha1 has value “666”
 
-:image_fedora_pid has value "hypatia:coll_img_file_asset_fixture"
-:image_ds_label has value "my_image.jpg"
-:image_size has value "302080"
-:image_md5 has value "789"
-:image_sha1 has value "666"
+#### xpath-y stuff, also using :ref and :proxy and namespaces
 
+Let’s say we have xml like this:
 
-h4. xpath-y stuff, also using :ref and :proxy and namespaces
-
-Let's say we have xml like this:
-
-<pre>
+```text/xml
 <contentMetadata>
    <resource type="file" id="BU3A5" objectId="val2">
     <file id="BURCH1" format="BINARY">
@@ -176,14 +174,16 @@ Let's say we have xml like this:
     </file>
   </resource>
 </contentMetadata>
-</pre>
+```
 
-We want an OM term corresponding to the <file> element based on the value of the <location> element.  That is, we want to have a :content term when the value of <location> is "content" and an :html term when the value of <location> is "html".
+We want an OM term corresponding to the `<file>` element based on the
+value of the `<location>` element. That is, we want to have a :content
+term when the value of `<location>` is “content” and an :html term when
+the value of `<location>` is “html”.
 
 In the Datastream Model:
 
-<pre>  
-# defines the expected OM terminology for example xml
+```ruby
 class ExampleXMLDS < ActiveFedora::NokogiriDatastream 
   # OM (Opinionated Metadata) terminology mapping 
   t.root(:path=>"contentMetadata", :xmlns => '', :namespace_prefix => nil) 
@@ -208,47 +208,50 @@ class ExampleXMLDS < ActiveFedora::NokogiriDatastream
   t.html_filename(:proxy=>[:html, :filename])
   t.html_format(:proxy=>[:html, :format])
 end
-</pre>
+```
 
 Another example from Molly Pickral of UVa:
 
-We want to access just the author and the advisor from the XML below.  The two <name> elements must be distinguished by their <roleTerm> value, a grandchild of the <name> element.
-We want an :author term with value "Mary Pickral", and an :advisor term with value "David Jones".
-
-<pre>
-  <mods xmlns="http://www.loc.gov/mods/v3"
-  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.3"
-  xsi:schemaLocation="http://www.loc.gov/mods/v3
-  http://www.loc.gov/standards/mods/v3/mods-3-3.xsd">
-     <name type="personal">
-         <namePart type="given">Mary</namePart>
-         <namePart type="family">Pickral</namePart>
-         <affiliation>University of Virginia</affiliation>
-         <namePart>mpc3c</namePart>
-         <affiliation>University of Virginia Library</affiliation>
-         <role>
-             <roleTerm authority="marcrelator" type="code">aut</roleTerm>
-             <roleTerm authority="marcrelator" type="text">author</roleTerm>
-         </role>
-     </name>
-    <name type="personal">
-      <namePart>der5y</namePart>
-      <namePart type="given">David</namePart>
-      <namePart type="family">Jones</namePart>
-      <affiliation>University of Virginia</affiliation>
-      <affiliation>Architectural History Dept.</affiliation>
-      <role>
-           <roleTerm authority="marcrelator" type="code">ths</roleTerm>
-           <roleTerm authority="marcrelator" type="text">advisor</roleTerm>
-      </role>
-    </name>
-  </mods>
-</pre>
+We want to access just the author and the advisor from the XML below.
+The two `<name>` elements must be distinguished by their `<roleTerm>` value,
+a grandchild of the `<name>` element.
+
+We want an :author term with value “Mary Pickral”, and an :advisor term
+with value “David Jones”.
+      
+```text/xml
+<mods xmlns="http://www.loc.gov/mods/v3"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.3"
+xsi:schemaLocation="http://www.loc.gov/mods/v3
+http://www.loc.gov/standards/mods/v3/mods-3-3.xsd">
+ <name type="personal">
+     <namePart type="given">Mary</namePart>
+     <namePart type="family">Pickral</namePart>
+     <affiliation>University of Virginia</affiliation>
+     <namePart>mpc3c</namePart>
+     <affiliation>University of Virginia Library</affiliation>
+     <role>
+         <roleTerm authority="marcrelator" type="code">aut</roleTerm>
+         <roleTerm authority="marcrelator" type="text">author</roleTerm>
+     </role>
+ </name>
+<name type="personal">
+  <namePart>der5y</namePart>
+  <namePart type="given">David</namePart>
+  <namePart type="family">Jones</namePart>
+  <affiliation>University of Virginia</affiliation>
+  <affiliation>Architectural History Dept.</affiliation>
+  <role>
+       <roleTerm authority="marcrelator" type="code">ths</roleTerm>
+       <roleTerm authority="marcrelator" type="text">advisor</roleTerm>
+  </role>
+</name>
+</mods>
+```
 
 In the Datastream Model:
 
-<pre>  
-# defines the expected OM terminology for mods thesis example xml
+```ruby
 class ModsThesis < ActiveFedora::NokogiriDatastream
   set_terminology do |t|
     t.root(:path=>"mods", :xmlns=>"http://www.loc.gov/mods/v3"))
@@ -269,20 +272,24 @@ class ModsThesis < ActiveFedora::NokogiriDatastream
     t.advisor_family(:proxy=>[:advisor, :family])
   end
 end
-</pre>
-
-This isn't quite what the doctor ordered, but :author_given and :author_family can be used to get the author name;  similarly for advisor.
-
+```
 
+This isn’t quite what the doctor ordered, but :author\_given and
+:author\_family can be used to get the author name; similarly for
+advisor.
 
 And a variant on the previous example using namespace prefixes.
 
-We want to access just the creator and the repository from the XML below.  The two <name> elements must be distinguished by their <roleTerm> value, a grandchild of the <name> element.
-We want a :creator term with value "David Small", and a :repository term with value "Graphic Novel Repository".
+We want to access just the creator and the repository from the XML
+below. The two `<name>` elements must be distinguished by their `<roleTerm>`
+value, a grandchild of the `<name>` element.
+
+We want a :creator term with value “David Small”, and a :repository term
+with value “Graphic Novel Repository”.
 
 Our xml:
 
-<pre>
+```text/xml
 <mods:mods xmlns:mods="http://www.loc.gov/mods/v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.3" xsi:schemaLocation="http://www.loc.gov/mods/v3 http://www.loc.gov/standards/mods/v3/mods-3-3.xsd">
   
   <mods:name type="personal">
@@ -298,12 +305,11 @@ Our xml:
     </mods:role>
   </mods:name>
 </mods:mods>
-</pre>
+```
 
 In the Datastream model:
 
-<pre>
-# defines the expected OM terminology for mods name example xml
+```ruby
 class ModsName < ActiveFedora::NokogiriDatastream
   t.root(:path=>"mods", :xmlns=>"http://www.loc.gov/mods/v3", :schema=>"http://www.loc.gov/standards/mods/v3/mods-3-3.xsd", :namespace_prefix => "mods")
 
@@ -326,37 +332,41 @@ class ModsName < ActiveFedora::NokogiriDatastream
   t.corporate(:proxy=>[:corporate_full, :name_part])
   t.repository(:ref=>:corporate, :path=>'name[mods:role/mods:roleTerm="repository"]', :xmlns=>"http://www.loc.gov/mods/v3", :namespace_prefix => "mods")
 end
-</pre>
-
-This terminology not only gives the :creator and :repository values as desired, but also has :person and :corporate terms for more generic <name> xml.  The :person_full and :corporate_full values include the value of the <roleTerm> field, which is undesirable for display, if not the index.
+```
 
+This terminology not only gives the :creator and :repository values as
+desired, but also has :person and :corporate terms for more generic
+`<name>` xml. The `:person_full` and `:corporate_full` values include the
+value of the `<roleTerm>` field, which is undesirable for display, if not
+the index.
 
-h3. Arguments that can be used in the terminology
+### Arguments that can be used in the terminology
 
-e.g. :path, :default_content_path, :namespace_prefix ...
+e.g. :path, :default\_content\_path, :namespace\_prefix …
 
-ok if this is a link to the rdoc that describes ALL of these with 
+ok if this is a link to the rdoc that describes ALL of these with
 
+### Reserved method names (ie. id\_, root\_)
 
-h3. Reserved method names (ie. id_, root_)
+Like Nokogiri …
 
-Like Nokogiri ...
+### Namespaces
+- oxns
+- document namespaces & node namespaces
+- *no namespace* (suppressing oxns in xpath queries)
 
-h3. Namespaces
-oxns
-document namespaces & node namespaces
-_no namespace_ (suppressing oxns in xpath queries)
+### :ref and :proxy Terms
 
-h3. :ref and :proxy Terms
+If needed (as a differentiator) you can use the root element as a member
+of the proxy address:
 
-If needed (as a differentiator) you can use the root element as a member of the proxy address:
-<pre>
-    t.root(:path=>"mods")
-    t.titleInfo {
-      t.title
-    } 
-    This produces a relative xpath: (e.g. //titleInfo/title)
-    t.title(:proxy=>[:titleInfo, :title])
-    This produces an absolute query (e.g. /mods/titleInfo/title)
-    t.title(:proxy=>[:mods, :titleInfo, :title])
-</pre>
+```ruby
+t.root(:path=>"mods")
+t.titleInfo {
+  t.title
+} 
+This produces a relative xpath: (e.g. //titleInfo/title)
+t.title(:proxy=>[:titleInfo, :title])
+This produces an absolute query (e.g. /mods/titleInfo/title)
+t.title(:proxy=>[:mods, :titleInfo, :title])
+```

data/CONTRIBUTING.md

@@ -39,7 +39,7 @@ You should also add yourself to the `CONTRIBUTORS.md` file in the root of the pr
   * Please avoid working directly on the `master` branch.
   * You may find the [hub suite of commands](https://github.com/defunkt/hub) helpful
 * Make commits of logical units.
-  * Your commit should include a high level description of your work in HISTORY.textile 
+  * Your commit should include a high level description of your work in HISTORY.md 
 * Check for unnecessary whitespace with `git diff --check` before committing.
 * Make sure your commit messages are [well formed](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 * If you created an issue, you can close it by including "Closes #issue" in your commit message. See [Github's blog post for more details](https://github.com/blog/1386-closing-issues-via-commit-messages)
@@ -96,7 +96,7 @@ You should also add yourself to the `CONTRIBUTORS.md` file in the root of the pr
 
 ### Merging Changes
 
-* It is considered "poor from" to merge your own request.
+* It is considered "poor form" to merge your own request.
 * Please take the time to review the changes and get a sense of what is being changed. Things to consider:
   * Does the commit message explain what is going on?
   * Does the code changes have tests? _Not all changes need new tests, some changes are refactorings_

data/GETTING_FANCY.md

@@ -0,0 +1,153 @@
+# Getting Fancy
+
+## Alternative ways to Manipulate Terms, Terminologies and their Builders
+
+There is more than one way to build a terminology.
+
+### OM::XML::Terminology::Builder Block Syntax
+
+The simplest way to create an OM Terminology is to use the
+[OM::XML::Terminology::Builder](OM/XML/Terminology/Builder.html) block
+syntax.
+
+In the following examples, we will show different ways of building this
+Terminology:
+
+```ruby
+builder = OM::XML::Terminology::Builder.new do |t|
+t.root(:path=>"grants", :xmlns=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", :schema=>"http://example.org/schemas/grants-v1.xsd")
+t.grant {
+  t.org(:path=>"organization", :attributes=>{:type=>"funder"}) {
+    t.name(:index_as=>:searchable)
+  }
+  t.number
+}
+end
+another_terminology = builder.build
+```
+
+### Using [OM::XML::Term](OM/XML/Term.html)::Builders
+
+First, create the Terminology Builder object:
+
+```ruby
+terminology_builder = OM::XML::Terminology::Builder.new
+```
+
+The .root method handles creating the root term and setting namespaces,
+schema, etc. on the Terminology:
+
+```ruby
+terminology_builder.root(:path=>"grants", :xmlns=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", :schema=>"http://example.org/schemas/grants-v1.xsd")
+```
+
+This sets the namespaces for you and created the “grants” root term:
+
+```ruby
+terminology_builder.namespaces
+   => {"oxns"=>"http://yourmediashelf.com/schemas/hydra-dataset/v0", "xmlns"=>"http://yourmediashelf.com/schemas/hydra-dataset/v0"}
+terminology_builder.term_builders
+```
+
+Create Term Builders for each of the Terms:
+
+```ruby
+term1_builder      = OM::XML::Term::Builder.new("grant", terminology_builder).path("grant")
+subterm1_builder   = OM::XML::Term::Builder.new("org", terminology_builder).attributes(:type=>"funder")
+subsubterm_builder = OM::XML::Term::Builder.new("name", terminology_builder).index_as(:searchable)
+subterm2_builder   = OM::XML::Term::Builder.new("number", terminology_builder)
+```
+
+Assemble the tree of Term builders by adding child builders to their
+parents; then add the top level terms to the root term in the
+Terminology builder:
+
+```ruby
+subterm1_builder.add_child(subsubterm_builder)
+term1_builder.add_child(subterm1_builder)
+term1_builder.add_child(subterm2_builder)
+terminology_builder.term_builders["grant"] = term1_builder
+```
+
+Now build the Terminology, which will also call .build on each of the
+Term Builders in the tree:
+
+```ruby
+built_terminology = terminology_builder.build
+```
+
+Test it out:
+
+```ruby
+built_terminology.retrieve_term(:grant, :org, :name)
+built_terminology.xpath_for(:grant, :org, :name)
+built_terminology.root_terms
+built_terminology.terms.keys  # This will only return the Terms at the root of the terminology hierarchy
+built_terminology.retrieve_term(:grant).children.keys
+```
+
+### Creating Terms & Terminologies without any Builders
+
+If you want to manipulate Terms and Terminologies directly rather than
+using the Builder classes, you can consume their APIs at any time.
+
+People don’t often do this, but the option is there if you need it.
+
+Create the Terminology, set its namespaces & (optional) schema:
+(Note that you have to set the :oxns namespaces to match :xmlns. This is
+usually done for you by the Terminology::Builder.root method.)
+
+```ruby
+handcrafted_terminology = OM::XML::Terminology.new
+handcrafted_terminology.namespaces[:xmlns] = "http://yourmediashelf.com/schemas/hydra-dataset/v0"
+handcrafted_terminology.namespaces[:oxns]  = "http://yourmediashelf.com/schemas/hydra-dataset/v0"
+handcrafted_terminology.schema = "http://example.org/schemas/grants-v1.xsd"
+```
+
+Create the Terms:
+
+```ruby
+# Create term1 (the root) and set it as the root term
+root_term = OM::XML::Term.new("grants")
+root_term.is_root_term = true
+
+# Create term1 (grant) and its subterms
+term1 = OM::XML::Term.new("grant")
+
+subterm1 = OM::XML::Term.new("org")
+subterm1.path = "organization"
+subterm1.attributes = {:type=>"funder"}
+
+subsubterm = OM::XML::Term.new("name")
+subsubterm.index_as = :searchable
+
+subterm2 = OM::XML::Term.new("number")
+```
+
+Assemble the tree of terms by adding child terms to their parents, then
+add those to the Terminology.
+
+```ruby
+subterm1.add_child(subsubterm)
+term1.add_child(subterm1)
+term1.add_child(subterm2)
+handcrafted_terminology.add_term(root_term)
+handcrafted_terminology.add_term(term1)
+```
+
+Generate the xpath queries for each term. This is usually done for you
+by the Term Builder.build method:
+
+```ruby
+[root_term, term1, subterm1, subsubterm, subterm2].each {|t| t.generate_xpath_queries!}
+```
+
+Test it out:
+
+```ruby
+handcrafted_terminology.retrieve_term(:grant, :org, :name)
+handcrafted_terminology.xpath_for(:grant, :org, :name)
+handcrafted_terminology.root_terms
+handcrafted_terminology.terms.keys  # This will only return the Terms at the root of the terminology hierarchy
+handcrafted_terminology.retrieve_term(:grant).children.keys
+```