jsi 0.2.0 → 0.6.0

data/lib/jsi/jsi_coder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JSI
   # this is an ActiveRecord serialization coder intended to serialize between
   # JSON-compatible objects on the database side, and a JSI instance loaded on
@@ -9,34 +11,37 @@ 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', JSI::JSICoder.new(Preferences)
+  #       serialize 'preferences_json', JSI::JSICoder.new(Preferences)
   #
   #       # for a text column, arms_serialize will go from JSI to JSON-compatible
   #       # objects to a string. the symbol `:jsi` is a shortcut for JSI::JSICoder.
-  #       arms_serialize 'preferences', [:jsi, Preferences], :json
+  #       arms_serialize 'preferences_txt', [:jsi, Preferences], :json
   #     end
   #
-  # the column data may be either a single instance of the loaded class
+  # the column data may be either a single instance of the schema class
   # (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 loaded_class [Class] the JSI::Base subclass which #load will instantiate
-    # @param array [Boolean] whether the dumped data represent one instance of loaded_class,
-    #   or an array of them. note that it may be preferable to have loaded_class simply be
-    #   an array schema class.
-    def initialize(loaded_class, array: false)
-      @loaded_class = loaded_class
+    # @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, "schema param does not respond to #new_jsi: #{schema.inspect}")
+      end
+      @schema = schema
       @array = array
     end
 
-    # loads the database column to instances of #loaded_class
+    # loads the database column to JSI instances of our schema
     #
     # @param data [Object, Array, nil] the dumped schema instance(s) of the JSI(s)
-    # @return [loaded_class instance, Array<loaded_class instance>, nil] the JSI or JSIs
-    #   containing the schema instance(s), or nil if data is nil
+    # @return [JSI::Base, Array<JSI::Base>, nil] the JSI or JSIs containing the schema
+    #   instance(s), or nil if data is nil
     def load(data)
       return nil if data.nil?
       object = if @array
@@ -50,8 +55,9 @@ module JSI
       object
     end
 
-    # @param object [loaded_class instance, Array<loaded_class instance>, nil] the JSI or array
-    #   of JSIs containing the schema instance(s)
+    # 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
     def dump(object)
       return nil if object.nil?
@@ -72,12 +78,12 @@ module JSI
 
     private
     # @param data [Object]
-    # @return [loaded_class]
+    # @return [JSI::Base]
     def load_object(data)
-      @loaded_class.new(data)
+      @schema.new_jsi(data)
     end
 
-    # @param object [loaded_class]
+    # @param object [JSI::Base, Object]
     # @return [Object]
     def dump_object(object)
       JSI::Typelike.as_json(object)

data/lib/jsi/metaschema.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module JSI
+  module Metaschema
+    include JSI::Schema::DescribesSchema
+  end
+end

data/lib/jsi/metaschema_node/bootstrap_schema.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module JSI
+  # @private
+  # 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.
+  #
+  # metaschema instance 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.
+  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} (#{metaschema_instance_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
+    )
+      unless respond_to?(:metaschema_instance_modules)
+        raise(TypeError, "cannot instantiate #{self.class.inspect} which has no method #metaschema_instance_modules")
+      end
+
+      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
+
+    # 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,
+        "(#{metaschema_instance_modules.map(&:inspect).join(', ')})",
+        jsi_ptr.uri,
+      ]
+    end
+
+    # @private
+    def jsi_fingerprint
+      {
+        class: self.class,
+        jsi_ptr: @jsi_ptr,
+        jsi_document: @jsi_document,
+        metaschema_instance_modules: metaschema_instance_modules,
+      }
+    end
+  end
+end

