jsi-dev 0.0.0.pre.kramdown

data/lib/jsi/schema_set.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module JSI
+  # a Set of JSI Schemas. always frozen.
+  #
+  # any schema instance is described by a set of schemas.
+  class SchemaSet < ::Set
+    class << self
+      # builds a SchemaSet from a mutable Set which is added to by the given block
+      #
+      # @yield [Set] a Set to which the block may add schemas
+      # @return [SchemaSet]
+      def build
+        mutable_set = Set.new
+        yield mutable_set
+        new(mutable_set)
+      end
+
+      # ensures the given param becomes a SchemaSet. returns the param if it is already SchemaSet, otherwise
+      # initializes a SchemaSet from it.
+      #
+      # @param schemas [SchemaSet, Enumerable] the object to ensure becomes a SchemaSet
+      # @return [SchemaSet] the given SchemaSet, or a SchemaSet initialized from the given Enumerable
+      # @raise [ArgumentError] when the schemas param is not an Enumerable
+      # @raise [Schema::NotASchemaError] when the schemas param contains objects which are not Schemas
+      def ensure_schema_set(schemas)
+        if schemas.is_a?(SchemaSet)
+          schemas
+        else
+          new(schemas)
+        end
+      end
+    end
+
+    # initializes a SchemaSet from the given enum and freezes it.
+    #
+    # if a block is given, each element of the enum is passed to it, and the result must be a Schema.
+    # if no block is given, the enum must contain only Schemas.
+    #
+    # @param enum [#each] the schemas to be included in the SchemaSet, or items to be passed to the block
+    # @yieldparam yields each element of enum for preprocessing into a Schema
+    # @yieldreturn [JSI::Schema]
+    # @raise [JSI::Schema::NotASchemaError]
+    def initialize(enum, &block)
+      if enum.is_a?(Schema)
+        raise(ArgumentError, [
+          "#{SchemaSet} initialized with a #{Schema}",
+          "you probably meant to pass that to #{SchemaSet}[]",
+          "or to wrap that schema in a Set or Array for #{SchemaSet}.new",
+          "given: #{enum.pretty_inspect.chomp}",
+        ].join("\n"))
+      end
+
+      unless enum.is_a?(Enumerable)
+        raise(ArgumentError, "#{SchemaSet} initialized with non-Enumerable: #{enum.pretty_inspect.chomp}")
+      end
+
+      super
+
+      not_schemas = reject { |s| s.is_a?(Schema) }
+      if !not_schemas.empty?
+        raise(Schema::NotASchemaError, [
+          "#{SchemaSet} initialized with non-schema objects:",
+          *not_schemas.map { |ns| ns.pretty_inspect.chomp },
+        ].join("\n"))
+      end
+
+      freeze
+    end
+
+    # Instantiates a new JSI whose content comes from the given `instance` param.
+    # This SchemaSet indicates the schemas of the JSI - its schemas are inplace
+    # applicators of this set's schemas which apply to the given instance.
+    #
+    # @param instance [Object] the instance to be represented as a JSI
+    # @param uri [#to_str, Addressable::URI] The retrieval URI of the instance.
+    #
+    #   It is rare that this needs to be specified, and only useful for instances which contain schemas.
+    #   See {Schema::DescribesSchema#new_schema}'s `uri` param documentation.
+    # @param register [Boolean] Whether schema resources in the instantiated JSI will be registered
+    #   in the schema registry indicated by param `schema_registry`.
+    #   This is only useful when the JSI is a schema or contains schemas.
+    #   The JSI's root will be registered with the `uri` param, if specified, whether or not the
+    #   root is a schema.
+    # @param schema_registry [SchemaRegistry, nil] The registry to use for references to other schemas and,
+    #    depending on `register` and `uri` params, to register this JSI and/or any contained schemas with
+    #    declared URIs.
+    # @param stringify_symbol_keys [Boolean] Whether the instance content will have any Symbol keys of Hashes
+    #   replaced with Strings (recursively through the document).
+    #   Replacement is done on a copy; the given instance is not modified.
+    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
+    #   inplace applicators of the schemas in this set.
+    def new_jsi(instance,
+        uri: nil,
+        register: false,
+        schema_registry: JSI.schema_registry,
+        stringify_symbol_keys: false
+    )
+      if stringify_symbol_keys
+        instance = Util.deep_stringify_symbol_keys(instance)
+      end
+
+      applied_schemas = inplace_applicator_schemas(instance)
+
+      if uri
+        unless uri.respond_to?(:to_str)
+          raise(TypeError, "uri must be string or Addressable::URI; got: #{uri.inspect}")
+        end
+        uri = Util.uri(uri)
+        unless uri.absolute? && !uri.fragment
+          raise(ArgumentError, "uri must be an absolute URI with no fragment; got: #{uri.inspect}")
+        end
+      end
+
+      jsi_class = JSI::SchemaClasses.class_for_schemas(applied_schemas,
+        includes: SchemaClasses.includes_for(instance),
+      )
+      jsi = jsi_class.new(instance,
+        jsi_indicated_schemas: self,
+        jsi_schema_base_uri: uri,
+        jsi_schema_registry: schema_registry,
+      )
+
+      if register && schema_registry
+        schema_registry.register(jsi)
+      end
+
+      jsi
+    end
+
+    # a set of inplace applicator schemas of each schema in this set which apply to the given instance.
+    # (see {Schema#inplace_applicator_schemas})
+    #
+    # @param instance (see Schema#inplace_applicator_schemas)
+    # @return [JSI::SchemaSet]
+    def inplace_applicator_schemas(instance)
+      SchemaSet.new(each_inplace_applicator_schema(instance))
+    end
+
+    # yields each inplace applicator schema which applies to the given instance.
+    #
+    # @param instance (see Schema#inplace_applicator_schemas)
+    # @yield [JSI::Schema]
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def each_inplace_applicator_schema(instance, &block)
+      return to_enum(__method__, instance) unless block
+
+      each do |schema|
+        schema.each_inplace_applicator_schema(instance, &block)
+      end
+
+      nil
+    end
+
+    # a set of child applicator subschemas of each schema in this set which apply to the child
+    # of the given instance on the given token.
+    # (see {Schema#child_applicator_schemas})
+    #
+    # @param instance (see Schema#child_applicator_schemas)
+    # @return [JSI::SchemaSet]
+    def child_applicator_schemas(token, instance)
+      SchemaSet.new(each_child_applicator_schema(token, instance))
+    end
+
+    # yields each child applicator schema which applies to the child of
+    # the given instance on the given token.
+    #
+    # @param (see Schema#child_applicator_schemas)
+    # @yield [JSI::Schema]
+    # @return [nil, Enumerator] an Enumerator if invoked without a block; otherwise nil
+    def each_child_applicator_schema(token, instance, &block)
+      return to_enum(__method__, token, instance) unless block
+
+      each do |schema|
+        schema.each_child_applicator_schema(token, instance, &block)
+      end
+
+      nil
+    end
+
+    # validates the given instance against our schemas
+    #
+    # @param instance [Object] the instance to validate against our schemas
+    # @return [JSI::Validation::Result]
+    def instance_validate(instance)
+      results = map { |schema| schema.instance_validate(instance) }
+      results.inject(Validation::FullResult.new, &:merge).freeze
+    end
+
+    # whether the given instance is valid against our schemas
+    # @param instance [Object] the instance to validate against our schemas
+    # @return [Boolean]
+    def instance_valid?(instance)
+      all? { |schema| schema.instance_valid?(instance) }
+    end
+
+    # @return [String]
+    def inspect
+      -"#{self.class}[#{map(&:inspect).join(", ")}]"
+    end
+
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text self.class.to_s
+      q.text '['
+      q.group_sub {
+        q.nest(2) {
+          q.breakable('')
+          q.seplist(self, nil, :each) { |e|
+            q.pp e
+          }
+        }
+      }
+      q.breakable ''
+      q.text ']'
+    end
+  end
+end

