berkeley_library-location 2.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: af0453d4f60ad7276b64c48937b36cc76d250eb2a41ff23914f30d7c35edbf85
+  data.tar.gz: 2cb9fb72635d239f6b6726f4278b555913b9f209dddb43dbeb03072b495de3d1
+SHA512:
+  metadata.gz: 5a9dc82778e93207bc4f23e328b1699f4cb58abed4b7deda70cb8ec713b4c47a95d36be19fdab962b591df78c15182af841d111ef941a6d8ab2436b6587109fe
+  data.tar.gz: f6f78720f85d04530e656940d5dcaa1056cfd086de7ca280253d4a3d6aeca22a98236ad6ba2dc6666c4b3b6e765bd1e0cf3842dc69104e7b30eaa50685a69e9e

data/CHANGES.md

@@ -0,0 +1,33 @@
+# 2.0.0 (2023-06-06)
+
+- Rename from "holdings" to "location"
+
+# 1.0.5 (2023-06-01)
+
+- Update to `berkeley_library-util` 0.1.9 to handle non-ASCII OCLC numbers
+- Fix issue where locating blank columns could fail on spreadsheets with nil rows
+
+# 1.0.4 (2023-04-28)
+
+- Escape OCLC numbers before constructing query URIs
+  (not an issue for correct OCLC numbers, but can be an issue in the event of bad data)
+
+# 1.0.3 (2023-04-27)
+
+- Fix issue requiring RubyXL extensions to be explicitly required 
+
+# 1.0.2 (2023-04-27)
+
+- Overwrite existing blank columns when writing results to spreadsheet
+
+# 1.0.1 (2023-04-26)
+
+- First working RubyGems release
+
+# 1.0.0 (2023-04-25)
+
+- Initial (broken) RubyGems release
+
+# 0.1.0 (2023-02-24)
+
+- Initial release

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2023 The Regents of the University of California
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,6 @@
+# BerkeleyLibrary::Location
+
+[![Build Status](https://github.com/BerkeleyLibrary/location/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/BerkeleyLibrary/location/actions/workflows/build.yml)
+[![Gem Version](https://img.shields.io/gem/v/berkeley_library-location.svg)](https://github.com/BerkeleyLibrary/location/releases)
+
+Miscellaneous location-related utilities for the UC Berkeley Library.

data/lib/berkeley_library/location/constants.rb

@@ -0,0 +1,8 @@
+module BerkeleyLibrary
+  module Location
+    module Constants
+      OCLC_COL_HEADER = 'OCLC Number'.freeze
+
+    end
+  end
+end

data/lib/berkeley_library/location/hathi_trust/config.rb

@@ -0,0 +1,56 @@
+require 'berkeley_library/util'
+
+module BerkeleyLibrary
+  module Location
+    module HathiTrust
+      module Config
+        include BerkeleyLibrary::Util::URIs
+
+        ENV_HATHITRUST_BASE_URL = 'LIT_HATHITRUST_BASE_URL'.freeze
+
+        # The default HathiTrust base URL, if ENV_HATHITRUST_BASE_URL is not set.
+        DEFAULT_HATHITRUST_BASE_URL = 'https://catalog.hathitrust.org/api/'.freeze
+
+        class << self
+          include Config
+        end
+
+        def base_uri
+          @base_uri ||= default_hathitrust_base_uri
+        end
+
+        def base_uri=(value)
+          @base_uri = uri_or_nil(value)
+        end
+
+        private
+
+        def reset!
+          remove_instance_variable(:@base_uri) if instance_variable_defined?(:@base_uri)
+        end
+
+        def default_hathitrust_base_uri
+          uri_or_nil(default_hathitrust_base_url)
+        end
+
+        def default_hathitrust_base_url
+          ENV[ENV_HATHITRUST_BASE_URL] || rails_hathitrust_base_url || DEFAULT_HATHITRUST_BASE_URL
+        end
+
+        def rails_hathitrust_base_url
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:hathitrust_base_url)
+
+          rails_config.hathitrust_base_url
+        end
+
+        def rails_config
+          return unless defined?(Rails)
+          return unless (app = Rails.application)
+
+          app.config
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/hathi_trust/record_url_batch_request.rb

@@ -0,0 +1,56 @@
+require 'berkeley_library/location/hathi_trust/record_url_request_base'
+
+module BerkeleyLibrary
+  module Location
+    module HathiTrust
+      class RecordUrlBatchRequest
+        include RecordUrlRequestBase
+
+        # Per HathiTrust API docs: https://www.hathitrust.org/bib_api
+        MAX_BATCH_SIZE = 20
+
+        attr_reader :oclc_numbers
+
+        def initialize(oclc_numbers)
+          @oclc_numbers = ensure_valid_oclc_numbers!(oclc_numbers)
+        end
+
+        def execute
+          response_body = URIs.get(uri, log: false)
+          record_urls_from(response_body)
+        end
+
+        def uri
+          @uri ||= URIs.append(volumes_base_uri, 'json', URIs.path_escape(oclc_list))
+        end
+
+        private
+
+        def ensure_valid_oclc_numbers!(oclc_numbers)
+          raise ArgumentError, 'No OCLC numbers provided' if oclc_numbers.empty?
+          raise ArgumentError, "Too many OCLC numbers; expected <= #{MAX_BATCH_SIZE}, was #{oclc_numbers.size}" if oclc_numbers.size > MAX_BATCH_SIZE
+
+          OCLCNumber.ensure_oclc_numbers!(oclc_numbers)
+        end
+
+        def oclc_list
+          @oclc_list = oclc_numbers.map(&method(:key_for)).join('|')
+        end
+
+        def key_for(oclc_number)
+          "oclc:#{oclc_number}"
+        end
+
+        def record_urls_from(json_str)
+          json = JSON.parse(json_str)
+          oclc_numbers.filter_map do |oclc_num|
+            next unless (entry = json[key_for(oclc_num)])
+
+            record_url = find_record_url(entry, oclc_num)
+            [oclc_num, record_url] if record_url
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/hathi_trust/record_url_request.rb

@@ -0,0 +1,33 @@
+require 'berkeley_library/location/hathi_trust/record_url_request_base'
+
+module BerkeleyLibrary
+  module Location
+    module HathiTrust
+      class RecordUrlRequest
+        include RecordUrlRequestBase
+
+        attr_reader :oclc_number
+
+        def initialize(oclc_number)
+          @oclc_number = OCLCNumber.ensure_oclc_number!(oclc_number)
+        end
+
+        def execute
+          response_body = URIs.get(uri, log: false)
+          record_url_from(response_body, oclc_number)
+        end
+
+        def uri
+          @uri ||= URIs.append(volumes_base_uri, 'oclc', URIs.path_escape("#{oclc_number}.json"))
+        end
+
+        private
+
+        def record_url_from(json_str, oclc_number)
+          json_obj = JSON.parse(json_str)
+          find_record_url(json_obj, oclc_number)
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/hathi_trust/record_url_request_base.rb

@@ -0,0 +1,37 @@
+require 'json'
+require 'berkeley_library/util'
+require 'berkeley_library/location/oclc_number'
+require 'berkeley_library/location/hathi_trust/config'
+
+module BerkeleyLibrary
+  module Location
+    module HathiTrust
+      module RecordUrlRequestBase
+        include BerkeleyLibrary::Util
+
+        protected
+
+        def volumes_base_uri
+          URIs.append(Config.base_uri, 'volumes', 'brief')
+        end
+
+        def find_record_url(json_obj, oclc_number)
+          return unless (records = json_obj['records'])
+          return unless (record = find_record(records, oclc_number))
+
+          record['recordURL']
+        end
+
+        def find_record(records, oclc_number)
+          return if records.empty?
+
+          records.values.find do |rec|
+            (oclc_nums = rec['oclcs']) &&
+              oclc_nums.include?(oclc_number) &&
+              rec.key?('recordURL')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/hathi_trust.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('hathi_trust/*.rb', __dir__)).each(&method(:require))

data/lib/berkeley_library/location/location_result.rb

@@ -0,0 +1,29 @@
+require 'berkeley_library/location/world_cat/symbols'
+
+module BerkeleyLibrary
+  module Location
+    class LocationResult
+      attr_reader :oclc_number, :wc_symbols, :ht_record_url, :wc_error, :ht_error
+
+      def initialize(oclc_number, wc_symbols: [], wc_error: nil, ht_record_url: nil, ht_error: nil)
+        @oclc_number = oclc_number
+        @wc_symbols = wc_symbols
+        @wc_error = wc_error
+        @ht_record_url = ht_record_url
+        @ht_error = ht_error
+      end
+
+      def nrlf?
+        @has_nrlf ||= wc_symbols.intersection(WorldCat::Symbols::NRLF).any?
+      end
+
+      def srlf?
+        @has_srlf ||= wc_symbols.intersection(WorldCat::Symbols::SRLF).any?
+      end
+
+      def uc_symbols
+        @uc_symbols ||= wc_symbols.intersection(WorldCat::Symbols::UC)
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/module_info.rb

@@ -0,0 +1,14 @@
+module BerkeleyLibrary
+  module Location
+    module ModuleInfo
+      NAME = 'berkeley_library-location'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'Locaton-related utilities for the UC Berkeley Library'.freeze
+      DESCRIPTION = 'A collection of location-related utilities for the UC Berkeley Library'.freeze
+      LICENSE = 'MIT'.freeze
+      VERSION = '2.0.0'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/location'.freeze
+    end
+  end
+end

data/lib/berkeley_library/location/oclc_number.rb

@@ -0,0 +1,22 @@
+module BerkeleyLibrary
+  module Location
+    module OCLCNumber
+      class << self
+        def ensure_oclc_number!(oclc_number)
+          raise ArgumentError, 'OCLC number cannot be nil' if oclc_number.nil?
+          raise ArgumentError, "OCLC number #{oclc_number.inspect} is not a string" unless oclc_number.is_a?(String)
+          raise ArgumentError, 'OCLC number cannot be empty' if oclc_number == ''
+          raise ArgumentError, "OCLC number #{oclc_number.inspect} must not be blank" if oclc_number.strip == ''
+
+          oclc_number
+        end
+
+        def ensure_oclc_numbers!(oclc_numbers)
+          oclc_numbers.tap do |numbers|
+            numbers.each { |num| ensure_oclc_number!(num) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/world_cat/config.rb

@@ -0,0 +1,81 @@
+require 'berkeley_library/util/uris'
+
+module BerkeleyLibrary
+  module Location
+    module WorldCat
+      module Config
+        include BerkeleyLibrary::Util::URIs
+
+        # The environment variable from which to read the WorldCat API key.
+        ENV_WORLDCAT_API_KEY = 'LIT_WORLDCAT_API_KEY'.freeze
+
+        # The environment variable from which to read the WorldCat base URL.
+        ENV_WORLDCAT_BASE_URL = 'LIT_WORLDCAT_BASE_URL'.freeze
+
+        # The default WorldCat base URL, if ENV_WORLDCAT_BASE_URL is not set.
+        DEFAULT_WORLDCAT_BASE_URL = 'https://www.worldcat.org/webservices/'.freeze
+
+        class << self
+          include Config
+        end
+
+        # Sets the WorldCat API key.
+        # @param value [String] the API key.
+        attr_writer :api_key
+
+        # Gets the WorldCat API key.
+        # @return [String, nil] the WorldCat API key, or `nil` if not set.
+        def api_key
+          @api_key ||= default_worldcat_api_key
+        end
+
+        def base_uri
+          @base_uri ||= default_worldcat_base_uri
+        end
+
+        def base_uri=(value)
+          @base_uri = uri_or_nil(value)
+        end
+
+        private
+
+        def reset!
+          %i[@api_key @base_uri].each { |v| remove_instance_variable(v) if instance_variable_defined?(v) }
+        end
+
+        def default_worldcat_api_key
+          ENV[ENV_WORLDCAT_API_KEY] || rails_worldcat_api_key
+        end
+
+        def default_worldcat_base_uri
+          uri_or_nil(default_worldcat_base_url)
+        end
+
+        def default_worldcat_base_url
+          ENV[ENV_WORLDCAT_BASE_URL] || rails_worldcat_base_url || DEFAULT_WORLDCAT_BASE_URL
+        end
+
+        def rails_worldcat_base_url
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:worldcat_base_url)
+
+          rails_config.worldcat_base_url
+        end
+
+        def rails_worldcat_api_key
+          return unless (rails_config = self.rails_config)
+          return unless rails_config.respond_to?(:worldcat_api_key)
+
+          rails_config.worldcat_api_key
+        end
+
+        def rails_config
+          return unless defined?(Rails)
+          return unless (app = Rails.application)
+
+          app.config
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/world_cat/libraries_request.rb

@@ -0,0 +1,57 @@
+require 'nokogiri'
+require 'berkeley_library/util'
+require 'berkeley_library/location/oclc_number'
+require 'berkeley_library/location/world_cat/symbols'
+
+module BerkeleyLibrary
+  module Location
+    module WorldCat
+      # @see https://developer.api.oclc.org/wcv1#/Holdings
+      class LibrariesRequest
+        include BerkeleyLibrary::Util
+
+        XPATH_INST_ID_VALS = '/holdings/holding/institutionIdentifier/value'.freeze
+
+        attr_reader :oclc_number, :symbols
+
+        def initialize(oclc_number, symbols: Symbols::ALL)
+          @oclc_number = OCLCNumber.ensure_oclc_number!(oclc_number)
+          @symbols = Symbols.ensure_valid!(symbols)
+        end
+
+        def uri
+          @uri ||= URIs.append(libraries_base_uri, URIs.path_escape(oclc_number))
+        end
+
+        # TODO: Check that this works w/more than 10 results
+        #       See https://developer.api.oclc.org/wcv1#/Holdings
+        def params
+          @params ||= {
+            'oclcsymbol' => symbols.join(','),
+            'servicelevel' => 'full',
+            'frbrGrouping' => 'off',
+            'wskey' => Config.api_key
+          }
+        end
+
+        def execute
+          response_body = URIs.get(uri, params:, log: false)
+          inst_symbols = inst_symbols_from(response_body)
+          inst_symbols.select { |sym| symbols.include?(sym) } # just in case
+        end
+
+        private
+
+        def libraries_base_uri
+          URIs.append(Config.base_uri, 'catalog', 'content', 'libraries')
+        end
+
+        def inst_symbols_from(xml)
+          xml_doc = Nokogiri::XML(xml)
+          id_vals = xml_doc.xpath(XPATH_INST_ID_VALS)
+          id_vals.filter_map { |value| value.text.strip }
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/world_cat/symbols.rb

@@ -0,0 +1,37 @@
+module BerkeleyLibrary
+  module Location
+    module WorldCat
+      module Symbols
+        NRLF = %w[ZAP ZAPSP].freeze
+        SRLF = %w[HH0 ZAS ZASSP].freeze
+        RLF = (NRLF + SRLF).freeze
+
+        UC = %w[CLU CRU CUI CUN CUS CUT CUV CUX CUY CUZ MERUC].freeze
+        ALL = (RLF + UC).freeze
+
+        class << self
+          include Symbols
+        end
+
+        def valid?(sym)
+          ALL.include?(sym)
+        end
+
+        def ensure_valid!(symbols)
+          raise ArgumentError, "Not a list of institution symbols: #{symbols.inspect}" unless array_like?(symbols)
+          raise ArgumentError, 'No institution symbols provided' if symbols.empty?
+
+          return symbols unless (invalid = symbols.reject { |s| Symbols.valid?(s) }).any?
+
+          raise ArgumentError, "Invalid institution symbol(s): #{invalid.map(&:inspect).join(', ')}"
+        end
+
+        private
+
+        def array_like?(a)
+          %i[reject empty?].all? { |m| a.respond_to?(m) }
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/world_cat.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('world_cat/*.rb', __dir__)).each(&method(:require))

data/lib/berkeley_library/location/xlsx_reader.rb

@@ -0,0 +1,29 @@
+require 'marcel'
+require 'rubyXL'
+require 'berkeley_library/location/constants'
+require 'berkeley_library/util/xlsx/spreadsheet'
+
+module BerkeleyLibrary
+  module Location
+    class XLSXReader
+      include Constants
+
+      attr_reader :ss, :oclc_col_index
+
+      def initialize(xlsx_path)
+        @ss = Util::XLSX::Spreadsheet.new(xlsx_path)
+        @oclc_col_index = ss.find_column_index_by_header!(OCLC_COL_HEADER)
+      end
+
+      def each_oclc_number
+        return to_enum(:each_oclc_number) unless block_given?
+
+        ss.each_value(oclc_col_index, include_header: false) do |v|
+          next if (v_str = v.to_s).strip == ''
+
+          yield v_str
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location/xlsx_writer.rb

@@ -0,0 +1,140 @@
+require 'berkeley_library/logging'
+require 'berkeley_library/location/constants'
+
+module BerkeleyLibrary
+  module Location
+    class XLSXWriter
+      include Constants
+      include BerkeleyLibrary::Logging
+
+      COL_NRLF = 'NRLF'.freeze
+      COL_SRLF = 'SRLF'.freeze
+      COL_OTHER_UC = 'Other UC'.freeze
+      COL_WC_ERROR = 'WorldCat Error'.freeze
+
+      COL_HATHI_TRUST = 'Hathi Trust'.freeze
+      COL_HATHI_TRUST_ERROR = "#{COL_HATHI_TRUST} Error".freeze
+
+      V_NRLF = 'nrlf'.freeze
+      V_SRLF = 'srlf'.freeze
+
+      attr_reader :ss, :rlf, :uc, :hathi_trust
+
+      def initialize(ss, rlf: true, uc: true, hathi_trust: true)
+        @ss = ss
+        @rlf = rlf
+        @uc = uc
+        @hathi_trust = hathi_trust
+
+        ensure_columns!
+      end
+
+      def <<(result)
+        r_index = row_index_for(result.oclc_number)
+        write_wc_cols(r_index, result) if rlf || uc
+        write_ht_cols(r_index, result) if hathi_trust
+      end
+
+      private
+
+      def write_wc_cols(r_index, result)
+        write_wc_error(r_index, result)
+        write_rlf(r_index, result) if rlf
+        write_uc(r_index, result) if uc
+      end
+
+      def write_ht_cols(r_index, result)
+        write_ht_error(r_index, result)
+        write_hathi(r_index, result)
+      end
+
+      def ensure_columns!
+        if rlf
+          nrlf_col_index
+          srlf_col_index
+        end
+        uc_col_index if uc
+        ht_col_index if hathi_trust
+      end
+
+      def row_index_for(oclc_number)
+        row_index = row_index_by_oclc_number[oclc_number]
+        return row_index if row_index
+
+        raise ArgumentError, "Unknown OCLC number: #{oclc_number}"
+      end
+
+      def write_rlf(r_index, result)
+        ss.set_value_at(r_index, nrlf_col_index, V_NRLF) if result.nrlf?
+        ss.set_value_at(r_index, srlf_col_index, V_SRLF) if result.srlf?
+      end
+
+      def write_uc(r_index, result)
+        return if (uc_symbols = result.uc_symbols).empty?
+
+        ss.set_value_at(r_index, uc_col_index, uc_symbols.join(','))
+      end
+
+      def write_hathi(r_index, result)
+        return unless (ht_record_url = result.ht_record_url)
+
+        ss.set_value_at(r_index, ht_col_index, ht_record_url)
+      end
+
+      def write_wc_error(r_index, result)
+        return unless (wc_error = result.wc_error)
+
+        ss.set_value_at(r_index, wc_err_col_index, wc_error)
+      end
+
+      def write_ht_error(r_index, result)
+        return unless (ht_error = result.ht_error)
+
+        ss.set_value_at(r_index, ht_err_col_index, ht_error)
+      end
+
+      def oclc_col_index
+        @oclc_col_index ||= ss.find_column_index_by_header!(OCLC_COL_HEADER)
+      end
+
+      def nrlf_col_index
+        @nrlf_col_index ||= ss.ensure_column!(COL_NRLF)
+      end
+
+      def srlf_col_index
+        @srlf_col_index ||= ss.ensure_column!(COL_SRLF)
+      end
+
+      def uc_col_index
+        @uc_col_index ||= ss.ensure_column!(COL_OTHER_UC)
+      end
+
+      def wc_err_col_index
+        @wc_err_col_index ||= ss.ensure_column!(COL_WC_ERROR)
+      end
+
+      def ht_col_index
+        @ht_col_index ||= ss.ensure_column!(COL_HATHI_TRUST)
+      end
+
+      def ht_err_col_index
+        @ht_err_col_index ||= ss.ensure_column!(COL_HATHI_TRUST_ERROR)
+      end
+
+      def row_index_by_oclc_number
+        # Start at 1 to skip header row
+        @row_index_by_oclc_number ||= (1...ss.row_count).each_with_object({}) do |r_index, r_indices|
+          oclc_number_raw = ss.value_at(r_index, oclc_col_index)
+          next unless oclc_number_raw
+
+          oclc_number = oclc_number_raw.to_s
+          if r_indices.key?(oclc_number)
+            logger.warn("Skipping duplicate OCLC number #{oclc_number} in row #{r_index}")
+          else
+            r_indices[oclc_number] = r_index
+          end
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/location.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('location/*.rb', __dir__)).each(&method(:require))

