berkeley_library-tind 0.4.0

data/lib/berkeley_library/util/paths.rb

@@ -0,0 +1,111 @@
+require 'berkeley_library/util/stringios'
+
+module BerkeleyLibrary
+  module Util
+    # This module, modeled on the {https://golang.org/pkg/path/ Go `path` package},
+    # provides utility routines for modifying paths separated by forward slashes,
+    # such as URL paths. For system-dependent file paths, use
+    # {https://ruby-doc.org/stdlib-2.7.0/libdoc/pathname/rdoc/Pathname.html `Pathname`}
+    # instead.
+    module Paths
+      include BerkeleyLibrary::Util::StringIOs
+
+      class << self
+        include Paths
+      end
+
+      # Returns the shortest path name equivalent to `path` by purely lexical
+      # processing by:
+      #
+      # 1. replacing runs of multiple `/` with a single `/`
+      # 2. eliminating all `.` (current directory) elements
+      # 3. eliminating all `<child>/..` in favor of directly
+      #    referencing the parent directory
+      # 4. replaing all `/..` at the beginning of the path
+      #    with a single leading `/`
+      #
+      # The returned path ends in a slash only if it is the root `/`.
+      # @see https://9p.io/sys/doc/lexnames.html Rob Pike, "Lexical File Names in Plan 9 or Getting Dot-Dot Right"
+      #
+      # @param path [String, nil] the path to clean
+      # @return [String, nil] the cleaned path, or `nil` for a nil path.
+      def clean(path)
+        return unless path
+        return '.' if ['', '.'].include?(path)
+
+        StringIO.new.tap do |out|
+          out << '/' if path[0] == '/'
+          dotdot = (r = out.size)
+          r, dotdot = process_next(r, dotdot, path, out) while r < path.size
+          out << '.' if out.pos == 0
+        end.string
+      end
+
+      # Joins any number of path elements into a single path, separating
+      # them with slashes, ignoring empty elements and passing the result
+      # to {Paths#clean}.
+      #
+      # @param elements [Array<String>] the elements to join
+      # @return [String] the joined path
+      def join(*elements)
+        elements = elements.reject { |e| [nil, ''].include?(e) }
+        joined_raw = elements.join('/')
+        return '' if joined_raw == ''
+
+        clean(joined_raw)
+      end
+
+      private
+
+      def process_next(r, dotdot, path, out)
+        # empty path element, or .
+        return r + 1, dotdot if empty_or_dot?(r, path)
+        # .. element: remove to last /
+        return handle_dotdot(r, dotdot, path, out) if dotdot?(r, path)
+
+        # real path element
+        [append_from(r, path, out), dotdot]
+      end
+
+      def handle_dotdot(r, dotdot, path, out)
+        if out.pos > dotdot
+          backtrack_to_dotdot(out, dotdot)
+        elsif path[0] != '/'
+          dotdot = append_dotdot(out)
+        end
+
+        [r + 2, dotdot]
+      end
+
+      def dotdot?(r, path)
+        path[r] == '.' && (r + 2 == path.size || path[r + 2] == '/')
+      end
+
+      def empty_or_dot?(r, path)
+        path[r] == '/' || (path[r] == '.' && (r + 1 == path.size || path[r + 1] == '/'))
+      end
+
+      def append_from(r, path, out)
+        out << '/' if (path[0] == '/' && out.pos != 1) || (path[0] != '/' && out.pos != 0)
+        while r < path.size && path[r] != '/'
+          out << path[r]
+          r += 1
+        end
+        r
+      end
+
+      def append_dotdot(out)
+        out << '/' if out.pos > 1
+        out << '..'
+        out.pos
+      end
+
+      def backtrack_to_dotdot(out, dotdot)
+        out.seek(-1, IO::SEEK_CUR)
+        out.seek(-1, IO::SEEK_CUR) while out.pos > dotdot && getbyte(out, out.pos) != 47 # '/' is ASCII 37
+        out.truncate(out.pos)
+      end
+
+    end
+  end
+end

