jsi 0.4.0 → 0.7.0

data/lib/jsi/simple_wrap.rb

@@ -1,12 +1,31 @@
 # frozen_string_literal: true
 
 module JSI
-  SimpleWrap = JSI::Schema.new({
-    "additionalProperties": {"$ref": "#"},
-    "items": {"$ref": "#"}
-  }).jsi_schema_module
+  simple_wrap_implementation = Module.new do
+    include Schema
+    include Schema::Application::ChildApplication
+    include Schema::Application::InplaceApplication
+    include Schema::Validation::Core
+
+    def internal_child_applicate_keywords(token, instance)
+      yield self
+    end
+
+    def internal_inplace_applicate_keywords(instance, visited_refs)
+      yield self
+    end
+
+    def internal_validate_keywords(result_builder)
+    end
+  end
+
+  simple_wrap_metaschema = MetaschemaNode.new(nil, schema_implementation_modules: [simple_wrap_implementation])
+  SimpleWrap = simple_wrap_metaschema.new_schema_module({})
 
   # SimpleWrap is a JSI schema module which recursively wraps nested structures
   module SimpleWrap
   end
+
+  SimpleWrap::Implementation = simple_wrap_implementation
+  SimpleWrap::METASCHEMA = simple_wrap_metaschema
 end

data/lib/jsi/util/private/attr_struct.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module JSI
+  module Util::Private
+    # like a Struct, but stores all the attributes in one @attributes Hash, instead of individual instance
+    # variables for each attribute.
+    # this tends to be easier to work with and more flexible. keys which are symbols are converted to strings.
+    class AttrStruct
+      class AttrStructError < StandardError
+      end
+
+      class UndefinedAttributeKey < AttrStructError
+      end
+
+      class << self
+        # creates a AttrStruct subclass with the given attribute keys.
+        # @param attribute_keys [Enumerable<String, Symbol>]
+        def subclass(*attribute_keys)
+          bad = attribute_keys.reject { |key| key.respond_to?(:to_str) || key.is_a?(Symbol) }
+          unless bad.empty?
+            raise ArgumentError, "attribute keys must be String or Symbol; got keys: #{bad.map(&:inspect).join(', ')}"
+          end
+          attribute_keys = attribute_keys.map { |key| convert_key(key) }
+
+          all_attribute_keys = (self.attribute_keys + attribute_keys).freeze
+
+          Class.new(self).tap do |klass|
+            klass.define_singleton_method(:attribute_keys) { all_attribute_keys }
+
+            attribute_keys.each do |attribute_key|
+              # reader
+              klass.send(:define_method, attribute_key) do
+                @attributes[attribute_key]
+              end
+
+              # writer
+              klass.send(:define_method, "#{attribute_key}=") do |value|
+                @attributes[attribute_key] = value
+              end
+            end
+          end
+        end
+
+        alias_method :[], :subclass
+
+        # the attribute keys defined for this class
+        # @return [Set<String>]
+        def attribute_keys
+          # empty for AttrStruct itself; redefined on each subclass
+          Util::Private::EMPTY_SET
+        end
+
+        # returns a frozen string, given a string or symbol.
+        # returns anything else as-is for the caller to handle.
+        # @api private
+        def convert_key(key)
+          # TODO use Symbol#name when available on supported rubies
+          key.is_a?(Symbol) ? key.to_s.freeze : key.frozen? ? key : key.is_a?(String) ? key.dup.freeze : key
+        end
+      end
+
+      def initialize(attributes = {})
+        unless attributes.respond_to?(:to_hash)
+          raise(TypeError, "expected attributes to be a Hash; got: #{attributes.inspect}")
+        end
+        @attributes = {}
+        attributes.to_hash.each do |k, v|
+          @attributes[self.class.convert_key(k)] = v
+        end
+        bad = @attributes.keys.reject { |k| attribute_keys.include?(k) }
+        unless bad.empty?
+          raise UndefinedAttributeKey, "undefined attribute keys: #{bad.map(&:inspect).join(', ')}"
+        end
+      end
+
+      def [](key)
+        @attributes[key.is_a?(Symbol) ? key.to_s : key]
+      end
+
+      def []=(key, value)
+        key = self.class.convert_key(key)
+        unless attribute_keys.include?(key)
+          raise UndefinedAttributeKey, "undefined attribute key: #{key.inspect}"
+        end
+        @attributes[key] = value
+      end
+
+      # @return [String]
+      def inspect
+        "\#<#{self.class.name}#{@attributes.empty? ? '' : ' '}#{@attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+      end
+
+      alias_method :to_s, :inspect
+
+      # pretty-prints a representation of self to the given printer
+      # @return [void]
+      def pretty_print(q)
+        q.text '#<'
+        q.text self.class.name
+        q.group_sub {
+          q.nest(2) {
+            q.breakable(@attributes.empty? ? '' : ' ')
+            q.seplist(@attributes, nil, :each_pair) { |k, v|
+              q.group {
+                q.text k
+                q.text ': '
+                q.pp v
+              }
+            }
+          }
+        }
+        q.breakable ''
+        q.text '>'
+      end
+
+      # (see AttrStruct.attribute_keys)
+      def attribute_keys
+        self.class.attribute_keys
+      end
+
+      include FingerprintHash
+      def jsi_fingerprint
+        {class: self.class, attributes: @attributes}
+      end
+    end
+  end
+end

