cocina_display 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e86f2100a204e574eaf48f86dccf3b9bdc4985285e72e05292f9dd722d9d87e9
-  data.tar.gz: 5730dd6764fa87f39dc6d00dc66c8ea72f10685c7e3aef0b92864c16b1186cb6
+  metadata.gz: 68f245cc22043da571e4a9abf0f0fedd613fc19035c4a50369b95400c76573b5
+  data.tar.gz: 86de10bbfcabc44d23d9b3df480eb6b3f0d28b358c9f4fece1ece089cf5cca20
 SHA512:
-  metadata.gz: fcfa03dd80c3673045803c11c1d7fa3f9c5284f75806c7c76b5ccb52cb765631670696fe3777a2a5cfbcd90b209ba5e898a618a92d9ecf0186670fdddb09cb6e
-  data.tar.gz: acbcb5d312ac4755cfff3a74119b68e316d929da0d0d91f397afdd51480f3a90332166f2ccc052e53c2d675d749f62a12f814513b58413611475e36d732c5041
+  metadata.gz: 9ea9ac44480ac83533704c06705f0f6f078ac4065b27756cea527f4110ab99b3bafcfcf525097368005e89534bed78a8bb17a81cb96dc1c48c479a5052b877f6
+  data.tar.gz: 3600cc57ec5e162cb39e2547fa09c9dc7aadc87742146649a0c9d3427ad6c8a2eede1357103af6d4cab531e51d93136a69f075de0995c86daaf471fac2ff08c7

data/lib/cocina_display/cocina_record.rb

@@ -14,6 +14,8 @@ require_relative "concerns/titles"
 require_relative "concerns/access"
 require_relative "concerns/subjects"
 require_relative "concerns/forms"
+require_relative "concerns/languages"
+require_relative "concerns/geospatial"
 require_relative "utils"
 
 module CocinaDisplay
@@ -26,6 +28,8 @@ module CocinaDisplay
     include CocinaDisplay::Concerns::Access
     include CocinaDisplay::Concerns::Subjects
     include CocinaDisplay::Concerns::Forms
+    include CocinaDisplay::Concerns::Languages
+    include CocinaDisplay::Concerns::Geospatial
 
     # Fetch a public Cocina document from PURL and create a CocinaRecord.
     # @note This is intended to be used in development or testing only.

data/lib/cocina_display/concerns/contributors.rb

@@ -1,4 +1,4 @@
-require_relative "../contributor"
+require_relative "../contributors/contributor"
 
 module CocinaDisplay
   module Concerns
@@ -62,8 +62,8 @@ module CocinaDisplay
       def contributor_names_by_role(with_date: false)
         contributors.each_with_object({}) do |contributor, hash|
           contributor.roles.each do |role|
-            hash[role.display_str] ||= []
-            hash[role.display_str] << contributor.display_name(with_date: with_date)
+            hash[role.to_s] ||= []
+            hash[role.to_s] << contributor.display_name(with_date: with_date)
           end
         end
       end
@@ -79,9 +79,13 @@ module CocinaDisplay
       end
 
       # All contributors for the object, including authors, editors, etc.
+      # Checks both description.contributor and description.event.contributor.
       # @return [Array<Contributor>]
       def contributors
-        @contributors ||= path("$.description.contributor.*").map { |c| Contributor.new(c) }
+        @contributors ||= Enumerator::Chain.new(
+          path("$.description.contributor.*"),
+          path("$.description.event.*.contributor.*")
+        ).map { |c| CocinaDisplay::Contributors::Contributor.new(c) }
       end
 
       # All contributors with a "publisher" role.

data/lib/cocina_display/concerns/events.rb

@@ -62,8 +62,8 @@ module CocinaDisplay
       # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
       # @return [String, nil]
       # @example Year range