data/lib/berkeley_library/util/stringios.rb

@@ -0,0 +1,30 @@
+require 'stringio'
+
+module BerkeleyLibrary
+  module Util
+    module StringIOs
+      class << self
+        include StringIOs
+      end
+
+      # Returns the byte (**not** character) at the specified byte index
+      # in the specified `StringIO`.
+      #
+      # @param s [StringIO] the StringIO to search in
+      # @param i [Integer] the byte index
+      # @return [Integer, nil] the byte, or nil if the byte index is invalid.
+      def getbyte(s, i)
+        return if i >= s.size
+        return if s.size + i < 0
+
+        pos_orig = s.pos
+        begin
+          s.seek(i >= 0 ? i : s.size + i)
+          s.getbyte
+        ensure
+          s.seek(pos_orig)
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/strings.rb

@@ -0,0 +1,42 @@
+module BerkeleyLibrary
+  module Util
+    module Strings
+
+      ASCII_0 = '0'.ord
+      ASCII_9 = '9'.ord
+
+      def ascii_numeric?(s)
+        s.chars.all? do |c|
+          ord = c.ord
+          ord >= ASCII_0 && ord <= ASCII_9
+        end
+      end
+
+      # Locates the point at which two strings differ
+      #
+      # @return [Integer, nil] the index of the first character in either string
+      #   that differs from the other, or `nil` if the strings are identical,
+      #   or are not strings
+      def diff_index(s1, s2)
+        return unless string_like?(s1, s2)
+
+        shorter, longer = s1.size > s2.size ? [s2, s1] : [s1, s2]
+        shorter.chars.each_with_index do |c, i|
+          return i if c != longer[i]
+        end
+        shorter.length if shorter.length < longer.length # otherwise they're equal
+      end
+
+      class << self
+        include Strings
+      end
+
+      private
+
+      def string_like?(*strs)
+        strs.all? { |s| s.respond_to?(:chars) && s.respond_to?(:size) }
+      end
+
+    end
+  end
+end

data/lib/berkeley_library/util/sys_exits.rb

@@ -0,0 +1,15 @@
+module BerkeleyLibrary
+  module Util
+    # cf. BSD sysexits.h https://cgit.freebsd.org/src/tree/include/sysexits.h?h=releng/2.0
+    module SysExits
+      # successful termination
+      EX_OK = 0
+
+      # command line usage error
+      EX_USAGE = 64
+
+      # internal software error
+      EX_SOFTWARE = 70 # command line usage error
+    end
+  end
+end

data/lib/berkeley_library/util/times.rb

@@ -0,0 +1,22 @@
+require 'time'
+
+module BerkeleyLibrary
+  module Util
+    module Times
+      class << self
+        include Times
+      end
+
+      # @param time [Time, Date] the time
+      # @return the UTC time corresponding to `time`
+      def ensure_utc(time)
+        return unless time
+        return time if time.respond_to?(:utc?) && time.utc?
+        return time.getutc if time.respond_to?(:getutc)
+        return time.to_time.getutc if time.respond_to?(:to_time)
+
+        raise ArgumentError, "Not a date or time: #{time.inspect}"
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/uris.rb

