jsi 0.4.0 → 0.7.0

data/lib/jsi/jsi_coder.rb

@@ -11,7 +11,7 @@ module JSI
   # `preferences_json` which is an actual json column, and `preferences_txt`
   # which is a string:
   #
-  #     Preferences = JSI.class_for_schema(preferences_json_schema)
+  #     Preferences = JSI.new_schema_module(preferences_json_schema)
   #     class Foo < ActiveRecord::Base
   #       # as a single serializer, loads a Preferences instance from a json column
   #       serialize 'preferences_json', JSI::JSICoder.new(Preferences)
@@ -25,13 +25,13 @@ module JSI
   # (represented as one json object) or an array of them (represented as a json
   # array of json objects), indicated by the keyword argument `array`.
   class JSICoder
-    # @param schema [JSI::Schema, JSI::SchemaModule, Class < JSI::Base] a schema, a JSI schema class, or
-    #   a JSI schema module. #load will instantiate column data using the JSI schema represented.
+    # @param schema [#new_jsi] a Schema, SchemaSet, or JSI schema module. #load
+    #   will instantiate column data using the JSI schemas represented.
     # @param array [Boolean] whether the dumped data represent one instance of the schema,
     #   or an array of them. note that it may be preferable to simply use an array schema.
     def initialize(schema, array: false)
       unless schema.respond_to?(:new_jsi)
-        raise(ArgumentError, "not a JSI schema, class, or module: #{schema.inspect}")
+        raise(ArgumentError, "schema param does not respond to #new_jsi: #{schema.inspect}")
       end
       @schema = schema
       @array = array
@@ -48,13 +48,14 @@ module JSI
         unless data.respond_to?(:to_ary)
           raise TypeError, "expected array-like column data; got: #{data.class}: #{data.inspect}"
         end
-        data.map { |el| load_object(el) }
+        data.to_ary.map { |el| load_object(el) }
       else
         load_object(data)
       end
       object
     end
 
+    # dumps the object for the database
     # @param object [JSI::Base, Array<JSI::Base>, nil] the JSI or array of JSIs containing
     #   the schema instance(s)
     # @return [Object, Array, nil] the schema instance(s) of the JSI(s), or nil if object is nil
@@ -65,7 +66,7 @@ module JSI
           unless object.respond_to?(:to_ary)
             raise(TypeError, "expected array-like attribute; got: #{object.class}: #{object.inspect}")
           end
-          object.map do |el|
+          object.to_ary.map do |el|
             dump_object(el)
           end
         else
@@ -85,7 +86,7 @@ module JSI
     # @param object [JSI::Base, Object]
     # @return [Object]
     def dump_object(object)
-      JSI::Typelike.as_json(object)
+      JSI::Util.as_json(object)
     end
   end
 end

data/lib/jsi/metaschema.rb

@@ -2,6 +2,5 @@
 
 module JSI
   module Metaschema
-    include JSI::Schema::DescribesSchema
   end
 end