data/lib/berkeley_library/util/xlsx/rubyxl_cell_extensions.rb

@@ -0,0 +1,31 @@
+require 'rubyXL'
+
+module BerkeleyLibrary
+  module Util
+    module XLSX
+      module RubyXLCellExtensions
+        # Workaround for https://github.com/weshatheleopard/rubyXL/issues/441
+        def initialize(params = nil)
+          super
+
+          return unless params.respond_to?(:[])
+
+          @worksheet ||= params[:worksheet]
+          self.row ||= params[:row] # NOTE: not an instance variable
+        end
+
+        def blank?
+          return true if value.nil?
+
+          value.respond_to?(:strip) && value.strip.empty?
+        end
+      end
+    end
+  end
+end
+
+module RubyXL
+  class Cell
+    prepend BerkeleyLibrary::Util::XLSX::RubyXLCellExtensions
+  end
+end

data/lib/berkeley_library/util/xlsx/rubyxl_worksheet_extensions.rb

@@ -0,0 +1,26 @@
+require 'rubyXL'
+require 'berkeley_library/util/xlsx/rubyxl_cell_extensions'
+
+module BerkeleyLibrary
+  module Util
+    module XLSX
+      module RubyXLWorksheetExtensions
+        def first_blank_column_index
+          sheet_data.rows.inject(0) do |first_blank_c_index, row|
+            next first_blank_c_index unless row
+
+            trailing_blank_cells = row.cells.reverse.take_while(&:blank?)
+            row_first_blank_c_index = row.size - trailing_blank_cells.size
+            [first_blank_c_index, row_first_blank_c_index].max
+          end
+        end
+      end
+    end
+  end
+end
+
+module RubyXL
+  class Worksheet
+    prepend BerkeleyLibrary::Util::XLSX::RubyXLWorksheetExtensions
+  end
+end

