cocina_display 0.5.0 → 0.6.0

data/lib/cocina_display/marc_relator_codes.rb

@@ -0,0 +1,314 @@
+# Map of MARC relator codes to human-readable terms.
+# https://www.loc.gov/marc/relators/relaterm.html
+
+module CocinaDisplay
+  MARC_RELATOR = {
+    "abr" => "abridger",
+    "acp" => "art copyist",
+    "act" => "actor",
+    "adi" => "art director",
+    "adp" => "adapter",
+    "aft" => "author of afterword, colophon, etc.", # discontinued
+    "anc" => "announcer",
+    "anl" => "analyst",
+    "anm" => "animator",
+    "ann" => "annotator",
+    "ant" => "bibliographic antecedent",
+    "ape" => "appellee",
+    "apl" => "appellant",
+    "app" => "applicant",
+    "aqt" => "author in quotations or text abstracts",
+    "arc" => "architect",
+    "ard" => "artistic director",
+    "arr" => "arranger",
+    "art" => "artist",
+    "asg" => "assignee",
+    "asn" => "associated name",
+    "ato" => "autographer",
+    "att" => "attributed name",
+    "auc" => "auctioneer",
+    "aud" => "author of dialog",
+    "aue" => "audio engineer",
+    "aui" => "author of introduction, etc.", # discontinued
+    "aup" => "audio producer",
+    "aus" => "screenwriter",
+    "aut" => "author",
+    "bdd" => "binding designer",
+    "bjd" => "bookjacket designer",
+    "bka" => "book artist",
+    "bkd" => "book designer",
+    "bkp" => "book producer",
+    "blw" => "blurb writer",
+    "bnd" => "binder",
+    "bpd" => "bookplate designer",
+    "brd" => "broadcaster",
+    "brl" => "braille embosser",
+    "bsl" => "bookseller",
+    "cad" => "casting director",
+    "cas" => "caster",
+    "ccp" => "conceptor",
+    "chr" => "choreographer",
+    "clb" => "collaborator", # discontinued
+    "cli" => "client",
+    "cll" => "calligrapher",
+    "clr" => "colorist",
+    "clt" => "collotyper",
+    "cmm" => "commentator",
+    "cmp" => "composer",
+    "cmt" => "compositor",
+    "cnd" => "conductor",
+    "cng" => "cinematographer",
+    "cns" => "censor",
+    "coe" => "contestant-appellee",
+    "col" => "collector",
+    "com" => "compiler",
+    "con" => "conservator",
+    "cop" => "camera operator",
+    "cor" => "collection registrar",
+    "cos" => "contestant",
+    "cot" => "contestant-appellant",
+    "cou" => "court governed",
+    "cov" => "cover designer",
+    "cpc" => "copyright claimant",
+    "cpe" => "complainant-appellee",
+    "cph" => "copyright holder",
+    "cpl" => "complainant",
+    "cpt" => "complainant-appellant",
+    "cre" => "creator",
+    "crp" => "correspondent",
+    "crr" => "corrector",
+    "crt" => "court reporter",
+    "csl" => "consultant",
+    "csp" => "consultant to a project",
+    "cst" => "costume designer",
+    "ctb" => "contributor",
+    "cte" => "contestee-appellee",
+    "ctg" => "cartographer",
+    "ctr" => "contractor",
+    "cts" => "contestee",
+    "ctt" => "contestee-appellant",
+    "cur" => "curator",
+    "cwt" => "commentator for written text",
+    "dbd" => "dubbing director",
+    "dbp" => "distribution place",
+    "dfd" => "defendant",
+    "dfe" => "defendant-appellee",
+    "dft" => "defendant-appellant",
+    "dgc" => "degree committee member",
+    "dgg" => "degree granting institution",
+    "dgs" => "degree supervisor",
+    "dis" => "dissertant",
+    "djo" => "dj",
+    "dln" => "delineator",
+    "dnc" => "dancer",
+    "dnr" => "donor",
+    "dpc" => "depicted",
+    "dpt" => "depositor",
+    "drm" => "draftsman",
+    "drt" => "director",
+    "dsr" => "designer",
+    "dst" => "distributor",
+    "dtc" => "data contributor",
+    "dte" => "dedicatee",
+    "dtm" => "data manager",
+    "dto" => "dedicator",
+    "dub" => "dubious author",
+    "edc" => "editor of compilation",
+    "edd" => "editorial director",
+    "edm" => "editor of moving image work",
+    "edt" => "editor",
+    "egr" => "engraver",
+    "elg" => "electrician",
+    "elt" => "electrotyper",
+    "eng" => "engineer",
+    "enj" => "enacting jurisdiction",
+    "etr" => "etcher",
+    "evp" => "event place",
+    "exp" => "expert",
+    "fac" => "facsimilist",
+    "fds" => "film distributor",
+    "fld" => "field director",
+    "flm" => "film editor",
+    "fmd" => "film director",
+    "fmk" => "filmmaker",
+    "fmo" => "former owner",
+    "fmp" => "film producer",
+    "fnd" => "funder",
+    "fon" => "founder",
+    "fpy" => "first party",
+    "frg" => "forger",
+    "gdv" => "game developer",
+    "gis" => "geographic information specialist",
+    "grt" => "graphic technician", # discontinued
+    "his" => "host institution",
+    "hnr" => "honoree",
+    "hst" => "host",
+    "ill" => "illustrator",
+    "ilu" => "illuminator",
+    "ink" => "inker",
+    "ins" => "inscriber",
+    "inv" => "inventor",
+    "isb" => "issuing body",
+    "itr" => "instrumentalist",
+    "ive" => "interviewee",
+    "ivr" => "interviewer",
+    "jud" => "judge",
+    "jug" => "jurisdiction governed",
+    "lbr" => "laboratory",
+    "lbt" => "librettist",
+    "ldr" => "laboratory director",
+    "led" => "lead",
+    "lee" => "libelee-appellee",
+    "lel" => "libelee",
+    "len" => "lender",
+    "let" => "libelee-appellant",
+    "lgd" => "lighting designer",
+    "lie" => "libelant-appellee",
+    "lil" => "libelant",
+    "lit" => "libelant-appellant",
+    "lsa" => "landscape architect",
+    "lse" => "licensee",
+    "lso" => "licensor",
+    "ltg" => "lithographer",
+    "ltr" => "letterer",
+    "lyr" => "lyricist",
+    "mcp" => "music copyist",
+    "mdc" => "metadata contact",
+    "med" => "medium",
+    "mfp" => "manufacture place",
+    "mfr" => "manufacturer",
+    "mka" => "makeup artist",
+    "mod" => "moderator",
+    "mon" => "monitor",
+    "mrb" => "marbler",
+    "mrk" => "markup editor",
+    "msd" => "musical director",
+    "mte" => "metal-engraver",
+    "mtk" => "minute taker",
+    "mup" => "music programmer",
+    "mus" => "musician",
+    "mxe" => "mixing engineer",
+    "nan" => "news anchor",
+    "nrt" => "narrator",
+    "onp" => "onscreen participant",
+    "opn" => "opponent",
+    "org" => "originator",
+    "orm" => "organizer",
+    "osp" => "onscreen presenter",
+    "oth" => "other",
+    "own" => "owner",
+    "pad" => "place of address",
+    "pan" => "panelist",
+    "pat" => "patron",
+    "pbd" => "publishing director",
+    "pbl" => "publisher",
+    "pdr" => "project director",
+    "pfr" => "proofreader",
+    "pht" => "photographer",
+    "plt" => "platemaker",
+    "pma" => "permitting agency",
+    "pmn" => "production manager",
+    "pnc" => "penciller",
+    "pop" => "printer of plates",
+    "ppm" => "papermaker",
+    "ppt" => "puppeteer",
+    "pra" => "praeses",
+    "prc" => "process contact",
+    "prd" => "production personnel",
+    "pre" => "presenter",
+    "prf" => "performer",
+    "prg" => "programmer",
+    "prm" => "printmaker",
+    "prn" => "production company",
+    "pro" => "producer",
+    "prp" => "production place",
+    "prs" => "production designer",
+    "prt" => "printer",
+    "prv" => "provider",
+    "pta" => "patent applicant",
+    "pte" => "plaintiff-appellee",
+    "ptf" => "plaintiff",
+    "pth" => "patent holder",
+    "ptt" => "plaintiff-appellant",
+    "pup" => "publication place",
+    "rap" => "rapporteur",
+    "rbr" => "rubricator",
+    "rcd" => "recordist",
+    "rce" => "recording engineer",
+    "rcp" => "addressee",
+    "rdd" => "radio director",
+    "red" => "redaktor",
+    "ren" => "renderer",
+    "res" => "researcher",
+    "rev" => "reviewer",
+    "rpc" => "radio producer",
+    "rps" => "repository",
+    "rpt" => "reporter",
+    "rpy" => "responsible party",
+    "rse" => "respondent-appellee",
+    "rsg" => "restager",
+    "rsp" => "respondent",
+    "rsr" => "restorationist",
+    "rst" => "respondent-appellant",
+    "rth" => "research team head",
+    "rtm" => "research team member",
+    "rxa" => "remix artist",
+    "sad" => "scientific advisor",
+    "sce" => "scenarist",
+    "scl" => "sculptor",
+    "scr" => "scribe",
+    "sde" => "sound engineer",
+    "sds" => "sound designer",
+    "sec" => "secretary",
+    "sfx" => "special effects provider",
+    "sgd" => "stage director",
+    "sgn" => "signer",
+    "sht" => "spporting host",
+    "sll" => "seller",
+    "sng" => "singer",
+    "spk" => "speaker",
+    "spn" => "sponsor",
+    "spy" => "second party",
+    "srv" => "surveyor",
+    "std" => "set designer",
+    "stg" => "setting",
+    "stl" => "storyteller",
+    "stm" => "stage manager",
+    "stn" => "standards body",
+    "str" => "stereotyper",
+    "swd" => "software developer",
+    "tad" => "technical advisor",
+    "tau" => "television writer",
+    "tcd" => "technical director",
+    "tch" => "teacher",
+    "ths" => "thesis advisor",
+    "tld" => "television director",
+    "tlg" => "television guest",
+    "tlh" => "television host",
+    "tlp" => "television producer",
+    "trc" => "transcriber",
+    "trl" => "translator",
+    "tyd" => "type designer",
+    "tyg" => "typographer",
+    "uvp" => "university place",
+    "vac" => "voice actor",
+    "vdg" => "videographer",
+    "vfx" => "visual effects provider",
+    "voc" => "vocalist", # discontinued
+    "wac" => "writer of added commentary",
+    "wal" => "writer of added lyrics",
+    "wam" => "writer of accompanying material",
+    "wat" => "writer of added text",
+    "waw" => "writer of afterword",
+    "wdc" => "woodcutter",
+    "wde" => "wood engraver",
+    "wfs" => "writer of film story",
+    "wft" => "writer of intertitles",
+    "wfw" => "writer of foreword",
+    "win" => "writer of introduction",
+    "wit" => "witness",
+    "wpr" => "writer of preface",
+    "wst" => "writer of supplementary textual content",
+    "wts" => "writer of television story"
+  }
+end

