neu-mods 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd81033ef60fdd497880f538d3730d1518a37b362307028a165a1f93105bdd2
-  data.tar.gz: 3f6e1aa77c231d6622dceb4d4ae66d500329776659bf4feb2cb4ea8ded455932
+  metadata.gz: 3c0467914a611aa9d46065edcd2c0a18cd0decd642e769b70ecfaecc18e7ef1e
+  data.tar.gz: f97ba11b67874fefcb98f9de2af47eda370bb61f679e9b10994cf465b31876f2
 SHA512:
-  metadata.gz: 6b643273728275f712a266a33a64cf34bbe078fa405ca29ffd59af52f0e9ee7c9102f3867f6d4129bcbb5b050d28c9a00995190ec5568fea6761ee1af87254c4
-  data.tar.gz: b86248e24362d8e1436c47c4a0decf5254207ad587791f8fb0434ac7560e4d7a79e3e429464d89ad50dcc92d208e63ad456235a0c94a6c328b7b6efc0951d22f
+  metadata.gz: 94029ec3b5d70d835677c4ad49cfc02bf7a501c782a91adb38c3a5cf6310ee727ffcef7736975526b699c796ff574ab3be5645ecaa7d576494b9b28c88c67ac1
+  data.tar.gz: 3b5c3b2f36af51e6af7424ff5ecdbf365a6c56358bf3aec3cff370b2473ad334cfaed9c20eae4aa2025ab583eb9d0ec9d7439d94fb7d8687e80dd301a64c7c38

data/.version

@@ -1 +1 @@
-0.7.0
+0.8.0

data/README.md

@@ -34,13 +34,17 @@ doc.abstract       # => normalized, paragraph-joined String
 doc.languages      # => ["English"]   a code-only <languageTerm>eng</> included
 doc.topical_subjects # => ["Civil society", ...]   (every <topic>, for the access copy)
 doc.keywords       # => [...]   (only the editable attribute-free keyword subjects)
-doc.date_created_with_precision
-                   # => [DateTime, "year"|"month"|"day"]   w3cdtf YYYY, YYYY-MM
-                   #    and YYYY-MM-DD all parse; the precision says which shape
-                   #    the record declared, so display cannot invent a month or
-                   #    a day the record never claimed. Same for
-                   #    date_issued_with_precision and
-                   #    copyright_date_with_precision.
+doc.date_created_parts
+                   # => { value:, precision:, end_value:, end_precision:,
+                   #      qualifier:, key_date: }   everything the record
+                   #    declared about one date. w3cdtf YYYY, YYYY-MM and
+                   #    YYYY-MM-DD all parse, and the precision says which
+                   #    shape it gave, so display cannot invent a month or a
+                   #    day. The points are read by @point, not by document
+                   #    order, and the end carries its OWN precision.
+                   #    Same for date_issued_parts and copyright_date_parts;
+                   #    each part is also a reader of its own, e.g.
+                   #    doc.date_created_qualifier.
 doc.notes          # => [{ type: "funding", value: "..." }, ...]
 doc.related_items  # => [{ type: "otherFormat", title: "..." }, ...]
                    #    every relatedItem that is not a series or a host
@@ -123,14 +127,17 @@ intentional notes:
   label vocabulary belongs to the consumer — Cerberus's edit form and Atlas's
   display word the same role differently. An unrecognised language code also
   stays raw, since the record still said something.
-- **`description` is not projected.** MODS has no element of that name, and the
-  two candidates — an `abstract` variant and `physicalDescription/note` —
-  describe different things. Projecting a guess would put wrong data in the
-  field rather than leave an empty one, so it waits on a decision.
-- **A date range is not projected.** `dateCreated`, `dateIssued` and
-  `copyrightDate` each project one value with its precision. A record that
-  ranges a date uses `point="start"` / `point="end"`, which needs a shape of its
-  own rather than a second array.
+- **`description` is not projected.** MODS does define `name/description`, but
+  that annotates a *name*, not the resource, so it is not the field Atlas once
+  called `description`. The two candidates for that one — an `abstract` variant
+  and `physicalDescription/note` — describe different things. Projecting a guess
+  would put wrong data in the field rather than leave an empty one, so it waits
+  on a decision.
+- **A date carries more than a value.** Each of `dateCreated`, `dateIssued` and
+  `copyrightDate` projects a value, its precision, an end value with its own
+  precision, the `@qualifier` and the `@keyDate` flag. The gem does not *pick*
+  the key date, because "which date to sort on" and "which date to display" are
+  not necessarily the same answer, and choosing is the consumer's job.
 
 ## Source convention
 

