berkeley_library-util 0.1.0

data/.rubocop.yml

@@ -0,0 +1,334 @@
+inherit_mode:
+  merge:
+    - Exclude
+    - Include
+
+# Allow one line around block body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundBlockBody:
+  Enabled: false
+
+# Allow one line around class body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundClassBody:
+  Enabled: false
+
+# Allow one line around module body (Layout/EmptyLines will still disallow two or more)
+Layout/EmptyLinesAroundModuleBody:
+  Enabled: false
+
+# Reasonable line-length check; it's too easy for the cure to be worse than the disease
+Layout/LineLength:
+  Max: 150
+
+# Make indents consistent regardless of the lengths of variables and method names and whatnot
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# Produces monsters
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+# We meant to do that
+Naming/MemoizedInstanceVariableName:
+  Enabled: False
+
+# It works in context, trust us
+Naming/MethodParameterName:
+  Enabled: False
+
+# Confusing and weird
+Naming/VariableNumber:
+  Enabled: False
+
+# Do what's readable in the context you're in
+Style/AccessModifierDeclarations:
+  Enabled: false
+
+# 👎 to cultural imperialism
+Style/AsciiComments:
+  Enabled: false
+
+# Seriously?
+Style/CommentedKeyword:
+  Enabled: False
+
+# Disable problematic module documentation check (see https://github.com/bbatsov/rubocop/issues/947)
+Style/Documentation:
+  Enabled: false
+
+# Adding more line noise to format strings will not improve them
+Style/FormatStringToken:
+  Enabled: false
+
+# Putting '# frozen_string_literal: true' everywhere does not make the world a better place
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+# Requiring the lambda() method just makes wordy calls wordier
+Style/Lambda:
+  EnforcedStyle: literal
+
+# `foo.positive?` is cute, but it's not actually more readable than `foo > 0`
+Style/NumericPredicate:
+  Enabled: false
+
+# Unclear why it's a good idea to give parameters semantically meaningless names
+Style/SingleLineBlockParams:
+  Enabled: false
+
+# The semantics of `foo&.bar` are a lot less interchangeable with `foo && foo.bar` than RuboCop thinks
+Style/SafeNavigation:
+  Enabled: false
+
+# Short arrays are often more readable as plain arrays
+Style/WordArray:
+  MinSize: 3
+
+############################################################
+# Added in RuboCop 0.80
+
+Style/HashEachMethods:
+  Enabled: true
+
+Style/HashTransformKeys:
+  Enabled: true
+
+Style/HashTransformValues:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.81
+
+Lint/StructNewOverride:
+  Enabled: true
+
+Lint/RaiseException:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.82
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+Style/ExponentialNotation:
+  Enabled: false
+
+############################################################
+# Added in RuboCop 0.83
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Style/SlicingWithRange:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.84
+
+Lint/DeprecatedOpenSSLConstant:
+  Enabled: true
+
+############################################################
+# Added in RuboCop 0.85
+
+Lint/MixedRegexpCaptureTypes:
+  Enabled: true
+
+Style/RedundantRegexpEscape:
+  Enabled: true
+
+Style/RedundantRegexpCharacterClass:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.86
+
+Style/RedundantFetchBlock:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.87
+
+# Sometimes we separate things for a reason
+Style/AccessorGrouping:
+  Enabled: false
+
+Style/BisectedAttrAccessor:
+  Enabled: true
+
+Style/RedundantAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.88
+
+Lint/DuplicateElsifCondition:
+  Enabled: true
+
+Style/ArrayCoercion:
+  Enabled: true
+
+Style/CaseLikeIf:
+  Enabled: true
+
+Style/HashAsLastArrayItem:
+  Enabled: true
+
+Style/HashLikeCase:
+  Enabled: true
+
+Style/RedundantFileExtensionInRequire:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.89
+
+Lint/BinaryOperatorWithIdenticalOperands:
+  Enabled: true
+
+Lint/DuplicateRescueException:
+  Enabled: true
+
+Lint/EmptyConditionalBody:
+  Enabled: true
+
+Lint/FloatComparison:
+  Enabled: true
+
+Lint/MissingSuper:
+  Enabled: true
+
+Lint/OutOfRangeRegexpRef:
+  Enabled: true
+
+Lint/SelfAssignment:
+  Enabled: true
+
+Lint/TopLevelReturnWithArgument:
+  Enabled: true
+
+Lint/UnreachableLoop:
+  Enabled: true
+
+Style/ExplicitBlockArgument:
+  Enabled: true
+
+Style/GlobalStdStream:
+  Enabled: true
+
+Style/OptionalBooleanParameter:
+  Enabled: true
+
+Style/SingleArgumentDig:
+  Enabled: true
+
+Style/SoleNestedConditional:
+  Enabled: true
+
+Style/StringConcatenation:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.90
+
+Lint/DuplicateRequire:
+  Enabled: true
+
+Lint/EmptyFile:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
+Lint/UselessMethodDefinition:
+  Enabled: true
+
+Style/CombinableLoops:
+  Enabled: true
+
+Style/KeywordParametersOrder:
+  Enabled: true
+
+Style/RedundantSelfAssignment:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 0.91
+
+Layout/BeginEndAlignment:
+  Enabled: true
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: true
+
+Lint/IdentityComparison:
+  Enabled: true
+
+Lint/UselessTimes:
+  Enabled: true
+
+############################################################
+# Added in Rubocop 1.1–1.9
+
+Layout/SpaceBeforeBrackets: # (new in 1.7)
+  Enabled: true
+Lint/AmbiguousAssignment: # (new in 1.7)
+  Enabled: true
+Lint/DeprecatedConstants: # (new in 1.8)
+  Enabled: true
+Lint/DuplicateBranch: # (new in 1.3)
+  Enabled: true
+Lint/DuplicateRegexpCharacterClassElement: # (new in 1.1)
+  Enabled: true
+Lint/EmptyBlock: # (new in 1.1)
+  Enabled: true
+Lint/EmptyClass: # (new in 1.3)
+  Enabled: true
+Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
+  Enabled: true
+Lint/NoReturnInBeginEndBlocks: # (new in 1.2)
+  Enabled: true
+Lint/NumberedParameterAssignment: # (new in 1.9)
+  Enabled: true
+Lint/OrAssignmentToConstant: # (new in 1.9)
+  Enabled: true
+Lint/RedundantDirGlobSort: # (new in 1.8)
+  Enabled: true
+Lint/SymbolConversion: # (new in 1.9)
+  Enabled: true
+Lint/ToEnumArguments: # (new in 1.1)
+  Enabled: true
+Lint/TripleQuotes: # (new in 1.9)
+  Enabled: true
+Lint/UnexpectedBlockArity: # (new in 1.5)
+  Enabled: true
+Lint/UnmodifiedReduceAccumulator: # (new in 1.1)
+  Enabled: true
+Style/ArgumentsForwarding: # (new in 1.1)
+  Enabled: true
+Style/CollectionCompact: # (new in 1.2)
+  Enabled: true
+Style/DocumentDynamicEvalDefinition: # (new in 1.1)
+  Enabled: true
+Style/EndlessMethod: # (new in 1.8)
+  Enabled: true
+Style/HashExcept: # (new in 1.7)
+  Enabled: true
+Style/IfWithBooleanLiteralBranches: # (new in 1.9)
+  Enabled: true
+Style/NegatedIfElseCondition: # (new in 1.2)
+  Enabled: true
+Style/NilLambda: # (new in 1.3)
+  Enabled: true
+Style/RedundantArgument: # (new in 1.4)
+  Enabled: true
+Style/SwapValues: # (new in 1.1)
+  Enabled: true
+
+############################################################
+# Added in RuboCop 1.10
+
+Gemspec/DateAssignment: # (new in 1.10)
+  Enabled: true
+Style/HashConversion: # (new in 1.10)
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+2.7.4

