jsi 0.6.0 → 0.8.0

data/lib/jsi/schema_classes.rb

@@ -1,13 +1,24 @@
 # frozen_string_literal: true
 
 module JSI
-  # 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 Module associated with a JSI Schema. See {Schema#jsi_schema_module}.
+  class SchemaModule < Module
+    # @private
+    def initialize(schema, &block)
+      super(&block)
 
+      @jsi_node = schema
+
+      schema.jsi_schemas.each do |schema_schema|
+        extend SchemaClasses.schema_property_reader_module(schema_schema, conflicting_modules: Set[SchemaModule])
+      end
+    end
+
+    # The schema for which this is the JSI Schema Module
+    # @return [Base + Schema]
+    def schema
+      @jsi_node
+    end
 
     # a URI which refers to the schema. see {Schema#schema_uri}.
     # @return (see Schema#schema_uri)
@@ -18,256 +29,339 @@ module JSI
     # @return [String]
     def inspect
       if name_from_ancestor
-        "#{name_from_ancestor} (JSI Schema Module)"
+        if schema.schema_absolute_uri
+          -"#{name_from_ancestor} <#{schema.schema_absolute_uri}> (JSI Schema Module)"
+        else
+          -"#{name_from_ancestor} (JSI Schema Module)"
+        end
       else
-        "(JSI Schema Module: #{schema.schema_uri || schema.jsi_ptr.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.
+    def to_s
+      inspect
+    end
+
+    # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given parameters.
     #
     # @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)
+    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
+    #   inplace applicators of this module's schema.
+    def new_jsi(instance, **kw)
+      schema.new_jsi(instance, **kw)
+    end
+
+    # See {Schema#schema_content}
+    def schema_content
+      schema.jsi_node_content
+    end
+
+    # See {Schema#instance_validate}
+    def instance_validate(instance)
+      schema.instance_validate(instance)
+    end
+
+    # See {Schema#instance_valid?}
+    def instance_valid?(instance)
+      schema.instance_valid?(instance)
     end
   end
 
-  # 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.
+  # A module to extend the {SchemaModule} of a schema which describes other schemas (a {Schema::MetaSchema})
+  module SchemaModule::MetaSchemaModule
+    # Instantiates the given schema content as a JSI Schema.
     #
-    # see {JSI::Schema::DescribesSchema#new_schema}
+    # see {JSI::Schema::MetaSchema#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)
+    # @param (see Schema::MetaSchema#new_schema)
+    # @yield (see Schema::MetaSchema#new_schema)
+    # @return [JSI::Base subclass + JSI::Schema] a JSI which is a {JSI::Schema} whose content comes from
+    #   the given `schema_content` and whose schemas are inplace applicators of this module's schema
+    def new_schema(schema_content, **kw, &block)
+      schema.new_schema(schema_content, **kw, &block)
     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
+    # (see Schema::MetaSchema#new_schema_module)
+    def new_schema_module(schema_content, **kw, &block)
+      schema.new_schema(schema_content, **kw, &block).jsi_schema_module
+    end
+
+    # @return [Set<Module>]
+    def schema_implementation_modules
+      schema.schema_implementation_modules
     end
   end
 
   # this module is a namespace for building schema classes and schema modules.
+  # @api private
   module SchemaClasses
-    extend Util::Memoize
-
     class << self
+      # @private
+      # @return [Set<Module>]
+      def includes_for(instance)
+        includes = Set[]
+        includes << Base::ArrayNode if instance.respond_to?(:to_ary)
+        includes << Base::HashNode if instance.respond_to?(:to_hash)
+        includes << Base::StringNode if instance.respond_to?(:to_str)
+        includes.freeze
+      end
+
       # 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
+      # @api private
       # @param schemas [Enumerable<JSI::Schema>] schemas which the class will represent
+      # @param includes [Enumerable<Module>] modules which will be included on the class
       # @return [Class subclassing JSI::Base]
-      def class_for_schemas(schemas)
-        schemas = SchemaSet.ensure_schema_set(schemas)
+      def class_for_schemas(schemas, includes: , mutable: )
+        @class_for_schemas_map[
+          schemas: SchemaSet.ensure_schema_set(schemas),
+          includes: Util.ensure_module_set(includes),
+          mutable: mutable,
+        ]
+      end
 
-        jsi_memoize(:class_for_schemas, schemas) do |schemas|
-          Class.new(Base).instance_exec(schemas) do |schemas|
+      private def class_for_schemas_compute(schemas: , includes: , mutable: )
+          Class.new(Base) do
             define_singleton_method(:jsi_class_schemas) { schemas }
             define_method(:jsi_schemas) { schemas }