data/lib/jsi/metaschema_node/bootstrap_schema.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module JSI
+  # internal class to bootstrap a metaschema. represents a schema without the complexity of JSI::Base. the
+  # schema is represented but schemas describing the schema are not.
+  #
+  # this class is to only be instantiated on nodes in the document that are known to be schemas.
+  # Schema#subschema and Schema#resource_root_subschema are the intended mechanisms to instantiate subschemas
+  # and resolve references. #[] and #jsi_root_node are not implemented.
+  #
+  # schema implementation modules are attached to generated subclasses of BootstrapSchema by
+  # {SchemaClasses.bootstrap_schema_class}. that subclass is instantiated with a document and
+  # pointer, representing a schema.
+  #
+  # @api private
+  class MetaschemaNode::BootstrapSchema
+    include Util::Memoize
+    include Util::FingerprintHash
+    include Schema::SchemaAncestorNode
+
+    class << self
+      def inspect
+        if self == MetaschemaNode::BootstrapSchema
+          name
+        else
+          "#{name || MetaschemaNode::BootstrapSchema.name} (#{schema_implementation_modules.map(&:inspect).join(', ')})"
+        end
+      end
+
+      alias_method :to_s, :inspect
+    end
+
+    # @param jsi_ptr [JSI::Ptr] pointer to the schema in the document
+    # @param jsi_document [#to_hash, #to_ary, Boolean, Object] document containing the schema
+    def initialize(
+        jsi_document,
+        jsi_ptr: Ptr[],
+        jsi_schema_base_uri: nil
+    )
+      raise(Bug, "no #schema_implementation_modules") unless respond_to?(:schema_implementation_modules)
+
+      jsi_initialize_memos
+
+      self.jsi_ptr = jsi_ptr
+      self.jsi_document = jsi_document
+      self.jsi_schema_base_uri = jsi_schema_base_uri
+    end
+
+    # document containing the schema content
+    attr_reader :jsi_document
+
+    # JSI::Ptr pointing to this schema within the document
+    attr_reader :jsi_ptr
+
+    def jsi_node_content
+      jsi_ptr.evaluate(jsi_document)
+    end
+
+    # @return [String]
+    def inspect
+      "\#<#{jsi_object_group_text.join(' ')} #{schema_content.inspect}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    # pretty-prints a representation of self to the given printer
+    # @return [void]
+    def pretty_print(q)
+      q.text '#<'
+      q.text jsi_object_group_text.join(' ')
+      q.group_sub {
+        q.nest(2) {
+          q.breakable ' '
+          q.pp schema_content
+        }
+      }
+      q.breakable ''
+      q.text '>'
+    end
+
+    # @private
+    # @return [Array<String>]
+    def jsi_object_group_text
+      [
+        self.class.name || MetaschemaNode::BootstrapSchema.name,
+        "(#{schema_implementation_modules.map(&:inspect).join(', ')})",
+        jsi_ptr.uri,
+      ]
+    end
+
+    # @private
+    def jsi_fingerprint
+      {
+        class: self.class,
+        jsi_ptr: @jsi_ptr,
+        jsi_document: @jsi_document,
+        schema_implementation_modules: schema_implementation_modules,
+      }
+    end
+  end
+end

data/lib/jsi/metaschema_node.rb

@@ -1,218 +1,242 @@
 # frozen_string_literal: true
 
 module JSI
-  # a MetaschemaNode is a PathedNode whose node_document contains a metaschema.
-  # as with any PathedNode the node_ptr points to the content of a node.
+  # a MetaschemaNode is a JSI instance representing a node in a document which contains a metaschema.
   # the root of the metaschema is pointed to by metaschema_root_ptr.
-  # the schema of the root of the document is pointed to by root_schema_ptr.
+  # the schema describing the root of the document is pointed to by root_schema_ptr.
   #
-  # like JSI::Base, this class represents an instance of a schema, an instance
-  # which may itself be a schema. unlike JSI::Base, the document containing the
-  # schema and the instance is the same, and a schema may be an instance of itself.
+  # like JSI::Base's normal subclasses, this class represents an instance of a schema set, an instance
+  # which may itself be a schema. unlike JSI::Base, the document containing the instance and its schemas
+  # is the same, and a schema (the metaschema) may be an instance of itself.
   #
-  # the document containing the metaschema, its subschemas, and instances of those
-  # subschemas is the node_document.
+  # unlike JSI::Base's normal subclasses, the schemas describing the instance are not part of the class.
+  # since the metaschema describes itself, attempting to construct a class from the JSI Schema Module of a
+  # schema which is itself an instance of that class results in a causality loop.
+  # instead, a MetaschemaNode calculates its {#jsi_schemas} and extends itself with their JSI Schema
+  # modules during initialization.
+  # the MetaschemaNode of the metaschema is extended with its own JSI Schema Module.
   #