-      #  CocinaRecord.fetch('bb099mt5053').pub_year_display_str #=> "1932 - 2012"
-      def pub_year_display_str(ignore_qualified: false)
+      #  CocinaRecord.fetch('bb099mt5053').pub_year_str #=> "1932 - 2012"
+      def pub_year_str(ignore_qualified: false)
         date = pub_date(ignore_qualified: ignore_qualified)
         return unless date
 
@@ -72,18 +72,18 @@ module CocinaDisplay
 
       # String for displaying the imprint statement(s).
       # @return [String, nil]
-      # @see CocinaDisplay::Imprint#display_str
+      # @see CocinaDisplay::Imprint#to_s
       # @example
-      #   CocinaRecord.fetch('bt553vr2845').imprint_display_str #=> "New York : Meridian Book, 1993, c1967"
-      def imprint_display_str
-        imprint_events.map(&:display_str).compact_blank.join("; ")
+      #   CocinaRecord.fetch('bt553vr2845').imprint_str #=> "New York : Meridian Book, 1993, c1967"
+      def imprint_str
+        imprint_events.map(&:to_s).compact_blank.join("; ")
       end
 
       # List of places of publication as strings.
       # Considers locations for all publication, creation, and capture events.
       # @return [Array<String>]
       def publication_places
-        publication_events.flat_map { |event| event.locations.map(&:display_str) }
+        publication_events.flat_map { |event| event.locations.map(&:to_s) }
       end
 
       # All events associated with the object.

data/lib/cocina_display/concerns/geospatial.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "../subjects/subject_value"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting geospatial metadata, such as coordinates.
+    module Geospatial
+      # All coordinate data as DMS format strings.
+      # @return [Array<String>]
+      # @example ["34°03′08″N 118°14′37″W"]
+      def coordinates
+        coordinate_subjects.map(&:to_s).compact.uniq
+      end
+
+      # All valid coordinate data formatted for indexing into a Solr RPT field.
+      # @note This type of field accommodates both points and bounding boxes.
+      # @see https://solr.apache.org/guide/solr/latest/query-guide/spatial-search.html#rpt
+      # @return [Array<String>]
+      # @example ["POINT(34.0522 -118.2437)", "POLYGON((-118.2437 34.0522, -118.2437 34.1996, -117.9522 34.1996, -117.9522 34.0522, -118.2437 34.0522))"]
+      def coordinates_as_wkt
+        coordinate_objects.map(&:as_wkt).uniq
+      end
+
+      # All valid coordinate data formatted for indexing into a Solr BBoxField.
+      # @note Points are not included since they can't be represented as a box.
+      # @see https://solr.apache.org/guide/solr/latest/query-guide/spatial-search.html#bboxfield
+      # @return [Array<String>]
+      # @example ["ENVELOPE(-118.2437, -117.9522, 34.1996, 34.0522)"]
+      def coordinates_as_envelope
+        coordinate_objects.map(&:as_envelope).compact.uniq
+      end
+
+      # All valid coordinate data formatted for indexing into a Solr LatLon field.
+      # @note Bounding boxes are automatically converted to their center point.
+      # @see https://solr.apache.org/guide/solr/latest/query-guide/spatial-search.html#indexing-points
+      # @return [Array<String>]
+      # @example ["34.0522,-118.2437"]
+      def coordinates_as_point
+        coordinate_objects.map(&:as_point).uniq
+      end
+
+      # Identifiers assigned by geonames.org for places related to the object.
+      # @return [Array<String>]
+      # @example ["6252001", "5368361"]
+      def geonames_ids
+        place_subject_values.map { |s| s.geonames_id }.compact.uniq
+      end
+
+      private
+
+      # Parsed coordinate values from the coordinate subject values.
+      # @return [Array<Geospatial::Coordinates>]
+      def coordinate_objects
+        coordinate_subjects.filter_map(&:coordinates)
+      end
+
+      # All subject values that could contain parsed coordinates.
+      # @return [Array<Subjects::CoordinatesSubjectValue>]
+      def coordinate_subjects
+        subject_values.filter { |s| s.is_a? CocinaDisplay::Subjects::CoordinatesSubjectValue }
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/languages.rb

