cocina_display 0.7.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575cbfb8b11f3cf71950bfb5234ada4a916a5e55d21116422de84361854f0713
-  data.tar.gz: 4e06ee33d664822bdb6a3057ad8c40539f1f8363350f4648a463c7be0cb533ad
+  metadata.gz: 7faaded226886ab37cfbff854b64721c55964959089a1675706ae6160d4a1a5c
+  data.tar.gz: 111b995bfdf70805eb7a613bf5f221bacf101be1ed3f9ad6fb2407266c7a35ab
 SHA512:
-  metadata.gz: 76ecb30d8a60bbb42bab880b0c3c5288d8daa7504cc044fb06c157e1b5e2fe21fd3e56668c3479d291f1e683eab4d719c11b2ac5d185b6e98a062e917f5ea74a
-  data.tar.gz: ce4c61a927f9bc034aeebcd9cfc0cb56c8cd1b3c4ee13f7d8d0fcd0cc83290e8d2d1fe31ead879bdb4b1d0090ee60164158ba24d9c8eeb4a7499dfd315b9cf07
+  metadata.gz: 6a8586d41059d8880ac29c48f564907a51b718dc7812f2314e564032e1f19722d97620755cd53f52aa927e17e45dbfab79b56936c022255f2c22c3147e2c110c
+  data.tar.gz: 58ddd5de3cfe25d78904c24c1edaed72d4212eb7149b58b3b6e5c216390db75acc0c8ad81c039c9c712da99480842df2cab27c70573c848e2cb9377f0a31b909

data/lib/cocina_display/cocina_record.rb

@@ -15,6 +15,8 @@ require_relative "concerns/access"
 require_relative "concerns/subjects"
 require_relative "concerns/forms"
 require_relative "concerns/languages"
+require_relative "concerns/geospatial"
+require_relative "concerns/structural"
 require_relative "utils"
 
 module CocinaDisplay
@@ -28,6 +30,8 @@ module CocinaDisplay
     include CocinaDisplay::Concerns::Subjects
     include CocinaDisplay::Concerns::Forms
     include CocinaDisplay::Concerns::Languages
+    include CocinaDisplay::Concerns::Geospatial
+    include CocinaDisplay::Concerns::Structural
 
     # Fetch a public Cocina document from PURL and create a CocinaRecord.
     # @note This is intended to be used in development or testing only.
@@ -107,16 +111,27 @@ module CocinaDisplay
       content_type == "collection"
     end
 
-    # Traverse nested FileSets and return an enumerator over their files.
-    # Each file is a +Hash+.
-    # @return [Enumerator] Enumerator over file hashes
-    # @example
-    #  record.files.each do |file|
-    #   puts file["filename"] #=> "image1.jpg"
-    #   puts file["size"] #=> 123456
-    #  end
-    def files
-      path("$.structural.contains.*.structural.contains[*]")
+    # Resources related to the object.
+    # @return [Array<CocinaDisplay::RelatedResource>]
+    def related_resources
+      @related_resources ||= path("$.description.relatedResource[*]").map { |res| RelatedResource.new(res) }
+    end
+  end
+
+  # A resource related to the record; behaves like a CocinaRecord.
+  # @note Related resources have no structural metadata.
+  class RelatedResource < CocinaRecord
+    # Description of the relation to the source record.
+    # @return [String]
+    # @example "is part of"
+    # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#relatedresource-types
+    attr_reader :type
+
+    # Restructure the hash so that everything is under "description" key, since
+    # it's all descriptive metadata. This makes CocinaRecord methods work.
+    def initialize(cocina_doc)
+      @type = cocina_doc["type"]
+      @cocina_doc = {"description" => cocina_doc.except("type")}
     end
   end
 end

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
@@ -85,7 +85,7 @@ module CocinaDisplay
         @contributors ||= Enumerator::Chain.new(
           path("$.description.contributor.*"),
           path("$.description.event.*.contributor.*")
-        ).map { |c| Contributor.new(c) }
+        ).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

@@ -13,7 +13,7 @@ module CocinaDisplay
       # Names of languages associated with the object, if recognized by Searchworks.
       # @return [Array<String>]
       def searchworks_language_names
-        languages.filter_map { |lang| lang.display_str if lang.searchworks_language? }.compact_blank.uniq
+        languages.filter_map { |lang| lang.to_s if lang.searchworks_language? }.compact_blank.uniq
       end
     end
   end

data/lib/cocina_display/concerns/structural.rb