data/lib/berkeley_library/util/xlsx/spreadsheet.rb

@@ -0,0 +1,158 @@
+require 'marcel'
+require 'rubyXL'
+require 'rubyXL/convenience_methods/cell'
+require 'rubyXL/convenience_methods/worksheet'
+require 'zip'
+require 'berkeley_library/util/xlsx'
+
+module BerkeleyLibrary
+  module Util
+    module XLSX
+      # Convenience wrapper RubyXL::Workbook
+      class Spreadsheet
+
+        # .xlsx format, a.k.a. "Office Open XML Workbook" spreadsheet
+        MIME_TYPE_OOXML_WB = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'.freeze
+
+        # path to Excel worksheet file in zipped OOXML archive
+        RE_EXCEL_WORKSHEET_ZIP_ENTRY = %r{^xl/worksheets/[^/.]+\.xml$}
+
+        DEFAULT_WORKSHEET_NAME = 'Sheet1'.freeze
+
+        attr_reader :workbook, :xlsx_path
+
+        delegate :stream, to: :workbook
+
+        def initialize(xlsx_path = nil)
+          @workbook = xlsx_path ? ensure_xlsx_workbook!(xlsx_path) : RubyXL::Workbook.new
+          @xlsx_path = xlsx_path
+        end
+
+        def save_as(new_xlsx_path)
+          workbook.write(new_xlsx_path)
+          @xlsx_path = new_xlsx_path
+        end
+
+        def worksheet
+          @worksheet ||= workbook.worksheets[0]
+        end
+
+        def header_row
+          @header_row ||= (hr = worksheet[0]) ? hr : worksheet.add_row
+        end
+
+        def find_column_index_by_header(header)
+          find_column_index(header_row, header)
+        end
+
+        def find_column_index_by_header!(header)
+          c_index = find_column_index_by_header(header)
+          return c_index if c_index
+
+          raise ArgumentError, "#{header.inspect} column not found"
+        end
+
+        def find_column_index(row, *args)
+          case args.size
+          when 0
+            (0...row.size).find { |c_index| yield row[c_index] }
+          when 1
+            find_column_index(row) { |cell| cell&.value == args[0] }
+          else
+            raise ArgumentError, "Wrong number of arguments (given #{args.size}, expected 0..1"
+          end
+        end
+
+        def each_value(c_index, include_header: true)
+          return to_enum(:each_value, c_index, include_header:) unless block_given?
+
+          start_index = include_header ? 0 : 1
+          (start_index...row_count).each do |r_index|
+            yield value_at(r_index, c_index)
+          end
+        end
+
+        def cell_at(r_index, c_index)
+          return unless (row = worksheet[r_index])
+
+          row[c_index]
+        end
+
+        def value_at(r_index, c_index)
+          return unless (cell = cell_at(r_index, c_index))
+
+          cell.value
+        end
+
+        def set_value_at(r_index, c_index, value)
+          if (cell = cell_at(r_index, c_index))
+            cell.change_contents(value)
+          else
+            worksheet.add_cell(r_index, c_index, value)
+          end
+        end
+
+        def rows
+          sheet_data.rows
+        end
+
+        def row_count
+          sheet_data.size
+        end
+
+        def column_count(r_index = nil)
+          if r_index
+            return (row = worksheet[r_index]) ? row.size : 0
+          end
+
+          rows.inject(0) do |cc_max, r|
+            r ? [r.size, cc_max].max : cc_max
+          end
+        end
+
+        def ensure_column!(header)
+          c_index_existing = find_column_index_by_header(header)
+          return c_index_existing if c_index_existing
+
+          c_index_next = worksheet.first_blank_column_index
+          c_index_next.tap { |cc| worksheet.add_cell(0, cc, header) }
+        end
+
+        private
+
+        def sheet_data
+          worksheet.sheet_data
+        end
+
+        def ensure_xlsx_workbook!(xlsx_path)
+          # RubyXL will try to parse an Excel 95 or 97 file (which are still)
+          # zip-based) but then choke when it tries to read the worksheet, so
+          # we explicitly check the MIME type here
+          check_mime_type!(xlsx_path)
+
+          RubyXL::Parser.parse(xlsx_path)
+        end
+
+        def check_mime_type!(xlsx_path)
+          xlsx_pathname = Pathname.new(xlsx_path)
+          mime_type = Marcel::MimeType.for(xlsx_pathname)
+
+          # TODO: test w/application/vnd.ms-excel.sheet.macroenabled.12
+          return if Marcel::Magic.child?(mime_type, MIME_TYPE_OOXML_WB)
+
+          # Marcel fails to recognize some OOXML files, probably due to unexpected entry order
+          # and/or large entries pushing the signature it's looking for too deep into the file
+          return ensure_xlsx!(xlsx_path) if Marcel::Magic.child?(mime_type, 'application/zip')
+
+          raise ArgumentError, "Expected Excel Workbook (.xlsx), got #{mime_type}: #{xlsx_path}"
+        end
+
+        def ensure_xlsx!(zipfile_path)
+          return if Zip::File.open(zipfile_path) { |zf| zf.any? { |e| e.name =~ RE_EXCEL_WORKSHEET_ZIP_ENTRY } }
+
+          raise ArgumentError, "No Excel worksheets found in ZIP archive #{zipfile_path}"
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/xlsx.rb