data/lib/jsi/metaschema_node.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module JSI
+  # 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 describing the root of the document is pointed to by root_schema_ptr.
+  #
+  # 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.
+  #
+  # 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.
+  #
+  # 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
+  # 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 metaschema_instance_modules [Enumerable<Module>] modules which implement the functionality of the
+    #   schema, to be applied to every schema which is an instance of the metaschema. this must include
+    #   JSI::Schema directly or indirectly. these are the {Schema#jsi_schema_instance_modules} of the
+    #   metaschema.
+    # @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[],
+        metaschema_instance_modules: ,
+        metaschema_root_ptr: Ptr[],
+        root_schema_ptr: Ptr[],
+        jsi_schema_base_uri: nil
+    )
+      jsi_initialize_memos
+
+      self.jsi_document = jsi_document
+      self.jsi_ptr = jsi_ptr
+      @metaschema_instance_modules = Util.ensure_module_set(metaschema_instance_modules)
+      @metaschema_root_ptr = metaschema_root_ptr
+      @root_schema_ptr = root_schema_ptr
+
+      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
+
+      if jsi_node_content.respond_to?(:to_hash)
+        extend PathedHashNode
+      end
+      if jsi_node_content.respond_to?(:to_ary)
+        extend PathedArrayNode
+      end
+
+      instance_for_schemas = jsi_document
+      bootstrap_schema_class = JSI::SchemaClasses.bootstrap_schema_class(metaschema_instance_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_instance_for_schemas = instance_for_schemas[tok]
+        bootstrap_schemas_for_instance = SchemaSet.build do |schemas|
+          bootstrap_schemas.each do |bootstrap_schema|
+            bootstrap_schema.each_child_applicator_schema(tok, instance_for_schemas) do |child_app_schema|
+              child_app_schema.each_inplace_applicator_schema(child_instance_for_schemas) do |child_inpl_app_schema|
+                schemas << child_inpl_app_schema
+              end
+            end
+          end
+        end
+        instance_for_schemas = child_instance_for_schemas
+        bootstrap_schemas_for_instance
+      end
+
+      our_bootstrap_schemas.each do |bootstrap_schema|
+        if bootstrap_schema.jsi_ptr == metaschema_root_ptr
+          metaschema_instance_modules.each do |metaschema_instance_module|
+            extend metaschema_instance_module
+          end
+        end
+        if bootstrap_schema.jsi_ptr == jsi_ptr
+          extend Metaschema
+          self.jsi_schema_instance_modules = metaschema_instance_modules
+        end
+      end
+
+      @jsi_schemas = SchemaSet.new(our_bootstrap_schemas) do |bootstrap_schema|
+        if bootstrap_schema.jsi_ptr == jsi_ptr
+          self
+        else
+          new_node(
+            jsi_ptr: bootstrap_schema.jsi_ptr,
+            jsi_schema_base_uri: bootstrap_schema.jsi_schema_base_uri,
+          )
+        end
+      end
+
+      @jsi_schemas.each do |schema|
+        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.
+        # since these describe schemas, their jsi_schema_instance_modules are the metaschema_instance_modules.
+        addtlPropsanyOf = metaschema_root_ptr["properties"]["additionalProperties"]["anyOf"]
+        addtlItemsanyOf = metaschema_root_ptr["properties"]["additionalItems"]["anyOf"]
+
+        if !jsi_ptr.root? && [addtlPropsanyOf, addtlItemsanyOf].include?(jsi_ptr.parent)
+          self.jsi_schema_instance_modules = metaschema_instance_modules
+        end
+      end
+    end
+
+    # Set of modules to apply to schemas which are instances of (described by) the metaschema
+    # @return [Set<Module>]
+    attr_reader :metaschema_instance_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 jsi_document
+    # @return [JSI::Ptr]
+    attr_reader :root_schema_ptr
+
+    # JSI Schemas describing this MetaschemaNode
+    # @return [JSI::SchemaSet]
+    attr_reader :jsi_schemas
+
+    # document root MetaschemaNode
+    # @return [MetaschemaNode]
+    def jsi_root_node
+      if jsi_ptr.root?
+        self
+      else
+        new_node(
+          jsi_ptr: Ptr[],
+          jsi_schema_base_uri: nil,
+        )
+      end
+    end
+
+    # parent MetaschemaNode
+    # @return [MetaschemaNode]
+    def jsi_parent_node
+      jsi_ptr.parent.evaluate(jsi_root_node)
+    end
+
+    # 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 = jsi_node_content_hash_pubsend(:key?, token)
+        value = jsi_node_content_hash_pubsend(:[], token)
+      elsif respond_to?(:to_ary)
+        token_in_range = jsi_node_content_ary_pubsend(:each_index).include?(token)
+        value = jsi_node_content_ary_pubsend(:[], token)
+      else
+        raise(NoMethodError, "cannot subscript (using token: #{token.inspect}) from content: #{jsi_node_content.pretty_inspect.chomp}")
+      end
+
+      begin
+        if token_in_range
+          value_node = jsi_subinstance_memos[token]
+
+          jsi_subinstance_as_jsi(value, value_node.jsi_schemas, as_jsi) do
+            value_node
+          end
+        else
+          # I think I will not support Hash#default/#default_proc in this case.
+          nil
+        end
+      end
+    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 jsi_modified_copy(&block)
+      MetaschemaNode.new(jsi_ptr.modified_document_copy(jsi_document, &block), **our_initialize_params)
+    end
+
+    # @private
+    # @return [Array<String>]
+    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,
+        *(jsi_node_content.respond_to?(:jsi_object_group_text) ? jsi_node_content.jsi_object_group_text : []),
+      ].compact
+    end
+
+    # an opaque fingerprint of this MetaschemaNode for FingerprintHash
+    def jsi_fingerprint
+      {class: self.class, jsi_document: jsi_document}.merge(our_initialize_params)
+    end
+
+    private
+
+    def our_initialize_params
+      {
+        jsi_ptr: jsi_ptr,
+        metaschema_instance_modules: metaschema_instance_modules,
+        metaschema_root_ptr: metaschema_root_ptr,
+        root_schema_ptr: root_schema_ptr,
+        jsi_schema_base_uri: jsi_schema_base_uri,
+      }
+    end
+
+    def new_node(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,
+        )
+      end
+    end
+  end
+end