data/lib/cocina_display/title_builder.rb

@@ -53,7 +53,7 @@ module CocinaDisplay
     def self.sort_title(titles, catalog_links: [])
       part_label = catalog_links.find { |link| link["catalog"] == "folio" }&.fetch("partLabel", nil)
       [new(strategy: :first, add_punctuation: false, only_one_parallel_value: false, part_label: part_label, sortable: true).build(titles)]
-        .flatten.compact.map { |title| title.gsub(/[[:punct:]]*/, "").strip }
+        .flatten.compact.map { |title| title.gsub(/[[:punct:]]*/, "").squeeze(" ").strip }
     end
 
     # @param strategy [Symbol] ":first" selects a single title value based on precedence of
@@ -116,6 +116,7 @@ module CocinaDisplay
     end
 
     def extract_title(cocina_title)
+      return if cocina_title.blank?
       title_values = if cocina_title["value"]
         cocina_title["value"]
       elsif cocina_title["structuredValue"].present?

data/lib/cocina_display/utils.rb

@@ -19,7 +19,7 @@ module CocinaDisplay
       end.delete_suffix(delimiter)
     end
 
-    # Recursively flatten structured and parallel values in Cocina metadata.
+    # Recursively flatten structured, parallel, and grouped values in Cocina metadata.
     # Returns a list of hashes representing the "leaf" nodes with +value+ key.
     # @return [Array<Hash>] List of node hashes with "value" present
     # @param cocina [Hash] The Cocina structured data to flatten
