neu-mods 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa2cba0771dfcd203ae956c9f5a84cb58c004df684620e378bf4034b978ee6b3
-  data.tar.gz: e3610d3984fecaebccdb88032ab07b4fab55b0e6932ee5f54218b654016ceca5
+  metadata.gz: f29586facbe4e40077b0875aa896886a812b231058e97c12822875fd6203edef
+  data.tar.gz: 0fc6d10f7b3a50ff8659497a2de526f0d9b394751c4b4acd09c1676338dfdb87
 SHA512:
-  metadata.gz: 8bcbcf544da159f6e2377ae868808e73e78d254e9c597e2dcd676d140cbb6f59a8624ca698233bd0ab18866c9438ddae988a7fc0ac485ce7fa3557c34d199a76
-  data.tar.gz: de478ac9c203c1edf05fb604c9da85b05e95e133fb20231716a6ef7dd9310292dacf753f13781d253ecbd93a04aa290e2eff40dc32c5331de0e278c1b07c736f
+  metadata.gz: 5801c6878c83a3ae03eef2af7970b1d492a215705d7105002eadb12740f5af35f383e490dc4bbc02f59a723c56c99e9b9afb2399a35b0f785613abe1ff11a922
+  data.tar.gz: 92ffead82d106913bb14ad273096397bb319290b9ce04db46c068412ce3da3cd7dc4670526c50b63413a4f70b10a145bfeef7feecc854abca0480ea3aed7c112

data/.version

@@ -1 +1 @@
-0.10.0
+0.11.0

data/README.md

@@ -27,7 +27,7 @@ require "neu-mods"
 doc = NEU::MODS::Document.parse(xml_string)
 
 # Projection (plain data)
-doc.plain_title    # => "What's New - How We Respond to Disaster, Episode 1"
+doc.plain_title    # => "What's New, Episode 1 - How We Respond to Disaster"
 doc.title_parts    # => { non_sort:, subtitle:, title:, part_name:, part_number: }
                    #    byte-faithful -- the edit forms pre-fill from these
 doc.abstract       # => normalized, paragraph-joined String
@@ -42,9 +42,23 @@ doc.date_created_parts
                    #    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.
+                   #    A keyDate="yes" node chooses the value, ahead of
+                   #    @point and document order; one date per type is the
+                   #    rule, so an unflagged repeat is discarded.
+                   #    Same for the other six originInfo dates --
+                   #    date_issued, copyright_date, date_captured,
+                   #    date_valid, date_other and date_modified. Each part is
+                   #    also a reader of its own, e.g.
                    #    doc.date_created_qualifier.
+doc.place_of_publication
+                   # => ["Boston"]   the type="text" placeTerm wins, so a
+                   #    marccountry code does not reach a places facet as a
+                   #    place name; a code-only place still projects its code
+doc.host_collections
+                   # => [{ title:, volume:, issue:, start_page:, end_page:,
+                   #      date:, text:, details: [...], extents: [...] }, ...]
+                   #    this work's position in its host. The entry survives on
+                   #    its part alone, so a host with no titleInfo is kept
 doc.notes          # => [{ type: "funding", value: "..." }, ...]
 doc.related_items  # => [{ type: "otherFormat", title: "..." }, ...]
                    #    every relatedItem that is not a series or a host
@@ -69,7 +83,9 @@ NEU::MODS::FIELDS  # => { main_title: :one, names: :many, ... }
 # 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",
                         part_name: "How We Respond to Disaster", part_number: "Episode 1")
-# => "What's New - How We Respond to Disaster, Episode 1"   (== doc.plain_title)
+# => "What's New, Episode 1 - How We Respond to Disaster"   (== doc.plain_title)
+# The part NUMBER precedes the part NAME: "Part 2. The Marshes" is the
+# cataloguing convention, and titleInfo is an unordered choice in the schema.
 
 # Selectors (live nodes — for editing)
 node = doc.primary_title_info.at_xpath("mods:title", NEU::MODS::NAMESPACE)

data/lib/neu/mods/projection.rb

@@ -52,10 +52,17 @@ module NEU
       # (reaching for Nokogiri in a decorator is the smell this avoids). Keys:
       # :non_sort :title :subtitle :part_name :part_number (nil or "" for absent).
       # Returns "" when there is no title. Exposed as NEU::MODS.compose_title.
