cocina_display 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca2e2a44615201a7709f9a7b4d7e0792aaea7f14344dc93b3bf800acdef83e91
-  data.tar.gz: 8dfd7f06a65930d2d639083c1235a7a9e41d8bcf59ac12f60bd4b2b87118d784
+  metadata.gz: 6ef43e2d573c99c10d6db87974ff32091ff7e7d312bf2e812ef1043f513f291c
+  data.tar.gz: f04b35117201aaebff5e8d041d2776525dcd18a46bc408baf9d8649376d90618
 SHA512:
-  metadata.gz: 11e6b9f94eaa777d1069deb972e046cda240e815524a2d938a8df97f75556393a10706c73dcaa9172a2c2a3cb90a459ed0ce8ca3c9d04f5f025242629b10f809
-  data.tar.gz: be9642a9205aca7b1aac2c73cb6250dbc1def18cba5fa88b3afdb4839186f6832ca80404f04ca47680fe181738276317f27b9c751c527b6ded4b6d637d1d1254
+  metadata.gz: c36dd129d129ce44c7c516b670295b59f68732d0270664dda63ce119fe37ec60e68c6fd615e37ada5ecef06777db7be30cd708d0f0c461c18c97085e98eb553f
+  data.tar.gz: cddd56237670d908a6be7951e24fe62a0fbd3076fd0eff96693c7debc03fa9ab8e01157a330923938143ec2067a4d97d4ead339f44fd2b00d0bcf99ea92b6af0

data/README.md

@@ -28,24 +28,18 @@ 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
 => "Bugatti Type 51A. Road & Track Salon January 1957"
 > record.content_type

data/lib/cocina_display/cocina_record.rb

@@ -2,16 +2,29 @@
 
 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"
 
 module CocinaDisplay
   # 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

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