data/lib/neu/mods/projection.rb

@@ -116,9 +116,7 @@ module NEU
 
       # Every <topic> under any top-level <subject> (the access-copy projection,
       # equivalent to Atlas's extract_topical_subjects).
-      def topical_subjects
-        doc.xpath("/mods:mods/mods:subject/mods:topic", NAMESPACE).map { |t| clean(t.text) }
-      end
+      def topical_subjects = texts_at("/mods:mods/mods:subject/mods:topic")
 
       # The other subject axes. Cerberus's IPTC ingest writes subject/geographic
       # from the IPTC City and State fields, so this one was also being written
@@ -134,14 +132,26 @@ module NEU
 
       # --- Names ---------------------------------------------------------------
 
+      # One name as the access copy wants it. `affiliation` is how a reader
+      # tells one J. Doe from another, and it is the field an institutional
+      # repository most wants: it repeats in the schema, so it is an array.
+      #
+      # Added to the entry rather than as a parallel field, so a name and its
+      # affiliation cannot be zipped together wrongly by a consumer.
+      def name_entry(node)
+        {
+          name: name_display_value_w_date(node),
+          role: name_role(node),
+          affiliation: texts_under(node, "mods:affiliation")
+        }
+      end
+
       # All top-level names as { name:, role: }. `name` reproduces the `mods` gem's
       # display_value_w_date (including its quirks -- faithfully, so existing Solr/
       # display output is preserved). `role` prefers the type="text" roleTerm,
       # falling back to the raw code (NOT MARC-relator-translated -- see README).
       def names
-        doc.xpath("/mods:mods/mods:name", NAMESPACE).map do |node|
-          { name: name_display_value_w_date(node), role: name_role(node) }
-        end
+        doc.xpath("/mods:mods/mods:name", NAMESPACE).map { |node| name_entry(node) }
       end
 
       # Editable (depositor-managed) creators: the plain names (no authority
@@ -163,7 +173,7 @@ module NEU
       def preserved_names
         doc.xpath("/mods:mods/mods:name", NAMESPACE)
            .reject { |node| editable_creator_name?(node) }
-           .map { |node| { name: name_display_value_w_date(node), role: name_role(node) } }
+           .map { |node| name_entry(node) }
       end
 
       # --- Scalars / simple arrays --------------------------------------------
@@ -190,9 +200,7 @@ module NEU
       def extent = texts_at("/mods:mods/mods:physicalDescription/mods:extent")
       def digital_origin = texts_at("/mods:mods/mods:physicalDescription/mods:digitalOrigin")
 
-      def genres
-        doc.xpath("/mods:mods/mods:genre", NAMESPACE).map { |g| clean(g.text) }
-      end
+      def genres = texts_at("/mods:mods/mods:genre")
 
       # originInfo repeats, and so do publisher and edition within one. Cerberus's
       # IPTC ingest writes the publisher from the IPTC Source field on every batch,
@@ -214,11 +222,15 @@ module NEU
       # location repeats, and one location mixes kinds: a shelf mark and a URL
       # are not interchangeable, and a consumer has to know which it holds
       # before it can decide to linkify it. So the parts stay apart.
+      #
+      # The shelf mark is mods:shelfLocator. There is no shelfLocation element
+      # in MODS, and the spec fixture carried the same misspelling, so the
+      # field was unconditionally nil and the spec asserted nothing.
       def location
         doc.xpath("/mods:mods/mods:location", NAMESPACE).filter_map do |node|
           entry = {
             physical_location: child_text(node, "mods:physicalLocation"),
-            shelf_location: child_text(node, "mods:shelfLocation"),
+            shelf_location: child_text(node, "mods:shelfLocator"),
             url: child_text(node, "mods:url")
           }
           entry if entry.values.any?
@@ -263,8 +275,17 @@ module NEU
         end
       end
 
+      # { type:, value: }, because a DOI, an accession number and a collection
+      # id are not the same kind of thing and no consumer can tell them apart
+      # from the digits alone -- a reader shown a bare 10.1234/x cannot see it
+      # is a DOI, and a display cannot decide to linkify it. The same argument
+      # #notes already makes for its @type, and #permanent_url already proves
+      # the attribute is load-bearing by special-casing @type='hdl'.
       def identifiers
