neu-mods 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66a8dc19c0e19ccd43f170c117414ddb1df82c3cec889a83c27c6416f778173b
-  data.tar.gz: 445176fc7abc0748d47eddae0ee99137321c743b53a9de3432bb5e45a418ea68
+  metadata.gz: cc4e71fca2d864b7e1d27cba079bf00f30dd6540747845cb37c18e64d88059e5
+  data.tar.gz: 268e50d8ffa81fe8c97760f524d3af8bb9b412fd925721e967db3281c7ffed98
 SHA512:
-  metadata.gz: 1f453251ae9fd5c98737370fcd26e69d85cc8cf615d4e16bf1fd2b0e0f6cb80a23a9b6819fb1f364044161725a9f828c8df3776b760b5b59f24ac0589ed956b3
-  data.tar.gz: 7a04ed96b243039b19457a7df660966f9cd73ec1de92585403fa02a2c0711a80455029d1107cb4d7f3efac9d39b3acf0069bd1ce00031856fff2ce0b350558e6
+  metadata.gz: 19b72bda07149f0e0f7d4797f20fa05866c3296a7612f4f90ac9b0c112d6ef12fef76b61e64f38f98e999102bf479e938a755b62f7dc8594d71a43ad026b5505
+  data.tar.gz: e63764144ec251467950d65a5e58728a7d9941fe85ce53080228453d8baf2e4ecdb2eef300b3af157ced06aad0051db8142b7b29ed3b537b78e95510130dd93d

data/.version

@@ -1 +1 @@
-0.12.0
+0.13.1

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, Episode 1 - How We Respond to Disaster"
+doc.plain_title    # => "What's New. How We Respond to Disaster. Episode 1"
 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
@@ -60,24 +60,55 @@ doc.date_created_parts
                    #    also a reader of its own, e.g.
                    #    doc.date_created_qualifier.
 doc.place_of_publication
-                   # => ["Boston"]   the type="text" placeTerm wins, and a
-                   #    bare marccountry code drops rather than reaching a
-                   #    places facet as a place name. A bare code under any
-                   #    other authority still projects
+                   # => [{ value: "Boston", display_label:, href: }, ...]
+                   #    the type="text" placeTerm wins, and a bare marccountry
+                   #    code drops rather than reaching a places facet as a
+                   #    place name. A bare code under any other authority
+                   #    still projects
+
+# A name entry also carries @usage (fixed="primary" in the schema, so a record
+# that sets it has said which name leads) and :alternative_names, the MODS 3.7
+# alternativeName composed with the ENCLOSING name's @type.
+
+doc.origin_agents  # => [{ name:, roles:, affiliation:, display_label:, href:,
+                   #      event_type: }, ...]
+                   #    originInfo/agent, new in MODS 3.8: who performed the
+                   #    event the block records
+
+# An originInfo child also carries its block's @eventType, and a place carries
+# the NAMES of the date elements beside it (:date_elements) -- "Creation place"
+# and "Publication place" are the same element under a different date, and the
+# place says nothing about the event itself. Each of the seven dates gains
+# <date>_display_label and <date>_event_type from the same block.
+
+# Every DISPLAYED projection carries the @displayLabel and xlink:href of the
+# element its header comes from, as { value:, display_label:, href: } -- or as
+# two extra keys where the entry already had a shape of its own. MODS puts the
+# pair on originInfo and physicalDescription rather than on the publisher,
+# place, extent or digitalOrigin inside them, so those children read it off
+# their parent. The two attribute sets overlap rather than match (26 elements
+# take @displayLabel, 14 take xlink:href); an element the schema gives neither
+# projects nil. The four fields that JOIN several elements into one string --
+# abstract and the three accessCondition fields -- take companion scalars
+# instead (doc.abstract_display_label, doc.abstract_href).
 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.identifiers    # => [{ type: "isbn", value: "...", invalid: false }, ...]
+doc.identifiers    # => [{ type: "isbn", value: "...", invalid: false,
+                   #      display_label:, href: }, ...]
                    #    @invalid means cancelled or superseded, so it travels
 doc.table_of_contents
-                   # => ["Ch 1\nCh 2"]   line breaks kept: in a contents list
+                   # => [{ value: "Ch 1\nCh 2", ... }]
+                   #    line breaks kept: in a contents list
                    #    the break is the structure, not stray formatting
-doc.notes          # => [{ type: "funding", value: "..." }, ...]
-doc.related_items  # => [{ type: "otherFormat", title: "..." }, ...]
+doc.notes          # => [{ type: "funding", value: "...", display_label:, href: }, ...]
+doc.related_items  # => [{ type: "otherFormat", title: "...",
+                   #      display_label:, href: }, ...]
                    #    every relatedItem that is not a series or a host
-doc.location       # => [{ physical_location:, shelf_location:, url: }, ...]
+doc.location       # => [{ physical_location:, shelf_location:, url:,
+                   #      display_label:, href: }, ...]
 doc.map_data       # => [{ scale:, projection:, coordinates: }, ...]
 doc.title_subjects # => ["The Great Gatsby"]   composed like the main title
 doc.hierarchical_geographic_subjects