data/lib/jsi/pathed_node.rb

@@ -1,26 +1,21 @@
+# frozen_string_literal: true
+
 module JSI
-  # including class MUST define
-  # - #node_document [Object] returning the document
-  # - #node_ptr [JSI::JSON::Pointer] returning a pointer for the node path in the document
-  # - #document_root_node [JSI::PathedNode] returning a PathedNode pointing at the document root
-  # - #parent_node [JSI::PathedNode] returning the parent node of this PathedNode
-  # - #deref [JSI::PathedNode] following a $ref
+  # this module represents a node in a document.
   #
-  # given these, this module represents the node in the document at the path.
+  # including class MUST define
   #
-  # the node content (#node_content) is the result of evaluating the node document at the path.
+  # - `#jsi_document` [Object] the document
+  # - `#jsi_ptr` [JSI::Ptr] a pointer to the node in the document
   module PathedNode
-    def node_content
-      content = node_ptr.evaluate(node_document)
+    # the content of this node
+    def jsi_node_content
+      content = jsi_ptr.evaluate(jsi_document)
       content
     end
-
-    def node_ptr_deref(&block)
-      node_ptr.deref(node_document, &block)
-    end
   end
 
-  # module extending a {JSI::PathedNode} object when its node_content is Hash-like (responds to #to_hash)
+  # module extending a {JSI::PathedNode} object when its jsi_node_content is Hash-like (responds to #to_hash)
   module PathedHashNode
     # yields each hash key and value of this node.
     #
@@ -29,41 +24,45 @@ module JSI
     #
     # returns an Enumerator if no block is given.
     #
+    # @param a arguments are passed to `#[]`
     # @yield [Object, Object] each key and value of this hash node
-    # @return [self, Enumerator]
-    def each(&block)
-      return to_enum(__method__) { node_content_hash_pubsend(:size) } unless block_given?
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(*a, &block)
+      return to_enum(__method__) { jsi_node_content_hash_pubsend(:size) } unless block
       if block.arity > 1
-        node_content_hash_pubsend(:each_key) { |k| yield k, self[k] }
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield k, self[k, *a] }
       else
-        node_content_hash_pubsend(:each_key) { |k| yield [k, self[k]] }
+        jsi_node_content_hash_pubsend(:each_key) { |k| yield [k, self[k, *a]] }
       end
       self
     end
 