-        doc.xpath("/mods:mods/mods:identifier", NAMESPACE).map { |i| clean(i.text) }
+        doc.xpath("/mods:mods/mods:identifier", NAMESPACE).filter_map do |node|
+          value = clean(node.text)
+          { type: clean(node["type"]), value: value } if value
+        end
       end
 
       def permanent_url
@@ -278,32 +299,57 @@ module NEU
       # instead of being guessed after it.
       W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?\z/
 
-      # The three originInfo dates, each paired with the granularity the record
-      # declared, as [value, precision]. value is nil if the element is absent,
-      # or "" if present but unparseable (mirrors Atlas's safe_date_parse
-      # rescue). precision is "year", "month" or "day", and nil whenever value
-      # is not a DateTime.
+      # What #date_parts returns when the element is absent entirely, so an
+      # absent date is distinguishable from one present and unparseable.
+      EMPTY_DATE = { value: nil, precision: nil, end_value: nil,
+                     end_precision: nil, qualifier: nil, key_date: nil }.freeze
+
+      # Everything a record declared about one originInfo date, as
+      # { value:, precision:, end_value:, end_precision:, qualifier:, key_date: }.
       #
-      # The precision has to be captured here, at the only point where the shape
-      # is still visible: a year-only date parses to January 1st, and no consumer
-      # downstream can tell that month and day from a record that claimed them.
-      # A preservation repository must not project a precision it was not given.
+      # A date is not a scalar. Precision established that: a year-only date
+      # parses to January 1st, and no consumer downstream can tell that month
+      # and day from a record that claimed them. A range and a qualifier are the
+      # same kind of claim, and dropping them breaks the same rule -- a
+      # preservation repository must not project a value the record did not
+      # give. A ranged record was worse than that: #at_xpath took the first
+      # node, so one end of the range was PROMOTED to be the date, and the
+      # output was indistinguishable from a single certain year.
       #
-      # These stay :one where the sibling originInfo elements are :many. MODS
-      # repeats them, but a date carries a precision alongside it, and an array
-      # of values paired with an array of precisions is a shape no consumer
-      # wants. A record that ranges its dates uses point="start"/"end", which is
-      # its own projection question rather than a cardinality one.
-      def date_created_with_precision = date_with_precision("dateCreated")
-      def date_issued_with_precision = date_with_precision("dateIssued")
-      def copyright_date_with_precision = date_with_precision("copyrightDate")
-
-      def date_created = date_created_with_precision.first
-      def date_created_precision = date_created_with_precision.last
-      def date_issued = date_issued_with_precision.first
-      def date_issued_precision = date_issued_with_precision.last
-      def copyright_date = copyright_date_with_precision.first
-      def copyright_date_precision = copyright_date_with_precision.last
+      # The parts are projected as separate flat fields rather than one nested
+      # value, because the value half has three consumers that need a real date
+      # object -- a Solr sort key, a citation year and an OAI date.
+      def date_created_parts = date_parts("dateCreated")
+      def date_issued_parts = date_parts("dateIssued")
+      def copyright_date_parts = date_parts("copyrightDate")
+
+      def date_created = date_created_parts[:value]
+      def date_created_precision = date_created_parts[:precision]
+      def date_created_end = date_created_parts[:end_value]
+      def date_created_end_precision = date_created_parts[:end_precision]
+      def date_created_qualifier = date_created_parts[:qualifier]
+      def date_created_key_date = date_created_parts[:key_date]
+
+      def date_issued = date_issued_parts[:value]
+      def date_issued_precision = date_issued_parts[:precision]
+      def date_issued_end = date_issued_parts[:end_value]
+      def date_issued_end_precision = date_issued_parts[:end_precision]
+      def date_issued_qualifier = date_issued_parts[:qualifier]
+      def date_issued_key_date = date_issued_parts[:key_date]
+
+      def copyright_date = copyright_date_parts[:value]
+      def copyright_date_precision = copyright_date_parts[:precision]
+      def copyright_date_end = copyright_date_parts[:end_value]
+      def copyright_date_end_precision = copyright_date_parts[:end_precision]
+      def copyright_date_qualifier = copyright_date_parts[:qualifier]
+      def copyright_date_key_date = copyright_date_parts[:key_date]
+
+      # The [value, precision] pair the precision work introduced. Retained
+      # because it is the documented entry point for a caller that wants both
+      # halves and nothing else.
+      def date_created_with_precision = [date_created, date_created_precision]
+      def date_issued_with_precision = [date_issued, date_issued_precision]
+      def copyright_date_with_precision = [copyright_date, copyright_date_precision]
 
       # --- Full projection -----------------------------------------------------
 
