neu-mods 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1469790b96ff15516d9766db6673159fb9ad14128e02c4399842580c198a1740
-  data.tar.gz: 97c442fbd0765c6de753bbb140da3fa2ac61fedcb63104d38801c569a876ddcd
+  metadata.gz: 5b89b85501bd24a3e03e6cb9c0d8945c32b5b053ce21ce12d06c92ff1d411f99
+  data.tar.gz: f7ba90fecf34428546872120f116b0de258bb56b4fb42e2c2d90a4d76eea338d
 SHA512:
-  metadata.gz: 5b2fdf0e42f5fd65fccbc732ddf4a15b3f311f4719a3a95a294517da643c8005dcbb3c25a7b3e2b1e7afcb67c1f29f9cecacf7ec157640ef3a2b2d56e13197ac
-  data.tar.gz: 4ffc16684b6176a667fcf62dadc6e20c5fed2733c1f6bdcd39df345fe6df77f5cd412f62fe879676f1075f7c690ca6cb368b6876bfca0e4a98477af8112731c2
+  metadata.gz: 126a6f6a2fc04be9ee91a14c9469b05c9ebd5535a65f254116ac402d681e5d68d113c060003b365269a496d18a3917976b5ff9cd60ad1cbc4dfc746b63f4c77a
+  data.tar.gz: db7440392fde517da3bd14f2ed90fe8623e8da15940989d49c85bb1e1c3a338f8b0c8f9e3df7bfbaafc608fe1379b3cd84cec627e3d78dab24a59e26f57d98a8

data/.version

@@ -1 +1 @@
-0.5.0
+0.6.0

data/README.md

@@ -37,9 +37,22 @@ 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
+                   #    a day the record never claimed. Same for
+                   #    date_issued_with_precision and
+                   #    copyright_date_with_precision.
+doc.notes          # => [{ type: "funding", value: "..." }, ...]
+doc.related_items  # => [{ type: "otherFormat", title: "..." }, ...]
+                   #    every relatedItem that is not a series or a host
+doc.location       # => [{ physical_location:, shelf_location:, url: }, ...]
+doc.map_data       # => [{ scale:, projection:, coordinates: }, ...]
 doc.to_h           # => full projection, keyed to Atlas's Metadata::MODS attributes
 
