neu-mods 0.14.0 → 0.14.1

data/lib/neu/mods/namespaces.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module NEU
+  module MODS
+    # 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"
+  end
+end

data/lib/neu/mods/projection/access.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "../canonicalize"
+require_relative "../selectors"
+require_relative "support"
+
+module NEU
+  module MODS
+    module Projection
+      # The abstract and the access conditions, each joined into one value with
+      # its header and link as companion scalars. See docs/other-fields.md.
+      module Access
+        include Support
+        include Selectors
+
+        def abstract
+          join_paragraphs(abstract_nodes)
+        end
+
+        # Companion scalars, because #abstract joins every element into one string.
+        def abstract_display_label = first_attr(abstract_nodes, "displayLabel")
+        def abstract_href = first_href(abstract_nodes)
+
+        # Every accessCondition, whatever its type. The only field that carries an
+        # untyped or unrecognised one.
+        def access_condition
+          join_paragraphs(doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE))
+        end
+
+        # Kept apart so a restriction is never shown to a reader as a licence.
+        def use_and_reproduction = access_conditions_of_type("use and reproduction")
+        def restriction_on_access = access_conditions_of_type("restriction on access")
+
+        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"))
+
+        # Letters and digits only, lower-cased: records write @type in any casing.
+        def self.fold_type(str)
+          Canonicalize.canonical_ws(str).downcase.gsub(/[^a-z0-9]/, "")
+        end
+
+        private
+
+        # Shared by the text and its companions, so a header always comes from
+        # the elements the value does.
+        def access_condition_nodes(type = nil)
+          nodes = doc.xpath("/mods:mods/mods:accessCondition", NAMESPACE)
+          return nodes if type.nil?
+
+          wanted = Access.fold_type(type)
+          nodes.select { |node| Access.fold_type(node["type"]) == wanted }
+        end
+
+        # Matched on the folded @type, not in the XPath, because @type is open.
+        def access_conditions_of_type(type)
+          join_paragraphs(access_condition_nodes(type))
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/dates.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../namespaces"
+require_relative "../canonicalize"
+require_relative "support"
+
+module NEU
+  module MODS
+    module Projection
+      # The seven originInfo date elements, each projected as nine flat fields.
+      # See docs/dates.md, which lists every generated field.
+      module Dates
+        include Support
+
+        # Year, year-month, full date, or full date with a time. Never fall back
+        # to a bare DateTime.parse: it fills missing parts from TODAY, so "19uu"
+        # would parse as the current date.
+        W3CDTF_DATE = /\A(\d{4})(?:-(\d{2})(?:-(\d{2})(T\S+)?)?)?\z/
+
+        # The same shapes without hyphens, read ONLY under @encoding="iso8601":
+        # an accession number is eight digits too.
+        ISO8601_BASIC_DATE = /\A(\d{4})(?:(\d{2})(?:(\d{2})(T\S+)?)?)?\z/
+
+        # @encoding, folded, so "ISO-8601" matches too.
+        ISO8601_ENCODING = "iso8601"
+
+        # Field prefix => the MODS element it reads, in FIELDS order. Written out
+        # rather than derived, so a search for a field name lands here.
+        DATE_FIELDS = {
+          date_created: "dateCreated",
+          date_issued: "dateIssued",
+          copyright_date: "copyrightDate",
+          date_captured: "dateCaptured",
+          date_valid: "dateValid",
+          date_other: "dateOther",
+          date_modified: "dateModified"
+        }.freeze
+
+        # Field suffix => the key of the #date_parts entry it reads. Each element
+        # projects one field per row.
+        DATE_KEYS = {
+          "" => :value,
+          "_precision" => :precision,
+          "_end" => :end_value,
+          "_end_precision" => :end_precision,
+          "_qualifier" => :qualifier,
+          "_key_date" => :key_date,
+          "_text" => :text,
+          "_display_label" => :display_label,
+          "_event_type" => :event_type
+        }.freeze
+
+        # What #date_parts returns when the element is absent entirely, so an
+        # absent date is distinguishable from one present and unparseable.
+        EMPTY_DATE = DATE_KEYS.values.to_h { |key| [key, nil] }.freeze
+
+        # The FIELDS rows for the generated fields, each element's rows together.
+        DATE_FIELD_ROWS = DATE_FIELDS.keys.product(DATE_KEYS.keys)
+                                     .to_h { |field, suffix| [:"#{field}#{suffix}", :one] }.freeze
+
+        # The same seven elements as DATE_FIELDS, in the order a consumer deciding
+        # a place header reads them. Keep this order: #origin_date_elements
+        # returns elements in it.
+        DATE_ELEMENTS = %w[dateIssued dateCreated copyrightDate dateCaptured
+                           dateValid dateOther dateModified].freeze
+
+        # A *_parts method per element and an accessor per DATE_FIELDS and
+        # DATE_KEYS pair (date_issued_end, date_created_text, ...). A search for
+        # `def date_issued_end` finds nothing; search the two tables instead.
+        DATE_FIELDS.each do |field, element|
+          define_method(:"#{field}_parts") { date_parts(element) }
+          DATE_KEYS.each do |suffix, key|
+            define_method(:"#{field}#{suffix}") { date_parts(element)[key] }
+          end
+        end
+
+        # [value, precision], for a caller that wants those two alone.
+        def date_created_with_precision = [date_created, date_created_precision]
+        def date_issued_with_precision = [date_issued, date_issued_precision]
+        def copyright_date_with_precision = [copyright_date, copyright_date_precision]
+
+        private
+
+        # [DateTime, precision], or nil for no shape or an impossible date
+        # (2026-02-30). A timestamp is parsed whole, so its time of day survives.
+        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), declared_precision(m)]
+        rescue Date::Error
+          nil
+        end
+
+        # w3cdtf always, then the basic ISO form only if the record declares 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.
+        def declared_precision(match)
+          return "day" if match[3]
+
+          match[2] ? "month" : "year"
+        end
+
+        # Everything a record declared about one date element. Nodes are chosen
+        # by @point and @keyDate, never by position: a record may write the end
+        # first. One date per element; see docs/dates.md.
+        def date_parts(element)
+          nodes = doc.xpath("/mods:mods/mods:originInfo/mods:#{element}", NAMESPACE)
+          return EMPTY_DATE if nodes.empty?
+
+          finish = nodes.find { |n| attr_value(n, "point") == "end" }
+          date_entry(start_date_node(nodes), finish, nodes)
+        end
+
+        # The flagged node, then the declared start, then document order. The
+        # flag leads so the value and #key_date always describe the same node.
+        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 carries its OWN precision ("1935-06" to "1940" is legal). The
+        # qualifier falls back from the start to the end, because v1 applied it
+        # to both points.
+        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,
+            end_value: end_value,
+            end_precision: end_precision,
+            qualifier: attr_value(start, "qualifier") || attr_value(finish, "qualifier"),
+            key_date: nodes.any? { |n| attr_value(n, "keyDate") == "yes" },
+            text: text,
+            # Off the enclosing originInfo, because that is where MODS puts both.
+            display_label: attr_value(origin, "displayLabel"),
+            event_type: attr_value(origin, "eventType")
+          }
+        end
+
+        # [value, precision, text]. An unreadable date keeps its literal as text
+        # ("ca. 1920") instead of a value: never invent a date, never drop one.
+        def node_date(node)
+          return [nil, nil, nil] unless node
+
+          str = Canonicalize.canonical_ws(node.text)
+          return [nil, nil, nil] if str.empty?
+
+          parsed = parse_declared_date(str, attr_value(node, "encoding"))
+          return [parsed[0], parsed[1], nil] if parsed
+
+          [nil, nil, str]
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/identifiers.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "support"
+
+module NEU
+  module MODS
+    module Projection
+      # Identifiers, classification, location and recordInfo: what the record
+      # is called elsewhere and where the resource is held. See docs/other-fields.md.
+      module Identifiers
+        include Support
+
+        # An LCC or DDC call number, not Atlas's classification_ssim.
+        def classification = labeled_texts_at("/mods:mods/mods:classification")
+
+        # Typed, so a display can tell a DOI from an accession number, and
+        # flagged when @invalid="yes" marks the identifier dead.
+        def identifiers
+          doc.xpath("/mods:mods/mods:identifier", NAMESPACE).filter_map do |node|
+            value = clean(node.text)
+            if value
+              { type: clean(node["type"]), value: value, invalid: attr_value(node, "invalid") == "yes",
+                **qualifiers_of(node) }
+            end
+          end
+        end
+
+        def permanent_url
+          clean(handle_node&.text)
+        end
+
+        # No href companion: the value is the URL.
+        def permanent_url_display_label
+          attr_value(handle_node, "displayLabel")
+        end
+
+        # The parts stay apart: a shelf mark and a URL are different kinds. The
+        # element is shelfLocator; MODS has no shelfLocation.
+        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:shelfLocator"),
+              url: child_text(node, "mods:url")
+            }
+            entry.merge(qualifiers_of(node)) if entry.values.any?
+          end
+        end
+
+        # recordInfo children, read as one value.
+        RECORD_INFO_PARTS = {
+          content_source: "mods:recordContentSource",
+          origin: "mods:recordOrigin",
+          description_standard: "mods:descriptionStandard",
+          creation_date: "mods:recordCreationDate",
+          change_date: "mods:recordChangeDate",
+          language_of_cataloging: "mods:languageOfCataloging/mods:languageTerm"
+        }.freeze
+
+        # Who catalogued the record, to what standard, and when.
+        def record_info
+          node = doc.at_xpath("/mods:mods/mods:recordInfo", NAMESPACE)
+          return nil unless node
+
+          entry = RECORD_INFO_PARTS.transform_values { |xpath| child_text(node, xpath) }
+          entry if entry.values.any?
+        end
+
+        private
+
+        # The handle identifier, which both the permanent URL and its header
+        # are read from.
+        def handle_node
+          doc.at_xpath("/mods:mods/mods:identifier[@type='hdl']", NAMESPACE)
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/languages.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "../language_codes"
+require_relative "support"
+
+module NEU
+  module MODS
+    module Projection
+      # Top-level language elements, a code-only term read through the ISO 639
+      # registry. See docs/other-fields.md.
+      module Languages
+        include Support
+
+        # { term:, object_part:, script: } per language element. An entry, because
+        # @objectPart changes what the record claims.
+        def languages
+          doc.xpath("/mods:mods/mods:language", NAMESPACE).filter_map do |lang|
+            node = language_term_node(lang)
+            term = language_term_of(node)
+            next unless term
+
+            # The authority comes off the <languageTerm>, never the <language>:
+            # MODS puts @authority on the term.
+            { term: term, object_part: attr_value(lang, "objectPart"), script: script_term(lang),
+              **authority_of(node), **qualifiers_of(lang) }
+          end
+        end
+
+        private
+
+        # Located apart from its text, so the term and its authority come from one
+        # node.
+        def language_term_node(lang)
+          lang.at_xpath("mods:languageTerm[@type='text']", NAMESPACE) ||
+            lang.at_xpath("mods:languageTerm", NAMESPACE)
+        end
+
+        # A text term as written; a code through the ISO 639 registry.
+        def language_term_of(node)
+          return nil unless node
+
+          return clean(node.text) if attr_value(node, "type") == "text"
+
+          code = clean(node.text)
+          code && LanguageCodes.term(code)
+        end
+
+        # Text form preferred, never translated: ISO 15924 is not vendored.
+        def script_term(lang)
+          text = lang.at_xpath("mods:scriptTerm[@type='text']", NAMESPACE)
+          return clean(text.text) if text
+
+          clean(lang.at_xpath("mods:scriptTerm", NAMESPACE)&.text)
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/name_display.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "support"
+
+module NEU
+  module MODS
+    module Projection
+      # Faithful port of the mods gem's display_value_w_date, quirks included,
+      # plus the role readers that decide whether the edit form owns a name.
+      # See docs/names.md.
+      module NameDisplay
+        include Support
+
+        private
+
+        # Read every namePart through #part_text, so the separators composed here
+        # are the only whitespace in the result.
+        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 = part_text(np)
+            dv += ", #{d}" unless d.empty? || dv.end_with?(d)
+          end
+          dv = dv.delete_prefix(", ")
+          dv.strip.empty? ? nil : dv.strip
+        end
+
+        def name_display_value(node, type)
+          display_form = part_text(node.at_xpath("mods:displayForm", NAMESPACE))
+          return display_form unless display_form.empty?
+
+          type == "personal" ? personal_display_value(node) : non_date_parts_joined(node)
+        end
+
+        def personal_display_value(node)
+          family = joined_parts(node, "family")
+          given  = joined_parts(node, "given")
+          dv =
+            if family.empty?
+              given
+            else
+              given.empty? ? family : "#{family}, #{given}"
+            end
+
+          return non_date_parts_joined(node) if dv.empty?
+
+          append_terms_of_address(node, dv)
+        end
+
+        def append_terms_of_address(node, dv)
+          first = true
+          node.xpath("mods:namePart[@type='termsOfAddress']", NAMESPACE).each do |np|
+            term = part_text(np)
+            next if term.empty?
+
+            dv += first ? " #{term}" : ", #{term}"
+            first = false
+          end
+          dv
+        end
+
+        # No separator, as the mods gem's NodeSet#text had: two `given` parts
+        # become "A.(B)". The conformance spec pins this quirk.
+        def joined_parts(node, type)
+          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" }
+              .map { |np| part_text(np) }
+              .reject(&:empty?)
+              .join(" ")
+        end
+
+        # One name element's text, whitespace-canonicalized, "" when absent.
+        def part_text(node)
+          clean_part(node&.text)
+        end
+
+        def name_roles(node)
+          node.xpath("mods:role", NAMESPACE).filter_map { |role| role_term_value(role) }
+        end
+
+        # The first declared role. Do not widen this to "any role is Creator":
+        # the form would then own a name whose other roles it cannot represent,
+        # and saving would drop them from the preservation XML.
+        def name_role(node) = name_roles(node).first
+
+        # The text roleTerm, else the raw code, untranslated. nil if neither.
+        def role_term_value(role)
+          %w[text code].each do |type|
+            term = part_text(role.at_xpath("mods:roleTerm[@type='#{type}']", NAMESPACE))
+            return term unless term.empty?
+          end
+          nil
+        end
+
+        # No authority attribute and a Creator role. Shared by the write path's
+        # node selection and the read path's pre-fill, and reads the attributes
+        # the way #authority_of does, so the two never disagree.
+        def editable_creator_name?(node)
+          AUTHORITY_ATTRIBUTES.values.none? { |attr| attr_value(node, attr) } &&
+            name_role(node) == "Creator"
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/names.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "../selectors"
+require_relative "support"
+require_relative "name_display"
+
+module NEU
+  module MODS
+    module Projection
+      # Top-level names: the composed entries for the access copy and the
+      # editable and preserved sets the edit form reads. See docs/names.md.
+      module Names
+        include Support
+        include NameDisplay
+        include Selectors
+
+        # One name as the access copy wants it.
+        def name_entry(node)
+          {
+            name: name_display_value_w_date(node),
+            roles: name_roles(node),
+            affiliation: texts_under(node, "mods:affiliation"),
+            usage: attr_value(node, "usage"),
+            alternative_names: alternative_names(node),
+            # Off the <name> alone: a marcrelator <roleTerm> says what the person
+            # did, not which list the name came from.
+            **authority_of(node),
+            **qualifiers_of(node)
+          }
+        end
+
+        # Composed with the ENCLOSING name's @type: alternativeName carries
+        # @altType, and an alternative for a personal name is still personal.
+        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
+
+        # Every top-level name with name text. #preserved_names keeps a name with
+        # none, so a curator can still see the element to fix it.
+        def names
+          doc.xpath("/mods:mods/mods:name", NAMESPACE).filter_map do |node|
+            entry = name_entry(node)
+            entry if entry[:name]
+          end
+        end
+
+        # The plain Creator names the edit form manages, as structured parts
+        # for pre-fill rather than composed display strings.
+        def editable_personal_creators
+          editable_creator_nodes("personal").map do |node|
+            { given: clean_part(joined_parts(node, "given")), family: clean_part(joined_parts(node, "family")) }
+          end
+        end
+
+        def editable_corporate_creators
+          editable_creator_nodes("corporate").map { |node| { name: clean_part(non_date_parts_joined(node)) } }
+        end
+
+        # The names the edit form does not manage, for read-only display.
+        def preserved_names
+          doc.xpath("/mods:mods/mods:name", NAMESPACE)
+             .reject { |node| editable_creator_name?(node) }
+             .map { |node| name_entry(node) }
+        end
+      end
+    end
+  end
+end

