jsi 0.2.0 → 0.6.0

data/lib/jsi/schema_classes.rb

@@ -1,79 +1,177 @@
+# frozen_string_literal: true
+
 module JSI
-  # this module is just a namespace for schema classes.
-  module SchemaClasses
-    # JSI::SchemaClasses[schema_id] returns a class for the schema with the
-    # given id, the same class as returned from JSI.class_for_schema.
+  # JSI Schema Modules are extended with JSI::SchemaModule
+  module SchemaModule
+    # @!method schema
+    #   the schema of which this is the JSI Schema Module
+    #   @return [Schema]
+    # note: defined on JSI Schema Module by JSI::SchemaClasses.module_for_schema
+
+
+    # a URI which refers to the schema. see {Schema#schema_uri}.
+    # @return (see Schema#schema_uri)
+    def schema_uri
+      schema.schema_uri
+    end
+
+    # @return [String]
+    def inspect
+      if name_from_ancestor
+        "#{name_from_ancestor} (JSI Schema Module)"
+      else
+        "(JSI Schema Module: #{schema.schema_uri || schema.jsi_ptr.uri})"
+      end
+    end
+
+    # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given instance.
     #
-    # @param schema_id [String] absolute schema id as returned by {JSI::Schema#schema_id}
-    # @return [Class subclassing JSI::Base] the class for that schema
-    def self.[](schema_id)
-      @classes_by_id[schema_id]
+    # @param (see JSI::Schema#new_jsi)
+    # @return [JSI::Base] a JSI whose instance is the given instance
+    def new_jsi(instance, **kw, &b)
+      schema.new_jsi(instance, **kw, &b)
     end
-    @classes_by_id = {}
+  end
 
-    class << self
-      include Memoize
+  # a module to extend the JSI Schema Module of a schema which describes other schemas
+  module DescribesSchemaModule
+    # instantiates the given schema content as a JSI Schema.
+    #
+    # see {JSI::Schema::DescribesSchema#new_schema}
+    #
+    # @param (see JSI::Schema::DescribesSchema#new_schema)
+    # @return [JSI::Base, JSI::Schema] a JSI whose instance is the given schema_content and whose schemas
+    #   consist of this module's schema.
+    def new_schema(schema_content, **kw)
+      schema.new_schema(schema_content, **kw)
+    end
 
-      # see {JSI.class_for_schema}
-      def class_for_schema(schema_object)
-        memoize(:class_for_schema, JSI::Schema.from_object(schema_object)) do |schema_|
-          Class.new(Base).instance_exec(schema_) do |schema|
-            define_singleton_method(:schema) { schema }
-            define_method(:schema) { schema }
-            include(JSI::SchemaClasses.module_for_schema(schema, conflicting_modules: [Base, BaseArray, BaseHash]))
+    # instantiates a given schema object as a JSI Schema and returns its JSI Schema Module.
+    #
+    # shortcut to chain {JSI::Schema::DescribesSchema#new_schema} + {Schema#jsi_schema_module}.
+    #
+    # @param (see JSI::Schema::DescribesSchema#new_schema)
+    # @return [Module, JSI::SchemaModule] the JSI Schema Module of the schema
+    def new_schema_module(schema_content, **kw)
+      schema.new_schema(schema_content, **kw).jsi_schema_module
+    end
+  end
+
+  # this module is a namespace for building schema classes and schema modules.
+  module SchemaClasses
+    extend Util::Memoize
+
+    class << self
+      # a JSI Schema Class which represents the given schemas.
+      # an instance of the class is a JSON Schema instance described by all of the given schemas.
+      # @private
+      # @param schemas [Enumerable<JSI::Schema>] schemas which the class will represent
+      # @return [Class subclassing JSI::Base]
+      def class_for_schemas(schemas)
+        schemas = SchemaSet.ensure_schema_set(schemas)
 
+        jsi_memoize(:class_for_schemas, schemas) do |schemas|
+          Class.new(Base).instance_exec(schemas) do |schemas|
+            define_singleton_method(:jsi_class_schemas) { schemas }
+            define_method(:jsi_schemas) { schemas }
+            schemas.each { |schema| include(schema.jsi_schema_module) }
             jsi_class = self
             define_method(:jsi_class) { jsi_class }
 
