jsi 0.6.0 → 0.8.0

data/lib/jsi/util/private.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module JSI
+  # JSI::Util::Private classes, modules, constants, and methods are internal, and will be added and removed without warning.
+  #
+  # @api private
+  module Util::Private
+    autoload :AttrStruct, 'jsi/util/private/attr_struct'
+    autoload :MemoMap, 'jsi/util/private/memo_map'
+
+    extend self
+
+    EMPTY_ARY = [].freeze
+
+    EMPTY_HASH = {}.freeze
+
+    EMPTY_SET = Set[].freeze
+
+    CLASSES_ALWAYS_FROZEN = Set[TrueClass, FalseClass, NilClass, Integer, Float, BigDecimal, Rational, Symbol].freeze
+
+    # is a hash as the last argument passed to keyword params? (false in ruby 3; true before - generates
+    # a warning in 2.7 but no way to make 2.7 behave like 3 so the warning is useless)
+    #
+    # TODO remove eventually (keyword argument compatibility)
+    LAST_ARGUMENT_AS_KEYWORD_PARAMETERS = begin
+      if Object.const_defined?(:Warning)
+        warn = ::Warning.instance_method(:warn)
+        ::Warning.send(:remove_method, :warn)
+        ::Warning.send(:define_method, :warn) { |*, **| }
+      end
+
+      -> (k: ) { k }[{k: nil}]
+      true
+    rescue ArgumentError
+      false
+    ensure
+      if Object.const_defined?(:Warning)
+        ::Warning.send(:remove_method, :warn)
+        ::Warning.send(:define_method, :warn, warn)
+      end
+    end
+
+    # we won't use #to_json on classes where it is defined by
+    # JSON::Ext::Generator::GeneratorMethods / JSON::Pure::Generator::GeneratorMethods
+    # this is a bit of a kluge and disregards any singleton class to_json, but it will do.
+    USE_TO_JSON_METHOD = Hash.new do |h, klass|
+      h[klass] = klass.method_defined?(:to_json) &&
+        klass.instance_method(:to_json).owner.name !~ /\AJSON:.*:GeneratorMethods\b/
+    end
+
+    RUBY_REJECT_NAME_CODEPOINTS = [
+      0..31, # C0 control chars
+      %q( !"#$%&'()*+,-./:;<=>?@[\\]^`{|}~).each_codepoint, # printable special chars (note: "_" not included)
+      127..159, # C1 control chars
+    ].inject(Set[], &:merge).freeze
+
+    RUBY_REJECT_NAME_RE = Regexp.new('[' + Regexp.escape(RUBY_REJECT_NAME_CODEPOINTS.to_a.pack('U*')) + ']+').freeze
+
+    # is the given name ok to use as a ruby method name?
+    def ok_ruby_method_name?(name)
+      # must be a string
+      return false unless name.respond_to?(:to_str)
+      # must not begin with a digit
+      return false if name =~ /\A[0-9]/
+      # must not contain special or control characters
+      return false if name =~ RUBY_REJECT_NAME_RE
+
+      return true
+    end
+
+    def const_name_from_parts(parts, join: '')
+      parts = parts.map do |part|
+        part = part.dup
+        part[/\A[^a-zA-Z]*/] = ''
+        part[0] = part[0].upcase if part[0]
+        part.gsub!(RUBY_REJECT_NAME_RE, '_')
+        part
+      end
+      if !parts.all?(&:empty?)
+        parts.reject(&:empty?).join(join).freeze
+      else
+        nil
+      end
+    end
+
+    # string or URI → frozen URI
+    # @return [Addressable::URI]
+    def uri(uri)
+      if uri.is_a?(Addressable::URI)
+        if uri.frozen?
+          uri
+        else
+          uri.dup.freeze
+        end
+      else
+        Addressable::URI.parse(uri).freeze
+      end
+    end
+
+    # this is the Y-combinator, which allows anonymous recursive functions. for a simple example,
+    # to define a recursive function to return the length of an array:
+    #
+    #     length = ycomb do |len|
+    #       proc { |list| list == [] ? 0 : 1 + len.call(list[1..-1]) }
+    #     end
+    #
+    #     length.call([0])
+    #     # => 1
+    #
+    # see https://en.wikipedia.org/wiki/Fixed-point_combinator#Y_combinator
+    # and chapter 9 of the little schemer, available as the sample chapter at
+    # https://felleisen.org/matthias/BTLS-index.html
+    def ycomb
+      proc { |f| f.call(f) }.call(proc { |f| yield proc { |*x| f.call(f).call(*x) } })
+    end
+
+    def require_jmespath
+      return if instance_variable_defined?(:@jmespath_required)
+      begin
+        require 'jmespath'
+      rescue ::LoadError => e
+        # :nocov:
+        msg = [
+          "please install and/or add to your Gemfile the `jmespath` gem to use this. jmespath is not a dependency of JSI.",
+          "original error message:",
+          e.message,
+        ].join("\n")
+        raise(e.class, msg, e.backtrace)
+        # :nocov:
+      end
+      hashlike = JSI::SchemaSet[].new_jsi({'test' => 0})
+      unless JMESPath.search('test', hashlike) == 0
+        # :nocov:
+        raise(::LoadError, [
+          "the loaded version of jmespath cannot be used with JSI.",
+          "jmespath is compatible with JSI objects as of version 1.5.0",
+        ].join("\n"))
+        # :nocov:
+      end
+      @jmespath_required = true
+      nil
+    end
+
+    # Defines equality methods and #hash (for Hash / Set), based on a method #jsi_fingerprint
+    # implemented by the includer. #jsi_fingerprint is to include the class and any properties
+    # of the instance which constitute its identity.
+    module FingerprintHash
+      # overrides BasicObject#==
+      def ==(other)
+        __id__ == other.__id__ || (other.is_a?(FingerprintHash) && jsi_fingerprint == other.jsi_fingerprint)
+      end
+
+      alias_method :eql?, :==
+
+      # overrides Kernel#hash
+      def hash
+        jsi_fingerprint.hash
+      end
+    end
+
+    module FingerprintHash::Immutable
+      include FingerprintHash
+
+      def ==(other)
+        return true if __id__ == other.__id__
+        return false unless other.is_a?(FingerprintHash)
+        # FingerprintHash::Immutable#hash being memoized, comparing that is basically free.
+        # not done with FingerprintHash, its #hash can be expensive.
+        return false if other.is_a?(FingerprintHash::Immutable) && hash != other.hash
+        jsi_fingerprint == other.jsi_fingerprint
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        @jsi_fingerprint_hash ||= jsi_fingerprint.hash
+      end
+
+      def freeze
+        hash
+        super
+      end
+    end
+  end
+end

data/lib/jsi/{typelike_modules.rb → util/typelike.rb}

@@ -1,102 +1,60 @@
 # frozen_string_literal: true
 
 module JSI
-  # a module relating to objects that act like Hash or Array instances
-  module Typelike
-    # yields the content of the given param `object`. for objects which have a #jsi_modified_copy
-    # method of their own (JSI::Base, JSI::MetaschemaNode) that method is invoked with the given
-    # block. otherwise the given object itself is yielded.
-    #
-    # the given block must result in a modified copy of its block parameter
-    # (not destructively modifying the yielded content).
-    #
-    # @yield [Object] the content of the given object. the block should result
-    #   in a (nondestructively) modified copy of this.
-    # @return [object.class] modified copy of the given object
-    def self.modified_copy(object, &block)
-      if object.respond_to?(:jsi_modified_copy)
-        object.jsi_modified_copy(&block)
-      else
-        return yield(object)
-      end
-    end
-
-    # recursive method to express the given argument object in json-compatible
-    # types of Hash, Array, and basic types of String/boolean/numeric/nil. this
-    # will raise TypeError if an object is given that is not a type that seems
-    # to be expressable as json.
-    #
-    # similar effect could be achieved by requiring 'json/add/core' and using #as_json,
-    # but I don't much care for how it represents classes that are
-    # not naturally expressable in JSON, and prefer not to load its
-    # monkey-patching.
-    #
-    # @param object [Object] the object to be converted to jsonifiability
-    # @return [Array, Hash, String, Boolean, NilClass, Numeric] jsonifiable
-    #   expression of param object
-    # @raise [TypeError] when the object (or an object nested with a hash or
-    #   array of object) cannot be expressed as json
-    def self.as_json(object, *opt)
-      if object.is_a?(JSI::PathedNode)
-        as_json(object.jsi_node_content, *opt)
-      elsif object.respond_to?(:to_hash)
-        (object.respond_to?(:map) ? object : object.to_hash).map do |k, v|
-          unless k.is_a?(Symbol) || k.respond_to?(:to_str)
-            raise(TypeError, "json object (hash) cannot be keyed with: #{k.pretty_inspect.chomp}")
-          end
-          {k.to_s => as_json(v, *opt)}
-        end.inject({}, &:update)
-      elsif object.respond_to?(:to_ary)
-        (object.respond_to?(:map) ? object : object.to_ary).map { |e| as_json(e, *opt) }
-      elsif [String, TrueClass, FalseClass, NilClass, Numeric].any? { |c| object.is_a?(c) }
-        object
-      elsif object.is_a?(Symbol)
-        object.to_s
-      elsif object.is_a?(Set)
-        as_json(object.to_a, *opt)
-      elsif object.respond_to?(:as_json)
-        as_json(object.as_json(*opt), *opt)
-      else
-        raise(TypeError, "cannot express object as json: #{object.pretty_inspect.chomp}")
-      end
-    end
-  end
-
   # a module of methods for objects which behave like Hash but are not Hash.
   #
   # this module is intended to be internal to JSI. no guarantees or API promises
   # are made for non-JSI classes including this module.
-  module Hashlike
+  module Util::Hashlike
+    include(Enumerable)
+
     # safe methods which can be delegated to #to_hash (which the includer is assumed to have defined).
     # 'safe' means, in this context, nondestructive - methods which do not modify the receiver.
 
     # methods which do not need to access the value.
-    SAFE_KEY_ONLY_METHODS = %w(each_key empty? has_key? include? key? keys length member? size)
-    SAFE_KEY_VALUE_METHODS = %w(< <= > >= any? assoc compact dig each_pair each_value fetch fetch_values has_value? invert key merge rassoc reject select to_h to_proc transform_values value? values values_at)
-    DESTRUCTIVE_METHODS = %w(clear delete delete_if keep_if reject! replace select! shift)
+    SAFE_KEY_ONLY_METHODS = %w(each_key empty? has_key? include? key? keys length member? size).map(&:freeze).freeze
+    SAFE_KEY_VALUE_METHODS = %w(< <= > >= any? assoc compact dig each_pair each_value fetch fetch_values has_value? invert key merge rassoc reject select to_h to_proc transform_values value? values values_at).map(&:freeze).freeze
+    DESTRUCTIVE_METHODS = %w(clear delete delete_if keep_if reject! replace select! shift).map(&:freeze).freeze
     # these return a modified copy
     safe_modified_copy_methods = %w(compact)
     # select and reject will return a modified copy but need the yielded block variable value from #[]
     safe_kv_block_modified_copy_methods = %w(select reject)
     SAFE_METHODS = SAFE_KEY_ONLY_METHODS | SAFE_KEY_VALUE_METHODS
-    safe_to_hash_methods = SAFE_METHODS - safe_modified_copy_methods - safe_kv_block_modified_copy_methods
+    custom_methods = %w(merge) # defined below
+    safe_to_hash_methods = SAFE_METHODS -
+      safe_modified_copy_methods -
+      safe_kv_block_modified_copy_methods -
+      custom_methods
     safe_to_hash_methods.each do |method_name|
-      define_method(method_name) { |*a, &b| to_hash.public_send(method_name, *a, &b) }
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) { |*a, &b| to_hash.public_send(method_name, *a, &b) }
+      else
+        define_method(method_name) { |*a, **kw, &b| to_hash.public_send(method_name, *a, **kw, &b) }
+      end
     end
     safe_modified_copy_methods.each do |method_name|