@@ -0,0 +1,20 @@
+require_relative "../language"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting language information from a Cocina object.
+    module Languages
+      # Languages objects associated with the object.
+      # @return [Array<CocinaDisplay::Language>]
+      def languages
+        @languages ||= path("$.description.language.*").map { |lang| CocinaDisplay::Language.new(lang) }
+      end
+
+      # Names of languages associated with the object, if recognized by Searchworks.
+      # @return [Array<String>]
+      def searchworks_language_names
+        languages.filter_map { |lang| lang.to_s if lang.searchworks_language? }.compact_blank.uniq
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/subjects.rb

@@ -1,53 +1,61 @@
-require_relative "../subject"
+require_relative "../subjects/subject"
+require_relative "../subjects/subject_value"
 
 module CocinaDisplay
   module Concerns
     # Methods for extracting and formatting subject information.
     module Subjects
-      # All unique subjects that are topics, formatted as strings for display.
+      # All unique subject values that are topics.
       # @return [Array<String>]
       def subject_topics
-        subjects.filter { |s| s.type == "topic" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "topic" }.map(&:to_s).uniq
       end
 
-      # All unique subjects that are genres, formatted as strings for display.
+      # All unique subject values that are genres.
       # @return [Array<String>]
       def subject_genres
-        subjects.filter { |s| s.type == "genre" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "genre" }.map(&:to_s).uniq
       end
 
-      # All unique subjects that are titles, formatted as strings for display.
+      # All unique subject values that are titles.
       # @return [Array<String>]
       def subject_titles
-        subjects.filter { |s| s.type == "title" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "title" }.map(&:to_s).uniq
       end
 
-      # All unique subjects that are date/time info, formatted as strings for display.
+      # All unique subject values that are date/time info.
       # @return [Array<String>]
       def subject_temporal
-        subjects.filter { |s| s.type == "time" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "time" }.map(&:to_s).uniq
       end
 
-      # All unique subjects that are occupations, formatted as strings for display.
+      # All unique subject values that are occupations.
       # @return [Array<String>]
       def subject_occupations
-        subjects.filter { |s| s.type == "occupation" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "occupation" }.map(&:to_s).uniq
       end
 
-      # All unique subjects that are names of entities, formatted as strings for display.
+      # All unique subject values that are named geographic places.
+      # @return [Array<String>]
+      def subject_places
+        place_subject_values.map(&:to_s).uniq
+      end
+
+      # All unique subject values that are names of entities.
       # @note Multiple types are handled: person, family, organization, conference, etc.
-      # @see CocinaDisplay::NameSubject
+      # @see CocinaDisplay::NameSubjectValue
       # @return [Array<String>]
       def subject_names
-        subjects.filter { |s| s.is_a? NameSubject }.map(&:display_str).uniq
+        subject_values.filter { |s| s.is_a? CocinaDisplay::Subjects::NameSubjectValue }.map(&:to_s).uniq
       end
 
       # Combination of all subject values for searching.
       # @see #subject_topics_other
       # @see #subject_temporal_genre
+      # @see #subject_places
       # @return [Array<String>]
       def subject_all
-        subject_topics_other + subject_temporal_genre
+        subject_topics_other + subject_temporal_genre + subject_places
       end
 
       # Combination of topic, occupation, name, and title subject values for searching.
@@ -75,6 +83,13 @@ module CocinaDisplay
         subject_temporal + subject_genres
       end
 
+      # Combination of all subjects with nested values concatenated for display.
+      # @see Subject#to_s
+      # @return [Array<String>]
+      def subject_all_display
+        subjects.map(&:to_s).uniq
+      end
+
       private
 
       # All subjects, accessible as Subject objects.
