cocina_display 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e3637cdbaae1a3227f2cfac3186ea15648151c0d90e5d71f678d32bb4242487
-  data.tar.gz: 12ee8a16fc75ff83361bbc929d3d15693f9dcf121585d61654c8cd5da60ca2d8
+  metadata.gz: 6ef43e2d573c99c10d6db87974ff32091ff7e7d312bf2e812ef1043f513f291c
+  data.tar.gz: f04b35117201aaebff5e8d041d2776525dcd18a46bc408baf9d8649376d90618
 SHA512:
-  metadata.gz: 02cea2ac8bbb9ecab1d142f48e78d237762d6394615f87aed6a9aa535f2d34e2bea6b3d4629e0851853e9b8708d2578d26c9e1baec8a0a7c952c7c1d8deffc4a
-  data.tar.gz: ba18d7424b7114525a5100bf73b619e9dbae259e2ec35fb6f0a754981457d8c67b6f686c3a4d53ef98f29122291fd564e6768fb2a348744e3e54813df3b03049
+  metadata.gz: c36dd129d129ce44c7c516b670295b59f68732d0270664dda63ce119fe37ec60e68c6fd615e37ada5ecef06777db7be30cd708d0f0c461c18c97085e98eb553f
+  data.tar.gz: cddd56237670d908a6be7951e24fe62a0fbd3076fd0eff96693c7debc03fa9ab8e01157a330923938143ec2067a4d97d4ead339f44fd2b00d0bcf99ea92b6af0

data/README.md

@@ -28,31 +28,26 @@ 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.titles
-=> ["Bugatti Type 51A. Road & Track Salon January 1957"]
+> record.title
+=> "Bugatti Type 51A. Road & Track Salon January 1957"
 > record.content_type
 => "image"
 > record.iiif_manifest_url 
 => "https://purl.stanford.edu/bb112zx3193/iiif3/manifest"
-> record.cocina_doc.dig("description", "contributor", 0, "name", 0, "value")  # access the hash representation
+# access the hash representation
+> record.cocina_doc.dig("description", "contributor", 0, "name", 0, "value")  
 => "Hearst Magazines, Inc."
 ```
 
@@ -65,14 +60,15 @@ Fetching data deeply nested in the record, especially when you need to filter ba
 The previous example used `Hash#dig` to access the first contributor's first name value. Using `#path`, you can query for _all_ contributor name values, or even filter to particular contributors:
 
 ```ruby
-> record.path('$.description.contributor[*].name[*].value').search # name values for all contributors in description
+# name values for all contributors in description
+> record.path('$.description.contributor[*].name[*].value').search
 => ["Hearst Magazines, Inc.", "Chesebrough, Jerry"]
-> record.path("$.description.contributor[?@.role[?@.value == 'photographer']].name[*].value").search # only contributors with a role with value "photographer"
+# only contributors with a role with value "photographer"
+> record.path("$.description.contributor[?@.role[?@.value == 'photographer']].name[*].value").search
 => ["Chesebrough, Jerry"]
-> 
 ```
 
-The JsonPath implementation used is [`janeway-jsonpath`](https://www.rubydoc.info/gems/janeway-jsonpath/0.6.0/file/README.md), which supports the full syntax from the [finalized 2024 version of the specification](https://www.rfc-editor.org/rfc/rfc9535.html). Results returned from `#path` are Enumerators.
+The JsonPath implementation used is [janeway](https://www.rubydoc.info/gems/janeway-jsonpath/0.6.0/file/README.md), which supports the full syntax from the [finalized 2024 version of the specification](https://www.rfc-editor.org/rfc/rfc9535.html). Results returned from `#path` are Enumerators.
 
 In the following example, we start an expression with `"$.."` to search for contributor nodes at _any_ level (e.g. `event.contributors`) and discover that there is a third contributor, but it has no `name` value. Using the `['code', 'value']` syntax, we can retrieve both `code` and `value` and show where they came from:
 
@@ -103,7 +99,7 @@ Documentation is generated using [yard](https://yardoc.org). You can generate it
 
 ## Background
 
-Historically, applications at SUL used a combination of several gems to render objects represented by MODS XML. With the transition to the Cocina data model, infrastructure applications adopted the [`cocina-models` gem](https://github.com/sul-dlss/cocina-models), which provides accessor objects and validators over Cocina JSON. Internal applications can fetch such objects over HTTP using [`dor-services-client`](https://github.com/sul-dlss/dor-services-client).
+Historically, applications at SUL used a combination of several gems to render objects represented by MODS XML. With the transition to the Cocina data model, infrastructure applications adopted the [cocina-models gem](https://github.com/sul-dlss/cocina-models), which provides accessor objects and validators over Cocina JSON. Internal applications can fetch such objects over HTTP using [dor-services-client](https://github.com/sul-dlss/dor-services-client).
 
 On the access side, Cocina JSON (the "public Cocina") is available statically via [PURL](https://purl.stanford.edu), but is only updated when an object is published ("shelved") from SDR. This frequently results in data that is technically invalid with respect to `cocina-models` but is still valid in the context of a patron-facing application.
 

data/lib/cocina_display/cocina_record.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
-require "cocina/models"
 require "janeway"
+require "json"
+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"
 
 module CocinaDisplay
-  # Public Cocina metadata for an SDR object
+  # Public Cocina metadata for an SDR object, as fetched from PURL.
   class CocinaRecord
+    include CocinaDisplay::Concerns::Events
+
+    # 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
@@ -109,6 +128,28 @@ 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/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