-            SchemaClasses.instance_exec(self) { |klass| @classes_by_id[klass.schema_id] = klass }
+            self
+          end
+        end
+      end
+
+      # @private
+      # a subclass of MetaschemaNode::BootstrapSchema with the given modules included
+      # @param modules [Set<Module>] metaschema instance modules
+      # @return [Class]
+      def bootstrap_schema_class(modules)
+        modules = Util.ensure_module_set(modules)
+        jsi_memoize(__method__, modules) do |modules|
+          Class.new(MetaschemaNode::BootstrapSchema).instance_exec(modules) do |modules|
+            define_singleton_method(:metaschema_instance_modules) { modules }
+            define_method(:metaschema_instance_modules) { modules }
+            modules.each { |mod| include(mod) }
 
             self
           end
         end
       end
 
-      # a module for the given schema, with accessor methods for any object
-      # property names the schema identifies. also has a singleton method
-      # called #schema to access the {JSI::Schema} this module represents.
-      #
-      # accessor methods are defined on these modules so that methods can be
-      # defined on {JSI.class_for_schema} classes without method redefinition
-      # warnings. additionally, these overriding instance methods can call
-      # `super` to invoke the normal accessor behavior.
-      #
-      # no property names that are the same as existing method names on the JSI
-      # class will be defined. users should use #[] and #[]= to access properties
-      # whose names conflict with existing methods.
-      def SchemaClasses.module_for_schema(schema_object, conflicting_modules: [])
-        schema__ = JSI::Schema.from_object(schema_object)
-        memoize(:module_for_schema, schema__, conflicting_modules) do |schema_, conflicting_modules_|
+      # see {Schema#jsi_schema_module}
+      # @api private
+      # @return [Module]
+      def module_for_schema(schema)
+        Schema.ensure_schema(schema)
+        jsi_memoize(:module_for_schema, schema) do |schema|
           Module.new.tap do |m|
-            m.instance_exec(schema_) do |schema|
+            m.module_eval do
               define_singleton_method(:schema) { schema }
-              define_singleton_method(:schema_id) do
-                schema.schema_id
+
+              extend SchemaModule
+
+              schema.jsi_schema_instance_modules.each do |mod|
+                include(mod)
               end