-  # the schema instance is the content in the document pointed to by the MetaschemaNode's node_ptr.
-  #
-  # unlike with JSI::Base, the schema is not part of the class, since a metaschema
-  # needs the ability to have its schema be the instance itself.
-  #
-  # if the MetaschemaNode's schema is its self, it will be extended with JSI::Metaschema.
+  # if the MetaschemaNode's schemas include its self, it is extended with JSI::Metaschema.
   #
   # a MetaschemaNode is extended with JSI::Schema when it represents a schema - this is the case when
-  # its schema is the metaschema.
-  class MetaschemaNode
-    include PathedNode
-    include Util::Memoize
-
-    # not every MetaschemaNode is actually an Enumerable, but it's better to include Enumerable on
-    # the class than to conditionally extend the instance.
-    include Enumerable
-
-    # @param node_document the document containing the metaschema
-    # @param node_ptr [JSI::JSON::Pointer] ptr to this MetaschemaNode in node_document
-    # @param metaschema_root_ptr [JSI::JSON::Pointer] ptr to the root of the metaschema in node_document
-    # @param root_schema_ptr [JSI::JSON::Pointer] ptr to the schema of the root of the node_document
-    def initialize(node_document, node_ptr: JSI::JSON::Pointer[], metaschema_root_ptr: JSI::JSON::Pointer[], root_schema_ptr: JSI::JSON::Pointer[])
-      @node_document = node_document
-      @node_ptr = node_ptr
+  # the metaschema is one of its schemas.
+  class MetaschemaNode < Base
+    autoload :BootstrapSchema, 'jsi/metaschema_node/bootstrap_schema'
+
+    # @param jsi_document the document containing the metaschema
+    # @param jsi_ptr [JSI::Ptr] ptr to this MetaschemaNode in jsi_document
+    # @param schema_implementation_modules [Enumerable<Module>] modules which implement the functionality
+    #   of the schema. these are included on the {Schema#jsi_schema_module} of the metaschema.
+    #   they extend any schema described by the metaschema, including those in the document containing
+    #   the metaschema, and the metaschema itself.
+    #   see {Schema#describes_schema!} param `schema_implementation_modules`.
+    # @param metaschema_root_ptr [JSI::Ptr] ptr to the root of the metaschema in the jsi_document
+    # @param root_schema_ptr [JSI::Ptr] ptr to the schema describing the root of the jsi_document
+    def initialize(
+        jsi_document,
+        jsi_ptr: Ptr[],
+        schema_implementation_modules: ,
+        metaschema_root_ptr: Ptr[],
+        root_schema_ptr: Ptr[],
+        jsi_schema_base_uri: nil,
+        jsi_root_node: nil
+    )
+      jsi_initialize_memos
+
+      self.jsi_document = jsi_document
+      self.jsi_ptr = jsi_ptr
+      @schema_implementation_modules = Util.ensure_module_set(schema_implementation_modules)
       @metaschema_root_ptr = metaschema_root_ptr
       @root_schema_ptr = root_schema_ptr
+      raise(Bug, 'jsi_root_node') if jsi_ptr.root? ^ !jsi_root_node
+      @jsi_root_node = jsi_ptr.root? ? self : jsi_root_node
+
+      if jsi_ptr.root? && jsi_schema_base_uri
+        raise(NotImplementedError, "unsupported jsi_schema_base_uri on metaschema document root")
+      end
+      self.jsi_schema_base_uri = jsi_schema_base_uri
+
+      jsi_node_content = self.jsi_node_content
 
-      node_content = self.node_content
+      if jsi_node_content.respond_to?(:to_hash)
+        extend HashNode
+      end
+      if jsi_node_content.respond_to?(:to_ary)
+        extend ArrayNode
+      end
 
