jsi-dev 0.0.8 → 0.0.9

data/lib/jsi/schema_set.rb

@@ -4,31 +4,17 @@ module JSI
   # a Set of JSI Schemas. always frozen.
   #
   # any schema instance is described by a set of schemas.
-  class SchemaSet < ::Set
+  class SchemaSet < Set
+    COMPARE_BY_IDENTITY_DEFINED = method_defined?(:compare_by_identity)
+    private_constant(:COMPARE_BY_IDENTITY_DEFINED)
+
     class << self
-      # builds a SchemaSet from a mutable Set which is added to by the given block
+      # Builds a SchemaSet, yielding a yielder to be called with each schema of the SchemaSet.
       #
-      # @yield [Set] a Set to which the block may add schemas
+      # @yield [Enumerator::Yielder]
       # @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
+      def build(&block)
+        new(Enumerator.new(&block))
       end
     end
 
@@ -38,7 +24,7 @@ module JSI
     # 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
+    # @yieldparam yields each element of `enum` for preprocessing into a Schema
     # @yieldreturn [JSI::Schema]
     # @raise [JSI::Schema::NotASchemaError]
     def initialize(enum, &block)
@@ -55,7 +41,20 @@ module JSI
         raise(ArgumentError, "#{SchemaSet} initialized with non-Enumerable: #{enum.pretty_inspect.chomp}")
       end
 
-      super
+      super(&nil) # note super() does implicitly pass block without &nil
+      if COMPARE_BY_IDENTITY_DEFINED
+        compare_by_identity
+      else
+        # TODO rm when Set#compare_by_identity is universally available.
+        # note does not work on JRuby, but JRuby has Set#compare_by_identity.
+        @hash.compare_by_identity
+      end
+
+      if block
+        enum.each_entry { |o| add(block[o]) }
+      else
+        merge(enum)
+      end
 
       not_schemas = reject { |s| s.is_a?(Schema) }
       if !not_schemas.empty?
@@ -69,122 +68,87 @@ module JSI
     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
+    #
+    # The schemas of the JSI (its {Base#jsi_schemas}) are in-place
     # applicators of this set's schemas which apply to the given instance.
+    # The JSI's {Base#jsi_indicated_schemas} set is this set.
+    #
+    # The resulting JSI is an instance of a number of modules:
+    #
+    # - The {SchemaModule JSI schema module} of each applicator schema.
+    # - {Base::HashNode}, {Base::ArrayNode}, or {Base::StringNode} if the instance is
+    #   a hash/object, array, or string.
+    # - A module defining readers for properties described by applicator schemas.
+    #   If the instance is mutable, writers as well.
     #
     # @param instance [Object] the instance to be represented as a JSI
-    # @param uri [#to_str, Addressable::URI] The retrieval URI of the instance.
+    # @param base_uri [#to_str, URI, nil]
+    #   The base URI of the instance document. An absolute URI.
+    #
+    #   It is rare that this needs to be specified. It is useful when the instance contains schemas,
+    #   and schemas in the document use relative URIs for `$id` or `$ref` without an absolute id
+    #   in an ancestor schema - those URIs will be resolved relative to `base_uri`.
     #
-    #   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.
+    #   See also {Base::Conf conf} {Base::Conf#root_uri `root_uri`}. `base_uri` is not used to identify
+    #   any resource, only to resolve relative URIs. `root_uri` does identify the root resource.
     # @param register [Boolean] Whether schema resources in the instantiated JSI will be registered
-    #   in the schema registry indicated by param `schema_registry`.
+    #   in the {Base::Conf configured} {Base::Conf#registry `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.
+    # @param mutable [Boolean] Whether the instantiated JSI will be mutable.
+    #   The instance content will be transformed with the {Base::Conf configured}
+    #   {Base::Conf#to_immutable `to_immutable`} if the JSI will be immutable.
+    # @param conf_kw Additional keyword params are passed to initialize a {Base::Conf}, the JSI's {Base#jsi_conf}.
+    # @return [Base] a JSI whose content comes from the given instance and whose schemas are
+    #   in-place applicators of the schemas in this set.
     def new_jsi(instance,
-        uri: nil,
+        base_uri: nil,
         register: false,
-        schema_registry: JSI.schema_registry,
-        stringify_symbol_keys: false
+        stringify_symbol_keys: false,
+        mutable: false,
+        **conf_kw
     )