@@ -84,7 +99,19 @@ module CocinaDisplay
         @subjects ||= Enumerator::Chain.new(
           path("$.description.subject[*]"),
           path("$.description.geographic.*.subject[*]")
-        ).map { |s| Subject.from_cocina(s) }
+        ).map { |s| CocinaDisplay::Subjects::Subject.new(s) }
+      end
+
+      # All subject values, flattened from all subjects.
+      # @return [Array<SubjectValue>]
+      def subject_values
+        @subject_values ||= subjects.flat_map(&:subject_values)
+      end
+
+      # All subject values that are named places.
+      # @return [Array<PlaceSubjectValue>]
+      def place_subject_values
+        @place_subject_values ||= subject_values.filter { |s| s.is_a? CocinaDisplay::Subjects::PlaceSubjectValue }
       end
     end
   end

data/lib/cocina_display/contributors/contributor.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/array/conversions"
+
+require_relative "../utils"
+require_relative "name"
+require_relative "role"
+
+module CocinaDisplay
+  module Contributors
+    # A contributor to a work, such as an author or publisher.
+    class Contributor
+      attr_reader :cocina
+
+      # Initialize a Contributor object with Cocina structured data.
+      # @param cocina [Hash] The Cocina structured data for the contributor.
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # String representation of the contributor, including name and role.
+      # Used for debugging and logging.
+      # @return [String]
+      def to_s
+        Utils.compact_and_join([display_name, display_role], delimiter: ": ")
+      end
+
+      # Is this contributor a human?
+      # @return [Boolean]
+      def person?
+        cocina["type"] == "person"
+      end
+
+      # Is this contributor an organization?
+      # @return [Boolean]
+      def organization?
+        cocina["type"] == "organization"
+      end
+
+      # Is this contributor a conference?
+      # @return [Boolean]
+      def conference?
+        cocina["type"] == "conference"
+      end
+
+      # Is this contributor marked as primary?
+      # @return [Boolean]
+      def primary?
+        cocina["status"] == "primary"
+      end
+
+      # Does this contributor have a role that indicates they are an author?
+      # @return [Boolean]
+      def author?
+        roles.any?(&:author?)
+      end
+
+      # Does this contributor have a role that indicates they are a publisher?
+      # @return [Boolean]
+      def publisher?
+        roles.any?(&:publisher?)
+      end
+
+      # Does this contributor have any roles defined?
+      # @return [Boolean]
+      def role?
+        roles.any?
+      end
+
+      # The display name for the contributor as a string.
+      # Uses the first name if multiple names are present.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [String]
+      def display_name(with_date: false)
+        names.map { |name| name.to_s(with_date: with_date) }.first
+      end
+
+      # A string representation of the contributor's roles, formatted for display.
+      # If there are multiple roles, they are joined with commas.
+      # @return [String]
+      def display_role
+        roles.map(&:to_s).to_sentence
+      end
+
+      # All names in the Cocina as Name objects.
+      # @return [Array<Name>]
+      def names
+        @names ||= Array(cocina["name"]).map { |name| Name.new(name) }
+      end
+
+      # All roles in the Cocina structured data.
+      # @return [Array<Hash>]
+      def roles
+        @roles ||= Array(cocina["role"]).map { |role| Role.new(role) }
+      end
+    end
+  end
+end