@@ -98,7 +129,7 @@ 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, Episode 1 - How We Respond to Disaster"   (== doc.plain_title)
+# => "What's New. How We Respond to Disaster. Episode 1"   (== 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.
 

data/lib/neu/mods/projection.rb

@@ -53,17 +53,24 @@ module NEU
       # :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.
+      # nonSort, title, subtitle, partName, partNumber -- the order the
+      # librarians chose. titleInfo is an unordered choice in the schema, so no
+      # document order is available to follow and the composer has to fix one.
+      #
+      # A period separates the title or subtitle from the parts, and one part
+      # from the next. The separator travels with its part rather than with the
+      # position, so a record giving only a partNumber still gets the period.
+      # Nothing is appended after the last part: a title is a value, not a
+      # sentence, and a trailing period reads as part of the title everywhere
+      # the value is re-used.
+      TITLE_SEPARATORS = [[": ", :subtitle], [". ", :part_name], [". ", :part_number]].freeze
+
       def self.compose_title(parts)
         return "" if parts[:title].to_s.strip.empty?
 
-        optional = { ": " => parts[:subtitle], ", " => parts[:part_number], " - " => parts[:part_name] }
-        suffix = optional.filter_map { |sep, val| "#{sep}#{val}" unless val.to_s.strip.empty? }.join
+        suffix = TITLE_SEPARATORS.filter_map do |separator, key|
+          "#{separator}#{parts[key]}" unless parts[key].to_s.strip.empty?
+        end.join
         "#{join_non_sort(parts[:non_sort], parts[:title])}#{suffix}"
       end
 
@@ -98,6 +105,13 @@ module NEU
         join_paragraphs(abstract_nodes)
       end
 
+      # The header and the link a record attached to its abstract. Companion
+      # scalars rather than an entry, because #abstract joins every abstract
+      # element into one value and three consumers -- the OAI dc:description,
+      # the citation and description_tsim -- hold that value as a string.
+      def abstract_display_label = first_attr(abstract_nodes, "displayLabel")
+      def abstract_href = first_href(abstract_nodes)
+
       # 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
@@ -113,6 +127,24 @@ module NEU
       def use_and_reproduction = access_conditions_of_type("use and reproduction")
       def restriction_on_access = access_conditions_of_type("restriction on access")
 
+      # Companion scalars for the same reason the abstract's are: each of the
+      # three fields joins several elements into one value, and a licence URI
+      # belongs beside the licence text a reader is given.
+      def access_condition_display_label = first_attr(access_condition_nodes, "displayLabel")
+      def access_condition_href = first_href(access_condition_nodes)
+
+      def use_and_reproduction_display_label
+        first_attr(access_condition_nodes("use and reproduction"), "displayLabel")
+      end
+
+      def use_and_reproduction_href = first_href(access_condition_nodes("use and reproduction"))
+
+      def restriction_on_access_display_label
+        first_attr(access_condition_nodes("restriction on access"), "displayLabel")
+      end
+
+      def restriction_on_access_href = first_href(access_condition_nodes("restriction on access"))
+
       # An open-string @type reduced to its letters and digits, so casing, word
       # separators and camelCasing cannot decide whether a field matches.
       def self.fold_type(str)
@@ -124,7 +156,7 @@ module NEU
       # The editable free-text keyword set (Cerberus simple form): topics under the
       # attribute-free keyword subjects only.
       def keywords
-        keyword_subjects.flat_map { |s| s.xpath("mods:topic", NAMESPACE).map { |t| t.text.strip } }
+        keyword_subjects.flat_map { |s| texts_under(s, "mods:topic") }
       end
 
       # Neither child carries heading text: cartographics is a structured
@@ -143,7 +175,7 @@ module NEU
       def subject_headings
         doc.xpath("/mods:mods/mods:subject", NAMESPACE).filter_map do |node|
           parts = subject_heading_parts(node)
-          { parts: parts } unless parts.empty?
+          { parts: parts, **qualifiers_of(node) } unless parts.empty?
         end
       end
 
@@ -208,10 +240,28 @@ module NEU
         {
           name: name_display_value_w_date(node),
           roles: name_roles(node),
-          affiliation: texts_under(node, "mods:affiliation")
+          affiliation: texts_under(node, "mods:affiliation"),
+          # @usage is fixed="primary" in the schema and exists to nominate the
+          # principal name. A record that sets it has said which name leads,
+          # and without it a consumer grouping role-less names can only guess.
+          usage: attr_value(node, "usage"),
+          alternative_names: alternative_names(node),
+          **qualifiers_of(node)
         }
       end
 
+      # mods:alternativeName, new in MODS 3.7: a second form of the same name,
+      # not a second name. Composed with the ENCLOSING name's @type, because
+      # alternativeName carries @altType rather than @type and an alternative
+      # for a personal name is still a personal name -- read from its own
+      # attributes it would compose "Doe Jane" where the name above it
+      # composes "Doe, Jane".
+      def alternative_names(node)
+        node.xpath("mods:alternativeName", NAMESPACE).filter_map do |alt|
+          name_display_value_w_date(alt, attr_value(node, "type"))
+        end
+      end
+
       # All top-level names as { name:, roles: }. `name` reproduces the `mods` gem's
       # display_value_w_date (including its quirks -- faithfully, so existing Solr/
       # display output is preserved). MODS repeats `role` on one name, and a