-              define_singleton_method(:inspect) do
-                %Q(#<Module for Schema: #{schema_id}>)
+
+              accessor_module = JSI::SchemaClasses.accessor_module_for_schema(schema,
+                conflicting_modules: Set[JSI::Base, JSI::PathedArrayNode, JSI::PathedHashNode] +
+                  schema.jsi_schema_instance_modules,
+              )
+              include accessor_module
+
+              define_singleton_method(:jsi_property_accessors) { accessor_module.jsi_property_accessors }
+
+              if schema.describes_schema?
+                extend DescribesSchemaModule
               end
 
-              conflicting_instance_methods = (conflicting_modules_ + [m]).map do |mod|
+              @possibly_schema_node = schema
+              extend(SchemaModulePossibly)
+              schema.jsi_schemas.each do |schema_schema|
+                extend JSI::SchemaClasses.accessor_module_for_schema(schema_schema,
+                  conflicting_modules: Set[Module, SchemaModule, SchemaModulePossibly],
+                  setters: false,
+                )
+              end
+            end
+          end
+        end
+      end
+
+      # a module of accessors for described property names of the given schema.
+      # getters are always defined. setters are defined by default.
+      # @param schema [JSI::Schema] a schema for which to define accessors for any described property names
+      # @param conflicting_modules [Enumerable<Module>] an array of modules (or classes) which
+      #   may be used alongside the accessor module. methods defined by any conflicting_module
+      #   will not be defined as accessors.
+      # @param setters [Boolean] whether to define setter methods
+      # @return [Module]
+      def accessor_module_for_schema(schema, conflicting_modules: , setters: true)
+        Schema.ensure_schema(schema)
+        jsi_memoize(:accessor_module_for_schema, schema, conflicting_modules, setters) do |schema, conflicting_modules, setters|
+          Module.new.tap do |m|
+            m.module_eval do
+              conflicting_instance_methods = (conflicting_modules + [m]).map do |mod|
                 mod.instance_methods + mod.private_instance_methods
               end.inject(Set.new, &:|)
-              accessors_to_define = schema.described_object_property_names.map(&:to_s) - conflicting_instance_methods.map(&:to_s)
+
+              accessors_to_define = schema.described_object_property_names.select do |name|
+                # must not conflict with any method on a conflicting module
+                Util.ok_ruby_method_name?(name) && !conflicting_instance_methods.any? { |mn| mn.to_s == name }
+              end.to_set.freeze
+
+              define_singleton_method(:jsi_property_accessors) { accessors_to_define }
+
               accessors_to_define.each do |property_name|
-                define_method(property_name) do
-                  if respond_to?(:[])
-                    self[property_name]
-                  else
-                    raise(NoMethodError, "schema instance of class #{self.class} does not respond to []; cannot call reader '#{property_name}'. instance is #{instance.pretty_inspect.chomp}")
-                  end
+                define_method(property_name) do |*a|
+                  self[property_name, *a]
                 end
-                define_method("#{property_name}=") do |value|
-                  if respond_to?(:[]=)
+                if setters
+                  define_method("#{property_name}=") do |value|
                     self[property_name] = value
-                  else
-                    raise(NoMethodError, "schema instance of class #{self.class} does not respond to []=; cannot call writer '#{property_name}='. instance is #{instance.pretty_inspect.chomp}")
                   end
                 end
               end
@@ -83,4 +181,93 @@ module JSI
       end
     end
   end
+
+  # a JSI Schema module and a JSI::NotASchemaModule are both a SchemaModulePossibly.
+  # this module provides a #[] method.
+  module SchemaModulePossibly
+    attr_reader :possibly_schema_node
+
+    # a name relative to a named schema module of an ancestor schema.
+    # for example, if `Foos = JSI::JSONSchemaOrgDraft07.new_schema_module({'items' => {}})`
+    # then the module `Foos.items` will have a name_from_ancestor of `"Foos.items"`
+    # @return [String, nil]
+    def name_from_ancestor
+      schema_ancestors = [possibly_schema_node] + possibly_schema_node.jsi_parent_nodes
+      named_parent_schema = schema_ancestors.detect { |jsi| jsi.is_a?(JSI::Schema) && jsi.jsi_schema_module.name }
+
+      return nil unless named_parent_schema
+
+      tokens = possibly_schema_node.jsi_ptr.ptr_relative_to(named_parent_schema.jsi_ptr).tokens
+      name = named_parent_schema.jsi_schema_module.name
+      parent = named_parent_schema
+      tokens.each do |token|
+        if parent.jsi_schemas.any? { |s| s.jsi_schema_module.jsi_property_accessors.include?(token) }
+          name += ".#{token}"
+        elsif [String, Numeric, TrueClass, FalseClass, NilClass].any? { |m| token.is_a?(m) }
+          name += "[#{token.inspect}]"
+        else
+          return nil
+        end
+        parent = parent[token]
+      end
+      name
+    end
+
+    # subscripting a JSI schema module or a NotASchemaModule will subscript the node, and
+    # if the result is a JSI::Schema, return the JSI Schema module of that schema; if it is a PathedNode,
+    # return a NotASchemaModule; or if it is another value (a basic type), return that value.
+    #
+    # @param token [Object]
+    # @return [Module, NotASchemaModule, Object]
+    def [](token)
+      sub = @possibly_schema_node[token]
+      if sub.is_a?(JSI::Schema)
+        sub.jsi_schema_module
+      elsif sub.is_a?(JSI::PathedNode)
+        NotASchemaModule.new(sub)
+      else
+        sub
+      end
+    end
+  end
+
+  # a JSI Schema Module is a module which represents a schema. a NotASchemaModule represents
+  # a node in a schema's document which is not a schema, such as the 'properties'
+  # object (which contains schemas but is not a schema).
+  #
+  # instances of this class act as a stand-in to allow users to subscript or call property accessors on
+  # schema modules to refer to their subschemas' schema modules.
+  #
+  # a NotASchemaModule is extended with the module_for_schema of the node's schema.
+  #
+  # NotASchemaModule holds a node which is not a schema. when subscripted, it subscripts
+  # its node. if the value is a JSI::Schema, its schema module is returned. if the value
+  # is another node, a NotASchemaModule for that node is returned. otherwise - when the
+  # value is a basic type - that value itself is returned.
+  class NotASchemaModule
+    # @param node [JSI::PathedNode]
+    def initialize(node)
+      unless node.is_a?(JSI::PathedNode)
+        raise(TypeError, "not JSI::PathedNode: #{node.pretty_inspect.chomp}")
+      end
+      if node.is_a?(JSI::Schema)
+        raise(TypeError, "cannot instantiate NotASchemaModule for a JSI::Schema node: #{node.pretty_inspect.chomp}")
+      end
+      @possibly_schema_node = node
+      node.jsi_schemas.each do |schema|
+        extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [NotASchemaModule, SchemaModulePossibly], setters: false))
+      end
+    end
+
+    include SchemaModulePossibly
+
+    # @return [String]
+    def inspect
+      if name_from_ancestor
+        "#{name_from_ancestor} (JSI wrapper for Schema Module)"
+      else
+        "(JSI wrapper for Schema Module: #{@possibly_schema_node.jsi_ptr.uri})"
+      end
+    end
+  end
 end