data/lib/jsi/util/private.rb

@@ -0,0 +1,204 @@
+# 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'
+
+    EMPTY_ARY = [].freeze
+
+    EMPTY_SET = Set[].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
+
+    # 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 characters special to ruby syntax
+      return false if name =~ /[\\\s\#;\.,\(\)\[\]\{\}'"`%\+\-\/\*\^\|&=<>\?:!@\$~]/
+
+      return true
+    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
+
+    module FingerprintHash
+      # overrides BasicObject#==
+      def ==(other)
+        __id__ == other.__id__ || (other.respond_to?(:jsi_fingerprint) && other.jsi_fingerprint == jsi_fingerprint)
+      end
+
+      alias_method :eql?, :==
+
+      # overrides Kernel#hash
+      def hash
+        jsi_fingerprint.hash
+      end
+    end
+
+    class MemoMap
+      Result = AttrStruct[*%w(
+        value
+        inputs
+        inputs_hash
+      )]
+
+      class Result
+      end
+
+      def initialize(key_by: nil, &block)
+        @key_by = key_by
+        @block = block
+
+        # each result has its own mutex to update its memoized value thread-safely
+        @result_mutexes = {}
+        # another mutex to thread-safely initialize each result mutex
+        @result_mutexes_mutex = Mutex.new
+
+        @results = {}
+      end
+
+      def [](**inputs)
+        if @key_by
+          key = @key_by.call(**inputs)
+        else
+          key = inputs
+        end
+        result_mutex = @result_mutexes_mutex.synchronize do
+          @result_mutexes[key] ||= Mutex.new
+        end
+
+        result_mutex.synchronize do
+          inputs_hash = inputs.hash
+          if @results.key?(key) && inputs_hash == @results[key].inputs_hash && inputs == @results[key].inputs
+            @results[key].value
+          else
+            value = @block.call(**inputs)
+            @results[key] = Result.new(value: value, inputs: inputs, inputs_hash: inputs_hash)
+            value
+          end
+        end
+      end
+    end
+
+    module Memoize
+      def self.extended(object)
+        object.send(:jsi_initialize_memos)
+      end
+
+      private
+
+      def jsi_initialize_memos
+        @jsi_memomaps_mutex = Mutex.new
+        @jsi_memomaps = {}
+      end
+
+      # @return [Util::MemoMap]
+      def jsi_memomap(name, **options, &block)
+        raise(Bug, 'must jsi_initialize_memos') unless @jsi_memomaps
+        unless @jsi_memomaps.key?(name)
+          @jsi_memomaps_mutex.synchronize do
+            # note: this ||= appears redundant with `unless @jsi_memomaps.key?(name)`,
+            # but that check is not thread safe. this check is.
+            @jsi_memomaps[name] ||= Util::MemoMap.new(**options, &block)
+          end
+        end
+        @jsi_memomaps[name]
+      end
+
+      def jsi_memoize(name, **inputs, &block)
+        jsi_memomap(name, &block)[**inputs]
+      end
+    end
+
+    module Virtual
+      class InstantiationError < StandardError
+      end
+
+      # this virtual class is not intended to be instantiated except by its subclasses, which override #initialize
+      def initialize
+        # :nocov:
+        raise(InstantiationError, "cannot instantiate virtual class #{self.class}")
+        # :nocov:
+      end
+
+      # virtual_method is used to indicate that the method calling it must be implemented on the (non-virtual) subclass
+      def virtual_method
+        # :nocov:
+        raise(Bug, "class #{self.class} must implement #{caller_locations.first.label}")
+        # :nocov:
+      end
+    end
+
+    public
+
+    extend self
+  end
+end

data/lib/jsi/util/typelike.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module JSI
+  # @deprecated after v0.6
+  module Typelike
+    extend Util
+  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 Util::Hashlike
+    # 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)
+    # 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
+    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|
+      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|
+      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 |**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, **kw])
+          end
+        end
+      end
+    end
+
+    # like [Hash#update](https://ruby-doc.org/core/Hash.html#method-i-update)
+    # @param other [#to_hash] the other hash to update this hash from
+    # @yield [key, oldval, newval] for entries with duplicate keys, the value of each duplicate key
+    #   is determined by calling the block with the key, its value in self and its value in other.
+    # @return self, updated with other
+    # @raise [TypeError] when `other` does not respond to #to_hash
+    def update(other, &block)
+      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 = respond_to?(:key?) ? self : to_hash
+      other.to_hash.each_pair do |key, value|
+        if block && self_respondingto_key.key?(key)
+          value = yield(key, self[key], value)
+        end
+        self[key] = value
+      end
+      self
+    end
+
+    alias_method :merge!, :update
+
+    # like [Hash#merge](https://ruby-doc.org/core/Hash.html#method-i-merge)
+    # @param other [#to_hash] the other hash to merge into this
+    # @yield [key, oldval, newval] for entries with duplicate keys, the value of each duplicate key
+    #   is determined by calling the block with the key, its value in self and its value in other.
+    # @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)
+    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, 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
+
+    # 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, true) ? jsi_object_group_text : [self.class]).join(' ')
+      q.text "\#{<#{object_group_str}>"
+      q.group_sub {
+        q.nest(2) {
+          q.breakable(empty? ? '' : ' ')
+          q.seplist(self, nil, :each_pair) { |k, v|
+            q.group {
+              q.pp k
+              q.text ' => '
+              q.pp v
+            }
+          }
+        }
+      }
+      q.breakable ''
+      q.text '}'
+    end
+  end
+
+  # a module of methods for objects which behave like Array but are not Array.
+  #
+  # this module is intended to be internal to JSI. no guarantees or API promises
+  # are made for non-JSI classes including this module.
+  module Util::Arraylike
+    # 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)
+    # 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)
+
+    # methods (well, method) that returns a modified copy and doesn't need any handling of block variable(s)
+    safe_modified_copy_methods = %w(compact)
+
+    # methods that return a modified copy and do need handling of block variables
+    safe_el_block_methods = %w(reject select)
+
+    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|
+      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|
+      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 |**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, **kw]).tap { i += 1 }
+          end
+        end
+      end
+    end
+
+    # see [Array#assoc](https://ruby-doc.org/core/Array.html#method-i-assoc)
+    def assoc(obj)
+      # note: assoc implemented here (instead of delegated) due to inconsistencies in whether
+      # other implementations expect each element to be an Array or to respond to #to_ary
+      detect { |e| e.respond_to?(:to_ary) and e[0] == obj }
+    end
+
+    # see [Array#rassoc](https://ruby-doc.org/core/Array.html#method-i-rassoc)
+    def rassoc(obj)
+      # note: rassoc implemented here (instead of delegated) due to inconsistencies in whether
+      # other implementations expect each element to be an Array or to respond to #to_ary
+      detect { |e| e.respond_to?(:to_ary) and e[1] == obj }
+    end
+
+    # basically the same #inspect as Array, 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, true) ? jsi_object_group_text : [self.class]).join(' ')
+      "\#[<#{object_group_str}>#{map { |e| ' ' + e.inspect }.join(',')}]"
+    end
+
+    alias_method :to_s, :inspect
+
+    # 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, true) ? jsi_object_group_text : [self.class]).join(' ')
+      q.text "\#[<#{object_group_str}>"
+      q.group_sub {
+        q.nest(2) {
+          q.breakable(empty? ? '' : ' ')
+          q.seplist(self, nil, :each) { |e|
+            q.pp e
+          }
+        }
+      }
+      q.breakable ''
+      q.text ']'
+    end
+  end
+end