-      define_method(method_name) do |*a, &b|
-        jsi_modified_copy do |object_to_modify|
-          responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
-          responsive_object.public_send(method_name, *a, &b)
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_modified_copy do |object_to_modify|
+            responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
+            responsive_object.public_send(method_name, *a, &b)
+          end
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_modified_copy do |object_to_modify|
+            responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
+            responsive_object.public_send(method_name, *a, **kw, &b)
+          end
         end
       end
     end
     safe_kv_block_modified_copy_methods.each do |method_name|
-      define_method(method_name) do |*a, &b|
+      define_method(method_name) do |**kw, &b|
         jsi_modified_copy do |object_to_modify|
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
           responsive_object.public_send(method_name) do |k, _v|
-            b.call(k, self[k, *a])
+            b.call(k, self[k, **kw])
           end
         end
       end
@@ -112,9 +70,8 @@ module JSI
       unless other.respond_to?(:to_hash)
         raise(TypeError, "cannot update with argument that does not respond to #to_hash: #{other.pretty_inspect.chomp}")
       end
-      self_respondingto_key = self.respond_to?(:key?) ? self : to_hash
       other.to_hash.each_pair do |key, value|
-        if block && self_respondingto_key.key?(key)
+        if block && key?(key)
           value = yield(key, self[key], value)
         end
         self[key] = value