-    # @return [Hash] a hash in which each key is a key of the node_content hash and
-    #   each value is the result of self[key] (see #[]).
-    def to_hash
-      {}.tap { |h| each_key { |k| h[k] = self[k] } }
+    # a hash in which each key is a key of the jsi_node_content hash and each value is the
+    # result of `self[key]`
+    # @param a arguments are passed to `#[]`
+    # @return [Hash]
+    def to_hash(*a)
+      {}.tap { |h| jsi_node_content_hash_pubsend(:each_key) { |k| h[k] = self[k, *a] } }
     end
 
     include Hashlike
 
+    # invokes the method with the given name on the jsi_node_content (if defined) or its #to_hash
     # @param method_name [String, Symbol]
-    # @param *a, &b are passed to the invocation of method_name
-    # @return [Object] the result of calling method method_name on the node_content or its #to_hash
-    def node_content_hash_pubsend(method_name, *a, &b)
-      if node_content.respond_to?(method_name)
-        node_content.public_send(method_name, *a, &b)
+    # @param a arguments and block are passed to the invocation of method_name
+    # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_hash
+    def jsi_node_content_hash_pubsend(method_name, *a, &b)
+      if jsi_node_content.respond_to?(method_name)
+        jsi_node_content.public_send(method_name, *a, &b)
       else
-        node_content.to_hash.public_send(method_name, *a, &b)
+        jsi_node_content.to_hash.public_send(method_name, *a, &b)
       end
     end
 
     # methods that don't look at the value; can skip the overhead of #[] (invoked by #to_hash)
     SAFE_KEY_ONLY_METHODS.each do |method_name|
       define_method(method_name) do |*a, &b|
-        node_content_hash_pubsend(method_name, *a, &b)
+        jsi_node_content_hash_pubsend(method_name, *a, &b)
       end
     end
   end
@@ -75,30 +74,34 @@ module JSI
     #
     # returns an Enumerator if no block is given.
     #
+    # @param a arguments are passed to `#[]`
     # @yield [Object] each element of this array node
-    # @return [self, Enumerator]
-    def each
-      return to_enum(__method__) { node_content_ary_pubsend(:size) } unless block_given?
-      node_content_ary_pubsend(:each_index) { |i| yield(self[i]) }
+    # @return [self, Enumerator] an Enumerator if invoked without a block; otherwise self
+    def each(*a, &block)
+      return to_enum(__method__) { jsi_node_content_ary_pubsend(:size) } unless block
+      jsi_node_content_ary_pubsend(:each_index) { |i| yield(self[i, *a]) }
       self
     end
 
-    # @return [Array] an array, the same size as the node_content, in which the
-    #   element at each index is the result of self[index] (see #[])
-    def to_ary
-      to_a
+    # an array, the same size as the jsi_node_content, in which the element at each index is the
+    # result of `self[index]`
+    # @param a arguments are passed to `#[]`
+    # @return [Array]
+    def to_ary(*a)
+      to_a(*a)
     end
 
     include Arraylike
 
+    # invokes the method with the given name on the jsi_node_content (if defined) or its #to_ary
     # @param method_name [String, Symbol]
-    # @param *a, &b are passed to the invocation of method_name
-    # @return [Object] the result of calling method method_name on the node_content or its #to_ary
-    def node_content_ary_pubsend(method_name, *a, &b)
-      if node_content.respond_to?(method_name)
-        node_content.public_send(method_name, *a, &b)
+    # @param a arguments and block are passed to the invocation of method_name
+    # @return [Object] the result of calling method method_name on the jsi_node_content or its #to_ary
+    def jsi_node_content_ary_pubsend(method_name, *a, &b)
+      if jsi_node_content.respond_to?(method_name)
+        jsi_node_content.public_send(method_name, *a, &b)
       else
-        node_content.to_ary.public_send(method_name, *a, &b)
+        jsi_node_content.to_ary.public_send(method_name, *a, &b)
       end
     end
 
@@ -106,7 +109,7 @@ module JSI
     # we override these methods from Arraylike
     SAFE_INDEX_ONLY_METHODS.each do |method_name|
       define_method(method_name) do |*a, &b|
-        node_content_ary_pubsend(method_name, *a, &b)
+        jsi_node_content_ary_pubsend(method_name, *a, &b)
       end
     end
   end