data/lib/cocina_display/contributors/name.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../utils"
+
+module CocinaDisplay
+  module Contributors
+    # A name associated with a contributor.
+    class Name
+      attr_reader :cocina
+
+      # Initialize a Name object with Cocina structured data.
+      # @param cocina [Hash] The Cocina structured data for the name.
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # The display string for the name, optionally including life dates.
+      # Uses these values in order, if present:
+      # 1. Unstructured value
+      # 2. Any structured/parallel values marked as "display"
+      # 3. Joined structured values, optionally with life dates
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [String]
+      # @example no dates
+      #   name.to_s # => "King, Martin Luther, Jr."
+      # @example with dates
+      #   name.to_s(with_date: true) # => "King, Martin Luther, Jr., 1929-1968"
+      def to_s(with_date: false)
+        if cocina["value"].present?
+          cocina["value"]
+        elsif display_name_str.present?
+          display_name_str
+        elsif dates_str.present? && with_date
+          Utils.compact_and_join([full_name_str, dates_str], delimiter: ", ")
+        else
+          full_name_str
+        end
+      end
+
+      private
+
+      # The full name as a string, combining all name components and terms of address.
+      # @return [String]
+      def full_name_str
+        Utils.compact_and_join(name_components.push(terms_of_address_str), delimiter: ", ")
+      end
+
+      # Flattened form of any names explicitly marked as "display name".
+      # @return [String]
+      def display_name_str
+        Utils.compact_and_join(Array(name_values["display"]), delimiter: ", ")
+      end
+
+      # List of all name components.
+      # If any of forename, surname, or term of address are present, those are used.
+      # Otherwise, fall back to any names explicitly marked as "name" or untyped.
+      # @return [Array<String>]
+      def name_components
+        [surname_str, forename_ordinal_str].compact_blank.presence || Array(name_values["name"])
+      end
+
+      # Flatten all forenames and ordinals into a single string.
+      # @return [String]
+      def forename_ordinal_str
+        Utils.compact_and_join(Array(name_values["forename"]) + Array(name_values["ordinal"]), delimiter: " ")
+      end
+
+      # Flatten all terms of address into a single string.
+      # @return [String]
+      def terms_of_address_str
+        Utils.compact_and_join(Array(name_values["term of address"]), delimiter: ", ")
+      end
+
+      # Flatten all surnames into a single string.
+      # @return [String]
+      def surname_str
+        Utils.compact_and_join(Array(name_values["surname"]), delimiter: " ")
+      end
+
+      # Flatten all life and activity dates into a single string.
+      # @return [String]
+      def dates_str
+        Utils.compact_and_join(Array(name_values["life dates"]) + Array(name_values["activity dates"]), delimiter: ", ")
+      end
+
+      # A hash mapping destructured name types to their values.
+      # Name values with no type are grouped under "name".
+      # @return [Hash<String, Array<String>>]
+      # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#contributor-name-part-types-for-structured-value
+      # @note Currently we do nothing with "alternative", "inverted full name", "pseudonym", and "transliteration" types.
+      def name_values
+        Utils.flatten_nested_values(cocina).each_with_object({}) do |node, hash|
+          type = node["type"] || "name"
+          hash[type] ||= []
+          hash[type] << node["value"]
+        end.compact_blank
+      end
+    end
+  end
+end

data/lib/cocina_display/contributors/role.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../vocabularies/marc_relator_codes"
+
+module CocinaDisplay
+  module Contributors
+    # A role associated with a contributor.
+    class Role
+      attr_reader :cocina
+
+      # Initialize a Role object with Cocina structured data.
+      # @param cocina [Hash] The Cocina structured data for the role.
+      def initialize(cocina)
+        @cocina = cocina
+      end
+
+      # The name of the role.
+      # Translates the MARC relator code if no value was present.
+      # @return [String, nil]
+      def to_s
+        cocina["value"] || (Vocabularies::MARC_RELATOR[code] if marc_relator?)
+      end
+
+      # A code associated with the role, e.g. a MARC relator code.
+      # @return [String, nil]
+      def code
+        cocina["code"]
+      end
+
+      # Does this role indicate the contributor is an author?
+      # @return [Boolean]
+      def author?
+        to_s =~ /^(author|creator)/i
+      end
+
+      # Does this role indicate the contributor is a publisher?
+      # @return [Boolean]
+      def publisher?
+        to_s =~ /^publisher/i
+      end
+
+      private
+
+      # Does this role have a MARC relator code?
+      # @return [Boolean]
+      def marc_relator?
+        cocina.dig("source", "code") == "marcrelator"
+      end
+    end
+  end
+end

data/lib/cocina_display/dates/date_range.rb

@@ -63,7 +63,18 @@ module CocinaDisplay
         start&.encoding || stop&.encoding || super
       end
 