data/lib/neu/mods/projection/origin_info.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "../namespaces"
+require_relative "support"
+require_relative "names"
+require_relative "dates"
+
+module NEU
+  module MODS
+    module Projection
+      # The non-date originInfo children, each carrying its block's header
+      # attributes. See docs/other-fields.md.
+      module OriginInfo
+        include Support
+        include Names
+        include Dates
+
+        # Headed by the enclosing originInfo: MODS puts neither attribute on its
+        # children.
+        def publication_information = origin_texts_at("mods:publisher")
+        def edition = origin_texts_at("mods:edition")
+
+        # A bare marccountry code ("mau") is not a place name, so it drops.
+        # TODO: expand marccountry codes through a vendored registry, as
+        # LanguageCodes does for eng -> English.
+        MARC_COUNTRY_AUTHORITY = "marccountry"
+
+        def place_of_publication
+          doc.xpath("/mods:mods/mods:originInfo/mods:place", NAMESPACE).filter_map do |place|
+            value = place_term_value(place)
+            next unless value
+
+            { value: value, **origin_qualifiers_of(place.parent),
+              date_elements: origin_date_elements(place.parent) }
+          end
+        end
+
+        # originInfo/agent, composed like a top-level name.
+        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 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")
+
+        def frequency = origin_texts_at("mods:frequency")
+
+        private
+
+        # The general pair plus @eventType, which MODS puts on originInfo alone.
+        def origin_qualifiers_of(node)
+          qualifiers_of(node).merge(event_type: attr_value(node, "eventType"))
+        end
+
+        # `xpath` is relative to each originInfo, which the qualifiers come from.
+        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 beside a place, which decide how its row is headed.
+        def origin_date_elements(origin)
+          return [] unless origin
+
+          DATE_ELEMENTS.select { |name| origin.at_xpath("mods:#{name}", NAMESPACE) }
+        end
+      end
+    end
+  end
+end