@@ -131,27 +88,30 @@ module JSI
     # @return duplicate of this hash with the other hash merged in
     # @raise [TypeError] when `other` does not respond to #to_hash
     def merge(other, &block)
-      dup.update(other, &block)
+      jsi_modified_copy do |instance|
+        instance.merge(other.is_a?(Base) ? other.jsi_node_content : other, &block)
+      end
     end
 
     # basically the same #inspect as Hash, but has the class name and, if responsive,
     # self's #jsi_object_group_text
     # @return [String]
     def inspect
-      object_group_str = (respond_to?(:jsi_object_group_text) ? self.jsi_object_group_text : [self.class]).join(' ')
-      "\#{<#{object_group_str}>#{self.map { |k, v| " #{k.inspect} => #{v.inspect}" }.join(',')}}"
+      object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
+      -"\#{<#{object_group_str}>#{map { |k, v| " #{k.inspect} => #{v.inspect}" }.join(',')}}"
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
 
     # pretty-prints a representation of this hashlike to the given printer
     # @return [void]
     def pretty_print(q)
-      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
+      object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#{<#{object_group_str}>"
-      q.group_sub {
-        q.nest(2) {
-          q.breakable(empty? ? '' : ' ')
+      q.group(2) {
+          q.breakable ' ' if !empty?
           q.seplist(self, nil, :each_pair) { |k, v|
             q.group {
               q.pp k
@@ -159,9 +119,8 @@ module JSI
               q.pp v
             }
           }
-        }
       }
-      q.breakable ''
+      q.breakable '' if !empty?
       q.text '}'
     end
   end
@@ -170,15 +129,17 @@ module JSI
   #
   # this module is intended to be internal to JSI. no guarantees or API promises
   # are made for non-JSI classes including this module.
-  module Arraylike
+  module Util::Arraylike
+    include(Enumerable)
+
     # safe methods which can be delegated to #to_ary (which the includer is assumed to have defined).
     # 'safe' means, in this context, nondestructive - methods which do not modify the receiver.
 
     # methods which do not need to access the element.
-    SAFE_INDEX_ONLY_METHODS = %w(each_index empty? length size)
+    SAFE_INDEX_ONLY_METHODS = %w(each_index empty? length size).map(&:freeze).freeze
     # there are some ambiguous ones that are omitted, like #sort, #map / #collect.
-    SAFE_INDEX_ELEMENT_METHODS = %w(| & * + - <=> abbrev at bsearch bsearch_index combination compact count cycle dig drop drop_while fetch find_index first include? index join last pack permutation product reject repeated_combination repeated_permutation reverse reverse_each rindex rotate sample select shelljoin shuffle slice sort take take_while transpose uniq values_at zip)
-    DESTRUCTIVE_METHODS = %w(<< clear collect! compact! concat delete delete_at delete_if fill flatten! insert keep_if map! pop push reject! replace reverse! rotate! select! shift shuffle! slice! sort! sort_by! uniq! unshift)
+    SAFE_INDEX_ELEMENT_METHODS = %w(| & * + - <=> abbrev at bsearch bsearch_index combination compact count cycle dig drop drop_while fetch find_index first include? index join last pack permutation product reject repeated_combination repeated_permutation reverse reverse_each rindex rotate sample select shelljoin shuffle slice sort take take_while transpose uniq values_at zip).map(&:freeze).freeze
+    DESTRUCTIVE_METHODS = %w(<< clear collect! compact! concat delete delete_at delete_if fill flatten! insert keep_if map! pop push reject! replace reverse! rotate! select! shift shuffle! slice! sort! sort_by! uniq! unshift).map(&:freeze).freeze
 
     # methods (well, method) that returns a modified copy and doesn't need any handling of block variable(s)
     safe_modified_copy_methods = %w(compact)
@@ -189,23 +150,36 @@ module JSI
     SAFE_METHODS = SAFE_INDEX_ONLY_METHODS | SAFE_INDEX_ELEMENT_METHODS
     safe_to_ary_methods = SAFE_METHODS - safe_modified_copy_methods - safe_el_block_methods
     safe_to_ary_methods.each do |method_name|
-      define_method(method_name) { |*a, &b| to_ary.public_send(method_name, *a, &b) }
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) { |*a, &b| to_ary.public_send(method_name, *a, &b) }
+      else
+        define_method(method_name) { |*a, **kw, &b| to_ary.public_send(method_name, *a, **kw, &b) }
+      end
     end
     safe_modified_copy_methods.each do |method_name|