@@ -273,26 +323,39 @@ module NEU
           term = language_term(lang)
           next unless term
 
-          { term: term, object_part: attr_value(lang, "objectPart"), script: script_term(lang) }
+          { term: term, object_part: attr_value(lang, "objectPart"), script: script_term(lang),
+            **qualifiers_of(lang) }
         end
       end
 
       # 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 resource_type = labeled_texts_at("/mods:mods/mods:typeOfResource")
+
+      # MODS puts @displayLabel on physicalDescription, not on the form, extent,
+      # digitalOrigin, reformattingQuality or note inside it -- so these four
+      # take the label off their parent. `from: ".."` says which element the
+      # header comes from; the value still comes from the element itself.
+      def format = labeled_texts_at("/mods:mods/mods:physicalDescription/mods:form", from: "..")
+      def extent = labeled_texts_at("/mods:mods/mods:physicalDescription/mods:extent", from: "..")
+      def digital_origin = labeled_texts_at("/mods:mods/mods:physicalDescription/mods:digitalOrigin", from: "..")
+
+      def genres = labeled_texts_at("/mods:mods/mods:genre")
 
-      def genres = texts_at("/mods:mods/mods:genre")
+      # Who the resource is for. The last displayed top-level element with no
+      # projection at all: a record naming its audience said so to nobody.
+      def target_audience = labeled_texts_at("/mods:mods/mods:targetAudience")
 
       # 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")
+      # @displayLabel and @eventType sit on originInfo, not on the publisher,
+      # place, edition, issuance or frequency inside it, so each of these takes
+      # its header off the parent block.
+      def publication_information = origin_texts_at("mods:publisher")
+      def edition = origin_texts_at("mods:edition")
 
       # Prefer the type="text" term per place, falling back to a coded one --
       # the pattern #role_term_value and #languages already use.
@@ -311,23 +374,43 @@ module NEU
 
       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
+          value = place_term_value(place)
+          next unless value
 
-          code = place.at_xpath("mods:placeTerm", NAMESPACE)
-          next if attr_value(code, "authority") == MARC_COUNTRY_AUTHORITY
+          { value: value, **origin_qualifiers_of(place.parent),
+            date_elements: origin_date_elements(place.parent) }
+        end
+      end
 
-          clean(code&.text)
+      # originInfo/agent, new in MODS 3.8: who performed the event the block
+      # records. Read through the same port as a top-level name, so a publisher
+      # recorded as an agent composes the way a creator does and carries its
+      # roles -- which is what a consumer heads the row with when the block
+      # states no displayLabel or eventType.
+      def origin_agents
+        doc.xpath("/mods:mods/mods:originInfo/mods:agent", NAMESPACE).filter_map do |node|
+          entry = name_entry(node)
+          entry.merge(event_type: attr_value(node.parent, "eventType")) if entry[:name]
         end
       end
 
-      def issuance = texts_at("/mods:mods/mods:originInfo/mods:issuance")
+      def place_term_value(place)
+        text = clean(place.at_xpath("mods:placeTerm[@type='text']", NAMESPACE)&.text)
+        return text if text
+
+        code = place.at_xpath("mods:placeTerm", NAMESPACE)
+        return nil if attr_value(code, "authority") == MARC_COUNTRY_AUTHORITY
+
+        clean(code&.text)
+      end
+
+      def issuance = origin_texts_at("mods:issuance")
 
       # Serials. The @authority a record puts on a frequency is not projected:
       # authority handling is a question the gem defers everywhere else -- for
       # genre, subject and name -- and answering it for one field would be
       # inconsistent.
-      def frequency = texts_at("/mods:mods/mods:originInfo/mods:frequency")
+      def frequency = origin_texts_at("mods:frequency")
 
       # Read with its line breaks intact. A legacy contents list separates its
       # entries by newline, and the whitespace collapse every other field wants
@@ -336,24 +419,26 @@ module NEU
       def table_of_contents
         doc.xpath("/mods:mods/mods:tableOfContents", NAMESPACE).filter_map do |node|
           lines = NEU::MODS.canonical_lines(node.text)
-          lines unless lines.empty?
+          labeled(lines, node) unless lines.empty?
         end
       end
 
-      def reformatting_quality = texts_at("/mods:mods/mods:physicalDescription/mods:reformattingQuality")
+      def reformatting_quality
+        labeled_texts_at("/mods:mods/mods:physicalDescription/mods:reformattingQuality", from: "..")
+      end
 
       # A note about the object rather than about the work -- "Scanned at 600
       # dpi" belongs beside the extent, not beside a content note. Projected as
       # plain strings like its physicalDescription siblings: #notes keeps @type
       # because the type changes what a top-level note means, and nothing here
       # turns on it.