@@ -0,0 +1,44 @@
+require 'berkeley_library/util/uris/appender'
+require 'berkeley_library/util/uris/requester'
+require 'berkeley_library/util/uris/validator'
+
+module BerkeleyLibrary
+  module Util
+    module URIs
+      class << self
+        include URIs
+      end
+
+      # Appends the specified paths to the path of the specified URI, removing any extraneous slashes
+      # and merging additional query parameters, and returns a new URI with that path and the same scheme,
+      # host, query, fragment, etc. as the original.
+      #
+      # @param uri [URI, String] the original URI
+      # @param elements [Array<String, Symbol>] the URI elements to join.
+      # @return [URI] a new URI appending the joined path elements.
+      # @raise URI::InvalidComponentError if appending the specified elements would create an invalid URI
+      def append(uri, *elements)
+        Appender.new(uri, *elements).to_uri
+      end
+
+      # Performs a GET request.
+      #
+      # @param uri [URI, String] the URI to GET
+      # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+      # @param headers [Hash] the request headers.
+      # @return [String] the body as a string.
+      # @raise [RestClient::Exception] in the event of an error.
+      def get(uri, params = {}, headers = {})
+        Requester.get(uri, params, headers)
+      end
+
+      # Returns the specified URL as a URI.
+      # @param url [String, URI] the URL.
+      # @return [URI] the URI.
+      # @raise [URI::InvalidURIError] if `url` cannot be parsed as a URI.
+      def uri_or_nil(url)
+        Validator.uri_or_nil(url)
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/uris/appender.rb

@@ -0,0 +1,162 @@
+require 'berkeley_library/util/paths'
+require 'uri'
+require 'typesafe_enum'
+
+module BerkeleyLibrary
+  module Util
+    module URIs
+
+      # Appends the specified paths to the path of the specified URI, removing any extraneous slashes,
+      # and builds a new URI with that path and the same scheme, host, query, fragment, etc.
+      # as the original.
+      class Appender
+        attr_reader :original_uri, :elements
+
+        # Creates and invokes a new {Appender}.
+        #
+        # @param uri [URI, String] the original URI
+        # @param elements [Array<String, Symbol>] the URI elements to join.
+        # @raise URI::InvalidComponentError if appending the specified elements would create an invalid URI
+        def initialize(uri, *elements)
+          raise ArgumentError, 'uri cannot be nil' unless (@original_uri = URIs.uri_or_nil(uri))
+
+          @elements = elements.map(&:to_s)
+          @elements.each_with_index do |element, elem_index|
+            next start_query_at(elem_index) if element.include?('?')
+            next start_fragment_at(elem_index) if element.include?('#')
+
+            add_element(element)
+          end
+        end
+
+        # Returns the new URI.
+        #
+        # @return [URI] a new URI appending the joined path elements.
+        # @raise URI::InvalidComponentError if appending the specified elements would create an invalid URI
+        def to_uri
+          original_uri.dup.tap do |new_uri|
+            new_uri.path = Paths.join(original_uri.path, *path_elements)
+            new_uri.query = query unless query_elements.empty?
+            new_uri.fragment = fragment unless fragment_elements.empty?
+          end
+        end
+
+        private
+
+        def state
+          @state ||= :path
+        end
+
+        def in_query?
+          state == :query
+        end
+
+        def in_fragment?
+          state == :fragment
+        end
+
+        def query
+          query_elements.join
+        end
+
+        def fragment
+          fragment_elements.join
+        end
+
+        def path_elements
+          @path_elements ||= []
+        end
+
+        def query_elements
+          @query_elements ||= [].tap { |e| e << original_uri.query if original_uri.query }
+        end
+
+        def fragment_elements
+          @fragment_elements ||= [].tap { |e| e << original_uri.fragment if original_uri.fragment }
+        end
+
+        def start_query_at(elem_index)
+          raise URI::InvalidComponentError, err_query_after_fragment(elem_index) if in_fragment?
+          raise URI::InvalidComponentError, err_too_many_queries(elem_index) unless query_elements.empty?
+
+          handle_query_start(elem_index)
+          @state = :query
+        end
+
+        def start_fragment_at(elem_index)
+          raise URI::InvalidComponentError, err_too_many_fragments(elem_index) unless fragment_elements.empty?
+          raise URI::InvalidComponentError, err_query_after_fragment(elem_index) if query_after_fragment?(elem_index)
+
+          handle_fragment_start(elem_index)
+          @state = :fragment
+        end
+
+        def query_after_fragment?(elem_index)
+          e = elements[elem_index]
+          e.index('?', e.index('#'))
+        end
+
+        def add_element(e)
+          return fragment_elements << e if in_fragment?
+          return query_elements << e if in_query? || (e.include?('&') && !query_elements.empty?)
+
+          path_elements << e
+        end
+
+        def handle_query_start(elem_index)
+          element = elements[elem_index]
+
+          # if there's anything before the '?', we treat that excess as a path element
+          excess, q_start = split_around(element, element.index('?'))
+          q_start = push_fragment_start(elem_index, q_start)
+
+          query_elements << q_start
+          path_elements << excess
+        end
+
+        # if the fragment starts in the middle of this element, we keep the part before
+        # the fragment delimiter '#', and push the rest (w/'#') back onto the next element
+        # to be parsed in the next iteration
+        def push_fragment_start(elem_index, q_start)
+          return q_start unless (f_index = q_start.index('#'))
+
+          next_index = elem_index + 1
+          q_start, q_next = split_around(q_start, f_index)           # NOTE: this doesn't return the '#'
+          elements[next_index] = "##{q_next}#{elements[next_index]}" #       so we prepend one here
+          q_start
+        end
+
+        def handle_fragment_start(elem_index)
+          element = elements[elem_index]
+
+          # if there's anything before the '#', we treat that excess as a path element,
+          # or as a query element if there's a query
+          excess, f_start = split_around(element, element.index('#'))
+
+          fragment_elements << f_start
+          if in_query?
+            query_elements << excess
+          else
+            path_elements << excess
+          end
+        end
+
+        def split_around(s, i)
+          [s[0...i], s[(i + 1)..]]
+        end
+
+        def err_too_many_queries(elem_index)
+          "#{elements[elem_index].inspect}: URI already has a query string: #{query.inspect}"
+        end
+
+        def err_query_after_fragment(elem_index)
+          "#{elements[elem_index].inspect}: Query delimiter '?' cannot follow fragment delimeter '#'"
+        end
+
+        def err_too_many_fragments(elem_index)
+          "#{elements[elem_index].inspect}: URI already has a fragment: #{fragment.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/berkeley_library/util/uris/requester.rb

