jsi 0.8.1 → 0.9.0

data/lib/jsi/schema_classes.rb

@@ -1,19 +1,93 @@
 # frozen_string_literal: true
 
 module JSI
-  # 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
+  # class SchemaModule < class SchemaModule::Connection < class Module
+  # this unusual configuration of a class (SchemaModule) subclassing a class inside its own
+  # namespace (SchemaModule::Connection) follows reconfiguration changing Connection from a regular
+  # class to subclass Module, so that a JSI that isn't a Schema can have a named module, and schemas
+  # within that JSI's document have a useful name_from_ancestor when inspecting their instances.
+  begin # shenanigans to get classes configured while not confusing yard
+    SchemaModule = Class.new(Class.new(Module))
+    SchemaModule.const_set(:Connection, SchemaModule.superclass)
+  end
 
+  # A Module associated with a JSI Schema (its {Schema#jsi_schema_module #jsi_schema_module}).
+  #
+  # This module may be opened by the application to define methods for instances described by its schema.
+  #
+  # The schema module can also be used in some of the same ways as its schema:
+  # JSI instances of the schema can be instantiated using {#new_jsi}, or instances
+  # can be validated with {#instance_valid?} or {#instance_validate}.
+  # Often the schema module is the more convenient object to work with with than the JSI Schema.
+  #
+  # Naming the schema module (assigning it to a constant) can be useful in a few ways.
+  #
+  # - When inspected, instances of a schema with a named schema module will show that name.
+  # - Naming the module allows it to be opened with Ruby's `module` syntax. Any schema module
+  #   can be opened with [Module#module_exec](https://ruby-doc.org/core/Module.html#method-i-module_exec)
+  #   (or from the Schema with {Schema#jsi_schema_module_exec jsi_schema_module_exec})
+  #   but the `module` syntax can be more convenient, especially for assigning or accessing constants.
+  #
+  # The schema module makes it straightforward to access the schema modules of the schema's subschemas.
+  # It defines readers for schema properties (keywords) on its singleton (that is,
+  # called on the module itself, not on instances of it) to access these.
+  # The {SchemaModule::Connection#[] #[]} method can also be used.
+  #
+  # For example, given a schema with an `items` subschema, then `schema.items.jsi_schema_module`
+  # and `schema.jsi_schema_module.items` both refer to the same module.
+  # Subscripting with {SchemaModule::Connection#[] #[]} can refer to subschemas on properties
+  # that can have any name, e.g. `schema.properties['foo'].jsi_schema_module` is the same as
+  # `schema.jsi_schema_module.properties['foo']`.
+  #
+  # Schema module property readers and `#[]` can also take a block, which is passed to `module_exec`.
+  #
+  # Putting the above together, here is example usage with the schema module of the Contact
+  # schema used in the README:
+  #
+  # ```ruby
+  # Contact = JSI.new_schema_module({
+  #   "$schema" => "http://json-schema.org/draft-07/schema",
+  #   "type" => "object",
+  #   "properties" => {
+  #     "name" => {"type" => "string"},
+  #     "phone" => {
+  #       "type" => "array",
+  #       "items" => {
+  #         "type" => "object",
+  #         "properties" => {
+  #           "location" => {"type" => "string"},
+  #           "number" => {"type" => "string"}
+  #         }
+  #       }
+  #     }
+  #   }
+  # })
+  #
+  # module Contact
+  #   # name a subschema's schema module
+  #   PhoneNumber = properties['phone'].items
+  #
+  #   # open a subschema's schema module to define methods
+  #   properties['phone'] do
+  #     def numbers
+  #       map(&:number)
+  #     end
+  #   end
+  # end
+  #
+  # bill = Contact.new_jsi({"name" => "bill", "phone" => [{"location" => "home", "number" => "555"}]})
+  # #> #{<JSI (Contact)>
+  # #>   "name" => "bill",
+  # #>   "phone" => #[<JSI (Contact.properties["phone"])>
+  # #>     #{<JSI (Contact::PhoneNumber)> "location" => "home", "number" => "555"}
+  # #>   ],
+  # #>   "nickname" => "big b"
+  # #> }
+  # ```
+  #
+  # Note that when `bill` is inspected, schema module names `Contact`, `Contact.properties["phone"]`,
+  # and `Contact::PhoneNumber` are informatively shown on respective instances.
+  class SchemaModule < SchemaModule::Connection
     # The schema for which this is the JSI Schema Module
     # @return [Base + Schema]
     def schema
@@ -28,14 +102,15 @@ module JSI
 
     # @return [String]
     def inspect