-      def physical_description_notes = texts_at("/mods:mods/mods:physicalDescription/mods:note")
+      def physical_description_notes = labeled_texts_at("/mods:mods/mods:physicalDescription/mods:note", from: "..")
 
       # An LCC or DDC call number. Note this is NOT the same concept as Atlas's
       # classification_ssim, which carries a FileSet content-type vocabulary --
       # the name collision is accidental and the consumer has to pick a free
       # Solr field.
-      def classification = texts_at("/mods:mods/mods:classification")
+      def classification = labeled_texts_at("/mods:mods/mods:classification")
 
       # Every top-level note, keeping its @type. The type carries meaning -- a
       # "statement of responsibility" is not a "funding" note -- so flattening
@@ -361,7 +446,7 @@ module NEU
       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
+          { type: clean(node["type"]), value: value, **qualifiers_of(node) } if value
         end
       end
 
@@ -379,7 +464,7 @@ module NEU
             shelf_location: child_text(node, "mods:shelfLocator"),
             url: child_text(node, "mods:url")
           }
-          entry if entry.values.any?
+          entry.merge(qualifiers_of(node)) if entry.values.any?
         end
       end
 
@@ -394,7 +479,8 @@ module NEU
             projection: child_text(node, "mods:projection"),
             coordinates: child_text(node, "mods:coordinates")
           }
-          entry if entry.values.any?
+          # cartographics carries neither attribute; the enclosing subject does.
+          entry.merge(qualifiers_of(node.parent)) if entry.values.any?
         end
       end
 
@@ -412,7 +498,7 @@ module NEU
       def host_collections
         doc.xpath("/mods:mods/mods:relatedItem[@type='host']", NAMESPACE).filter_map do |node|
           entry = { title: child_text(node, "mods:titleInfo/mods:title"), **host_part(node) }
-          entry if entry.values.any?
+          entry.merge(qualifiers_of(node)) if entry.values.any?
         end
       end
 
@@ -439,7 +525,7 @@ module NEU
           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
+          { type: type, title: title, **qualifiers_of(node) } if title
         end
       end
 
@@ -455,7 +541,10 @@ module NEU
       def identifiers
         doc.xpath("/mods:mods/mods:identifier", NAMESPACE).filter_map do |node|
           value = clean(node.text)
-          { type: clean(node["type"]), value: value, invalid: attr_value(node, "invalid") == "yes" } if value
+          if value
+            { type: clean(node["type"]), value: value, invalid: attr_value(node, "invalid") == "yes",
+              **qualifiers_of(node) }
+          end
         end
       end
 
@@ -464,6 +553,14 @@ module NEU
         node && clean(node.text)
       end
 
+      # The handle identifier carries @displayLabel="Permanent URL" in Atlas's
+      # own MODS template, so the header a reader sees is one the record states
+      # rather than one a decorator invents. No href companion: the value is the
+      # URL.
+      def permanent_url_display_label
+        attr_value(doc.at_xpath("/mods:mods/mods:identifier[@type='hdl']", NAMESPACE), "displayLabel")
+      end
+
       # The eleven children the XSD allows under hierarchicalGeographic, in the
       # order MODS lists them -- broadest first, which is also the order a
       # consumer composing a place string wants to reverse.
@@ -497,10 +594,22 @@ module NEU
       # wrote survives in the matching *_text field instead.
       W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2})(T\S+)?)?)?\z/
 
+      # ISO 8601 basic format: the same year, month and day written without the
+      # hyphens. Accepted ONLY where the record declares @encoding="iso8601",
+      # because eight bare digits are a date only because the encoding says so
+      # -- an accession number is eight digits too, and guessing is the mistake
+      # dropping the DateTime.parse fallback exists to prevent.
+      ISO8601_BASIC_DATE = /\A(\d{4})(?:(\d{2})(?:(\d{2})(T\S+)?)?)?\z/
+
+      # @encoding, folded. MODS leaves the attribute an open string and records
+      # write "iso8601" and "ISO-8601" alike.
+      ISO8601_ENCODING = "iso8601"
+
       # 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, text: nil }.freeze
+                     qualifier: nil, key_date: nil, text: nil,
+                     display_label: nil, event_type: nil }.freeze
 
       # Everything a record declared about one originInfo date, as
       # { value:, precision:, end_value:, end_precision:, qualifier:, key_date:,
@@ -527,6 +636,11 @@ module NEU
       # 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.
+      # The seven date elements MODS puts under originInfo, in the order a
+      # consumer deciding a place header reads them.
+      DATE_ELEMENTS = %w[dateIssued dateCreated copyrightDate dateCaptured
+                         dateValid dateOther dateModified].freeze
+
       def date_created_parts = date_parts("dateCreated")
       def date_issued_parts = date_parts("dateIssued")
       def copyright_date_parts = date_parts("copyrightDate")
@@ -542,6 +656,8 @@ module NEU
       def date_created_qualifier = date_created_parts[:qualifier]
       def date_created_key_date = date_created_parts[:key_date]
       def date_created_text = date_created_parts[:text]
+      def date_created_display_label = date_created_parts[:display_label]
+      def date_created_event_type = date_created_parts[:event_type]
 
       def date_issued = date_issued_parts[:value]
       def date_issued_precision = date_issued_parts[:precision]