+
+            define_singleton_method(:jsi_class_includes) { includes }
+
+            mutability_module = mutable ? Base::Mutable : Base::Immutable
+            conflicting_modules = Set[JSI::Base, mutability_module] + includes + schemas.map(&:jsi_schema_module)
+
+            include(mutability_module)
+
+            reader_modules = schemas.map do |schema|
+              JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
+            end
+            reader_modules.each { |m| include m }
+            readers = reader_modules.map(&:jsi_property_readers).inject(Set[], &:merge).freeze
+            define_method(:jsi_property_readers) { readers }
+            define_singleton_method(:jsi_property_readers) { readers }
+
+            if mutable
+              writer_modules = schemas.map do |schema|
+                JSI::SchemaClasses.schema_property_writer_module(schema, conflicting_modules: conflicting_modules)
+              end
+              writer_modules.each { |m| include(m) }
+            end
+
+            includes.each { |m| include(m) }
             schemas.each { |schema| include(schema.jsi_schema_module) }
             jsi_class = self
             define_method(:jsi_class) { jsi_class }
 
             self
           end
-        end
       end
 
-      # @private
-      # a subclass of MetaschemaNode::BootstrapSchema with the given modules included
-      # @param modules [Set<Module>] metaschema instance modules
+      # a subclass of MetaSchemaNode::BootstrapSchema with the given modules included
+      # @api private
+      # @param modules [Set<Module>] schema implementation 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 }
+        @bootstrap_schema_class_map[
+          modules: Util.ensure_module_set(modules),
+        ]
+      end
+
+      private def bootstrap_schema_class_compute(modules: )
+          Class.new(MetaSchemaNode::BootstrapSchema) do
+            define_singleton_method(:schema_implementation_modules) { modules }
+            define_method(:schema_implementation_modules) { modules }
             modules.each { |mod| include(mod) }
 
             self
           end
-        end
       end
 
       # see {Schema#jsi_schema_module}
       # @api private
-      # @return [Module]
+      # @return [SchemaModule]
       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
-              define_singleton_method(:schema) { schema }
+        raise(Bug, "non-Base schema cannot have schema module: #{schema}") unless schema.is_a?(Base)
+        @schema_module_map[schema]
+      end
 
-              extend SchemaModule
+      # @private
+      # @deprecated after v0.7
+      def accessor_module_for_schema(schema, conflicting_modules: , setters: true)
+        Module.new do
+          include SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
+          include SchemaClasses.schema_property_writer_module(schema, conflicting_modules: conflicting_modules) if setters
+        end
+      end
 
-              schema.jsi_schema_instance_modules.each do |mod|
-                include(mod)
-              end
+      # a module of readers for described property names of the given schema.
+      #
+      # @private
+      # @param schema [JSI::Schema] a schema for which to define readers 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]
+      def schema_property_reader_module(schema, conflicting_modules: )
+        Schema.ensure_schema(schema)
+        @schema_property_reader_module_map[schema: schema, conflicting_modules: conflicting_modules]
+      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
+      private def schema_property_reader_module_compute(schema: , conflicting_modules: )
+          Module.new do
+            readers = schema.described_object_property_names.select do |name|
+              Util.ok_ruby_method_name?(name) &&
+                !conflicting_modules.any? { |m| m.method_defined?(name) || m.private_method_defined?(name) }
+            end.to_set.freeze
 
-              define_singleton_method(:jsi_property_accessors) { accessor_module.jsi_property_accessors }
+            define_singleton_method(:inspect) { "(JSI Schema Property Reader Module: #{readers.join(', ')})" }
 
-              if schema.describes_schema?
-                extend DescribesSchemaModule
-              end
+            define_singleton_method(:jsi_property_readers) { readers }
 
-              @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,
-                )
+            readers.each do |property_name|
+              define_method(property_name) do |**kw, &block|
+                self[property_name, **kw, &block]
               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)
+      # a module of writers for described property names of the given schema.
+      # @private
+      def schema_property_writer_module(schema, conflicting_modules: )
         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.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 |*a|
-                  self[property_name, *a]
-                end
-                if setters
+        @schema_property_writer_module_map[schema: schema, conflicting_modules: conflicting_modules]
+      end
+
+      private def schema_property_writer_module_compute(schema: , conflicting_modules: )
+          Module.new do
+            define_singleton_method(:inspect) { '(JSI Schema Property Writer Module)' }
+
+            writers = schema.described_object_property_names.select do |name|
+              writer = "#{name}="
+              Util.ok_ruby_method_name?(name) &&
+                !conflicting_modules.any? { |m| m.method_defined?(writer) || m.private_method_defined?(writer) }
+            end.to_set.freeze
+
+            define_singleton_method(:jsi_property_writers) { writers }
+
+            writers.each do |property_name|
                   define_method("#{property_name}=") do |value|
                     self[property_name] = value
                   end
-                end
-              end
             end
           end
-        end
       end
     end