data/lib/jsi/schema_registry.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module JSI
+  class SchemaRegistry
+    # an exception raised when an attempt is made to register a resource using a URI which is already
+    # registered with another resource
+    class Collision < StandardError
+    end
+
+    # an exception raised when an attempt is made to access (register or find) a resource of the
+    # registry using a URI which is not absolute (it is a relative URI or it contains a fragment)
+    class NonAbsoluteURI < StandardError
+    end
+
+    # an exception raised when a URI we are looking for has not been registered
+    class ResourceNotFound < StandardError
+    end
+
+    def initialize
+      @resources = {}
+      @autoload_uris = {}
+      @resources_mutex = Mutex.new
+    end
+
+    # registers the given resource and/or schema resources it contains in the registry.
+    #
+    # each child of the resource (including the resource itself) is registered if it is a schema that
+    # has an absolute URI (generally defined by the '$id' keyword).
+    #
+    # the given resource itself will be registered, whether or not it is a schema, if it is the root
+    # of its document and was instantiated with the option `uri` specified.
+    #
+    # @param resource [JSI::Base] a JSI containing resources to register
+    # @return [void]
+    def register(resource)
+      unless resource.is_a?(JSI::Base)
+        raise(ArgumentError, "resource must be a JSI::Base. got: #{resource.pretty_inspect.chomp}")
+      end
+      unless resource.is_a?(JSI::Schema) || resource.jsi_ptr.root?
+        # unsure, should this be allowed? the given JSI is not a "resource" as we define it, but
+        # if this check is removed it will just register any resources (schemas) below the given JSI.
+        raise(ArgumentError, "undefined behavior: registration of a JSI which is not a schema and is not at the root of a document")
+      end
+
+      # allow for registration of resources at the root of a document whether or not they are schemas.
+      # jsi_schema_base_uri at the root comes from the `uri` parameter to new_jsi / new_schema.
+      if resource.jsi_schema_base_uri && resource.jsi_ptr.root?
+        register_single(resource.jsi_schema_base_uri, resource)
+      end
+
+      resource.jsi_each_child_node do |node|
+        if node.is_a?(JSI::Schema) && node.schema_absolute_uri
+          register_single(node.schema_absolute_uri, node)
+        end
+      end
+
+      nil
+    end
+
+    # takes a URI identifying a resource to be loaded by the given block
+    # when a reference to the URI is followed.
+    #
+    # for example:
+    #
+    #     JSI.schema_registry.autoload_uri('http://example.com/schema.json') do
+    #       JSI.new_schema({
+    #         '$schema' => 'http://json-schema.org/draft-07/schema#',
+    #         '$id' => 'http://example.com/schema.json',
+    #         'title' => 'my schema',
+    #       })
+    #     end
+    #
+    # the block would normally load JSON from the filesystem or similar.
+    #
+    # @param uri [Addressable::URI]
+    # @yieldreturn [JSI::Base] a JSI instance containing the resource identified by the given uri
+    # @return [void]
+    def autoload_uri(uri, &block)
+      uri = Addressable::URI.parse(uri)
+      ensure_uri_absolute(uri)
+      @autoload_uris[uri] = block
+      nil
+    end
+
+    # @param uri [Addressable::URI, #to_str]
+    # @return [JSI::Base]
+    # @raise [JSI::SchemaRegistry::ResourceNotFound]
+    def find(uri)
+      uri = Addressable::URI.parse(uri)
+      ensure_uri_absolute(uri)
+      if @autoload_uris.key?(uri) && !@resources.key?(uri)
+        register(@autoload_uris[uri].call)
+      end
+      registered_uris = @resources.keys
+      if !registered_uris.include?(uri)
+        raise(ResourceNotFound, "URI #{uri} is not registered. registered URIs:\n#{registered_uris.join("\n")}")
+      end
+      @resources[uri]
+    end
+
+    def dup
+      self.class.new.tap do |reg|
+        @resources.each do |uri, resource|
+          reg.register_single(uri, resource)
+        end
+        @autoload_uris.each do |uri, autoload|
+          reg.autoload_uri(uri, &autoload)
+        end
+      end
+    end
+
+    protected
+    # @param uri [Addressable::URI]
+    # @param resource [JSI::Base]
+    # @return [void]
+    def register_single(uri, resource)
+      @resources_mutex.synchronize do
+        ensure_uri_absolute(uri)
+        if @resources.key?(uri)
+          if @resources[uri] != resource
+            raise(Collision, "URI collision on #{uri}.\nexisting:\n#{@resources[uri].pretty_inspect.chomp}\nnew:\n#{resource.pretty_inspect.chomp}")
+          end
+        else
+          @resources[uri] = resource
+        end
+      end
+      nil
+    end
+
+    private
+
+    def ensure_uri_absolute(uri)
+      if uri.fragment
+        raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access URI with fragment: #{uri}")
+      end
+      if uri.relative?
+        raise(NonAbsoluteURI, "#{self.class} only registers absolute URIs. cannot access relative URI: #{uri}")
+      end
+    end
+  end
+end