@@ -334,12 +380,26 @@ module NEU
         # origin
         publication_information: :many,
         edition: :many,
+        # Six rows per originInfo date. Flat rather than one nested value,
+        # because the value half has consumers that need a real date object.
         date_created: :one,
         date_created_precision: :one,
+        date_created_end: :one,
+        date_created_end_precision: :one,
+        date_created_qualifier: :one,
+        date_created_key_date: :one,
         date_issued: :one,
         date_issued_precision: :one,
+        date_issued_end: :one,
+        date_issued_end_precision: :one,
+        date_issued_qualifier: :one,
+        date_issued_key_date: :one,
         copyright_date: :one,
         copyright_date_precision: :one,
+        copyright_date_end: :one,
+        copyright_date_end_precision: :one,
+        copyright_date_qualifier: :one,
+        copyright_date_key_date: :one,
 
         # physical description
         resource_type: :many,
@@ -421,8 +481,42 @@ module NEU
         ["", nil]
       end
 
-      def date_with_precision(element)
-        node = doc.at_xpath("/mods:mods/mods:originInfo/mods:#{element}", NAMESPACE)
+      # One originInfo date element, read by its attributes rather than by
+      # position. A record is free to write point="end" first, and taking the
+      # first node would then invert the range.
+      def date_parts(element)
+        nodes = doc.xpath("/mods:mods/mods:originInfo/mods:#{element}", NAMESPACE)
+        return EMPTY_DATE if nodes.empty?
+
+        start = nodes.find { |n| attr_value(n, "point") == "start" } ||
+                nodes.find { |n| attr_value(n, "point") != "end" }
+        finish = nodes.find { |n| attr_value(n, "point") == "end" }
+        date_entry(start, finish, nodes)
+      end
+
+      # The end point carries its OWN precision. "1935-06" to "1940" is legal,
+      # and reusing the start's granularity for both would assert something the
+      # end never claimed -- the precision bug in a new place.
+      #
+      # The qualifier falls back from the start to the end because v1's loader
+      # applied it to both points, and a record marking only one is still
+      # telling us the date is uncertain. An unrecognised value survives as
+      # itself: MODS enumerates approximate, inferred and questionable, but the
+      # record still said something.
+      def date_entry(start, finish, nodes)
+        value, precision = node_date(start)
+        end_value, end_precision = node_date(finish)
+        {
+          value: value,
+          precision: precision,
+          end_value: end_value,
+          end_precision: end_precision,
+          qualifier: attr_value(start, "qualifier") || attr_value(finish, "qualifier"),
+          key_date: nodes.any? { |n| attr_value(n, "keyDate") == "yes" }
+        }
+      end
+
+      def node_date(node)
         return [nil, nil] unless node
 
         str = NEU::MODS.canonical_ws(node.text)
@@ -431,6 +525,13 @@ module NEU
         parse_w3cdtf(str)
       end
 
+      def attr_value(node, name)
+        return nil unless node
+
+        value = NEU::MODS.canonical_ws(node[name].to_s)
+        value.empty? ? nil : value
+      end
+
       # Byte-faithful title parts off any titleInfo node, shared by #title_parts
       # (which Cerberus pre-fills its edit forms from) and the variant titles.
       def title_parts_of(node)
@@ -467,8 +568,17 @@ module NEU
         node ? NEU::MODS.canonical_ws(node.text) : ""
       end
 
-      # The :many counterpart of #text_at. Blank members drop out rather than
-      # arriving as nil, so a consumer mapping over the array cannot trip on one.
+      # The :many counterpart of #text_at, and the one way this file builds a
+      # string array. Blank members drop out rather than arriving as nil: a
+      # record template that seeds an empty <topic> for an edit form to fill --
+      # which is exactly what Atlas's MODSBuilder writes -- otherwise projects
+      # [nil], and every consumer of that array has to guard for it.
+      # #texts_at scoped to a node rather than the document, for a repeatable
+      # child of one element.
+      def texts_under(node, xpath)
+        node.xpath(xpath, NAMESPACE).filter_map { |child| clean(child.text) }
+      end
+
       def texts_at(xpath)
         doc.xpath(xpath, NAMESPACE).filter_map { |node| clean(node.text) }
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neu-mods
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - David Cliff