+
+    @class_for_schemas_map          = Hash.new { |h, k| h[k] = class_for_schemas_compute(**k) }
+    @bootstrap_schema_class_map      = Hash.new { |h, k| h[k] = bootstrap_schema_class_compute(**k) }
+    @schema_module_map                = Hash.new { |h, schema| h[schema] = SchemaModule.new(schema) }
+    @schema_property_reader_module_map = Hash.new { |h, k| h[k] = schema_property_reader_module_compute(**k) }
+    @schema_property_writer_module_map = Hash.new { |h, k| h[k] = schema_property_writer_module_compute(**k) }
   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
+  # connecting {SchemaModule}s via {SchemaModule::Connection}s
+  module SchemaModule::Connects
+    attr_reader :jsi_node
 
     # a name relative to a named schema module of an ancestor schema.
-    # for example, if `Foos = JSI::JSONSchemaOrgDraft07.new_schema_module({'items' => {}})`
+    # for example, if `Foos = JSI::JSONSchemaDraft07.new_schema_module({'items' => {}})`
     # then the module `Foos.items` will have a name_from_ancestor of `"Foos.items"`
+    # @api private
     # @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
+      named_ancestor_schema, tokens = named_ancestor_schema_tokens
+      return nil unless named_ancestor_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
+      name = named_ancestor_schema.jsi_schema_module.name
+      ancestor = named_ancestor_schema
       tokens.each do |token|
-        if parent.jsi_schemas.any? { |s| s.jsi_schema_module.jsi_property_accessors.include?(token) }
+        if ancestor.jsi_property_readers.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]
+        ancestor = ancestor[token]
       end
-      name
+      name.freeze
     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.
+    # Subscripting a JSI schema module or a {SchemaModule::Connection} will subscript its node, and
+    # if the result is a JSI::Schema, return the JSI Schema module of that schema; if it is a JSI::Base,
+    # return a SchemaModule::Connection; 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]
+    # @yield If the token identifies a schema and a block is given,
+    #   it is evaluated in the context of the schema's JSI schema module
+    #   using [Module#module_exec](https://ruby-doc.org/core/Module.html#method-i-module_exec).
+    # @return [SchemaModule, SchemaModule::Connection, Object]
+    def [](token, **kw, &block)
+      raise(ArgumentError) unless kw.empty? # TODO remove eventually (keyword argument compatibility)
+      sub = @jsi_node[token]
       if sub.is_a?(JSI::Schema)
+        sub.jsi_schema_module_exec(&block) if block
         sub.jsi_schema_module
-      elsif sub.is_a?(JSI::PathedNode)
-        NotASchemaModule.new(sub)
+      elsif block
+        raise(ArgumentError, "block given but token #{token.inspect} does not identify a schema")
+      elsif sub.is_a?(JSI::Base)
+        SchemaModule::Connection.new(sub)
       else
         sub
       end
     end
+
+    private
+
+    # @return [Array<JSI::Schema, Array>, nil]
+    def named_ancestor_schema_tokens
+      schema_ancestors = @jsi_node.jsi_ancestor_nodes
+      named_ancestor_schema = schema_ancestors.detect { |jsi| jsi.is_a?(JSI::Schema) && jsi.jsi_schema_module.name }
+      return nil unless named_ancestor_schema
+      tokens = @jsi_node.jsi_ptr.relative_to(named_ancestor_schema.jsi_ptr).tokens
+      [named_ancestor_schema, tokens]
+    end
+  end
+
+  class SchemaModule
+    include Connects
   end
 
-  # a JSI Schema Module is a module which represents a schema. a NotASchemaModule represents
+  # A JSI Schema Module is a module which represents a schema. A SchemaModule::Connection 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]
+  # A SchemaModule::Connection has readers for property names described by the node's schemas.
+  class SchemaModule::Connection
+    include SchemaModule::Connects
+
+    # @param node [JSI::Base]
     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
+      raise(Bug, "node must be JSI::Base: #{node.pretty_inspect.chomp}") unless node.is_a?(JSI::Base)
+      raise(Bug, "node must not be JSI::Schema: #{node.pretty_inspect.chomp}") if node.is_a?(JSI::Schema)
+      @jsi_node = node
       node.jsi_schemas.each do |schema|
-        extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [NotASchemaModule, SchemaModulePossibly], setters: false))
+        extend(JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: [SchemaModule::Connection]))
       end
     end
 
-    include SchemaModulePossibly
-
     # @return [String]
     def inspect
       if name_from_ancestor
-        "#{name_from_ancestor} (JSI wrapper for Schema Module)"
+        -"#{name_from_ancestor} (#{self.class})"
       else
-        "(JSI wrapper for Schema Module: #{@possibly_schema_node.jsi_ptr.uri})"
+        -"(#{self.class}: #{@jsi_node.jsi_ptr.uri})"
       end
     end
+
+    def to_s
+      inspect
+    end
   end
 end