@@ -40,10 +40,33 @@ module CocinaDisplay
       return [cocina] if cocina["value"].present?
       return cocina.flat_map { |node| flatten_nested_values(node, output) } if cocina.is_a?(Array)
 
-      nested_values = Array(cocina["structuredValue"]) + Array(cocina["parallelValue"])
+      nested_values = Array(cocina["structuredValue"]) + Array(cocina["parallelValue"]) + Array(cocina["groupedValue"])
       return output unless nested_values.any?
 
       nested_values.flat_map { |node| flatten_nested_values(node, output) }
     end
+
+    # Recursively remove empty values from a hash, including nested hashes and arrays.
+    # @param hash [Hash] The hash to process
+    # @param output [Hash] Used for recursion, should be empty on first call
+    # @return [Hash] The hash with empty values removed
+    # @example
+    #  hash = { "name" => "", "age" => nil, "address => { "city" => "Anytown", "state" => [] } }
+    #  #  Utils.remove_empty_values(hash)
+    #  #=> { "address" => { "city" => "Anytown" } }
+    def self.deep_compact_blank(hash, output = {})
+      hash.each do |key, value|
+        if value.is_a?(Hash)
+          nested = deep_compact_blank(value)
+          output[key] = nested unless nested.empty?
+        elsif value.is_a?(Array)
+          compacted_array = value.map { |v| deep_compact_blank(v) }.reject(&:blank?)
+          output[key] = compacted_array unless compacted_array.empty?
+        elsif value.present?
+          output[key] = value
+        end
+      end
+      output
+    end
   end
 end