data/lib/jsi/schema_set.rb

@@ -0,0 +1,141 @@
+# 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)
+      super
+
+      not_schemas = reject { |s| s.is_a?(Schema) }
+      if !not_schemas.empty?
+        raise(Schema::NotASchemaError, [
+          "JSI::SchemaSet initialized with non-schema objects:",
+          *not_schemas.map { |ns| ns.pretty_inspect.chomp },
+        ].join("\n"))
+      end
+
+      freeze
+    end
+
+    # instantiates the given instance as a JSI. its schemas are inplace applicators matched from the schemas
+    # in this SchemaSet which apply to the given instance.
+    #
+    # @param instance [Object] the JSON Schema instance to be represented as a JSI
+    # @param uri [nil, #to_str, Addressable::URI] for an instance document containing schemas, this is
+    #   the URI of the document, whether or not the document is itself a schema.
+    #   in the normal case where the document does not contain any schemas, `uri` has no effect.
+    #   schemas within the document use this uri as the base URI to resolve relative URIs.
+    #   the resulting JSI may be registered with a {SchemaRegistry} (see {JSI.schema_registry}).
+    # @return [JSI::Base subclass] a JSI whose instance is the given instance and whose schemas are inplace
+    #   applicators matched to the instance from the schemas in this set.
+    def new_jsi(instance,
+        uri: nil
+    )
+      applied_schemas = inplace_applicator_schemas(instance)
+
+      jsi = JSI::SchemaClasses.class_for_schemas(applied_schemas).new(instance,
+        jsi_schema_base_uri: uri,
+      )
+
+      jsi
+    end
+
+    # a set of inplace applicator schemas of each schema in this set which apply to the given instance.
+    # (see {Schema::Application::InplaceApplication#inplace_applicator_schemas})
+    #
+    # @param instance (see Schema::Application::InplaceApplication#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::Application::InplaceApplication#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
+
+    # 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
+
+    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

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 module JSI
-  SimpleWrap = JSI.class_for_schema({"additionalProperties": {"$ref": "#"}, "items": {"$ref": "#"}})
+  SimpleWrap = JSI::JSONSchemaOrgDraft06.new_schema_module({
+    "additionalProperties": {"$ref": "#"},
+    "items": {"$ref": "#"}
+  })
 
-  # SimpleWrap is a JSI class which recursively wraps nested structures
-  class SimpleWrap
+  # SimpleWrap is a JSI schema module which recursively wraps nested structures
+  module SimpleWrap
   end
 end