-      if stringify_symbol_keys
-        instance = Util.deep_stringify_symbol_keys(instance)
-      end
+      raise(BlockGivenError) if block_given?
+
+      conf = Base::Conf.new(**conf_kw)
 
-      applied_schemas = inplace_applicator_schemas(instance)
+      instance = Util.deep_stringify_symbol_keys(instance) if stringify_symbol_keys
 
-      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
+      instance = conf.to_immutable.call(instance) if !mutable && conf.to_immutable
+
+      applied_schemas = SchemaSet.build do |y|
+        c = y.method(:yield) # TODO drop c, just pass y, when all supported Enumerator::Yielder.method_defined?(:to_proc)
+        each { |is| is.each_inplace_applicator_schema(instance, &c) }
       end
 
+      base_uri = Util.uri(base_uri, nnil: false, yabs: true) || conf.root_uri
+
       jsi_class = JSI::SchemaClasses.class_for_schemas(applied_schemas,
         includes: SchemaClasses.includes_for(instance),
+        mutable: mutable,
       )
-      jsi = jsi_class.new(instance,
+      jsi = jsi_class.new(
+        jsi_document: instance,
         jsi_indicated_schemas: self,
-        jsi_schema_base_uri: uri,
-        jsi_schema_registry: schema_registry,
-      )
+        jsi_base_uri: base_uri,
+        jsi_conf: conf,
+      ).send(:jsi_initialized)
 
-      if register && schema_registry
-        schema_registry.register(jsi)
-      end
+      conf.registry.register(jsi) if register && conf.registry
 
       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
+      inject(Validation::Result::Full.new) do |result, schema|
+        result.merge(schema.instance_validate(instance))
+      end.freeze
     end
 
     # whether the given instance is valid against our schemas
@@ -194,26 +158,19 @@ module JSI
       all? { |schema| schema.instance_valid?(instance) }
     end
 
-    # @return [String]
-    def inspect
-      -"#{self.class}[#{map(&:inspect).join(", ")}]"
+    # @return [Set<SchemaModule>]
+    def jsi_schema_modules
+      Set.new(self, &:jsi_schema_module).freeze
     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 ']'
+    # Builds a SchemaSet, yielding each schema and a callable to be called with each schema of the resulting SchemaSet.
+    # @yield [Schema, #to_proc]
+    # @return [SchemaSet]
+    def each_yield_set(&block)
+      self.class.new(Enumerator.new do |y|
+        c = y.method(:yield) # TODO drop c, just pass y, when all supported Enumerator::Yielder.method_defined?(:to_proc)
+        each { |schema| yield(schema, c) }
+      end)
     end
   end
 end

data/lib/jsi/set.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module JSI
+  # @private
+  class Set < ::Set
+    include(Util::Pretty)
+
+    def pretty_print(q)
+      q.text(self.class.to_s)
+      q.text('[')
+      q.group do
+        q.nest(2) do
+          q.breakable('')
+          q.seplist(self) do |e|
+            q.pp(e)
+          end
+        end
+        q.breakable('')
+      end
+      q.text(']')
+    end
+  end
+end

data/lib/jsi/simple_wrap.rb

@@ -1,26 +1,23 @@
 # frozen_string_literal: true
 
 module JSI