@@ -0,0 +1,41 @@
+require "active_support/number_helper/number_to_human_size_converter"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for inspecting structural metadata (e.g. file hierarchy)
+    module Structural
+      # Structured data for all individual files in the object.
+      # Traverses nested FileSet structure to return a flattened array.
+      # @return [Array<Hash>]
+      # @example
+      #  record.files.each do |file|
+      #   puts file["filename"] #=> "image1.jpg"
+      #   puts file["size"] #=> 123456
+      #  end
+      def files
+        @files ||= path("$.structural.contains.*.structural.contains.*").search
+      end
+
+      # All unique MIME types of files in this object.
+      # @return [Array<String>]
+      # @example ["image/jpeg", "application/pdf"]
+      def file_mime_types
+        files.pluck("hasMimeType").uniq
+      end
+
+      # Human-readable string representation of {total_file_size_int}.
+      # @return [String]
+      # @example "2.5 MB"
+      def total_file_size_str
+        ActiveSupport::NumberHelper.number_to_human_size(total_file_size_int)
+      end
+
+      # Summed size of all files in bytes.
+      # @return [Integer]
+      # @example 2621440
+      def total_file_size_int
+        files.pluck("size").sum
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/subjects.rb

@@ -8,31 +8,37 @@ module CocinaDisplay
       # All unique subject values that are topics.
       # @return [Array<String>]
       def subject_topics
-        subject_values.filter { |s| s.type == "topic" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "topic" }.map(&:to_s).uniq
       end
 
       # All unique subject values that are genres.
       # @return [Array<String>]
       def subject_genres
-        subject_values.filter { |s| s.type == "genre" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "genre" }.map(&:to_s).uniq
       end
 
       # All unique subject values that are titles.
       # @return [Array<String>]
       def subject_titles
-        subject_values.filter { |s| s.type == "title" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "title" }.map(&:to_s).uniq
       end
 
       # All unique subject values that are date/time info.
       # @return [Array<String>]
       def subject_temporal
-        subject_values.filter { |s| s.type == "time" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "time" }.map(&:to_s).uniq
       end
 
       # All unique subject values that are occupations.
       # @return [Array<String>]
       def subject_occupations
-        subject_values.filter { |s| s.type == "occupation" }.map(&:display_str).uniq
+        subject_values.filter { |s| s.type == "occupation" }.map(&:to_s).uniq
+      end
+
+      # 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.
@@ -40,15 +46,16 @@ module CocinaDisplay
       # @see CocinaDisplay::NameSubjectValue
       # @return [Array<String>]
       def subject_names
-        subject_values.filter { |s| s.is_a? CocinaDisplay::Subjects::NameSubjectValue }.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.
@@ -77,10 +84,10 @@ module CocinaDisplay
       end
 
       # Combination of all subjects with nested values concatenated for display.
-      # @see Subject#display_str
+      # @see Subject#to_s
       # @return [Array<String>]
       def subject_all_display
-        subjects.map(&:display_str).uniq
+        subjects.map(&:to_s).uniq
       end
 
       private
@@ -100,6 +107,12 @@ module CocinaDisplay
       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
 end

data/lib/cocina_display/contributors/contributor.rb

@@ -0,0 +1,120 @@
+# 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 a role that indicates they are a funder?
+      # @return [Boolean]
+      def funder?
+        roles.any?(&:funder?)
+      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
+
+      # The full forename for the contributor from the first available name.
+      # @see Contributor::Name::forename_str
+      # @return [String, nil]
+      def forename
+        names.map(&:forename_str).first.presence
+      end
+
+      # The full surname for the contributor from the first available name.
+      # @see Contributor::Name::surname_str
+      # @return [String, nil]
+      def surname
+        names.map(&:surname_str).first.presence
+      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
+
+      # 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_str].compact_blank.presence || Array(name_values["name"])
+      end
+
+      # Flatten all terms of address into a comma-delimited string.
+      # @return [String]
+      def terms_of_address_str
+        Utils.compact_and_join(Array(name_values["term of address"]), delimiter: ", ")
+      end
+
+      # Flatten all forename values and ordinals into a whitespace-delimited string.
+      # @return [String]
+      def forename_str
+        Utils.compact_and_join(Array(name_values["forename"]) + Array(name_values["ordinal"]), delimiter: " ")
+      end
+
+      # Flatten all surname values into a whitespace-delimited string.
+      # @return [String]
+      def surname_str
+        Utils.compact_and_join(Array(name_values["surname"]), delimiter: " ")
+      end
+
+      # Flatten all life and activity dates into a comma-delimited string.
+      # @return [String]
+      def dates_str
+        Utils.compact_and_join(Array(name_values["life dates"]) + Array(name_values["activity dates"]), delimiter: ", ")
+      end
+
+      private
+
+      # 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,57 @@
+# 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|primary investigator)/i
+      end
+
+      # Does this role indicate the contributor is a publisher?
+      # @return [Boolean]
+      def publisher?
+        to_s =~ /^publisher/i
+      end
+
+      # Does this role indicate the contributor is a funder?
+      # @return [Boolean]
+      def funder?
+        to_s =~ /^funder/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/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

@@ -16,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: ", ")
@@ -93,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

@@ -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