data/lib/cocina_display/version.rb

@@ -2,5 +2,5 @@
 
 # :nodoc:
 module CocinaDisplay
-  VERSION = "0.5.0" # :nodoc:
+  VERSION = "0.6.0" # :nodoc:
 end

data/script/find_records.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# This script is a simple, brute-force method for finding records that
+# exhibit certain characteristics in the public Cocina JSON for testing.
+#
+# It queries purl-fetcher for all DRUIDs released to a specific target and
+# then fetches each corresponding public Cocina record from PURL and examines it.
+#
+# You need to be on VPN to do this, as the purl-fetcher API is only accessible
+# from within the Stanford network.
+#
+# To use, modify any of the noted items below, then run:
+# $ bundle exec ruby script/find_records.rb
+#
+# You can exit early with Ctrl-C, and it will report how many records were
+# checked before exiting. Running through an entire target will take awhile,
+# on the order of 30 minutes or more.
+
+require "benchmark"
+require "pp"
+require "purl_fetcher/client"
+require "cocina_display"
+require "cocina_display/utils"
+
+# This should correspond to one of the release targets available in purl-fetcher,
+# i.e. "Searchworks", "Earthworks", etc.
+RELEASE_TARGET = "Searchworks"
+
+# Modify this expression to match the JSON path you want to search, or just
+# modify the `examine_record` method directly.
+PATH_EXPR = "$..[?length(@.groupedValue) > 0]"
+
+# Modify this method as needed to change what you're looking for in each record.
+# It takes a CocinaRecord object and should return an array of [path, result] pairs.
+def examine_record(record)
+  record.path(PATH_EXPR).map { |value, _node, _key, path| [path, CocinaDisplay::Utils.deep_compact_blank(value)] }
+end
+
+# Track total records in target and how many we've seen
+released_to_target = []
+processed_records = 0
+
+# Handle Ctrl-C gracefully
+Signal.trap("INT") do
+  puts "\nExiting after processing #{processed_records} records."
+  exit
+end
+
+# Fetch everything from purl-fetcher; note that this is one single HTTP request
+# that returns a massive JSON response – it can be quite slow
+puts "Finding records released to #{RELEASE_TARGET}..."
+client = PurlFetcher::Client::Reader.new
+query_time = Benchmark.realtime do
+  client.released_to(RELEASE_TARGET).each do |record|
+    released_to_target << record["druid"].delete_prefix("druid:")
+  end
+rescue Faraday::ConnectionFailed => e
+  puts "Connection failed: #{e.message}; are you on VPN?"
+  exit 1
+end
+puts "Found #{released_to_target.size} records released to #{RELEASE_TARGET} in #{query_time.round(2)} seconds"
+
+# Iterate through the list of DRUIDs and fetch each one from PURL, creating a
+# CocinaRecord object. Then call our examine_record method on it and if
+# anything was returned, print the DRUID and the results.
+released_to_target.each do |druid|
+  begin
+    cocina_record = CocinaDisplay::CocinaRecord.fetch(druid)
+    processed_records += 1
+  rescue => e
+    puts "Error fetching record #{druid}: #{e.message}"
+    next
+  end
+
+  results = examine_record(cocina_record)
+  next if results.empty?
+
+  puts "Druid: #{druid}"
+  results.each do |path, result|
+    puts "  Path: #{path}"
+    puts "  Result: #{result.pretty_inspect}\n"
+  end
+
+  puts "-" * 80
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cocina_display
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Nick Budak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-11 00:00:00.000000000 Z
+date: 2025-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: janeway-jsonpath
@@ -156,6 +156,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.9.1
+- !ruby/object:Gem::Dependency
+  name: purl_fetcher-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 description:
 email:
 - budak@stanford.edu