-  simple_wrap_implementation = Module.new do
-    def internal_child_applicate_keywords(token, instance)
-      yield self
-    end
+  dialect = Schema::Dialect.new(
+    vocabularies: [
+      Schema::Vocabulary.new(elements: [
+        Schema::Element.new do |element|
+          element.add_action(:inplace_applicate) { inplace_schema_applicate(schema) }
+          element.add_action(:child_applicate) { child_schema_applicate(schema) }
+        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({})
+  simple_wrap_metaschema = JSI.new_metaschema_node(nil, dialect: dialect)
+  SimpleWrap = simple_wrap_metaschema.new_schema_module(Util::EMPTY_HASH)
 
   # SimpleWrap is a JSI schema module which recursively wraps nested structures
-  module SimpleWrap
-  end
+  module SimpleWrap end
 
-  SimpleWrap::Implementation = simple_wrap_implementation
+  SimpleWrap::DIALECT = dialect
   SimpleWrap::METASCHEMA = simple_wrap_metaschema
 end

data/lib/jsi/struct.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module JSI
+  # JSI::Struct adds to Struct:
+  #
+  # - always initialized by keywords
+  # - .subclass enables hierarchical class inheritance with added members
+  # - better pretty/inspect
+  # @private
+  class Struct < ::Struct
+    include(Util::Pretty)
+
+    STRUCT_NEW = Struct.singleton_class.instance_method(:new)
+    private_constant(:STRUCT_NEW)
+
+    HAS_KEYWORD_INIT = Struct.new(:_, keyword_init: true) && true rescue false
+    private_constant(:HAS_KEYWORD_INIT)
+
+    class << self
+      # @return [Class]
+      def subclass(*members)
+        #chkbug fail if !members.all? { |m| m.is_a?(Symbol) }
+        self_members = self.members rescue [] # NoMethodError on mri, NameError on truffle
+        # Struct does not enable adding members to subclasses of its generated classes,
+        # but that is still possible by binding Struct.new to the class and calling
+        # that with both existing and new members.
+        if HAS_KEYWORD_INIT
+          STRUCT_NEW.bind(self).call(*self_members, *members, keyword_init: true)
+        else
+          STRUCT_NEW.bind(self).call(*self_members, *members)
+        end
+      end
+    end
+
+    if !HAS_KEYWORD_INIT
+      def initialize(h = {})
+        super(*members.map { |m| h.key?(m) ? h.delete(m) : nil })
+        raise(ArgumentError, "#{self.class} given non-members: #{h}") if !h.empty?
+      end
+    end
+
+    # @return [self.class]
+    def merge(**h)
+      self.class.new(**to_h, **h)
+    end
+
+    def pretty_print(q)
+      jsi_pp_object_group(q) do
+        q.seplist(each_pair) do |k, v|
+          q.text(k.to_s)
+          q.text(': ')
+          q.pp(v)
+        end
+      end
+    end
+  end
+end

data/lib/jsi/uri.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module JSI
+  # JSI::URI adds to Addressable::URI:
+  #
+  # - `JSI::URI["http://x"]` parses, and JSI::URI#inspect shows this form, copy/pastable
+  # - Immutable when instantiated with `.[]`, `.parse`, or modified-copy instance methods join, merge, or normalize.
+  #   However `.new` and `#dup` do not freeze for compatibility with some libraries (Faraday) that dup and mutate URIs.
+  # @private
+  class URI < Addressable::URI
+    class << self
+      # @param uri [#to_str]
+      # @return [URI]
+      def [](uri)
+        parse(uri)
+      end
+
+      def parse(uri)
+        super.freeze
+      end
+    end
+
+    def join(uri)
+      super.freeze
+    end
+
+    def merge(hash)
+      super.freeze
+    end
+
+    def normalize
+      super.freeze
+    end
+
+    # @return [String]
+    def inspect
+      -"#{self.class}[#{to_s.inspect}]"
+    end
+  end
+end

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

@@ -25,15 +25,6 @@ module JSI
     end
 
     class MemoMap::Mutable < MemoMap
-      Result = AttrStruct[*%w(
-        value
-        inputs
-        inputs_hash
-      )]
-
-      class Result
-      end
-
       def [](**inputs)
         key = key_for(inputs)
 
@@ -43,11 +34,12 @@ module JSI
 
         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
+          result_value, result_inputs, result_inputs_hash = @results[key]
+          if inputs_hash == result_inputs_hash && inputs == result_inputs
+            result_value
           else
             value = @block.call(**inputs)
-            @results[key] = Result.new(value: value, inputs: inputs, inputs_hash: inputs_hash)
+            @results[key] = [value, inputs, inputs_hash]
             value
           end
         end
@@ -58,6 +50,8 @@ module JSI
       def [](**inputs)
         key = key_for(inputs)
 
+        return @results[key] if @results.key?(key)
+
         result_mutex = @result_mutexes_mutex.synchronize do
           @result_mutexes[key] ||= Mutex.new
         end
@@ -66,7 +60,9 @@ module JSI
           if @results.key?(key)
             @results[key]
           else
-            @results[key] = @block.call(**inputs)
+            result = @results[key] = @block.call(**inputs)
+            @result_mutexes.delete(key)
+            result
           end
         end
       end

data/lib/jsi/util/private.rb

@@ -5,13 +5,14 @@ module JSI
   #
   # @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
@@ -67,10 +68,16 @@ module JSI
     end
 
     def const_name_from_parts(parts, join: '')
+      initAZ = false
       parts = parts.map do |part|
-        part = part.dup
-        part[/\A[^a-zA-Z]*/] = ''
-        part[0] = part[0].upcase if part[0]
+        part = part.to_str.dup
+        if !initAZ
+          part[/\A[^a-zA-Z]*/] = ''
+        end
+        if part[0]
+          part[0] = part[0].upcase
+          initAZ = true
+        end
         part.gsub!(RUBY_REJECT_NAME_RE, '_')
         part
       end
@@ -81,18 +88,46 @@ module JSI
       end
     end
 
+    if JSON.parse('[]', freeze: true).frozen?
+      def json_parse_freeze(json)
+        JSON.parse(json, freeze: true)
+      end
+    else
+      def json_parse_freeze(json)
+        Util.deep_to_frozen(JSON.parse(json))
+      end
+    end
+
     # string or URI → frozen URI
-    # @return [Addressable::URI]
-    def uri(uri)
-      if uri.is_a?(Addressable::URI)
-        if uri.frozen?
-          uri
+    # @param nnil must not be nil
+    # @param yabs must be absolute
+    # @param ynorm must be normalized
+    # @param tonorm normalize returned URI
+    # @return [URI, nil]
+    def uri(uri, nnil: false, yabs: false, ynorm: false, tonorm: false)
+      return nil if !nnil && uri.nil?
+      if uri.is_a?(URI)
+        auri = uri
+      elsif uri.is_a?(String) || uri.respond_to?(:to_str)
+        auri = URI.parse(uri)
+      else
+        raise(URIError, "URI is not a string: #{uri.inspect}")
+      end
+      if yabs && !auri.scheme
+        raise(URIError, "URI must be an absolute URI. got: #{uri.inspect}")
+      end
+      if yabs && auri.fragment
+        if auri.fragment.empty?
+          auri = auri.merge(fragment: nil)
         else
-          uri.dup.freeze
+          raise(URIError, "URI must have no fragment. got: #{uri.inspect}")
         end
-      else
-        Addressable::URI.parse(uri).freeze
       end
+      if ynorm && uri.to_str != auri.normalize.to_s
+        raise(URIError, "URI must be in normalized form. got: #{uri.inspect}; normalized: #{auri.normalize.to_s.inspect}")
+      end
+      auri = auri.normalize if tonorm
+      auri
     end
 
     # this is the Y-combinator, which allows anonymous recursive functions. for a simple example,
@@ -139,6 +174,18 @@ module JSI
       nil
     end
 
+    # @param visited_refs [Array<Schema::Ref>]
+    # @param ref [Schema::Ref, nil]
+    # @return [Array<Schema::Ref>]
+    def add_visited_ref(visited_refs, ref)
+      return(visited_refs) if ref.nil?
+      #chkbug fail unless ref.is_a?(Schema::Ref) && visited_refs.is_a?(Array) && visited_refs.frozen?
+      if visited_refs.include?(ref)
+        raise(ResolutionError, "cyclical ref application with refs: #{visited_refs}")
+      end
+      visited_refs.dup.push(ref).freeze
+    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.
@@ -179,24 +226,5 @@ module JSI
         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