jsi 0.4.0 → 0.6.0

data/lib/jsi/schema_classes.rb

@@ -3,37 +3,73 @@
 module JSI
   # JSI Schema Modules are extended with JSI::SchemaModule
   module SchemaModule
-    # @return [String] absolute schema_id of the schema this module represents.
-    #   see {Schema#schema_id}.
-    def schema_id
-      schema.schema_id
+    # @!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
-      uri = schema.schema_id || schema.node_ptr.uri
-      if name
-        "#{name} (#{uri})"
+      if name_from_ancestor
+        "#{name_from_ancestor} (JSI Schema Module)"
       else
-        "(JSI Schema Module: #{uri})"
+        "(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 (see JSI::Schema#new_jsi)
     # @return [JSI::Base] a JSI whose instance is the given instance
-    def new_jsi(instance, *a, &b)
-      schema.new_jsi(instance, *a, &b)
+    def new_jsi(instance, **kw, &b)
+      schema.new_jsi(instance, **kw, &b)
     end
   end
 
-  # this module is just a namespace for schema classes.
+  # 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
+
+    # 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
-      include Util::Memoize
+      # 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)
 
-      # see {JSI.class_for_schemas}
-      def class_for_schemas(schema_objects)
-        schemas = schema_objects.map { |schema_object| JSI::Schema.from_object(schema_object) }.to_set
         jsi_memoize(:class_for_schemas, schemas) do |schemas|
           Class.new(Base).instance_exec(schemas) do |schemas|
             define_singleton_method(:jsi_class_schemas) { schemas }
@@ -47,13 +83,28 @@ module JSI
         end
       end
 
-      # a module for the given schema, with accessor methods for any object property names the schema
-      # identifies (see {JSI::Schema#described_object_property_names}).
-      #
-      # defines a singleton method #schema to access the {JSI::Schema} this module represents, and extends
-      # the module with {JSI::SchemaModule}.
-      def module_for_schema(schema_object)
-        schema = JSI::Schema.from_object(schema_object)
+      # @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
+
+      # 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.module_eval do
@@ -61,41 +112,67 @@ module JSI
 
               extend SchemaModule
 
-              include JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [JSI::Base, JSI::PathedArrayNode, JSI::PathedHashNode])
+              schema.jsi_schema_instance_modules.each do |mod|
+                include(mod)
+              end
+
+              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
 
               @possibly_schema_node = schema
               extend(SchemaModulePossibly)
               schema.jsi_schemas.each do |schema_schema|
-                extend(JSI::SchemaClasses.accessor_module_for_schema(schema_schema, conflicting_modules: [Module, SchemaModule, SchemaModulePossibly]))
+                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.
-      # @return [Module] a module of accessors (setters and getters) for described property names of the given
-      #   schema
-      def accessor_module_for_schema(schema, conflicting_modules: )
-        unless schema.is_a?(JSI::Schema)
-          raise(JSI::Schema::NotASchemaError, "not a schema: #{schema.pretty_inspect.chomp}")
-        end
-        jsi_memoize(:accessor_module_for_schema, schema, conflicting_modules) do |schema, conflicting_modules|
+      # @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
-                  self[property_name]
+                define_method(property_name) do |*a|
+                  self[property_name, *a]
                 end
-                define_method("#{property_name}=") do |value|
-                  self[property_name] = value
+                if setters
+                  define_method("#{property_name}=") do |value|
+                    self[property_name] = value
+                  end
                 end
               end
             end
@@ -105,17 +182,43 @@ module JSI
     end
   end
 
-  # a JSI::Schema module and a JSI::NotASchemaModule are both a SchemaModulePossibly.
+  # 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 a JSI::Schema class; if it is a PathedNode,
+    # 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 [Class, NotASchemaModule, Object]
+    # @return [Module, NotASchemaModule, Object]
     def [](token)
       sub = @possibly_schema_node[token]
       if sub.is_a?(JSI::Schema)
@@ -128,9 +231,12 @@ module JSI
     end
   end
 
-  # a schema module is a module which represents a schema. a NotASchemaModule represents
+  # 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'
-  # node (which contains schemas but is not a schema).
+  # 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.
   #
@@ -149,10 +255,19 @@ module JSI
       end
       @possibly_schema_node = node
       node.jsi_schemas.each do |schema|
-        extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [NotASchemaModule, SchemaModulePossibly]))
+        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,10 +1,10 @@
 # frozen_string_literal: true
 
 module JSI
-  SimpleWrap = JSI::Schema.new({
+  SimpleWrap = JSI::JSONSchemaOrgDraft06.new_schema_module({
     "additionalProperties": {"$ref": "#"},
     "items": {"$ref": "#"}
-  }).jsi_schema_module
+  })
 
   # SimpleWrap is a JSI schema module which recursively wraps nested structures
   module SimpleWrap