@@ -550,6 +666,8 @@ module NEU
       def date_issued_qualifier = date_issued_parts[:qualifier]
       def date_issued_key_date = date_issued_parts[:key_date]
       def date_issued_text = date_issued_parts[:text]
+      def date_issued_display_label = date_issued_parts[:display_label]
+      def date_issued_event_type = date_issued_parts[:event_type]
 
       def copyright_date = copyright_date_parts[:value]
       def copyright_date_precision = copyright_date_parts[:precision]
@@ -558,6 +676,8 @@ module NEU
       def copyright_date_qualifier = copyright_date_parts[:qualifier]
       def copyright_date_key_date = copyright_date_parts[:key_date]
       def copyright_date_text = copyright_date_parts[:text]
+      def copyright_date_display_label = copyright_date_parts[:display_label]
+      def copyright_date_event_type = copyright_date_parts[:event_type]
 
       def date_captured = date_captured_parts[:value]
       def date_captured_precision = date_captured_parts[:precision]
@@ -566,6 +686,8 @@ module NEU
       def date_captured_qualifier = date_captured_parts[:qualifier]
       def date_captured_key_date = date_captured_parts[:key_date]
       def date_captured_text = date_captured_parts[:text]
+      def date_captured_display_label = date_captured_parts[:display_label]
+      def date_captured_event_type = date_captured_parts[:event_type]
 
       def date_valid = date_valid_parts[:value]
       def date_valid_precision = date_valid_parts[:precision]
@@ -574,6 +696,8 @@ module NEU
       def date_valid_qualifier = date_valid_parts[:qualifier]
       def date_valid_key_date = date_valid_parts[:key_date]
       def date_valid_text = date_valid_parts[:text]
+      def date_valid_display_label = date_valid_parts[:display_label]
+      def date_valid_event_type = date_valid_parts[:event_type]
 
       def date_other = date_other_parts[:value]
       def date_other_precision = date_other_parts[:precision]
@@ -582,6 +706,8 @@ module NEU
       def date_other_qualifier = date_other_parts[:qualifier]
       def date_other_key_date = date_other_parts[:key_date]
       def date_other_text = date_other_parts[:text]
+      def date_other_display_label = date_other_parts[:display_label]
+      def date_other_event_type = date_other_parts[:event_type]
 
       def date_modified = date_modified_parts[:value]
       def date_modified_precision = date_modified_parts[:precision]
@@ -590,6 +716,8 @@ module NEU
       def date_modified_qualifier = date_modified_parts[:qualifier]
       def date_modified_key_date = date_modified_parts[:key_date]
       def date_modified_text = date_modified_parts[:text]
+      def date_modified_display_label = date_modified_parts[:display_label]
+      def date_modified_event_type = date_modified_parts[:event_type]
 
       # The [value, precision] pair the precision work introduced. Retained
       # because it is the documented entry point for a caller that wants both
@@ -628,6 +756,7 @@ module NEU
       FIELDS = {
         # titles
         main_title: :one,
+        main_title_display_label: :one,
         alternative_title: :many,
         uniform_title: :many,
         translated_title: :many,
@@ -636,10 +765,13 @@ module NEU
         names: :many,
         languages: :many,
         abstract: :one,
+        abstract_display_label: :one,
+        abstract_href: :one,
 
         # origin
         publication_information: :many,
         place_of_publication: :many,
+        origin_agents: :many,
         edition: :many,
         issuance: :many,
         frequency: :many,
@@ -653,6 +785,8 @@ module NEU
         date_created_qualifier: :one,
         date_created_key_date: :one,
         date_created_text: :one,
+        date_created_display_label: :one,
+        date_created_event_type: :one,
         date_issued: :one,
         date_issued_precision: :one,
         date_issued_end: :one,
@@ -660,6 +794,8 @@ module NEU
         date_issued_qualifier: :one,
         date_issued_key_date: :one,
         date_issued_text: :one,
+        date_issued_display_label: :one,
+        date_issued_event_type: :one,
         copyright_date: :one,
         copyright_date_precision: :one,
         copyright_date_end: :one,
@@ -667,6 +803,8 @@ module NEU
         copyright_date_qualifier: :one,
         copyright_date_key_date: :one,
         copyright_date_text: :one,
+        copyright_date_display_label: :one,
+        copyright_date_event_type: :one,
         date_captured: :one,
         date_captured_precision: :one,
         date_captured_end: :one,
@@ -674,6 +812,8 @@ module NEU
         date_captured_qualifier: :one,
         date_captured_key_date: :one,
         date_captured_text: :one,
+        date_captured_display_label: :one,
+        date_captured_event_type: :one,
         date_valid: :one,
         date_valid_precision: :one,
         date_valid_end: :one,
@@ -681,6 +821,8 @@ module NEU
         date_valid_qualifier: :one,
         date_valid_key_date: :one,
         date_valid_text: :one,
+        date_valid_display_label: :one,
+        date_valid_event_type: :one,
         date_other: :one,
         date_other_precision: :one,
         date_other_end: :one,
@@ -688,6 +830,8 @@ module NEU
         date_other_qualifier: :one,
         date_other_key_date: :one,
         date_other_text: :one,
+        date_other_display_label: :one,
+        date_other_event_type: :one,
         date_modified: :one,
         date_modified_precision: :one,
         date_modified_end: :one,
@@ -695,9 +839,12 @@ module NEU
         date_modified_qualifier: :one,
         date_modified_key_date: :one,
         date_modified_text: :one,
+        date_modified_display_label: :one,
+        date_modified_event_type: :one,
 
         # physical description
         resource_type: :many,
+        target_audience: :many,
         genres: :many,
         format: :many,
         extent: :many,
@@ -730,13 +877,20 @@ module NEU
         identifiers: :many,
         classification: :many,
         permanent_url: :one,
+        permanent_url_display_label: :one,
         record_info: :one,
         location: :many,
 
         # access
         access_condition: :one,
+        access_condition_display_label: :one,
+        access_condition_href: :one,
         use_and_reproduction: :one,
-        restriction_on_access: :one
+        use_and_reproduction_display_label: :one,
+        use_and_reproduction_href: :one,
+        restriction_on_access: :one,
+        restriction_on_access_display_label: :one,
+        restriction_on_access_href: :one
       }.freeze
 
       # The complete read projection, keyed to Atlas's Metadata::MODS attribute