@@ -173,18 +187,23 @@ files:
 - lib/cocina_display/concerns/access.rb
 - lib/cocina_display/concerns/contributors.rb
 - lib/cocina_display/concerns/events.rb
+- lib/cocina_display/concerns/forms.rb
 - lib/cocina_display/concerns/identifiers.rb
 - lib/cocina_display/concerns/subjects.rb
 - lib/cocina_display/concerns/titles.rb
 - lib/cocina_display/contributor.rb
 - lib/cocina_display/dates/date.rb
 - lib/cocina_display/dates/date_range.rb
-- lib/cocina_display/imprint.rb
+- lib/cocina_display/events/event.rb
+- lib/cocina_display/events/imprint.rb
+- lib/cocina_display/events/location.rb
 - lib/cocina_display/marc_country_codes.rb
+- lib/cocina_display/marc_relator_codes.rb
 - lib/cocina_display/subject.rb
 - lib/cocina_display/title_builder.rb
 - lib/cocina_display/utils.rb
 - lib/cocina_display/version.rb
+- script/find_records.rb
 - sig/cocina_display.rbs
 homepage: https://sul-dlss.github.io/cocina_display/
 licenses:

data/lib/cocina_display/imprint.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-require "edtf"
-require "active_support"
-require "active_support/core_ext/enumerable"
-require "active_support/core_ext/object/blank"
-
-require_relative "utils"
-require_relative "marc_country_codes"
-require_relative "dates/date"
-require_relative "dates/date_range"
-
-module CocinaDisplay
-  # Wrapper for Cocina events used to generate an imprint statement for display.
-  class Imprint
-    # Parse Cocina dates and convert any non-single dates to DateRange objects.
-    # This ensures that we can correctly deduplicate ranges against single dates.
-    # @param cocina_dates [Array<Hash>] Array of Cocina date hashes
-    # @return [Array<CocinaDisplay::Dates::Date | CocinaDisplay::Dates::DateRange>]
-    def self.parse_dates(cocina_dates)
-      cocina_dates.map { |cd| CocinaDisplay::Dates::Date.from_cocina(cd) }.filter(&:parsable?).compact
-    end
-
-    attr_reader :cocina, :dates
-
-    # Initialize the imprint with Cocina event data.
-    # @param cocina [Hash] Cocina structured data for a single event
-    def initialize(cocina)
-      @cocina = cocina
-      @dates = self.class.parse_dates(Array(cocina["date"]))
-    end
-
-    # The entire imprint statement formatted as a string for display.
-    # @return [String]
-    def display_str
-      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: ", ")
-    end
-
-    # Were any of the dates encoded?
-    # Used to detect which event(s) most likely represent the actual imprint(s).
-    def date_encoding?
-      @dates.any?(&:encoding?)
-    end
-
-    private
-
-    # The date portion of the imprint statement, comprising all unique dates.
-    # @return [String]
-    def date_str
-      Utils.compact_and_join(unique_dates_for_display.map(&:qualified_value))
-    end
-
-    # The editions portion of the imprint statement, combining all edition notes.
-    # @return [String]
-    def edition_str
-      Utils.compact_and_join(Janeway.enum_for("$.note[?@.type == 'edition'].value", cocina))
-    end
-
-    # The place of publication, combining all location values.
-    # @return [String]
-    def place_str
-      Utils.compact_and_join(locations_for_display, delimiter: " : ")
-    end
-
-    # The publisher information, combining all name values for publishers.
-    # @return [String]
-    def publisher_str
-      Utils.compact_and_join(Janeway.enum_for("$.contributor[?@.role[?@.value == 'publisher']].name[*].value", cocina), delimiter: " : ")
-    end
-
-    # Get the place name for a location, decoding from MARC if necessary.
-    # Ignores the unknown/"various locations" country codes and returns nil.
-    # @param location [Hash] A location hash parsed from Cocina
-    # @return [String] The decoded location name
-    # @return [nil] If no valid location value is found
-    def decoded_location(location)
-      return location["value"] if location["value"].present?
-
-      if location.dig("source", "code") == "marccountry" &&
-          location["code"].present? &&
-          ["xx", "vp"].exclude?(location["code"])
-        CocinaDisplay::MARC_COUNTRY[location["code"]]
-      end
-    end
-
-    # Filter locations to display according to predefined rules.
-    # 1. Prefer unencoded locations (plain value) over encoded ones
-    # 2. If no unencoded locations but there are MARC country codes, decode them
-    # 3. Keep only unique locations after decoding
-    def locations_for_display
-      unencoded_locs, encoded_locs = Array(cocina["location"]).partition { |loc| loc["value"].present? }
-      locs_for_display = unencoded_locs.presence || encoded_locs
-      locs_for_display.map { |loc| decoded_location(loc) }.compact_blank.uniq
-    end
-
-    # Filter dates for uniqueness using base value according to predefined rules.
-    # 1. For a group of dates with the same base value, choose a single one
-    # 2. Prefer unencoded dates over encoded ones when choosing a single date
-    # 3. Remove date ranges that duplicate any unencoded non-range dates
-    # @return [Array<CocinaDisplay::Dates::Date>]
-    # @see CocinaDisplay::Dates::Date#base_value
-    # @see https://consul.stanford.edu/display/chimera/MODS+display+rules#MODSdisplayrules-3b.%3CoriginInfo%3E
-    def unique_dates_for_display
-      # Choose a single date for each group with the same base value
-      deduped_dates = dates.group_by(&:base_value).map do |base_value, group|
-        if (unencoded = group.reject(&:encoding?)).any?
-          unencoded.first
-        else
-          group.first
-        end
-      end
-
-      # Remove any ranges that duplicate part of an unencoded non-range date
-      ranges, singles = deduped_dates.partition { |date| date.is_a?(CocinaDisplay::Dates::DateRange) }
-      unencoded_singles_dates = singles.reject(&:encoding?).flat_map(&:to_a)
-      ranges.reject! { |range| unencoded_singles_dates.any? { |date| range.as_interval.include?(date) } }
-
-      (singles + ranges).sort
-    end
-  end
-end