-      # Is either date in the range qualified in any way?
+      # The qualifier for the entire range.
+      # If both qualifiers match, uses that qualifier. If both are empty, falls
+      # back to the top level qualifier, if any.
+      # @see CocinaDisplay::Date#qualifier
+      # @return [String, nil]
+      def qualifier
+        if start&.qualifier == stop&.qualifier
+          start&.qualifier || stop&.qualifier || super
+        end
+      end
+
+      # Is either date in the range, or the range itself, qualified?
       # @see CocinaDisplay::Date#qualified?
       # @return [Boolean]
       def qualified?
@@ -105,14 +116,15 @@ module CocinaDisplay
       # @see CocinaDisplay::Date#qualified_value
       # @return [String]
       def qualified_value
-        if start&.qualifier == stop&.qualifier
-          qualifier = start&.qualifier || stop&.qualifier
-          date = decoded_value
-          return "[ca. #{date}]" if qualifier == "approximate"
-          return "[#{date}?]" if qualifier == "questionable"
-          return "[#{date}]" if qualifier == "inferred"
-
-          date
+        if qualifier
+          case qualifier
+          when "approximate"
+            "[ca. #{decoded_value}]"
+          when "questionable"
+            "[#{decoded_value}?]"
+          when "inferred"
+            "[#{decoded_value}]"
+          end
         else
           "#{start&.qualified_value} - #{stop&.qualified_value}"
         end

data/lib/cocina_display/events/event.rb

@@ -1,6 +1,6 @@
 require_relative "location"
 require_relative "../dates/date"
-require_relative "../contributor"
+require_relative "../contributors/contributor"
 
 module CocinaDisplay
   module Events
@@ -62,7 +62,7 @@ module CocinaDisplay
       # @return [Array<CocinaDisplay::Contributor>]
       def contributors
         @contributors ||= Array(cocina["contributor"]).map do |contributor|
-          CocinaDisplay::Contributor.new(contributor)
+          CocinaDisplay::Contributors::Contributor.new(contributor)
         end
       end
 

data/lib/cocina_display/events/imprint.rb

@@ -7,7 +7,6 @@ require "active_support/core_ext/object/blank"
 
 require_relative "event"
 require_relative "../utils"
-require_relative "../marc_country_codes"
 require_relative "../dates/date"
 require_relative "../dates/date_range"
 
@@ -17,7 +16,7 @@ module CocinaDisplay
     class Imprint < Event
       # The entire imprint statement formatted as a string for display.
       # @return [String]
-      def display_str
+      def to_s
         place_pub = Utils.compact_and_join([place_str, publisher_str], delimiter: " : ")
         edition_place_pub = Utils.compact_and_join([edition_str, place_pub], delimiter: " - ")
         Utils.compact_and_join([edition_place_pub, date_str], delimiter: ", ")
@@ -94,7 +93,7 @@ module CocinaDisplay
       def locations_for_display
         unencoded_locs, encoded_locs = locations.partition { |loc| loc.unencoded_value? }
         locs_for_display = unencoded_locs.presence || encoded_locs
-        locs_for_display.map(&:display_str).compact_blank.uniq
+        locs_for_display.map(&:to_s).compact_blank.uniq
       end
     end
   end

data/lib/cocina_display/events/location.rb

@@ -1,4 +1,4 @@
-require_relative "../marc_country_codes"
+require_relative "../vocabularies/marc_country_codes"
 
 module CocinaDisplay
   module Events
@@ -15,7 +15,7 @@ module CocinaDisplay
       # The name of the location.
       # Decodes a MARC country code if present and no value was present.
       # @return [String, nil]
-      def display_str
+      def to_s
         cocina["value"] || decoded_country
       end
 
@@ -36,7 +36,7 @@ module CocinaDisplay
       # Decoded country name if the location is encoded with a MARC country code.
       # @return [String, nil]
       def decoded_country
-        MARC_COUNTRY[code] if marc_country? && valid_country_code?
+        Vocabularies::MARC_COUNTRY[code] if marc_country? && valid_country_code?
       end
 
       # Is this a decodable country code?