@@ -763,31 +917,49 @@ module NEU
       # returns. Kept as an alias rather than a rename so both read well.
       def main_title = access_title_parts
 
+      # What the record wants the title row headed, which is almost never set --
+      # but a record that does set it means it, and "Title" is the one header a
+      # display would otherwise never let a curator change.
+      def main_title_display_label = attr_value(primary_title_info, "displayLabel")
+
       private
 
       # --- helpers -------------------------------------------------------------
 
-      # [DateTime, precision] for a w3cdtf date, or nil for a string that is not
-      # one. A shape-matched but impossible date (2026-13, 2026-02-30) reaches
-      # DateTime, raises, and is nil like any other unreadable value; the caller
-      # keeps its literal text.
+      # [DateTime, precision] for a string matching one date shape, or nil for a
+      # string that matches none. A shape-matched but impossible date (2026-13,
+      # 2026-02-30) reaches DateTime, raises, and is nil like any other
+      # unreadable value; the caller keeps its literal text.
       #
       # A full timestamp goes through DateTime.parse rather than being rebuilt,
       # so the time of day a dateModified declares survives. Its precision is
       # "day" because that is the finest granularity a consumer renders.
-      def parse_w3cdtf(str)
-        m = W3CDTF_DATE.match(str)
+      def parse_shaped_date(regexp, str)
+        m = regexp.match(str)
         return nil unless m
         return [DateTime.parse(str), "day"] if m[4]
 
-        [DateTime.new(m[1].to_i, (m[2] || 1).to_i, (m[3] || 1).to_i), w3cdtf_precision(m)]
+        [DateTime.new(m[1].to_i, (m[2] || 1).to_i, (m[3] || 1).to_i), declared_precision(m)]
       rescue Date::Error
         nil
       end
 
+      # [DateTime, precision], reading the shape the record's own @encoding
+      # declares. w3cdtf is tried first and unconditionally, because it is what
+      # the corpus and Atlas's own MODS template write; the basic ISO form is
+      # tried only for a record that asked for it.
+      def parse_declared_date(str, encoding)
+        parse_shaped_date(W3CDTF_DATE, str) ||
+          (iso8601?(encoding) ? parse_shaped_date(ISO8601_BASIC_DATE, str) : nil)
+      end
+
+      def iso8601?(encoding)
+        encoding.to_s.downcase.delete("-") == ISO8601_ENCODING
+      end
+
       # The granularity the record stopped at, which is the whole point of
       # matching the shape rather than widening the parse.
-      def w3cdtf_precision(match)
+      def declared_precision(match)
         return "day" if match[3]
 
         match[2] ? "month" : "year"
@@ -837,6 +1009,7 @@ module NEU
       def date_entry(start, finish, nodes)
         value, precision, text = node_date(start)
         end_value, end_precision = node_date(finish)
+        origin = (start || finish)&.parent
         {
           value: value,
           precision: precision,
@@ -844,7 +1017,12 @@ module NEU
           end_precision: end_precision,
           qualifier: attr_value(start, "qualifier") || attr_value(finish, "qualifier"),
           key_date: nodes.any? { |n| attr_value(n, "keyDate") == "yes" },
-          text: text
+          text: text,
+          # Off the enclosing originInfo, because that is where MODS puts both.
+          # A date row is headed by its element ("Date created"), and these are
+          # the two things a record can say to override that.
+          display_label: attr_value(origin, "displayLabel"),
+          event_type: attr_value(origin, "eventType")
         }
       end
 
@@ -861,7 +1039,7 @@ module NEU
         str = NEU::MODS.canonical_ws(node.text)
         return [nil, nil, nil] if str.empty?
 
-        parsed = parse_w3cdtf(str)
+        parsed = parse_declared_date(str, attr_value(node, "encoding"))
         return [parsed[0], parsed[1], nil] if parsed
 
         [nil, nil, str]