+      #
+      # The part NUMBER precedes the part NAME. titleInfo is an unordered choice
+      # in the schema, so no document order is available to follow, and a fixed
+      # order that put the name first read the number as a trailing qualifier on
+      # the section rather than as the section it numbers. Cataloguing practice
+      # is "Part 2. The Marshes". The separator travels with the part, not with
+      # the position, so the swap moves the comma with the number.
       def self.compose_title(parts)
         return "" if parts[:title].to_s.strip.empty?
 
-        optional = { ": " => parts[:subtitle], " - " => parts[:part_name], ", " => parts[:part_number] }
+        optional = { ": " => parts[:subtitle], ", " => parts[:part_number], " - " => parts[:part_name] }
         suffix = optional.filter_map { |sep, val| "#{sep}#{val}" unless val.to_s.strip.empty? }.join
         "#{join_non_sort(parts[:non_sort], parts[:title])}#{suffix}"
       end
@@ -205,8 +212,18 @@ module NEU
       # cataloguer who records that a person both wrote and edited a work means
       # both. Each term prefers the type="text" roleTerm, falling back to the raw
       # code (NOT MARC-relator-translated -- see README).
+      #
+      # A name with no name text drops out. A mods:name carrying only a role
+      # projected { name: nil, roles: ["edt"] }, which a display renders as a
+      # labelled empty row and which every consumer had to guard against with
+      # its own compact_blank. #preserved_names deliberately keeps it: that list
+      # tells a curator what the XML holds, so an element they need to fix has
+      # to stay visible there.
       def names
-        doc.xpath("/mods:mods/mods:name", NAMESPACE).map { |node| name_entry(node) }
+        doc.xpath("/mods:mods/mods:name", NAMESPACE).filter_map do |node|
+          entry = name_entry(node)
+          entry if entry[:name]
+        end
       end
 
       # Editable (depositor-managed) creators: the plain names (no authority
@@ -263,7 +280,25 @@ module NEU
       # back by nothing.
       def publication_information = texts_at("/mods:mods/mods:originInfo/mods:publisher")
       def edition = texts_at("/mods:mods/mods:originInfo/mods:edition")
-      def place_of_publication = texts_at("/mods:mods/mods:originInfo/mods:place/mods:placeTerm")
+
+      # Prefer the type="text" term per place, falling back to a coded one --
+      # the pattern #role_term_value and #languages already use. Unfiltered, a
+      # marccountry code reached the display and the Solr places facet as a
+      # place name, so "mau" sat in the list beside Boston. A code still
+      # projects when it is all the record gives, because dropping it would
+      # lose the only statement the record made.
+      #
+      # TODO: expand a marccountry code through a registry, as LanguageCodes
+      # does for eng -> English. That needs a vendored code list.
+      def place_of_publication
+        doc.xpath("/mods:mods/mods:originInfo/mods:place", NAMESPACE).filter_map do |place|
+          text = clean(place.at_xpath("mods:placeTerm[@type='text']", NAMESPACE)&.text)
+          next text if text
+
+          clean(place.at_xpath("mods:placeTerm", NAMESPACE)&.text)
+        end
+      end
+
       def issuance = texts_at("/mods:mods/mods:originInfo/mods:issuance")
 
       # Serials. The @authority a record puts on a frequency is not projected:
@@ -338,10 +373,14 @@ module NEU
       # record, and a transcribed copy goes stale the moment that record is
       # edited. A part is the exception, because a volume, issue and page range
       # describe this article and no other record holds that fact.
+      #
+      # An entry survives on its part alone. Requiring a title discarded the
+      # one piece of the block that was ours along with the metadata that never
+      # was, and how to render a titleless host is the consumer's call.
       def host_collections
         doc.xpath("/mods:mods/mods:relatedItem[@type='host']", NAMESPACE).filter_map do |node|
-          title = child_text(node, "mods:titleInfo/mods:title")
-          { title: title, **host_part(node) } if title
+          entry = { title: child_text(node, "mods:titleInfo/mods:title"), **host_part(node) }
+          entry if entry.values.any?
         end
       end
 
@@ -349,6 +388,13 @@ module NEU
       # catch-all below does not repeat them.
       NAMED_RELATED_ITEM_TYPES = %w[series host].freeze
 
+      # The part detail types volume and issue already have named keys on a
+      # host entry, so #host_details does not repeat them -- the same split
+      # NAMED_RELATED_ITEM_TYPES makes for relatedItem. A caption is kept
+      # because it is the label a cataloguer wrote for the number ("chap."
+      # before "3"), which no consumer can reconstruct from an open @type.
+      NAMED_HOST_DETAIL_TYPES = %w[volume issue].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.
@@ -429,9 +475,20 @@ module NEU
       # 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.
