cocina_display 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca2e2a44615201a7709f9a7b4d7e0792aaea7f14344dc93b3bf800acdef83e91
-  data.tar.gz: 8dfd7f06a65930d2d639083c1235a7a9e41d8bcf59ac12f60bd4b2b87118d784
+  metadata.gz: 0724f307088c9cdd9348af463e3c659811eef65d0f1f04e094b4c664a36cfed1
+  data.tar.gz: 4b49472d07a085455ca72204e6ebde3cfc27c634f8ba9cd5b2c2a47d62d19aad
 SHA512:
-  metadata.gz: 11e6b9f94eaa777d1069deb972e046cda240e815524a2d938a8df97f75556393a10706c73dcaa9172a2c2a3cb90a459ed0ce8ca3c9d04f5f025242629b10f809
-  data.tar.gz: be9642a9205aca7b1aac2c73cb6250dbc1def18cba5fa88b3afdb4839186f6832ca80404f04ca47680fe181738276317f27b9c751c527b6ded4b6d637d1d1254
+  metadata.gz: edc1e8977792d21fd6fef292f486c11eab4011dc63c854af1217aced6930ea55538e158abc261491c08b1f8492c374c52102b44931849b2350e1dacf54310d41
+  data.tar.gz: 664691764d4a4ff7da024af64ce9dd2d0841d8c014ee9439c3ebebe4b3a4c2e585e7f608f2ff943a04586dfaad8fc4ec7cfa714fade929ca9b0278ec740bff8b

data/README.md

@@ -28,25 +28,19 @@ To start, you need some Cocina in JSON form.
 
 You can download some directly from PURL by visiting an object's PURL URL and appending `.json` to the end, like `https://purl.stanford.edu/bb112zx3193.json`. Some examples are available in the `spec/fixtures` directory.
 
-You can also use the built-in `HTTP` library or `faraday` gem to fetch the record for you, e.g.:
+There is also a helper method to fetch the Cocina JSON for a given DRUID and immediately parse it into a `CocinaRecord` object:
 
 ```ruby
-require 'http'
-cocina_json = HTTP.get('https://purl.stanford.edu/bb112zx3193.json').to_s
+> record = CocinaDisplay::CocinaRecord.fetch('bb112zx3193')
+=> #<CocinaDisplay::CocinaRecord:0x00007f8c8c0b5c80
 ```
 
 ### Working with objects
 