@@ -874,6 +1052,108 @@ module NEU
         value.empty? ? nil : value
       end
 
+      # The two attributes a display reads off an element rather than out of its
+      # text: the header the record asked for, and the link the record attached.
+      # They travel together as one pair rather than as two parallel
+      # projections a consumer has to zip.
+      #
+      # The two sets overlap rather than match. MODS 3.8 puts @displayLabel on
+      # 26 elements and xlink:href on 14 -- titleInfo, name, alternativeName,
+      # agent, subject, abstract, tableOfContents, note, relatedItem,
+      # accessCondition, physicalLocation and three more. Reading both off
+      # every element costs nothing: an element the schema does not let carry
+      # one simply projects nil for it, and a consumer asking the pair of any
+      # entry does not have to hold the two lists.
+      #
+      # An href with no text displays nothing. Every caller drops a value-less
+      # element already, which is also what the librarians asked for: a link
+      # needs something to hang on.
+      def qualifiers_of(node)
+        { display_label: attr_value(node, "displayLabel"), href: xlink_href(node) }
+      end
+
+      # xlink:href by namespace rather than by prefix. A document is free to
+      # bind the XLink namespace to any prefix, or to none, and node["xlink:href"]
+      # matches the literal prefix alone.
+      def xlink_href(node)
+        return nil unless node
+
+        attribute = node.attribute_with_ns("href", XLINK_NAMESPACE)
+        attribute && clean(attribute.value)
+      end
+
+      # A displayed value plus the qualifiers of the element a display takes its
+      # header from. That is not always the element holding the text: MODS puts
+      # @displayLabel on originInfo and physicalDescription, never on the
+      # publisher, place, extent or digitalOrigin inside them.
+      def labeled(value, label_node)
+        { value: value, **qualifiers_of(label_node) }
+      end
+
+      # The qualifiers of an originInfo block. @eventType says what the block
+      # records -- a publication, a production, a distribution -- and the
+      # librarians asked that its value head the block when no displayLabel
+      # does. MODS puts it on originInfo alone, so it is not part of the
+      # general pair.
+      def origin_qualifiers_of(node)
+        qualifiers_of(node).merge(event_type: attr_value(node, "eventType"))
+      end
+
+      # An originInfo child, carrying the block's header attributes. `xpath` is
+      # relative to the originInfo, which is the element the qualifiers come
+      # from -- MODS puts neither attribute on the children.
+      def origin_texts_at(xpath)
+        doc.xpath("/mods:mods/mods:originInfo", NAMESPACE).flat_map do |origin|
+          origin.xpath(xpath, NAMESPACE).filter_map do |node|
+            value = clean(node.text)
+            { value: value, **origin_qualifiers_of(origin) } if value
+          end
+        end
+      end
+
+      # The date elements the enclosing originInfo carries. A place is headed
+      # "Creation place" or "Publication place" depending on which date sits
+      # beside it, and the place element itself says nothing about the event.
+      # Which dates are present is data; the header text is display policy and
+      # stays with the consumer.
+      def origin_date_elements(origin)
+        return [] unless origin
+
+        DATE_ELEMENTS.select { |name| origin.at_xpath("mods:#{name}", NAMESPACE) }
+      end
+
+      # #texts_at, with each value carrying the qualifiers of its element.
+      # `from:` is an XPath relative to the text-bearing node, naming the
+      # ancestor the header comes from instead.
+      def labeled_texts_at(xpath, from: nil)
+        doc.xpath(xpath, NAMESPACE).filter_map do |node|
+          value = clean(node.text)
+          labeled(value, from ? node.at_xpath(from, NAMESPACE) : node) if value
+        end
+      end
+
+      # The first of a node set to state the attribute. A field joining several
+      # elements into one value has one header, and a record that labels only
+      # its second abstract still meant the label.
+      def first_attr(nodes, name)
+        nodes.filter_map { |node| attr_value(node, name) }.first
+      end
+
+      def first_href(nodes)
+        nodes.filter_map { |node| xlink_href(node) }.first
+      end
+
+      # Every top-level accessCondition, or those of one folded @type. Shared by
+      # the joined text projections and by the qualifier companions, so a header
+      # cannot come from a different element than the value it heads.
+      def access_condition_nodes(type = nil)
+        nodes = doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE)
+        return nodes if type.nil?
+
+        wanted = Projection.fold_type(type)
+        nodes.select { |node| Projection.fold_type(node["type"]) == wanted }
+      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)
@@ -899,7 +1179,8 @@ module NEU
       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))
+          value = clean(Projection.compose_title(parts))
+          labeled(value, node) if value
         end
       end
 
@@ -936,7 +1217,7 @@ module NEU
       end
 
       def related_item_titles(type)
-        texts_at("/mods:mods/mods:relatedItem[@type='#{type}']/mods:titleInfo/mods:title")
+        labeled_texts_at("/mods:mods/mods:relatedItem[@type='#{type}']/mods:titleInfo/mods:title", from: "../..")
       end
 
       # Kept in parts rather than composed into "24(3), pp. 210-218". The