+      # MODS puts seven date elements under originInfo and this reads all of
+      # them. dateCaptured is when the object was digitised and dateModified is
+      # when the resource changed -- preservation and cataloguing provenance,
+      # which a consumer may keep off a page but cannot recover from anywhere
+      # else. dateValid is the period the content holds for, and dateOther is
+      # where a date fitting no other element lands, which is where a quantity
+      # of migrated v1 date data goes.
       def date_created_parts = date_parts("dateCreated")
       def date_issued_parts = date_parts("dateIssued")
       def copyright_date_parts = date_parts("copyrightDate")
+      def date_captured_parts = date_parts("dateCaptured")
+      def date_valid_parts = date_parts("dateValid")
+      def date_other_parts = date_parts("dateOther")
+      def date_modified_parts = date_parts("dateModified")
 
       def date_created = date_created_parts[:value]
       def date_created_precision = date_created_parts[:precision]
@@ -454,6 +511,34 @@ module NEU
       def copyright_date_qualifier = copyright_date_parts[:qualifier]
       def copyright_date_key_date = copyright_date_parts[:key_date]
 
+      def date_captured = date_captured_parts[:value]
+      def date_captured_precision = date_captured_parts[:precision]
+      def date_captured_end = date_captured_parts[:end_value]
+      def date_captured_end_precision = date_captured_parts[:end_precision]
+      def date_captured_qualifier = date_captured_parts[:qualifier]
+      def date_captured_key_date = date_captured_parts[:key_date]
+
+      def date_valid = date_valid_parts[:value]
+      def date_valid_precision = date_valid_parts[:precision]
+      def date_valid_end = date_valid_parts[:end_value]
+      def date_valid_end_precision = date_valid_parts[:end_precision]
+      def date_valid_qualifier = date_valid_parts[:qualifier]
+      def date_valid_key_date = date_valid_parts[:key_date]
+
+      def date_other = date_other_parts[:value]
+      def date_other_precision = date_other_parts[:precision]
+      def date_other_end = date_other_parts[:end_value]
+      def date_other_end_precision = date_other_parts[:end_precision]
+      def date_other_qualifier = date_other_parts[:qualifier]
+      def date_other_key_date = date_other_parts[:key_date]
+
+      def date_modified = date_modified_parts[:value]
+      def date_modified_precision = date_modified_parts[:precision]
+      def date_modified_end = date_modified_parts[:end_value]
+      def date_modified_end_precision = date_modified_parts[:end_precision]
+      def date_modified_qualifier = date_modified_parts[:qualifier]
+      def date_modified_key_date = date_modified_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.
@@ -506,8 +591,9 @@ module NEU
         edition: :many,
         issuance: :many,
         frequency: :many,
-        # Six rows per originInfo date. Flat rather than one nested value,
-        # because the value half has consumers that need a real date object.
+        # Six rows per originInfo date, for each of the seven MODS defines.
+        # 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,
@@ -526,6 +612,30 @@ module NEU
         copyright_date_end_precision: :one,
         copyright_date_qualifier: :one,
         copyright_date_key_date: :one,
+        date_captured: :one,
+        date_captured_precision: :one,
+        date_captured_end: :one,
+        date_captured_end_precision: :one,
+        date_captured_qualifier: :one,
+        date_captured_key_date: :one,
+        date_valid: :one,
+        date_valid_precision: :one,
+        date_valid_end: :one,
+        date_valid_end_precision: :one,
+        date_valid_qualifier: :one,
+        date_valid_key_date: :one,
+        date_other: :one,
+        date_other_precision: :one,
+        date_other_end: :one,
+        date_other_end_precision: :one,
+        date_other_qualifier: :one,
+        date_other_key_date: :one,
+        date_modified: :one,
+        date_modified_precision: :one,
+        date_modified_end: :one,
+        date_modified_end_precision: :one,
+        date_modified_qualifier: :one,
+        date_modified_key_date: :one,
 
         # physical description
         resource_type: :many,
@@ -621,14 +731,33 @@ module NEU
       # 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.
+      #
+      # ONE DATE PER TYPE is the rule, and a repeated, non-ranged, unflagged
+      # date of the same type is discarded. A range is one date with two ends,
+      # which @point already models, and every consumer of the value -- a sort
+      # key, a citation year, an OAI date -- holds exactly one. Note the
+      # contrast with a repeated publisher, which survives because
+      # publication_information is :many; dates differ because the value is
+      # singular downstream, not because repetition went unnoticed.
       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)