@@ -0,0 +1 @@
+Dir.glob(File.expand_path('xlsx/*.rb', __dir__)).each(&method(:require))

metadata

@@ -0,0 +1,313 @@
+--- !ruby/object:Gem::Specification
+name: berkeley_library-location
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- David Moles
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-06-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: berkeley_library-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: berkeley_library-util
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.9
+- !ruby/object:Gem::Dependency
+  name: marcel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: rubyXL
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: bundle-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: ci_reporter_rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.39'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '1.39'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: ruby-prof
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.17.0
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: A collection of location-related utilities for the UC Berkeley Library
+email: dmoles@berkeley.edu
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGES.md
+- LICENSE.md
+- README.md
+- lib/berkeley_library/location.rb
+- lib/berkeley_library/location/constants.rb
+- lib/berkeley_library/location/hathi_trust.rb
+- lib/berkeley_library/location/hathi_trust/config.rb
+- lib/berkeley_library/location/hathi_trust/record_url_batch_request.rb
+- lib/berkeley_library/location/hathi_trust/record_url_request.rb
+- lib/berkeley_library/location/hathi_trust/record_url_request_base.rb
+- lib/berkeley_library/location/location_result.rb
+- lib/berkeley_library/location/module_info.rb
+- lib/berkeley_library/location/oclc_number.rb
+- lib/berkeley_library/location/world_cat.rb
+- lib/berkeley_library/location/world_cat/config.rb
+- lib/berkeley_library/location/world_cat/libraries_request.rb
+- lib/berkeley_library/location/world_cat/symbols.rb
+- lib/berkeley_library/location/xlsx_reader.rb
+- lib/berkeley_library/location/xlsx_writer.rb
+- lib/berkeley_library/util/xlsx.rb
+- lib/berkeley_library/util/xlsx/rubyxl_cell_extensions.rb
+- lib/berkeley_library/util/xlsx/rubyxl_worksheet_extensions.rb
+- lib/berkeley_library/util/xlsx/spreadsheet.rb
+homepage: https://github.com/BerkeleyLibrary/location
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/BerkeleyLibrary/location
+  source_code_uri: https://github.com/BerkeleyLibrary/location
+  changelog_uri: https://github.com/BerkeleyLibrary/location/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.25
+signing_key:
+specification_version: 4
+summary: Locaton-related utilities for the UC Berkeley Library
+test_files: []