@@ -1084,10 +1365,7 @@ module NEU
       # A genuinely unrecognised type still falls through, which is what
       # #access_condition is for.
       def access_conditions_of_type(type)
-        wanted = Projection.fold_type(type)
-        nodes = doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE)
-                   .select { |node| Projection.fold_type(node["type"]) == wanted }
-        join_paragraphs(nodes)
+        join_paragraphs(access_condition_nodes(type))
       end
 
       def join_paragraphs(nodes)
@@ -1096,25 +1374,26 @@ module NEU
 
       # --- name display (faithful port of mods gem display_value_w_date) -------
 
-      def name_display_value_w_date(node)
-        dv = name_display_value(node)
+      # Every namePart is read through #part_text, so the separators this method
+      # composes are the only whitespace in the result. Read raw, an indented
+      # `<namePart>\n  Doe\n</namePart>` -- what a pretty-printer writes and what
+      # a curator pasting from a form leaves behind -- composed as "Doe ,  John",
+      # and the outer strip could not reach the spaces around the comma.
+      def name_display_value_w_date(node, type = attr_value(node, "type"))
+        dv = name_display_value(node, type)
         node.xpath("mods:namePart[@type='date']", NAMESPACE).each do |np|
-          d = np.text
+          d = part_text(np)
           dv += ", #{d}" unless d.empty? || dv.end_with?(d)
         end
         dv = dv.sub(/\A, /, "")
         dv.strip.empty? ? nil : dv.strip
       end
 
-      def name_display_value(node)
-        display_form = node.at_xpath("mods:displayForm", NAMESPACE)
-        return display_form.text if display_form && !display_form.text.empty?
+      def name_display_value(node, type)
+        display_form = part_text(node.at_xpath("mods:displayForm", NAMESPACE))
+        return display_form unless display_form.empty?
 
-        if node["type"] == "personal"
-          personal_display_value(node)
-        else
-          non_date_parts_joined(node)
-        end
+        type == "personal" ? personal_display_value(node) : non_date_parts_joined(node)
       end
 
       def personal_display_value(node)
@@ -1135,9 +1414,10 @@ module NEU
       def append_terms_of_address(node, dv)
         first = true
         node.xpath("mods:namePart[@type='termsOfAddress']", NAMESPACE).each do |np|
-          next if np.text.empty?
+          term = part_text(np)
+          next if term.empty?
 
-          dv += first ? " #{np.text}" : ", #{np.text}"
+          dv += first ? " #{term}" : ", #{term}"
           first = false
         end
         dv
@@ -1147,13 +1427,23 @@ module NEU
       # NodeSet#text (no separator) -- e.g. two `given` parts become "A.(B)". We
       # reproduce that (quirk included) to stay behavior-preserving.
       def joined_parts(node, type)
-        node.xpath("mods:namePart[@type='#{type}']", NAMESPACE).map(&:text).join
+        node.xpath("mods:namePart[@type='#{type}']", NAMESPACE).map { |np| part_text(np) }.join
       end
 
       def non_date_parts_joined(node)
         node.xpath("mods:namePart", NAMESPACE)
-            .reject { |np| np["type"] == "date" || np.text.empty? }
-            .map(&:text).join(" ")
+            .reject { |np| np["type"] == "date" }
+            .map { |np| part_text(np) }
+            .reject(&:empty?)
+            .join(" ")
+      end
+
+      # One name element's text, whitespace-canonicalized, "" when absent. The
+      # name composition joins its parts with separators of its own, so a part
+      # has to arrive without the insignificant whitespace an XML document is
+      # free to carry around element content.
+      def part_text(node)
+        node ? NEU::MODS.canonical_ws(node.text) : ""
       end
 
       def name_roles(node)
@@ -1170,9 +1460,8 @@ module NEU
       # (NOT MARC-relator-translated -- see README). nil if neither is present.
       def role_term_value(role)
         %w[text code].each do |type|
-          term = role.at_xpath("mods:roleTerm[@type='#{type}']", NAMESPACE)
-          text = term&.text.to_s.strip
-          return text unless text.empty?
+          term = part_text(role.at_xpath("mods:roleTerm[@type='#{type}']", NAMESPACE))
+          return term unless term.empty?
         end
         nil
       end

data/lib/neu-mods.rb

@@ -25,6 +25,11 @@ module NEU
     # The MODS v3 namespace, as a Nokogiri xpath namespace hash.
     NAMESPACE = { "mods" => "http://www.loc.gov/mods/v3" }.freeze
 
+    # XLink, which MODS uses for the @xlink:href a display hyperlinks an element
+    # to. Held as a bare URI rather than a prefix map because the attribute is
+    # read by namespace: a document may bind XLink to any prefix it likes.
+    XLINK_NAMESPACE = "http://www.w3.org/1999/xlink"
+
     # 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

metadata

@@ -1,55 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: neu-mods
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.1
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.13'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.13'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.60'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.60'
 description: 'Nokogiri-native, dependency-light reading/projection contract over MODS
@@ -62,7 +62,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .version
+- ".version"
 - Gemfile
 - README.md
 - Rakefile
@@ -85,16 +85,16 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.9
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Northeastern-flavored MODS XML projection + selection for the DRS.