-      if node_content.respond_to?(:to_hash)
-        extend PathedHashNode
-      elsif node_content.respond_to?(:to_ary)
-        extend PathedArrayNode
+      instance_for_schemas = jsi_document
+      bootstrap_schema_class = JSI::SchemaClasses.bootstrap_schema_class(schema_implementation_modules)
+      root_bootstrap_schema = bootstrap_schema_class.new(
+        jsi_document,
+        jsi_ptr: root_schema_ptr,
+        jsi_schema_base_uri: nil, # supplying jsi_schema_base_uri on root bootstrap schema is not supported
+      )
+      our_bootstrap_schemas = jsi_ptr.tokens.inject(SchemaSet[root_bootstrap_schema]) do |bootstrap_schemas, tok|
+        child_indicated_schemas = bootstrap_schemas.child_applicator_schemas(tok, instance_for_schemas)
+        child_schemas = child_indicated_schemas.inplace_applicator_schemas(instance_for_schemas[tok])
+        instance_for_schemas = instance_for_schemas[tok]
+        child_schemas
       end
 
-      instance_for_schema = node_document
-      schema_ptrs = node_ptr.reference_tokens.inject(Set.new << root_schema_ptr) do |ptrs, tok|
-        if instance_for_schema.respond_to?(:to_ary)
-          subschema_ptrs_for_token = ptrs.map do |ptr|
-            ptr.schema_subschema_ptrs_for_index(node_document, tok)
-          end.inject(Set.new, &:|)
-        else
-          subschema_ptrs_for_token = ptrs.map do |ptr|
-            ptr.schema_subschema_ptrs_for_property_name(node_document, tok)
-          end.inject(Set.new, &:|)
+      our_bootstrap_schemas.each do |bootstrap_schema|
+        if bootstrap_schema.jsi_ptr == metaschema_root_ptr
+          # this is described by the metaschema, i.e. this is a schema
+          schema_implementation_modules.each do |schema_implementation_module|
+            extend schema_implementation_module
+          end
+        end
+        if bootstrap_schema.jsi_ptr == jsi_ptr
+          # this is the metaschema (it is described by itself)
+          extend Metaschema
         end
-        instance_for_schema = instance_for_schema[tok]
-        ptrs_for_instance = subschema_ptrs_for_token.map do |ptr|
-          ptr.schema_match_ptrs_to_instance(node_document, instance_for_schema)
-        end.inject(Set.new, &:|)
-        ptrs_for_instance
       end
 
-      @jsi_schemas = schema_ptrs.map do |schema_ptr|
-        if schema_ptr == node_ptr
+      @jsi_schemas = SchemaSet.new(our_bootstrap_schemas) do |bootstrap_schema|
+        if bootstrap_schema.jsi_ptr == jsi_ptr
           self
+        elsif bootstrap_schema.jsi_ptr.root?
+          @jsi_root_node
         else
-          new_node(node_ptr: schema_ptr)
+          new_node(
+            jsi_ptr: bootstrap_schema.jsi_ptr,
+            jsi_schema_base_uri: bootstrap_schema.jsi_schema_base_uri,
+            jsi_root_node: @jsi_root_node,
+          )
         end
-      end.to_set
+      end
+
+      # note: jsi_schemas must already be set for jsi_schema_module to be used/extended
+      if is_a?(Metaschema)
+        describes_schema!(schema_implementation_modules)
+      end
 
       @jsi_schemas.each do |schema|
-        if schema.node_ptr == metaschema_root_ptr
-          extend JSI::Schema
-        end
-        if schema.node_ptr == node_ptr
-          extend Metaschema
-        end
-        extend(JSI::SchemaClasses.accessor_module_for_schema(schema, conflicting_modules: [Metaschema, Schema, MetaschemaNode, PathedArrayNode, PathedHashNode]))
+        extend schema.jsi_schema_module
       end
 
       # workarounds
       begin # draft 4 boolean schema workaround
         # in draft 4, boolean schemas are not described in the root, but on anyOf schemas on
         # properties/additionalProperties and properties/additionalItems.
-        # we need to extend those as DescribesSchema.
+        # these still describe schemas, despite not being described by the metaschema.
         addtlPropsanyOf = metaschema_root_ptr["properties"]["additionalProperties"]["anyOf"]
         addtlItemsanyOf = metaschema_root_ptr["properties"]["additionalItems"]["anyOf"]
 