+# The field registry -- the single declaration of what this gem projects.
+# name => :one or :many. to_h is derived from it, and a consumer builds its own
+# schema from it rather than re-listing the field set by hand. Cardinality
+# follows what MODS marks repeatable, so a field can never silently truncate.
+NEU::MODS::FIELDS  # => { main_title: :one, names: :many, ... }
+
 # Pure title composition (no document needed) — for callers that already hold
 # the parts (e.g. Atlas's access-copy model) and must not re-parse XML on read.
 NEU::MODS.compose_title(non_sort: "", title: "What's New",
@@ -104,6 +117,14 @@ intentional notes:
   text forms (the norm) are unaffected; code-only records would differ. Vendoring
   those lookup tables (or depending on `iso-639`) is deferred to keep the gem
   Nokogiri-only and small.
+- **`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.
 
 ## Source convention
 

data/lib/neu/mods/projection.rb

@@ -12,6 +12,8 @@ module NEU
     # Empty-value conventions mirror Atlas: scalar fields are "" when absent
     # (matching `.text.squish` on an empty node set), except `permanent_url` and
     # `date_created`, which are nil when their node is absent. Arrays are [].
+    # Which fields are scalar and which are arrays is declared in FIELDS, not
+    # left to each method to decide.
     module Projection
       # --- Title ---------------------------------------------------------------
 
@@ -25,16 +27,19 @@ module NEU
       # rewrite the curator's characters in the preservation XML on the next save.
       # #access_title_parts is the normalised surface.
       def title_parts
-        ti = primary_title_info
-        {
-          non_sort: child_text(ti, "mods:nonSort"),
-          subtitle: child_text(ti, "mods:subTitle"),
-          title: child_text(ti, "mods:title"),
-          part_name: child_text(ti, "mods:partName"),
-          part_number: child_text(ti, "mods:partNumber")
-        }
+        title_parts_of(primary_title_info)
       end
 
+      # The variant titles, each composed and normalised like the main title.
+      # MODS repeats titleInfo, so a record may carry more than one of a type.
+      # These are what keeps the primary-title fallback's refusal to promote a
+      # variant from hiding anything: the variant still reaches a reader, under
+      # a label that says which kind of title it is.
+      def alternative_title = variant_titles("alternative")
+      def uniform_title = variant_titles("uniform")
+      def translated_title = variant_titles("translated")
+      def abbreviated_title = variant_titles("abbreviated")
+
       # Composed display title (the former Atlas MODSDecoration#plain_title), driven
       # off the scoped primary title.
       def plain_title
@@ -86,10 +91,21 @@ module NEU
         join_paragraphs(abstract_nodes)
       end
 
+      # Every top-level accessCondition joined, regardless of @type. Retained
+      # because it is the only projection that carries an untyped or
+      # unrecognised accessCondition, which the two typed fields below cannot
+      # see -- a consumer that renders only those needs this as its fallback.
       def access_condition
         join_paragraphs(doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE))
       end
 
+      # The two @type values MODS defines, projected apart. Collapsing them into
+      # one value presented an access *restriction* to a reader as a *licence*,
+      # which is the one defect in this area that misinforms someone about their
+      # rights rather than merely hiding a field.
+      def use_and_reproduction = access_conditions_of_type("use and reproduction")
+      def restriction_on_access = access_conditions_of_type("restriction on access")
+
       # --- Subjects ------------------------------------------------------------
 
       # The editable free-text keyword set (Cerberus simple form): topics under the
@@ -104,6 +120,18 @@ module NEU
         doc.xpath("/mods:mods/mods:subject/mods:topic", NAMESPACE).map { |t| clean(t.text) }
       end
 
+      # 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
+      # on every batch and read back by nothing.
+      def geographic_subjects = texts_at("/mods:mods/mods:subject/mods:geographic")
+      def temporal_subjects = texts_at("/mods:mods/mods:subject/mods:temporal")
+
+      # Name subjects compose through the same display-value port as #names, so
+      # one person reads the same whether they authored the work or are its
+      # subject.
+      def personal_name_subjects = name_subjects("personal")
+      def corporate_name_subjects = name_subjects("corporate")
+
       # --- Names ---------------------------------------------------------------
 
       # All top-level names as { name:, role: }. `name` reproduces the `mods` gem's
@@ -148,18 +176,85 @@ module NEU
         end.compact
       end
 
-      def resource_type = text_at("/mods:mods/mods:typeOfResource")
-      def format = text_at("/mods:mods/mods:physicalDescription/mods:form")
-      def extent = text_at("/mods:mods/mods:physicalDescription/mods:extent")
-      def digital_origin = text_at("/mods:mods/mods:physicalDescription/mods:digitalOrigin")
+      # MODS repeats typeOfResource, and repeats physicalDescription (and form and
+      # extent within one), so all four are :many. A record that is both text and
+      # a still image used to project as text alone.
+      def resource_type = texts_at("/mods:mods/mods:typeOfResource")
+      def format = texts_at("/mods:mods/mods:physicalDescription/mods:form")
+      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 related_series
-        doc.xpath("/mods:mods/mods:relatedItem[@type='series']/mods:titleInfo/mods:title", NAMESPACE)
-           .map { |t| clean(t.text) }
+      # 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,
+      # so this element was being written into the preservation XML and then read
+      # back by nothing.
+      def publication_information = texts_at("/mods:mods/mods:originInfo/mods:publisher")
+      def edition = texts_at("/mods:mods/mods:originInfo/mods:edition")
+
+      # Every top-level note, keeping its @type. The type carries meaning -- a
+      # "statement of responsibility" is not a "funding" note -- so flattening
+      # them into bare strings would repeat the accessCondition mistake.
+      def notes
+        doc.xpath("/mods:mods/mods:note", NAMESPACE).filter_map do |node|
+          value = clean(node.text)
+          { type: clean(node["type"]), value: value } if value
+        end
+      end
+
+      # 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.
+      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"),
+            url: child_text(node, "mods:url")
+          }
+          entry if entry.values.any?
+        end
+      end
+
+      # subject/cartographics, kept structured. Composing "scale ; projection
+      # coordinates" into one string is display policy, and this gem does not own
+      # that -- a consumer that wants only the coordinates should not have to
+      # unpick a sentence to get them.
+      def map_data
+        doc.xpath("/mods:mods/mods:subject/mods:cartographics", NAMESPACE).filter_map do |node|
+          entry = {
+            scale: child_text(node, "mods:scale"),
+            projection: child_text(node, "mods:projection"),
+            coordinates: child_text(node, "mods:coordinates")
+          }
+          entry if entry.values.any?
+        end
+      end
+
+      def related_series = related_item_titles("series")
+      def host_collections = related_item_titles("host")
+
+      # relatedItem @type values that already have a field of their own, so the
+      # catch-all below does not repeat them.
+      NAMED_RELATED_ITEM_TYPES = %w[series host].freeze
+
+      # Every other relatedItem, keeping its @type. MODS also defines
+      # constituent, otherFormat, original, preceding, succeeding, isReferencedBy
+      # and reviewOf, and a record carrying any of them projected nothing at all.
+      # The type rides along because "the print edition" and "reviewed in" are
+      # not the same relationship, and no consumer can recover which it holds
+      # from the title alone. An untyped relatedItem lands here with a nil type.
+      def related_items
+        doc.xpath("/mods:mods/mods:relatedItem", NAMESPACE).filter_map do |node|
+          type = clean(node["type"])
+          next if NAMED_RELATED_ITEM_TYPES.include?(type)
+
+          title = clean(node.at_xpath("mods:titleInfo/mods:title", NAMESPACE)&.text)
+          { type: type, title: title } if title
+        end
       end
 
       def identifiers
@@ -177,56 +272,112 @@ module NEU
       # instead of being guessed after it.
       W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?\z/
 
-      # Parsed dateCreated paired with the granularity the record declared, as
-      # [value, precision]. value is nil if no originInfo/dateCreated, 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.
+      # 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.
       #
       # 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.
-      def date_created_with_precision
-        node = doc.at_xpath("/mods:mods/mods:originInfo/mods:dateCreated", NAMESPACE)
-        return [nil, nil] unless node
-
-        str = NEU::MODS.canonical_ws(node.text)
-        return [nil, nil] if str.empty?
-
-        parse_w3cdtf(str)
-      end
+      #
+      # 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
 
       # --- Full projection -----------------------------------------------------
 
+      # The field registry: the single declaration of what this gem projects.
+      # Field name => cardinality, :one or :many. The projection method of the
+      # same name owns the XPath; this row says the field exists and whether it
+      # is single- or multi-valued. #to_h is derived from it, and Atlas derives
+      # its Metadata::MODS attr_json set from it, so a field cannot be projected
+      # here and go undeclared there (or the reverse).
+      #
+      # Cardinality is the half that earns its keep. The at_xpath-versus-xpath
+      # choice here and the single-versus-array column choice in Atlas used to be
+      # made independently in two repos with nothing tying them together, which is
+      # how repeatable MODS elements ended up truncated to their first match.
+      # #cardinality_of checks each method against its row.
+      FIELDS = {
+        # titles
+        main_title: :one,
+        alternative_title: :many,
+        uniform_title: :many,
+        translated_title: :many,
+        abbreviated_title: :many,
+
+        names: :many,
+        languages: :many,
+        abstract: :one,
+
+        # origin
+        publication_information: :many,
+        edition: :many,
+        date_created: :one,
+        date_created_precision: :one,
+        date_issued: :one,
+        date_issued_precision: :one,
+        copyright_date: :one,
+        copyright_date_precision: :one,
+
+        # physical description
+        resource_type: :many,
+        genres: :many,
+        format: :many,
+        extent: :many,
+        digital_origin: :many,
+        notes: :many,
+
+        # subjects
+        topical_subjects: :many,
+        geographic_subjects: :many,
+        temporal_subjects: :many,
+        personal_name_subjects: :many,
+        corporate_name_subjects: :many,
+        map_data: :many,
+
+        # related items
+        related_series: :many,
+        host_collections: :many,
+        related_items: :many,
+
+        # identifiers and location
+        identifiers: :many,
+        permanent_url: :one,
+        location: :many,
+
+        # access
+        access_condition: :one,
+        use_and_reproduction: :one,
+        restriction_on_access: :one
+      }.freeze
+
       # The complete read projection, keyed to Atlas's Metadata::MODS attribute
       # names -- a drop-in source for `convert_xml_to_json`.
       def to_h
-        date, date_precision = date_created_with_precision
-
-        {
-          main_title: access_title_parts,
-          names: names,
-          languages: languages,
-          date_created: date,
-          date_created_precision: date_precision,
-          resource_type: resource_type,
-          genres: genres,
-          format: format,
-          extent: extent,
-          digital_origin: digital_origin,
-          abstract: abstract,
-          related_series: related_series,
-          topical_subjects: topical_subjects,
-          identifiers: identifiers,
-          permanent_url: permanent_url,
-          access_condition: access_condition
-        }
+        FIELDS.keys.to_h { |field| [field, public_send(field)] }
       end
 
+      # The cardinality a projected value actually has, for checking a value
+      # against its FIELDS row. An Array is :many and anything else is :one, so a
+      # field declared :many that forgot to switch at_xpath for xpath is caught.
+      def self.cardinality_of(value) = value.is_a?(Array) ? :many : :one
+
       # The title parts as the access copy wants them: normalised like the
       # abstract, so a curly quote, an invisible format mark or a Windows-1252
       # control cannot reach Solr or a display template. Titles and prose share
@@ -235,6 +386,11 @@ module NEU
         title_parts.transform_values { |value| NEU::MODS.normalize(value.to_s) }
       end
 
+      # Atlas names this field main_title; the registry requires a method per
+      # field name, and #access_title_parts is the descriptive name for what it
+      # returns. Kept as an alias rather than a rename so both read well.
+      def main_title = access_title_parts
+
       private
 
       # --- helpers -------------------------------------------------------------
@@ -259,11 +415,58 @@ module NEU
         ["", nil]
       end
 
+      def date_with_precision(element)
+        node = doc.at_xpath("/mods:mods/mods:originInfo/mods:#{element}", NAMESPACE)
+        return [nil, nil] unless node
+
+        str = NEU::MODS.canonical_ws(node.text)
+        return [nil, nil] if str.empty?
+
+        parse_w3cdtf(str)
+      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)
+        {
+          non_sort: child_text(node, "mods:nonSort"),
+          subtitle: child_text(node, "mods:subTitle"),
+          title: child_text(node, "mods:title"),
+          part_name: child_text(node, "mods:partName"),
+          part_number: child_text(node, "mods:partNumber")
+        }
+      end
+
+      # A variant title composed the way the access copy wants it: normalised
+      # first, like #access_title_parts, so a curly quote or an invisible format
+      # mark cannot reach Solr or a display template through this route either.
+      def variant_titles(type)
+        doc.xpath("/mods:mods/mods:titleInfo[@type='#{type}']", NAMESPACE).filter_map do |node|
+          parts = title_parts_of(node).transform_values { |value| NEU::MODS.normalize(value.to_s) }
+          clean(Projection.compose_title(parts))
+        end
+      end
+
+      def name_subjects(type)
+        doc.xpath("/mods:mods/mods:subject/mods:name[@type='#{type}']", NAMESPACE)
+           .filter_map { |node| name_display_value_w_date(node) }
+      end
+
+      def related_item_titles(type)
+        texts_at("/mods:mods/mods:relatedItem[@type='#{type}']/mods:titleInfo/mods:title")
+      end
+
       def text_at(xpath)
         node = doc.at_xpath(xpath, NAMESPACE)
         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.
+      def texts_at(xpath)
+        doc.xpath(xpath, NAMESPACE).filter_map { |node| clean(node.text) }
+      end
+
       def child_text(parent, xpath)
         return nil unless parent
 
@@ -288,6 +491,15 @@ module NEU
         NEU::MODS.canonical_ws(str)
       end
 
+      # The schema leaves accessCondition/@type an open string, so match on the
+      # canonicalised, case-folded value rather than in the XPath: real records
+      # carry "Use and Reproduction" as readily as the MODS-recommended casing.
+      def access_conditions_of_type(type)
+        nodes = doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE)
+                   .select { |node| NEU::MODS.canonical_ws(node["type"].to_s).downcase == type }
+        join_paragraphs(nodes)
+      end
+
       def join_paragraphs(nodes)
         nodes.map { |n| NEU::MODS.normalize_paragraphs(n.text) }.reject(&:empty?).join("\n\n")
       end

data/lib/neu/mods/selectors.rb

@@ -8,12 +8,28 @@ module NEU
     # definition is the point: the node an editor changes is provably the node the
     # projection reads. Mixed into Document; operates on `doc`.
     module Selectors
-      # Top-level primary titleInfo, falling back to the first top-level titleInfo.
-      # Scoped to direct children of <mods:mods> so a relatedItem's nested
-      # titleInfo (e.g. a series title) is never matched.
+      # Top-level primary titleInfo, falling back to the first top-level titleInfo
+      # that is NOT a variant. Scoped to direct children of <mods:mods> so a
+      # relatedItem's nested titleInfo (e.g. a series title) is never matched.
+      #
+      # MODS does not require usage="primary", so the fallback fires often, and
+      # an unfiltered one let document order decide the record's title. It also
+      # decided which node an edit form wrote to: MODSMerge overwrites the node
+      # this returns, so an alternative title reached here was destroyed on the
+      # next title edit, leaving the record with no primary title at all. nil is
+      # the right answer instead -- MODSMerge creates a proper primary titleInfo
+      # from nil, and each variant is projected under its own field.
       def primary_title_info
         doc.at_xpath("/mods:mods/mods:titleInfo[@usage='primary']", NAMESPACE) ||
-          doc.at_xpath("/mods:mods/mods:titleInfo", NAMESPACE)
+          doc.xpath("/mods:mods/mods:titleInfo", NAMESPACE).reject { |ti| variant_title?(ti) }.first
+      end
+
+      # MODS enumerates titleInfo/@type as exactly abbreviated, translated,
+      # alternative and uniform -- every one of them a variant. So the presence
+      # of any @type marks a variant, which also keeps an unrecognised or
+      # misspelled value out of the write path rather than guessing at it.
+      def variant_title?(node)
+        !NEU::MODS.canonical_ws(node["type"].to_s).empty?
       end
 
       # All top-level <abstract> elements (MODS permits several).

data/lib/neu-mods.rb

@@ -24,6 +24,12 @@ module NEU
     # The MODS v3 namespace, as a Nokogiri xpath namespace hash.
     NAMESPACE = { "mods" => "http://www.loc.gov/mods/v3" }.freeze
 
+    # The projected field set and its cardinality (see Projection::FIELDS),
+    # surfaced here so a consumer deriving its own schema from it -- Atlas's
+    # Metadata::MODS attr_json set -- reads the shared contract off the top-level
+    # module instead of reaching into a mixin.
+    FIELDS = Projection::FIELDS
+
     module_function
 
     # Whitespace no-op guard (see Canonicalize).

metadata

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