+        date_entry(start_date_node(nodes), finish, nodes)
+      end
+
+      # The node the value comes from: the flagged one, then the declared
+      # start, then document order.
+      #
+      # keyDate leads because the flag is the record nominating its own
+      # principal date. Projecting the flag while reading the value from a
+      # different node made the two contradict each other -- a consumer was told
+      # the record chose this date and then handed the one before it.
+      def start_date_node(nodes)
+        nodes.find { |n| attr_value(n, "keyDate") == "yes" && attr_value(n, "point") != "end" } ||
+          nodes.find { |n| attr_value(n, "point") == "start" } ||
+          nodes.find { |n| attr_value(n, "point") != "end" }
       end
 
       # The end point carries its OWN precision. "1935-06" to "1940" is legal,
@@ -738,6 +867,14 @@ module NEU
       # punctuation of a citation is display policy, the same call #map_data
       # makes for cartographics. MODS leaves @unit optional, so a page extent
       # without one is read rather than dropped.
+      #
+      # Volume, issue and the page range keep named keys because they are the
+      # citation and a consumer asks for them by name. Everything else the
+      # schema allows under part arrives structured, because detail/@type and
+      # extent/@unit are open strings -- a fixed key per type cannot cover a
+      # vocabulary the schema does not close. #date is the article's year within
+      # the host, which after the title is the most-cited element of a journal
+      # citation and was reaching no consumer at all.
       def host_part(node)
         part = node.at_xpath("mods:part", NAMESPACE)
         return {} if part.nil?
@@ -747,8 +884,46 @@ module NEU
           volume: child_text(part, "mods:detail[@type='volume']/mods:number"),
           issue: child_text(part, "mods:detail[@type='issue']/mods:number"),
           start_page: child_text(part, "#{pages}/mods:start"),
-          end_page: child_text(part, "#{pages}/mods:end")
-        }.compact
+          end_page: child_text(part, "#{pages}/mods:end"),
+          date: child_text(part, "mods:date"),
+          text: child_text(part, "mods:text"),
+          details: host_details(part),
+          extents: host_extents(part)
+        }.reject { |_, value| value.nil? || value == [] }
+      end
+
+      def host_details(part)
+        part.xpath("mods:detail", NAMESPACE).filter_map do |node|
+          type = clean(node["type"])
+          next if NAMED_HOST_DETAIL_TYPES.include?(type)
+
+          entry = {
+            type: type,
+            number: child_text(node, "mods:number"),
+            caption: child_text(node, "mods:caption"),
+            title: child_text(node, "mods:title")
+          }
+          entry if entry.except(:type).values.any?
+        end
+      end
+
+      # Every extent EXCEPT the page range, which start_page and end_page hold.
+      # A unit other than page -- the minutes of a recording, the columns of a
+      # newspaper -- means nothing without its unit, so the unit travels with
+      # the numbers rather than being flattened away.
+      def host_extents(part)
+        part.xpath("mods:extent", NAMESPACE).filter_map do |node|
+          unit = clean(node["unit"])
+          next if unit.nil? || unit == "page"
+
+          {
+            unit: unit,
+            start: child_text(node, "mods:start"),
+            end: child_text(node, "mods:end"),
+            total: child_text(node, "mods:total"),
+            list: child_text(node, "mods:list")
+          }
+        end
       end
 
       def text_at(xpath)

data/lib/neu/mods/selectors.rb

@@ -19,6 +19,15 @@ module NEU
       # 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.
+      #
+      # Where a record carries two UNTYPED titleInfo and marks neither, .first
+      # decides and the second reaches no field. That is the schema's answer
+      # rather than a shortfall: @usage is fixed="primary" and exists precisely
+      # to nominate the principal title, @type is a closed enumeration of the
+      # four variants, and MODS 3.5 gives a legitimate second untyped title an
+      # @altRepGroup (one title in two scripts) or an @otherType. An unmarked
+      # duplicate carries none of those, so MODS gives it no meaning to
+      # preserve, and it stays in the preservation XML with no projected field.
       def primary_title_info
         doc.at_xpath("/mods:mods/mods:titleInfo[@usage='primary']", NAMESPACE) ||
           doc.xpath("/mods:mods/mods:titleInfo", NAMESPACE).reject { |ti| variant_title?(ti) }.first

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: neu-mods
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri