berkeley_library-tind 0.4.0

data/lib/berkeley_library/tind/marc.rb

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

data/lib/berkeley_library/tind/marc/xml_reader.rb

@@ -0,0 +1,144 @@
+require 'nokogiri'
+require 'marc/xml_parsers'
+require 'marc_extensions'
+
+module BerkeleyLibrary
+  module TIND
+    module MARC
+      # A customized XML reader for reading MARC records from TIND search results.
+      class XMLReader
+        include Enumerable
+        include ::MARC::NokogiriReader
+
+        # ############################################################
+        # Constant
+
+        COMMENT_TOTAL_RE = /Search-Engine-Total-Number-Of-Results: ([0-9]+)/.freeze
+
+        # ############################################################
+        # Attributes
+
+        attr_reader :search_id
+
+        # Returns the total number of records, based on the `<total/>` tag
+        # returned by the TIND Search API, or the special comment
+        # `Search-Engine-Total-Number-Of-Results` returned by TIND
+        # Regular Search in XML format.
+        #
+        # Note that the total is not guaranteed to be present, and if present,
+        # may not be present unless at least some records have been parsed.
+        #
+        # @return [Integer, nil] the total number of records, or `nil` if the total has not been read yet
+        def total
+          @total&.to_i
+        end
+
+        # Returns the number of records yielded.
+        #
+        # @return [Integer] the number of records yielded.
+        def records_yielded
+          @records_yielded ||= 0
+        end
+
+        # ############################################################
+        # Initializer
+
+        # Reads MARC records from an XML datasource given either as a file path,
+        # or as an IO object.
+        #
+        # @param source [String, Pathname, IO] the path to a file, or an IO to read from directly
+        # @param freeze [Boolean] whether to freeze each record after reading
+        def initialize(source, freeze: false)
+          @handle = ensure_io(source)
+          @freeze = freeze
+          init
+        end
+
+        class << self
+          include MARCExtensions::XMLReaderClassExtensions
+        end
+
+        # ############################################################
+        # MARC::GenericPullParser overrides
+
+        def yield_record
+          @record[:record].freeze if @freeze
+          super
+        ensure
+          increment_records_yielded!
+        end
+
+        # ############################################################
+        # Nokogiri::XML::SAX::Document overrides
+
+        # @see Nokogiri::XML::Sax::Document#start_element_namespace
+        # rubocop:disable Metrics/ParameterLists
+        def start_element_namespace(name, attrs = [], prefix = nil, uri = nil, ns = [])
+          super
+
+          @current_element_name = name
+        end
+        # rubocop:enable Metrics/ParameterLists
+
+        # @see Nokogiri::XML::Sax::Document#end_element_namespace
+        def end_element_namespace(name, prefix = nil, uri = nil)
+          super
+
+          @current_element_name = nil
+        end
+
+        # @see Nokogiri::XML::Sax::Document#characters
+        def characters(string)
+          return unless (name = @current_element_name)
+
+          case name
+          when 'search_id'
+            @search_id = string
+          when 'total'
+            @total = string.to_i
+          else
+            super
+          end
+        end
+
+        # @see Nokogiri::XML::Sax::Document#comment
+        def comment(string)
+          return unless (md = COMMENT_TOTAL_RE.match(string))
+
+          @total = md[1].to_i
+        end
+
+        # ############################################################
+        # Private
+
+        private
+
+        def ensure_io(file)
+          return file if io_like?(file)
+          return File.new(file) if file_exists?(file)
+          return StringIO.new(file) if file =~ /^\s*</x
+
+          raise ArgumentError, "Don't know how to read XML from #{file.inspect}: not an IO, file path, or XML text"
+        end
+
+        # Returns true if `obj` is close enough to an IO object for Nokogiri
+        # to parse as one.
+        #
+        # @param obj [Object] the object that might be an IO
+        # @see https://github.com/sparklemotion/nokogiri/blob/v1.11.1/lib/nokogiri/xml/sax/parser.rb#L81 Nokogiri::XML::SAX::Parser#parse
+        def io_like?(obj)
+          obj.respond_to?(:read) && obj.respond_to?(:close)
+        end
+
+        def file_exists?(path)
+          (path.respond_to?(:exist?) && path.exist?) ||
+            (path.respond_to?(:to_str) && File.exist?(path))
+        end
+
+        def increment_records_yielded!
+          @records_yielded = records_yielded + 1
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/tind/module_info.rb

@@ -0,0 +1,14 @@
+module BerkeleyLibrary
+  module TIND
+    class ModuleInfo
+      NAME = 'berkeley_library-tind'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'TIND DA utilities for the UC Berkeley Library'.freeze
+      DESCRIPTION = 'UC Berkeley Library utility gem for working with the TIND DA digital archive.'.freeze
+      LICENSE = 'MIT'.freeze
+      VERSION = '0.4.0'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/tind'.freeze
+    end
+  end
+end

data/lib/berkeley_library/util/arrays.rb

@@ -0,0 +1,178 @@
+module BerkeleyLibrary
+  module Util
+    module Arrays
+      class << self
+        # Clients can chose to call class methods directly, or include the module
+        include Arrays
+      end
+
+      # Recursively checks whether the specified list contains, in the
+      # same order, all values in the other specified list (additional codes
+      # in between are fine)
+      #
+      # @param subset [Array] the values to look for
+      # @param superset [Array] the list of values to look in
+      # @return boolean True if all values were found, false otherwise
+      def ordered_superset?(superset:, subset:)
+        !find_indices(in_array: superset, for_array: subset).nil?
+      end
+
+      # Counts how many contiguous elements from the start of an
+      # sequence of values satisfy the given block.
+      #
+      # @overload count_while(arr:)
+      #   Returns an enumerator.
+      #   @param values [Enumerable] the values
+      #   @return [Enumerator] the enumerator.
+      # @overload count_while(arr:, &block)
+      #   Passes elements to the block until the block returns nil or false,
+      #   then stops iterating and returns the count of matching elements.
+      #   @param values [Enumerable] the values
+      #   @return [Integer] the count
+      def count_while(values:)
+        return to_enum(:count_while, values: values) unless block_given?
+
+        values.inject(0) do |count, x|
+          matched = yield x
+          break count unless matched
+
+          count + 1
+        end
+      end
+
+      # Given two lists, one of which is a superset of the other, with elements
+      # in the same order (but possibly with additional elements in the superset),
+      # returns an array the length of the subset, containing for each element in
+      # the subset the index of the corresponding element in the superset.
+      #
+      # @overload find_matching_indices(for_array:, in_array:)
+      #   For each value in `for_array`, finds the index of the first equal value
+      #   in `in_array` after the previously matched value.
+      #   @param in_array [Array] the list of values to look in
+      #   @param for_array [Array] the values to look for
+      #   @return [Array<Integer>, nil] the indices in `in_array` of each value in `for_array`,
+      #     or `nil` if not all values could be found
+      #
+      # @overload find_matching_indices(for_array:, in_array:)
+      #   For each value in `for_array`, finds the index of the first value
+      #   in `in_array` after the previously matched value that matches
+      #   the specified match function.
+      #   @param in_array [Array] the list of values to look in
+      #   @param for_array [Array] the values to look for
+      #   @yieldparam source [Object] the value to compare
+      #   @yieldparam target [Object] the value to compare against
+      #   @return [Array<Integer>, nil] the indices in `in_array` of each value in `for_array`,
+      #     or `nil` if not all values could be found
+      def find_indices(for_array:, in_array:, &block)
+        return find_indices_matching(for_array, in_array, &block) if block_given?
+
+        find_all_indices(for_array, in_array)
+      end
+
+      # Given a block or a value, finds the index of the first matching value
+      # at or after the specified start index.
+      #
+      # @overload find_index(value, in_array:, start_index:)
+      #   Finds the first index of the specified value.
+      #   @param value [Object] the value to find
+      #   @param in_array [Array] the array to search
+      #   @param start_index [Integer] the index to start with
+      #   @return [Integer, nil] the index, or `nil` if no value matches
+      # @overload find_index(&block)
+      #   Finds the index of the first value matching
+      #   the specified block.
+      #   @param in_array [Array] the array to search
+      #   @param start_index [Integer] the index to start with
+      #   @yieldreturn [Boolean] whether the element matches
+      #   @return [Integer, nil] the index, or `nil` if no value matches
+      # @overload find_index
+      #   @param in_array [Array] the array to search
+      #   @param start_index [Integer] the index to start with
+      #   @return [Enumerator] a new enumerator
+      def find_index(*args, in_array:, start_index: 0, &block)
+        raise ArgumentError, "wrong number of arguments (given #{value.length}, expected 0..1" if args.size > 1
+        return Enumerator.new { |y| find_index(in_array: in_array, start_index: start_index, &y) } if args.empty? && !block_given?
+        return unless (relative_index = in_array[start_index..].find_index(*args, &block))
+
+        relative_index + start_index
+      end
+
+      # Given an array of unique integers _a<sub>1</sub>_, returns a new array
+      # _a<sub>2</sub>_ in which the value at each index _i<sub>2</sub>_ is the
+      # index _i<sub>1</sub>_ at which that value was found in _a<sub>1</sub>_.
+      # E.g., given `[0, 2, 3]`, returns `[0, nil, 1, 2]`. The indices need
+      # not be in order but must be unique.
+      #
+      # @param arr [Array<Integer>, nil] the array to invert.
+      # @return [Array<Integer, nil>, nil] the inverted array, or nil if the input array is nil
+      # @raise TypeError if `arr` is not an array of integers
+      # @raise ArgumentError if `arr` contains duplicate values
+      def invert(arr)
+        return unless arr
+
+        # noinspection RubyNilAnalysis
+        Array.new(arr.size).tap do |inv|
+          arr.each_with_index do |v, i|
+            next inv[v] = i unless (prev_index = inv[v])
+
+            raise ArgumentError, "Duplicate value #{v} at index #{i} already found at #{prev_index}"
+          end
+        end
+      end
+
+      # Merges two arrays in an order-preserving manner.
+      # @param a1 [Array] the first array
+      # @param a2 [Array] the second array
+      # @return [Array] a merged array that is an ordered superset of both `a1` and `a2`
+      # @see Arrays#ordered_superset?
+      def merge(a1, a2)
+        return a1 if a2.empty?
+        return a2 if a1.empty?
+
+        shorter, longer = a1.size > a2.size ? [a2, a1] : [a1, a2]
+        do_merge(shorter, longer)
+      end
+
+      private
+
+      def do_merge(shorter, longer)
+        shorter.each_with_index do |v, ix_s|
+          next unless (ix_l = longer.find_index(v))
+
+          shorter_unmatched = shorter[0...ix_s]
+          longer_unmatched = longer[0...ix_l]
+          all_unmatched = sort_by_first_and_flatten(shorter_unmatched, longer_unmatched)
+          return (all_unmatched << v) + merge(shorter[ix_s + 1..], longer[ix_l + 1..])
+        end
+
+        sort_by_first_and_flatten(longer, shorter)
+      end
+
+      def sort_by_first_and_flatten(a1, a2)
+        return a1 if a2.empty?
+        return a2 if a1.empty?
+        return a2 + a1 if a1.first.respond_to?(:>) && a1.first > a2.first
+
+        a1 + a2
+      end
+
+      def find_all_indices(source, target)
+        source.each_with_object([]) do |src, target_indices|
+          target_offset = (target_indices.last&.+ 1) || 0
+          return nil unless (target_index = find_index(src, in_array: target, start_index: target_offset))
+
+          target_indices << target_index
+        end
+      end
+
+      def find_indices_matching(source, target)
+        source.each_with_object([]) do |src, target_indices|
+          target_offset = (target_indices.last&.+ 1) || 0
+          return nil unless (target_index = find_index(in_array: target, start_index: target_offset) { |tgt| yield src, tgt })
+
+          target_indices << target_index
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/logging.rb

@@ -0,0 +1 @@
+require 'berkeley_library/logging'

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

@@ -0,0 +1,170 @@
+require 'fileutils'
+require 'zip'
+require 'berkeley_library/util/logging'
+require 'berkeley_library/util/ods/xml/content_doc'
+require 'berkeley_library/util/ods/xml/styles_doc'
+require 'berkeley_library/util/ods/xml/manifest_doc'
+
+module BerkeleyLibrary
+  module Util
+    module ODS
+      class Spreadsheet
+        include BerkeleyLibrary::Logging
+
+        # ------------------------------------------------------------
+        # Utility methods
+
+        # Adds a table ('worksheet') to the spreadsheet.
+        #
+        # @param name [String] the table name
+        # @param protected [Boolean] whether to protect the table
+        # @return [BerkeleyLibrary::Util::ODS::XML::Table::Table] a new table with the specified name
+        def add_table(name, protected: true)
+          content.document_content.add_table(name, protected: protected)
+        end
+
+        # ------------------------------------------------------------
+        # Accessors
+
+        # Returns the content document
+        # @return [XML::ContentDoc] the container root-level content document
+        def content
+          @content ||= XML::ContentDoc.new
+        end
+
+        # Returns the container styles
+        # @return [XML::StylesDoc] the container root-level style document
+        def styles
+          @styles ||= XML::StylesDoc.new
+        end
+
+        # Returns the container manifest
+        # @return [XML::ManifestDoc] the container manifest document
+        def manifest
+          @manifest ||= XML::ManifestDoc.new.tap do |mf_doc|
+            manifest = mf_doc.manifest
+            manifest_docs.each { |doc| manifest.add_entry_for(doc) }
+          end
+        end
+
+        # Gets the document styles
+        #
+        # @return [BerkeleyLibrary::Util::ODS::XML::Office::AutomaticStyles] the styles
+        def auto_styles
+          content.document_content.automatic_styles
+        end
+
+        # ------------------------------------------------------------
+        # Output
+
+        # @overload write_to
+        #   Writes to a new string.
+        #   @return [String] a binary string containing the spreadsheet data.
+        # @overload write_to(out)
+        #   Writes to the specified output stream.
+        #   @param out [IO] the output stream
+        #   @return[void]
+        # @overload write_to(path)
+        #   Writes to the specified file. If `path` denotes a directory, the
+        #   spreadsheet will be written as exploded, pretty-printed XML.
+        #   @param path [String, Pathname] the path to the output file
+        #   @return[void]
+        #   @see BerkeleyLibrary::Util::ODS::Spreadsheet#write_exploded_to
+        # noinspection RubyYardReturnMatch
+        def write_to(out = nil)
+          return write_to_string unless out
+          return write_to_stream(out) if io_like?(out)
+          return write_exploded_to(out) if File.directory?(out)
+
+          write_to_file(out)
+        end
+
+        # Writes to a new string.
+        def write_to_string
+          # noinspection RubyYardParamTypeMatch
+          StringIO.new.tap { |out| write_to_stream(out) }.string
+        end
+
+        # Writes to the specified output stream.
+        # @param out [IO]
+        def write_to_stream(out)
+          zip64_orig = Zip.write_zip64_support
+          begin
+            Zip.write_zip64_support = true
+            write_zipfile(out)
+          ensure
+            Zip.write_zip64_support = zip64_orig
+          end
+        end
+
+        # Writes to the specified file.
+        # @param path [String, Pathname]
+        def write_to_file(path)
+          File.open(path, 'wb') { |f| write_to_stream(f) }
+        end
+
+        # Writes this spreadsheet as an exploded set of pretty-printed XML files.
+        # NOTE: OpenOffice itself and many other tools get confused by the extra text
+        # nodes in the pretty-printed files and won't read them properly; this method
+        # is mostly for debugging.
+        #
+        # @return [Array<String>] a list of files written.
+        def write_exploded_to(dir)
+          raise ArgumentError, "Not a directory: #{dir.inspect}" unless File.directory?(dir)
+
+          [].tap do |files_written|
+            each_document do |doc|
+              output_path = write_exploded(doc, dir)
+              files_written << File.absolute_path(output_path)
+              logger.debug("Wrote #{files_written.last}")
+            end
+          end
+        end
+
+        # ------------------------------------------------------------
+        # Private methods
+
+        private
+
+        def each_document(&block)
+          yield manifest
+
+          manifest_docs.each(&block)
+        end
+
+        def manifest_docs
+          [styles, content]
+        end
+
+        # Returns true if `out` is IO-like enough for {Zip::OutputStream}, false otherwise
+        # @return [Boolean] whether `out` can be passed to {Zip::OutputStream#write_buffer}
+        def io_like?(out)
+          %i[reopen rewind <<].all? { |m| out.respond_to?(m) }
+        end
+
+        def write_zipfile(out)
+          io = Zip::OutputStream.write_buffer(out) do |zip|
+            each_document { |doc| write_zip_entry(doc, zip) }
+          end
+          # NOTE: Zip::OutputStream plays games with the stream and
+          #   doesn't necessarily write everything unless flushed, see:
+          #   https://github.com/rubyzip/rubyzip/issues/265
+          io.flush
+        end
+
+        def write_zip_entry(doc, zip)
+          zip.put_next_entry(doc.path)
+          doc.to_xml(zip)
+        end
+
+        def write_exploded(doc, dir)
+          output_path = File.join(dir, doc.path)
+          FileUtils.mkdir_p(File.dirname(output_path))
+          doc.to_xml(output_path, compact: false)
+          output_path
+        end
+
+      end
+    end
+  end
+end