data/lib/jsi/simple_wrap.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module JSI
+  simple_wrap_implementation = Module.new do
+    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 = JSI.new_metaschema(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,130 @@
+# 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.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
+
+      # see {Util::Private::FingerprintHash}
+      # @api private
+      def jsi_fingerprint
+        {class: self.class, attributes: @attributes}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module JSI
+  module Util::Private
+    class MemoMap
+      def initialize(key_by: nil, &block)
+        @key_by = key_by
+        @block = block || raise(ArgumentError, "no block given")
+
+        # 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 key_for(inputs)
+        if @key_by
+          @key_by.call(**inputs)
+        else
+          inputs
+        end
+      end
+    end
+
+    class MemoMap::Mutable < MemoMap
+      Result = AttrStruct[*%w(
+        value
+        inputs
+        inputs_hash
+      )]
+
+      class Result
+      end
+
+      def [](**inputs)
+        key = key_for(inputs)
+
+        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
+
+    class MemoMap::Immutable < MemoMap
+      def [](**inputs)
+        key = key_for(inputs)
+
+        result_mutex = @result_mutexes_mutex.synchronize do
+          @result_mutexes[key] ||= Mutex.new
+        end
+
+        result_mutex.synchronize do
+          if @results.key?(key)
+            @results[key]
+          else
+            @results[key] = @block.call(**inputs)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsi/util/private.rb

@@ -0,0 +1,202 @@
+# 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_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
+
+    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
+  end
+end