-      define_method(method_name) do |*a, &b|
-        jsi_modified_copy do |object_to_modify|
-          responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
-          responsive_object.public_send(method_name, *a, &b)
+      if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
+        define_method(method_name) do |*a, &b|
+          jsi_modified_copy do |object_to_modify|
+            responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
+            responsive_object.public_send(method_name, *a, &b)
+          end
+        end
+      else
+        define_method(method_name) do |*a, **kw, &b|
+          jsi_modified_copy do |object_to_modify|
+            responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
+            responsive_object.public_send(method_name, *a, **kw, &b)
+          end
         end
       end
     end
     safe_el_block_methods.each do |method_name|
-      define_method(method_name) do |*a, &b|
+      define_method(method_name) do |**kw, &b|
         jsi_modified_copy do |object_to_modify|
           i = 0
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
           responsive_object.public_send(method_name) do |_e|
-            b.call(self[i, *a]).tap { i += 1 }
+            b.call(self[i, **kw]).tap { i += 1 }
           end
         end
       end
@@ -229,26 +203,26 @@ module JSI
     # self's #jsi_object_group_text
     # @return [String]
     def inspect
-      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
-      "\#[<#{object_group_str}>#{self.map { |e| ' ' + e.inspect }.join(',')}]"
+      object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
+      -"\#[<#{object_group_str}>#{map { |e| ' ' + e.inspect }.join(',')}]"
     end
 
-    alias_method :to_s, :inspect
+    def to_s
+      inspect
+    end
 
     # pretty-prints a representation of this arraylike to the given printer
     # @return [void]
     def pretty_print(q)
-      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
+      object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#[<#{object_group_str}>"
-      q.group_sub {
-        q.nest(2) {
-          q.breakable(empty? ? '' : ' ')
+      q.group(2) {
+          q.breakable ' ' if !empty?
           q.seplist(self, nil, :each) { |e|
             q.pp e
           }
-        }
       }
-      q.breakable ''
+      q.breakable '' if !empty?
       q.text ']'
     end
   end