-        if !node_ptr.root? && [addtlPropsanyOf, addtlItemsanyOf].include?(node_ptr.parent)
-          extend JSI::Schema::DescribesSchema
+        if !jsi_ptr.root? && [addtlPropsanyOf, addtlItemsanyOf].include?(jsi_ptr.parent)
+          describes_schema!(schema_implementation_modules)
         end
       end
     end
 
-    # document containing the metaschema. see PathedNode#node_document.
-    attr_reader :node_document
-    # ptr to this metaschema node. see PathedNode#node_ptr.
-    attr_reader :node_ptr
-    # ptr to the root of the metaschema in the node_document
+    # Set of modules to apply to schemas which are instances of (described by) the metaschema
+    # @return [Set<Module>]
+    attr_reader :schema_implementation_modules
+
+    # ptr to the root of the metaschema in the jsi_document
+    # @return [JSI::Ptr]
     attr_reader :metaschema_root_ptr
-    # ptr to the schema of the root of the node_document
-    attr_reader :root_schema_ptr
-    # JSI::Schemas describing this MetaschemaNode
-    attr_reader :jsi_schemas
 
-    # @return [MetaschemaNode] document root MetaschemaNode
-    def document_root_node
-      new_node(node_ptr: JSI::JSON::Pointer[])
-    end
+    # ptr to the schema of the root of the jsi_document
+    # @return [JSI::Ptr]
+    attr_reader :root_schema_ptr
 
-    # @return [MetaschemaNode] parent MetaschemaNode
-    def parent_node
-      new_node(node_ptr: node_ptr.parent)
-    end
+    # JSI Schemas describing this MetaschemaNode
+    # @return [JSI::SchemaSet]
+    attr_reader :jsi_schemas
 
-    # @param token [String, Integer, Object] the token to subscript
-    # @return [MetaschemaNode, Object] the node content's subscript value at the given token.
-    #   if there is a subschema defined for that token on this MetaschemaNode's schema,
-    #   returns that value as a MetaschemaNode instantiation of that subschema.
-    def [](token)
+    # subscripts to return a child value identified by the given token.
+    #
+    # @param token (see JSI::Base#[])
+    # @param as_jsi (see JSI::Base#[])
+    # @return (see JSI::Base#[])
+    def [](token, as_jsi: :auto)
       if respond_to?(:to_hash)
-        token_in_range = node_content_hash_pubsend(:key?, token)
-        value = node_content_hash_pubsend(:[], token)
+        token_in_range = jsi_node_content_hash_pubsend(:key?, token)
+        value = jsi_node_content_hash_pubsend(:[], token)
       elsif respond_to?(:to_ary)
-        token_in_range = node_content_ary_pubsend(:each_index).include?(token)
-        value = node_content_ary_pubsend(:[], token)
+        token_in_range = jsi_node_content_ary_pubsend(:each_index).include?(token)
+        value = jsi_node_content_ary_pubsend(:[], token)
       else
-        raise(NoMethodError, "cannot subcript (using token: #{token.inspect}) from content: #{node_content.pretty_inspect.chomp}")
+        raise(NoMethodError, "cannot subscript (using token: #{token.inspect}) from content: #{jsi_node_content.pretty_inspect.chomp}")
       end
 
-      result = jsi_memoize(:[], token, value, token_in_range) do |token, value, token_in_range|
+      begin
         if token_in_range
-          value_node = new_node(node_ptr: node_ptr[token])
+          value_node = jsi_subinstance_memos[token: token]
 
-          if value_node.is_a?(Schema) || value.respond_to?(:to_hash) || value.respond_to?(:to_ary)
+          jsi_subinstance_as_jsi(value, value_node.jsi_schemas, as_jsi) do
             value_node
-          else
-            value
           end
         else
           # I think I will not support Hash#default/#default_proc in this case.
           nil
         end
       end