-Once you have the JSON, you can initialize a `CocinaRecord` object and start working with it. The `CocinaRecord` class provides some methods to access common fields, as well as an underlying hash representation parsed from the JSON.
+The `CocinaRecord` class provides some methods to access common fields, as well as an underlying hash representation parsed from the JSON.
 
 ```ruby
-> require 'cocina_display/cocina_record'
-=> true
-> record = CocinaDisplay::CocinaRecord.new(cocina_json)
-=>
-#<CocinaDisplay::CocinaRecord:0x000000012d11b600
-...
-> record.title
+> record.main_title
 => "Bugatti Type 51A. Road & Track Salon January 1957"
 > record.content_type
 => "image"

data/lib/cocina_display/cocina_record.rb

@@ -2,16 +2,34 @@
 
 require "janeway"
 require "json"
-require "uri"
+require "net/http"
 require "active_support"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/hash/conversions"
 
-require_relative "title_builder"
+require_relative "concerns/events"
+require_relative "concerns/contributors"
+require_relative "concerns/identifiers"
+require_relative "concerns/titles"
 
 module CocinaDisplay
   # Public Cocina metadata for an SDR object, as fetched from PURL.
   class CocinaRecord
+    include CocinaDisplay::Concerns::Events
+    include CocinaDisplay::Concerns::Contributors
+    include CocinaDisplay::Concerns::Identifiers
+    include CocinaDisplay::Concerns::Titles
+
+    # Fetch a public Cocina document from PURL and create a CocinaRecord.
+    # @note This is intended to be used in development or testing only.
+    # @param druid [String] The bare DRUID of the object to fetch.
+    # @return [CocinaDisplay::CocinaRecord]
+    # :nocov:
+    def self.fetch(druid)
+      new(Net::HTTP.get(URI("https://purl.stanford.edu/#{druid}.json")))
+    end
+    # :nocov:
+
     # The parsed Cocina document.
     # @return [Hash]
     attr_reader :cocina_doc
@@ -32,60 +50,6 @@ module CocinaDisplay
       Janeway.enum_for(path_expression, cocina_doc)
     end
 
-    # The DRUID for the object, with the +druid:+ prefix.
-    # @return [String]
-    # @example
-    #   record.druid #=> "druid:bb099mt5053"
-    def druid
-      cocina_doc["externalIdentifier"]
-    end
-
-    # The DRUID for the object, without the +druid:+ prefix.
-    # @return [String]
-    # @example
-    #   record.bare_druid #=> "bb099mt5053"
-    def bare_druid
-      druid.delete_prefix("druid:")
-    end
-
-    # The DOI for the object, if there is one – just the identifier part.
-    # @return [String, nil]
-    # @example
-    #   record.doi #=> "10.25740/ppax-bf07"
-    def doi
-      doi_id = path("$.identification.doi").first ||
-        path("$.description.identifier[?match(@.type, 'doi|DOI')].value").first ||
-        path("$.description.identifier[?search(@.uri, 'doi.org')].uri").first
-
-      URI(doi_id).path.delete_prefix("/") if doi_id.present?
-    end
-
-    # The DOI as a URL, if there is one. Any valid DOI should resolve via doi.org.
-    # @return [String, nil]
-    # @example
-    #   record.doi_url #=> "https://doi.org/10.25740/ppax-bf07"
-    def doi_url
-      URI.join("https://doi.org", doi).to_s if doi.present?
-    end
-
-    # The HRID of the item in FOLIO, if defined.
-    # @note This doesn't imply the object is available in Searchworks at this ID.
-    # @return [String, nil]
-    # @example
-    #   record.folio_hrid #=> "a12845814"
-    def folio_hrid
-      path("$.identification.catalogLinks[?(@.catalog == 'folio')].catalogRecordId").first
-    end
-
-    # The FOLIO HRID if defined, otherwise the bare DRUID.
-    # @note This doesn't imply the object is available in Searchworks at this ID.
-    # @see folio_hrid
-    # @see bare_druid
-    # @return [String]
-    def searchworks_id
-      folio_hrid || bare_druid
-    end
-
     # Timestamp when the Cocina was created.
     # @note This is for the metadata itself, not the object.
     # @return [Time]
@@ -115,28 +79,6 @@ module CocinaDisplay
       content_type == "collection"
     end
 
-    # The main title for the object.
-    # @note If you need more formatting control, consider using {CocinaDisplay::TitleBuilder} directly.
-    # @return [String]
-    # @example
-    #   record.title #=> "Bugatti Type 51A. Road & Track Salon January 1957"
-    def title
-      CocinaDisplay::TitleBuilder.build(
-        cocina_doc.dig("description", "title"),
-        catalog_links: cocina_doc.dig("identification", "catalogLinks")
-      )
-    end
-
-    # Alternative or translated titles for the object. Does not include the main title.
-    # @return [Array<String>]
-    # @example
-    #  record.additional_titles #=> ["Alternate title 1", "Alternate title 2"]
-    def additional_titles
-      CocinaDisplay::TitleBuilder.additional_titles(
-        cocina_doc.dig("description", "title")
-      )
-    end
-
     # Traverse nested FileSets and return an enumerator over their files.
     # Each file is a +Hash+.
     # @return [Enumerator] Enumerator over file hashes

data/lib/cocina_display/concerns/contributors.rb

@@ -0,0 +1,94 @@
+require_relative "../contributor"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for finding and formatting names for contributors
+    module Contributors
+      # The main author's name, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [String]
+      # @return [nil] if no main author is found
+      # @example
+      #   record.main_author #=> "Smith, John"
+      # @example with date
+      #   record.main_author(with_date: true) #=> "Smith, John, 1970-2020"
+      def main_author(with_date: false)
+        main_author_contributor&.display_name(with_date: with_date)
+      end
+
+      # All author names except the main one, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [Array<String>]
+      def additional_authors(with_date: false)
+        additional_author_contributors.map { |c| c.display_name(with_date: with_date) }
+      end
+
+      # All names of authors who are people, formatted for display.
+      # @param with_date [Boolean] Include life dates, if present
+      # @return [Array<String>]
+      def person_authors(with_date: false)
+        authors.filter(&:person?).map { |c| c.display_name(with_date: with_date) }
+      end
+
+      # All names of non-person authors, formatted for display.
+      # This includes organizations, conferences, families, etc.
+      # @return [Array<String>]
+      # @see https://github.com/sul-dlss/cocina-models/blob/main/docs/description_types.md#contributor-types
+      def impersonal_authors
+        authors.reject(&:person?).map(&:display_name)
+      end
+
+      # All names of authors that are organizations, formatted for display.
+      # @return [Array<String>]
+      def organization_authors
+        authors.filter(&:organization?).map(&:display_name)
+      end
+
+      # All names of authors that are conferences, formatted for display.
+      # @return [Array<String>]
+      def conference_authors
+        authors.filter(&:conference?).map(&:display_name)
+      end
+
+      # A string value for sorting by author that sorts missing values last.
+      # Ignores punctuation and leading/trailing spaces.
+      # @return [String]
+      def sort_author
+        (main_author_contributor&.display_name || "\u{10FFFF}").gsub(/[[:punct:]]*/, "").strip
+      end
+
+      private
+
+      # All contributors for the object, including authors, editors, etc.
+      # @return [Array<Contributor>]
+      def contributors
+        @contributors ||= path("$.description.contributor[*]").map { |c| Contributor.new(c) }
+      end
+
+      # All contributors with a "creator" or "author" role.
+      # @return [Array<Contributor>]
+      # @see Contributor#author?
+      def authors
+        contributors.filter(&:author?)
+      end
+
+      # Contributor object representing the primary author.
+      # Selected according to the following rules:
+      # 1. If there is a primary author or creator, use that.
+      # 2. If there are no primary authors or creators, use the first one.
+      # 3. If there are none at all, use the first contributor without any role.
+      # @return [Contributor]
+      # @return [nil] if no suitable contributor is found
+      def main_author_contributor
+        authors.find(&:primary?).presence || authors.first || contributors.find { |c| !c.role? }.presence
+      end
+
+      # All author/creator contributors except the main one.
+      # @return [Array<Contributor>]
+      def additional_author_contributors
+        return [] if authors.empty? || authors.one? || !authors.include?(main_author_contributor)
+        authors - [main_author_contributor]
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/events.rb

@@ -0,0 +1,137 @@
+require_relative "../dates/date"
+require_relative "../dates/date_range"
+require_relative "../imprint"
+
+module CocinaDisplay
+  module Concerns
+    module Events
+      # The earliest preferred publication date as a Date object.
+      # If the date was a range or interval, uses the start (or end if no start).
+      # Considers publication, creation, and capture dates in that order.
+      # Prefers dates marked as primary and those with a declared encoding.
+      # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
+      # @return [Date, nil]
+      # @see https://github.com/inukshuk/edtf-ruby
+      def pub_date_edtf(ignore_qualified: false)
+        date = pub_date(ignore_qualified: ignore_qualified)
+        return unless date
+
+        if date.is_a? CocinaDisplay::Dates::DateRange
+          date = date.start || date.stop
+        end
+
+        edtf_date = date.date
+        return unless edtf_date
+
+        if edtf_date.is_a? EDTF::Interval
+          edtf_date.from
+        else
+          edtf_date
+        end
+      end
+
+      # The earliest preferred publication year as an integer.
+      # If the date was a range or interval, uses the start (or end if no start).
+      # Considers publication, creation, and capture dates in that order.
+      # Prefers dates marked as primary and those with a declared encoding.
+      # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
+      # @return [Integer, nil]
+      # @note 6 BCE will return -5; 4 CE will return 4.
+      def pub_year_int(ignore_qualified: false)
+        pub_date_edtf(ignore_qualified: ignore_qualified)&.year
+      end
+
+      # String for displaying the earliest preferred publication year or range.
+      # Considers publication, creation, and capture dates in that order.
+      # Prefers dates marked as primary and those with a declared encoding.
+      # @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)
+        date = pub_date(ignore_qualified: ignore_qualified)
+        return unless date
+
+        date.decoded_value(allowed_precisions: [:year, :decade, :century])
+      end
+
+      # String for displaying the imprint statement(s).
+      # @return [String, nil]
+      # @see CocinaDisplay::Imprint#display_str
+      # @example
+      #   CocinaRecord.fetch('bt553vr2845').imprint_display_str #=> "New York : Meridian Book, 1993, c1967"
+      def imprint_display_str
+        imprints.map(&:display_str).compact_blank.join("; ")
+      end
+
+      private
+
+      # Event dates as an array of CocinaDisplay::Dates::Date objects.
+      # If type is provided, keep dates with a matching event type OR date type.
+      # @param type [Symbol, nil] Filter by event type (e.g. :publication).
+      # @return [Array<CocinaDisplay::Dates::Date>] The list of event dates
+      def event_dates(type: nil)
+        filter_expr = type.present? ? "?match(@.type, \"#{type}\")" : "*"
+
+        Enumerator::Chain.new(
+          path("$.description.event[*].date[#{filter_expr}]"),
+          path("$.description.event[#{filter_expr}].date[*]")
+        ).uniq.map do |date|
+          CocinaDisplay::Dates::Date.from_cocina(date)
+        end
+      end
+
+      # Array of CocinaDisplay::Imprint objects for all relevant Cocina events.
+      # Considers publication, creation, capture, and copyright events.
+      # Considers event types as well as date types if the event is untyped.
+      # Prefers events where the date was not encoded, if any.
+      # @return [Array<CocinaDisplay::Imprint>] The list of Imprint objects
+      def imprints
+        filter_expr = "\"(publication|creation|capture|copyright)\""
+
+        imprints = Enumerator::Chain.new(
+          path("$.description.event[?match(@.type, #{filter_expr})]"),
+          path("$.description.event[?@.date[?match(@.type, #{filter_expr})]]")
+        ).uniq.map do |event|
+          CocinaDisplay::Imprint.new(event)
+        end
+
+        imprints.reject(&:date_encoding?).presence || imprints
+      end
+
+      # The earliest preferred publication date as a CocinaDisplay::Dates::Date object.
+      # Considers publication, creation, and capture dates in that order.
+      # Prefers dates marked as primary and those with a declared encoding.
+      # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
+      # @return [CocinaDisplay::Dates::Date] The earliest preferred date
+      # @return [nil] if no dates are left after filtering
+      def pub_date(ignore_qualified: false)
+        [:publication, :creation, :capture].map do |type|
+          earliest_preferred_date(event_dates(type: type), ignore_qualified: ignore_qualified)
+        end.compact.first
+      end
+
+      # Choose the earliest, best date from a provided list of event dates.
+      # Rules to consider:
+      # 1. Reject any dates that were not parsed.
+      # 2. If `ignore_qualified` is true, reject any qualified dates.
+      # 3. If there are any primary dates, prefer those dates.
+      # 4. If there are any encoded dates, prefer those dates.
+      # 5. From whatever is left, choose the earliest date.
+      # @param dates [Array<CocinaDisplay::Dates::Date>] The list of dates
+      # @param ignore_qualified [Boolean] Reject qualified dates (e.g. approximate)
+      # @return [CocinaDisplay::Dates::Date] The earliest preferred date
+      # @return [nil] if no dates are left after filtering
+      def earliest_preferred_date(dates, ignore_qualified: false)
+        return nil if dates.empty?
+
+        dates.filter!(&:parsed_date?)
+        dates.reject!(&:approximate?) if ignore_qualified
+        dates = dates.filter(&:primary?).presence || dates
+        dates = dates.filter(&:encoding?).presence || dates
+
+        dates.min
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/identifiers.rb

@@ -0,0 +1,60 @@
+module CocinaDisplay
+  module Concerns
+    # Methods for extracting and formatting identifiers from Cocina records.
+    module Identifiers
+      # The DRUID for the object, with the +druid:+ prefix.
+      # @return [String]
+      # @example
+      #   record.druid #=> "druid:bb099mt5053"
+      def druid
+        cocina_doc["externalIdentifier"]
+      end
+
+      # The DRUID for the object, without the +druid:+ prefix.
+      # @return [String]
+      # @example
+      #   record.bare_druid #=> "bb099mt5053"
+      def bare_druid
+        druid.delete_prefix("druid:")
+      end
+
+      # The DOI for the object, if there is one – just the identifier part.
+      # @return [String, nil]
+      # @example
+      #   record.doi #=> "10.25740/ppax-bf07"
+      def doi
+        doi_id = path("$.identification.doi").first ||
+          path("$.description.identifier[?match(@.type, 'doi|DOI')].value").first ||
+          path("$.description.identifier[?search(@.uri, 'doi.org')].uri").first
+
+        URI(doi_id).path.delete_prefix("/") if doi_id.present?
+      end
+
+      # The DOI as a URL, if there is one. Any valid DOI should resolve via doi.org.
+      # @return [String, nil]
+      # @example
+      #   record.doi_url #=> "https://doi.org/10.25740/ppax-bf07"
+      def doi_url
+        URI.join("https://doi.org", doi).to_s if doi.present?
+      end
+
+      # The HRID of the item in FOLIO, if defined.
+      # @note This doesn't imply the object is available in Searchworks at this ID.
+      # @return [String, nil]
+      # @example
+      #   record.folio_hrid #=> "a12845814"
+      def folio_hrid
+        path("$.identification.catalogLinks[?(@.catalog == 'folio')].catalogRecordId").first
+      end
+
+      # The FOLIO HRID if defined, otherwise the bare DRUID.
+      # @note This doesn't imply the object is available in Searchworks at this ID.
+      # @see folio_hrid
+      # @see bare_druid
+      # @return [String]
+      def searchworks_id
+        folio_hrid || bare_druid
+      end
+    end
+  end
+end

data/lib/cocina_display/concerns/titles.rb

@@ -0,0 +1,64 @@
+require_relative "../title_builder"
+
+module CocinaDisplay
+  module Concerns
+    # Methods for finding and formatting titles.
+    module Titles
+      # The main title for the object, without subtitle, part name, etc.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#main_title
+      # @note This corresponds to the "short title" in MODS XML, or MARC 245$a only.
+      # @return [String]
+      def main_title
+        CocinaDisplay::TitleBuilder.main_title(cocina_titles).first
+      end
+
+      # The full title for the object, including subtitle, part name, etc.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#full_title
+      # @note This corresponds to the entire MARC 245 field.
+      # @return [String]
+      def full_title
+        CocinaDisplay::TitleBuilder.full_title(cocina_titles, catalog_links: catalog_links).first
+      end
+
+      # The full title, joined together with additional punctuation.
+      # If there are multiple titles, uses the first.
+      # @see CocinaDisplay::TitleBuilder#build
+      # @return [String]
+      def display_title
+        CocinaDisplay::TitleBuilder.build(cocina_titles, catalog_links: catalog_links)
+      end
+
+      # Any additional titles for the object excluding the main title.
+      # @return [Array<String>]
+      # @see CocinaDisplay::TitleBuilder#additional_titles
+      def additional_titles
+        CocinaDisplay::TitleBuilder.additional_titles(cocina_titles)
+      end
+
+      # A string value for sorting by title that sorts missing values last.
+      # Ignores punctuation, leading/trailing spaces, and non-sorting characters.
+      # @see CocinaDisplay::TitleBuilder#sort_title
+      # @return [String]
+      def sort_title
+        CocinaDisplay::TitleBuilder.sort_title(cocina_titles, catalog_links: catalog_links).first || "\u{10FFFF}"
+      end
+
+      private
+
+      # The titles from the Cocina document, as an array of hashes.
+      # @return [Array<Hash>]
+      def cocina_titles
+        @cocina_titles ||= Array(cocina_doc.dig("description", "title"))
+      end
+
+      # The catalog links from the Cocina document, as an array of hashes.
+      # These link to FOLIO and can include part labels used to construct titles.
+      # @return [Array<Hash>]
+      def catalog_links
+        @catalog_links ||= Array(cocina_doc.dig("identification", "catalogLinks"))
+      end
+    end
+  end
+end