@@ -0,0 +1,62 @@
+require 'rest-client'
+require 'berkeley_library/util/uris/appender'
+require 'berkeley_library/util/uris/validator'
+require 'berkeley_library/logging'
+
+module BerkeleyLibrary
+  module Util
+    module URIs
+      module Requester
+        class << self
+          include BerkeleyLibrary::Logging
+
+          # Performs a GET request.
+          #
+          # @param uri [URI, String] the URI to GET
+          # @param params [Hash] the query parameters to add to the URI. (Note that the URI may already include query parameters.)
+          # @param headers [Hash] the request headers.
+          # @return [String] the body as a string.
+          # @raise [RestClient::Exception] in the event of an error.
+          def get(uri, params = {}, headers = {})
+            url_str = url_str_with_params(uri, params)
+            resp = get_or_raise(url_str, headers)
+            resp.body
+          end
+
+          private
+
+          def url_str_with_params(uri, params)
+            raise ArgumentError, 'uri cannot be nil' unless (url_str = Validator.url_str_or_nil(uri))
+
+            elements = [].tap do |ee|
+              ee << url_str
+              ee << '?' unless url_str.include?('?')
+              ee << URI.encode_www_form(params)
+            end
+
+            uri = Appender.new(*elements).to_uri
+            uri.to_s
+          end
+
+          def get_or_raise(url_str, headers)
+            resp = RestClient.get(url_str, headers)
+            begin
+              return resp if (status = resp.code) == 200
+
+              raise(exception_for(resp, status))
+            ensure
+              logger.info("GET #{url_str} returned #{status}")
+            end
+          end
+
+          def exception_for(resp, status)
+            RestClient::RequestFailed.new(resp, status).tap do |ex|
+              status_message = RestClient::STATUSES[status] || '(Unknown)'
+              ex.message = "#{status} #{status_message}"
+            end
+          end
+        end
+      end
+    end
+  end
+end