-      result
-    end
-
-    # if this MetaschemaNode is a $ref then the $ref is followed. otherwise this MetaschemaNode is returned.
-    # @return [MetaschemaNode]
-    def deref(&block)
-      node_ptr_deref do |deref_ptr|
-        return new_node(node_ptr: deref_ptr).tap(&(block || Util::NOOP))
-      end
-      return self
     end
 
+    # instantiates a new MetaschemaNode whose instance is a modified copy of this MetaschemaNode's instance
     # @yield [Object] the node content of the instance. the block should result
     #   in a (nondestructively) modified copy of this.
     # @return [MetaschemaNode] modified copy of self
-    def modified_copy(&block)
-      MetaschemaNode.new(node_ptr.modified_document_copy(node_document, &block), our_initialize_params)
-    end
-
-    # @return [String]
-    def inspect
-      "\#<#{object_group_text.join(' ')} #{node_content.inspect}>"
-    end
-
-    def pretty_print(q)
-      q.text '#<'
-      q.text object_group_text.join(' ')
-      q.group_sub {
-        q.nest(2) {
-          q.breakable ' '
-          q.pp node_content
-        }
-      }
-      q.breakable ''
-      q.text '>'
+    def jsi_modified_copy(&block)
+      if jsi_ptr.root?
+        modified_document = jsi_ptr.modified_document_copy(jsi_document, &block)
+        MetaschemaNode.new(modified_document, **our_initialize_params)
+      else
+        modified_jsi_root_node = jsi_root_node.jsi_modified_copy do |root|
+          jsi_ptr.modified_document_copy(root, &block)
+        end
+        modified_jsi_root_node.jsi_descendent_node(jsi_ptr)
+      end
     end
 
+    # @private
     # @return [Array<String>]
-    def object_group_text
-      if jsi_schemas.any?
-        class_n_schemas = "#{self.class} (#{jsi_schemas.map { |s| s.node_ptr.uri }.join(' ')})"
+    def jsi_object_group_text
+      if jsi_schemas && jsi_schemas.any?
+        class_n_schemas = "#{self.class} (#{jsi_schemas.map { |s| s.jsi_ptr.uri }.join(' ')})"
       else
         class_n_schemas = self.class.to_s
       end
       [
         class_n_schemas,
         is_a?(Metaschema) ? "Metaschema" : is_a?(Schema) ? "Schema" : nil,
-        *(node_content.respond_to?(:object_group_text) ? node_content.object_group_text : []),
+        *(jsi_node_content.respond_to?(:jsi_object_group_text) ? jsi_node_content.jsi_object_group_text : []),
       ].compact
     end
 
-    # @return [Object] an opaque fingerprint of this MetaschemaNode for FingerprintHash
+    # an opaque fingerprint of this MetaschemaNode for FingerprintHash
     def jsi_fingerprint
-      {class: self.class, node_document: node_document}.merge(our_initialize_params)
+      {class: self.class, jsi_document: jsi_document}.merge(our_initialize_params)
     end
-    include Util::FingerprintHash
 
     private
 
+    # note: does not include jsi_root_node
     def our_initialize_params
-      {node_ptr: node_ptr, metaschema_root_ptr: metaschema_root_ptr, root_schema_ptr: root_schema_ptr}
+      {
+        jsi_ptr: jsi_ptr,
+        schema_implementation_modules: schema_implementation_modules,
+        metaschema_root_ptr: metaschema_root_ptr,
+        root_schema_ptr: root_schema_ptr,
+        jsi_schema_base_uri: jsi_schema_base_uri,
+      }
     end
 
+    # note: not for root node
     def new_node(params)
-      MetaschemaNode.new(node_document, our_initialize_params.merge(params))
+      MetaschemaNode.new(jsi_document, **our_initialize_params.merge(params))
+    end
+
+    def jsi_subinstance_memos
+      jsi_memomap(:subinstance) do |token: |
+        new_node(
+          jsi_ptr: jsi_ptr[token],
+          jsi_schema_base_uri: jsi_resource_ancestor_uri,
+          jsi_root_node: jsi_root_node,
+        )
+      end
     end
   end
 end