+      dam_s = " #{schema.jsi_schema_dynamic_anchor_map.anchor_schemas_identifier}" if !schema.jsi_schema_dynamic_anchor_map.empty?
       if name_from_ancestor
-        if schema.schema_absolute_uri
-          -"#{name_from_ancestor} <#{schema.schema_absolute_uri}> (JSI Schema Module)"
+        if schema.jsi_resource_uri
+          -"#{name_from_ancestor} <#{schema.jsi_resource_uri}>#{dam_s} (JSI Schema Module)"
         else
-          -"#{name_from_ancestor} (JSI Schema Module)"
+          -"#{name_from_ancestor}#{dam_s} (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}#{dam_s})"
       end
     end
 
@@ -45,10 +120,10 @@ module JSI
 
     # invokes {JSI::Schema#new_jsi} on this module's schema, passing the given parameters.
     #
-    # @param (see JSI::Schema#new_jsi)
-    # @return [JSI::Base subclass] a JSI whose content comes from the given instance and whose schemas are
-    #   inplace applicators of this module's schema.
+    # @return [Base] a JSI whose content comes from the given instance and whose schemas are
+    #   in-place applicators of this module's schema.
     def new_jsi(instance, **kw)
+      raise(BlockGivenError) if block_given?
       schema.new_jsi(instance, **kw)
     end
 
@@ -66,35 +141,44 @@ module JSI
     def instance_valid?(instance)
       schema.instance_valid?(instance)
     end
+
+    # See {Schema#describes_schema!}
+    def describes_schema!(dialect = nil)
+      schema.describes_schema!(dialect)
+    end
+
+    # @private pending stronger stability of dynamic scope
+    # See {Schema#with_dynamic_scope_from}
+    def with_dynamic_scope_from(node)
+      schema.with_dynamic_scope_from(node).jsi_schema_module
+    end
   end
 
   # 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::MetaSchema#new_schema}
+    # See {JSI::Schema::MetaSchema#new_schema}.
     #
-    # @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
+    # @return [Base + Schema] A JSI which is a {Schema} whose content comes from
+    #   the given `schema_content` and whose schemas are in-place applicators of this module's schema.
     def new_schema(schema_content, **kw, &block)
       schema.new_schema(schema_content, **kw, &block)
     end
 
     # (see Schema::MetaSchema#new_schema_module)
     def new_schema_module(schema_content, **kw, &block)
-      schema.new_schema(schema_content, **kw, &block).jsi_schema_module
+      schema.new_schema_module(schema_content, **kw, &block)
     end
 
-    # @return [Set<Module>]
-    def schema_implementation_modules
-      schema.schema_implementation_modules
+    # @return [Schema::Dialect]
+    def described_dialect
+      schema.described_dialect
     end
   end
 
   # this module is a namespace for building schema classes and schema modules.
-  # @api private
+  # @private
   module SchemaClasses
     class << self
       # @private
@@ -112,24 +196,26 @@ module JSI
       # @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]
+      # @return [Class subclass of JSI::Base]
       def class_for_schemas(schemas, includes: , mutable: )
         @class_for_schemas_map[
-          schemas: SchemaSet.ensure_schema_set(schemas),
-          includes: Util.ensure_module_set(includes),
+          schema_modules: schemas.map(&:jsi_schema_module).to_set.freeze,
+          includes: includes.to_set.freeze,
           mutable: mutable,
         ]
       end
 
-      private def class_for_schemas_compute(schemas: , includes: , mutable: )
+      private def class_for_schemas_compute(schema_modules: , includes: , mutable: )
           Class.new(Base) do
+            schemas = SchemaSet.new(schema_modules.map(&:schema))
+
             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)
+            conflicting_modules = Set[JSI::Base, mutability_module] + includes + schema_modules
 
             include(mutability_module)
 
@@ -149,52 +235,10 @@ module JSI
             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
-
-      # 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)
-        @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
+            schema_modules.to_a.reverse_each { |m| include(m) }
           end
       end
 
-      # see {Schema#jsi_schema_module}
-      # @api private
-      # @return [SchemaModule]
-      def module_for_schema(schema)
-        Schema.ensure_schema(schema)
-        raise(Bug, "non-Base schema cannot have schema module: #{schema}") unless schema.is_a?(Base)
-        @schema_module_map[schema]
-      end
-
-      # @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
-
       # a module of readers for described property names of the given schema.
       #
       # @private
@@ -204,18 +248,17 @@ module JSI
       #   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
-
-      private def schema_property_reader_module_compute(schema: , conflicting_modules: )
-          Module.new do
-            readers = schema.described_object_property_names.select do |name|
+        @schema_property_reader_module_map[
+            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
+        ]
+      end
 