data/.simplecov

@@ -0,0 +1,8 @@
+require 'simplecov-rcov'
+
+SimpleCov.start 'rails' do
+  add_filter 'module_info.rb'
+  coverage_dir 'artifacts'
+  formatter SimpleCov::Formatter::RcovFormatter
+  minimum_coverage 100
+end

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected lib/**/*.rb -m markdown

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.1.0 (2021-09-23)
+
+Initial extraction of code from [`berkeley_library/tind`](https://github.com/BerkeleyLibrary/tind).

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.md

@@ -0,0 +1,21 @@
+# The MIT License (MIT)
+
+Copyright © 2021 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,21 @@
+# BerkeleyLibrary::Util
+
+[![Build Status](https://github.com/BerkeleyLibrary/util/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/BerkeleyLibrary/util/actions/workflows/build.yml)
+[![Gem Version](https://img.shields.io/gem/v/berkeley_library-util.svg)](https://github.com/BerkeleyLibrary/util/releases)
+
+Miscellaneous utility code for the UC Berkeley Library.
+
+### Notable modules
+
+## [BerkeleyLibrary::Util::Arrays](lib/berkeley_library/util/arrays.rb)]
+
+Routines for comparing, merging, and examining the contents of arrays.
+
+## [BerkeleyLibrary::Util::Paths](lib/berkeley_library/util/paths.rb)] 
+
+Routines for modifying paths separated by forward slashes,
+(such as URL paths), modeled on the [Go `path` package](https://golang.org/pkg/path/).
+
+## [BerkeleyLibrary::Util::URIs](lib/berkeley_library/util/uris.rb)]
+
+Routines for constructing, validating, and retrieving the content from URIs.

data/Rakefile

@@ -0,0 +1,20 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('Gemfile', __dir__)
+require 'bundler/setup' # Set up gems listed in the Gemfile.
+
+# ------------------------------------------------------------
+# Application code
+
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+# ------------------------------------------------------------
+# CI
+
+ENV['RAILS_ENV'] = 'test' if ENV['CI']
+
+# ------------------------------------------------------------
+# Custom tasks
+
+desc 'Run tests, check test coverage, check code style, check for vulnerabilities, build gem'
+task default: %i[coverage rubocop bundle:audit gem]

data/berkeley_library-util.gemspec

@@ -0,0 +1,42 @@
+File.expand_path('lib', __dir__).tap do |lib|
+  $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+end
+
+ruby_version = '>= 2.7'
+
+require 'berkeley_library/util/module_info'
+
+Gem::Specification.new do |spec|
+  spec.name = BerkeleyLibrary::Util::ModuleInfo::NAME
+  spec.author = BerkeleyLibrary::Util::ModuleInfo::AUTHOR
+  spec.email = BerkeleyLibrary::Util::ModuleInfo::AUTHOR_EMAIL
+  spec.summary = BerkeleyLibrary::Util::ModuleInfo::SUMMARY
+  spec.description = BerkeleyLibrary::Util::ModuleInfo::DESCRIPTION
+  spec.license = BerkeleyLibrary::Util::ModuleInfo::LICENSE
+  spec.version = BerkeleyLibrary::Util::ModuleInfo::VERSION
+  spec.homepage = BerkeleyLibrary::Util::ModuleInfo::HOMEPAGE
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = ruby_version
+
+  spec.add_dependency 'berkeley_library-logging', '~> 0.2'
+  spec.add_dependency 'rest-client', '~> 2.1'
+  spec.add_dependency 'typesafe_enum', '~> 0.3'
+
+  spec.add_development_dependency 'bundle-audit', '~> 0.1'
+  spec.add_development_dependency 'ci_reporter_rspec', '~> 1.0'
+  spec.add_development_dependency 'colorize', '~> 0.8'
+  spec.add_development_dependency 'dotenv', '~> 2.7'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.10'
+  spec.add_development_dependency 'rubocop', '= 1.11'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.5'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.2'
+  spec.add_development_dependency 'ruby-prof', '~> 0.17.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+  spec.add_development_dependency 'simplecov-rcov', '~> 0.2'
+  spec.add_development_dependency 'webmock', '~> 3.12'
+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/module_info.rb

@@ -0,0 +1,16 @@
+module BerkeleyLibrary
+  module Util
+    class ModuleInfo
+      NAME = 'berkeley_library-util'.freeze
+      AUTHOR = 'David Moles'.freeze
+      AUTHOR_EMAIL = 'dmoles@berkeley.edu'.freeze
+      SUMMARY = 'Miscellaneous Ruby utilities for the UC Berkeley Library'.freeze
+      DESCRIPTION = <<~DESC.gsub(/\s+/, ' ').strip
+        A collection of miscellaneous Ruby routines for the UC Berkeley Library.
+      DESC
+      LICENSE = 'MIT'.freeze
+      VERSION = '0.1.0'.freeze
+      HOMEPAGE = 'https://github.com/BerkeleyLibrary/util'.freeze
+    end
+  end
+end