-            define_singleton_method(:inspect) { "(JSI Schema Property Reader Module: #{readers.join(', ')})" }
+      private def schema_property_reader_module_compute(readers)
+          Module.new do
+            define_singleton_method(:inspect) { -"(JSI Schema Property Reader Module: #{readers.to_a.join(', ')})" }
 
             define_singleton_method(:jsi_property_readers) { readers }
 
@@ -230,19 +273,18 @@ module JSI
       # 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)
-        @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|
+        @schema_property_writer_module_map[
+            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
+        ]
+      end
+
+      private def schema_property_writer_module_compute(writers)
+          Module.new do
+            define_singleton_method(:inspect) { -"(JSI Schema Property Writer Module: #{writers.to_a.join(', ')})" }
 
             define_singleton_method(:jsi_property_writers) { writers }
 
@@ -256,14 +298,11 @@ module JSI
     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) }
+    @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
 
-  # connecting {SchemaModule}s via {SchemaModule::Connection}s
-  module SchemaModule::Connects
+  class SchemaModule::Connection
     attr_reader :jsi_node
 
     # a name relative to a named schema module of an ancestor schema.
@@ -272,11 +311,11 @@ module JSI
     # @api private
     # @return [String, nil]
     def name_from_ancestor
-      named_ancestor_schema, tokens = named_ancestor_schema_tokens
-      return nil unless named_ancestor_schema
+      named_ancestor, tokens = named_ancestor_tokens
+      return nil unless named_ancestor
 
-      name = named_ancestor_schema.jsi_schema_module.name
-      ancestor = named_ancestor_schema
+      name = named_ancestor.jsi_schema_module_connection.name
+      ancestor = named_ancestor
       tokens.each do |token|
         if ancestor.jsi_property_readers.include?(token)
           name += ".#{token}"
@@ -290,9 +329,16 @@ module JSI
       name.freeze
     end
 
+    # See {Base#/} - descendent's {Base#jsi_schema_module_connection}
+    # @param (see Base#/)
+    # @return [SchemaModule::Connection]
+    def /(ptr)
+      (jsi_node / ptr).jsi_schema_module_connection
+    end
+
     # 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.
+    # return a SchemaModule::Connection; or if it is another value (a simple type), return that value.
     #
     # @param token [Object]
     # @yield If the token identifies a schema and a block is given,
@@ -301,35 +347,32 @@ module JSI
     # @return [SchemaModule, SchemaModule::Connection, Object]
     def [](token, **kw, &block)
       raise(ArgumentError) unless kw.empty? # TODO remove eventually (keyword argument compatibility)
+      @jsi_node.jsi_child_ensure_present(token)
       sub = @jsi_node[token]
       if sub.is_a?(JSI::Schema)
         sub.jsi_schema_module_exec(&block) if block
         sub.jsi_schema_module
       elsif block
-        raise(ArgumentError, "block given but token #{token.inspect} does not identify a schema")
+        raise(BlockGivenError, "block given but token #{token.inspect} does not identify a schema")
       elsif sub.is_a?(JSI::Base)
-        SchemaModule::Connection.new(sub)
+        sub.jsi_schema_module_connection
       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]
+    private def named_ancestor_tokens
+      ancestors = @jsi_node.jsi_ancestor_nodes
+      named_ancestor = ancestors.detect do |jsi|
+        jsi.jsi_schema_module_connection_defined? && jsi.jsi_schema_module_connection.name
+      end
+      return nil unless named_ancestor
+      tokens = @jsi_node.jsi_ptr.relative_to(named_ancestor.jsi_ptr).tokens
+      [named_ancestor, tokens]
     end
   end
 
-  class SchemaModule
-    include Connects
-  end
-
   # 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).
@@ -338,17 +381,18 @@ module JSI
   # schema modules to refer to their subschemas' schema modules.
   #
   # A SchemaModule::Connection has readers for property names described by the node's schemas.
-  class SchemaModule::Connection
-    include SchemaModule::Connects
-
+  #
+  # This class subclasses Module only so that it can be named, to identify schemas descendent of its node.
+  # No object is ever expected to be an instance of a SchemaModule::Connection module.
+  class SchemaModule::Connection < Module
     # @param node [JSI::Base]
     def initialize(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)
+      fail(Bug, "node must be JSI::Base: #{node.pretty_inspect.chomp}") unless node.is_a?(JSI::Base)
       @jsi_node = node
       node.jsi_schemas.each do |schema|
         extend(JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: [SchemaModule::Connection]))
       end
+      node.jsi_schema_module_connection_created(self)
     end
 
     # @return [String]