jsi-dev 0.0.8 → 0.0.9

data/lib/jsi/metaschema_node.rb

@@ -1,111 +1,195 @@
 # 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.
+  # A MetaSchemaNode is a JSI instance representing a node in a document that contains a meta-schema,
+  # or contains a schema describing a meta-schema (e.g. a meta-schema vocabulary schema).
   #
-  # 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.
+  # A meta-schema typically has the unique property that it is an instance of itself.
+  # It may also be an instance of a number of other schemas, each of which
+  # may be an instance of the meta-schema, itself, and/or other schemas.
   #
-  # 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.
+  # This is not a configuration of schemas/instances that normal JSI::Base instantiation can accommodate.
+  # MetaSchemaNode instead bootstraps each node on initialization, computing and instantiating
+  # the schemas that describe it (other MetaSchemaNode instances) and their schema modules.
+  # This results in a node that is a meta-schema being an instance of its own schema module
+  # (as well as JSI::Schema and JSI::Schema::MetaSchema), and a node that is a schema being an instance of
+  # the meta-schema's schema module (and thereby JSI::Schema).
   #
-  # 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
+  # The meta-schema may be anywhere in a document, though it is rare to put it anywhere but at the root.
+  # The root of the meta-schema is referenced by the {MetaSchemaNode::Conf configured}
+  # {MetaSchemaNode::Conf#metaschema_root_ref `metaschema_root_ref`}.
+  # The schema describing the root of the document is referenced by the configured
+  # {MetaSchemaNode::Conf#root_schema_ref `root_schema_ref`}.
+  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
+    # @private - experimental
+    # `self` is a MetaSchemaNode
+    # @param node [MetaSchemaNode, MetaSchemaNode::BootstrapSchema]
+    # @return [Boolean] is `node` a meta-schema?
+    DEFAULT_IS_METASCHEMA = proc do |node|
+      node.jsi_document.equal?(@bootstrap_metaschema.jsi_document) && node.jsi_ptr == @bootstrap_metaschema.jsi_ptr
+    end
+    private_constant(:DEFAULT_IS_METASCHEMA)
+
+    include(Base::Immutable)
+
+    conf_attrs = {
+      dialect:             {fingerprint: true },
+      metaschema_root_ref: {fingerprint: true },
+      root_schema_ref:     {fingerprint: true },
+      bootstrap_registry:  {fingerprint: true },
+      is_metaschema:       {fingerprint: true },
+    }.freeze
+    Conf = Base::Conf.subclass(*conf_attrs.keys)
+    Conf::ATTRS = Base::Conf::ATTRS.merge(conf_attrs)
+
+    # {Base::Conf} with additional configuration for MetaSchemaNode.
+    #
+    # @!attribute dialect
+    #   @return [Schema::Dialect]
+    # @!attribute metaschema_root_ref
+    #   URI reference to the root of the meta-schema.
+    #
+    #   Default: `"#"` resolves to the root of the `jsi_document`.
+    #   @return [Addressable::URI]
+    # @!attribute root_schema_ref
+    #   URI reference to the schema describing the root of the jsi_document.
+    #   When schemas of the meta-schema are in multiple documents, this describes the roots of all instantiated documents.
+    #
+    #   Default: `metaschema_root_ref` value, i.e. the document root is a schema.
+    #   @return [Addressable::URI]
+    # @!attribute bootstrap_registry
+    #   Default: nil
+    #   @return [Registry, nil]
+    class Conf < Base::Conf
+      def initialize(
+          dialect: ,
+          metaschema_root_ref: '#',
+          root_schema_ref: metaschema_root_ref,
+          registry: nil, # overrides Base::Conf default value JSI.registry
+          is_metaschema: DEFAULT_IS_METASCHEMA,
+          **kw
+      )
+        super(
+          dialect: dialect,
+          metaschema_root_ref: Util.uri(metaschema_root_ref, nnil: true),
+          root_schema_ref: Util.uri(root_schema_ref, nnil: true),
+          registry: registry,
+          is_metaschema: is_metaschema,
+          **kw,
+        )
+      end
+    end
+
+    # See {JSI.new_metaschema_node} to instantiate.
+    #
+    # Note: when instantiating MetaSchemaNode directly, the caller must invoke #jsi_initialize_finish.
+    # @api private
+    # @param jsi_ptr [JSI::Ptr] ptr to this MetaSchemaNode in 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_schema_registry: nil,
-        jsi_root_node: nil
+        jsi_root_node: nil,
+        **kw
     )
-      super(jsi_document,
+      super(
         jsi_ptr: jsi_ptr,
         jsi_indicated_schemas: SchemaSet[],
-        jsi_schema_base_uri: jsi_schema_base_uri,
-        jsi_schema_registry: jsi_schema_registry,
+        # MSN doesn't track schema_resource_ancestors through descendents, but the root is included when appropriate
+        jsi_schema_resource_ancestors: jsi_ptr.root? || !jsi_root_node.is_a?(Schema) ? Util::EMPTY_ARY : [jsi_root_node].freeze,
         jsi_root_node: jsi_root_node,
+        **kw,
       )
 
-      @schema_implementation_modules = Util.ensure_module_set(schema_implementation_modules)
-      @metaschema_root_ptr = metaschema_root_ptr
-      @root_schema_ptr = root_schema_ptr
+      @initialize_finish_started = false
+      @initialize_finished = false
+      @to_initialize_finish = []
 
-      if jsi_ptr.root? && jsi_schema_base_uri
-        raise(NotImplementedError, "unsupported jsi_schema_base_uri on metaschema document root")
+      if jsi_ptr.root? && jsi_base_uri
+        raise(NotImplementedError, "unsupported jsi_base_uri on meta-schema document root")
       end
 
-      jsi_node_content = self.jsi_node_content
+      #chkbug fail(Bug, 'MetaSchemaNode instance must be frozen') unless jsi_node_content.frozen?
+
+      bootstrap_schema_from_ref = proc do |ref_uri|
+        ref_uri_nofrag = ref_uri.merge(fragment: nil)
+
+        if ref_uri_nofrag.empty?
+          ptr = Ptr.from_fragment(ref_uri.fragment).resolve_against(jsi_document) # anchor not supported
+          if jsi_conf.root_schema_ref == jsi_conf.metaschema_root_ref
+            # root is a schema
+            jsi_conf.dialect.bootstrap_schema(
+              jsi_document: jsi_document,
+              jsi_base_uri: nil, # not supported
+              jsi_registry: jsi_conf.bootstrap_registry,
+            ).resource_root_subschema(ptr)
+          else
+            jsi_conf.dialect.bootstrap_schema(
+              jsi_document: jsi_document,
+              jsi_ptr: ptr,
+              jsi_base_uri: nil, # not supported
+              jsi_registry: jsi_conf.bootstrap_registry,
+            )
+          end
+        else
+          # if not fragment-only, ref must be registered in the bootstrap_registry
+          ref = Schema::Ref.new(ref_uri, registry: jsi_conf.bootstrap_registry)
+          ref.resolve
+        end
+      end
 
-      extends = Set[]
+      @bootstrap_metaschema = bootstrap_schema_from_ref[jsi_conf.metaschema_root_ref]
 
       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
-      )
+      root_bootstrap_schema = bootstrap_schema_from_ref[jsi_conf.root_schema_ref]
       our_bootstrap_indicated_schemas = jsi_ptr.tokens.inject(SchemaSet[root_bootstrap_schema]) do |bootstrap_indicated_schemas, tok|
-        bootstrap_schemas = bootstrap_indicated_schemas.inplace_applicator_schemas(instance_for_schemas)
-        child_indicated_schemas = bootstrap_schemas.child_applicator_schemas(tok, instance_for_schemas)
+        child_indicated_schemas = bootstrap_indicated_schemas.each_yield_set do |is, y|
+          is.each_inplace_child_applicator_schema(tok, instance_for_schemas,
+            collect_evaluated_validate: jsi_conf.application_collect_evaluated_validate,
+            &y
+          )
+        end
         instance_for_schemas = instance_for_schemas[tok]
         child_indicated_schemas
       end
-      @indicated_schemas_map = jsi_memomap { bootstrap_schemas_to_msn(our_bootstrap_indicated_schemas) }
-
-      our_bootstrap_schemas = our_bootstrap_indicated_schemas.inplace_applicator_schemas(instance_for_schemas)
-      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
-          extend Schema
-          schema_implementation_modules.each do |schema_implementation_module|
-            extend schema_implementation_module
+      @indicated_schemas_map = jsi_memomap do
+        SchemaSet.new(our_bootstrap_indicated_schemas) { |s| bootstrap_schema_to_msn(s) }
+      end
+
+      @bootstrap_schemas = our_bootstrap_indicated_schemas.each_yield_set do |is, y|
+        is.each_inplace_applicator_schema(instance_for_schemas, &y) # note: instance_for_schemas == jsi_node_content now
+      end
+
+      @jsi_schemas = @bootstrap_schemas
+
+      @bootstrap_schemas.each do |bootstrap_schema|
+        if instance_exec(bootstrap_schema, &jsi_conf.is_metaschema)
+          # this is described by the meta-schema, i.e. this is a schema
+          define_singleton_method(:dialect) { jsi_conf.dialect }
+          extend(Schema)
+
+          if jsi_registry && jsi_resource_uris.any? { |uri| !jsi_registry.registered?(uri) }
+            jsi_registry.register_immediate(self)
           end
-          extends += schema_implementation_modules
-        end
-        if bootstrap_schema.jsi_ptr == jsi_ptr
-          # this is the metaschema (it is described by itself)
-          extend Metaschema
-          extends << Metaschema
         end
       end
+    end
+
+    # @api private
+    def jsi_initialize_finish
+      return self if @initialize_finish_started
+      @initialize_finish_started = true
 
-      @jsi_schemas = bootstrap_schemas_to_msn(our_bootstrap_schemas)
+      @jsi_schemas = SchemaSet.new(@bootstrap_schemas) { |s| bootstrap_schema_to_msn(s) }
 
       # note: jsi_schemas must already be set for jsi_schema_module to be used/extended
-      if is_a?(Metaschema)
-        describes_schema!(schema_implementation_modules)
+      if instance_exec(self, &jsi_conf.is_metaschema)
+        describes_schema!(jsi_conf.dialect)
       end
 
       extends_for_instance = JSI::SchemaClasses.includes_for(jsi_node_content)
-      extends.merge(extends_for_instance)
-      extends.freeze
 
-      conflicting_modules = Set[self.class] + extends + @jsi_schemas.map(&:jsi_schema_module)
+      conflicting_modules = Set[self.class] + extends_for_instance + @jsi_schemas.map(&:jsi_schema_module)
       reader_modules = @jsi_schemas.map do |schema|
         JSI::SchemaClasses.schema_property_reader_module(schema, conflicting_modules: conflicting_modules)
       end
@@ -122,21 +206,17 @@ module JSI
       @jsi_schemas.each do |schema|
         extend schema.jsi_schema_module
       end
-    end
-
-    # 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
+      @initialize_finished = true
+      while !@to_initialize_finish.empty?
+        node = @to_initialize_finish.shift
+        node.jsi_initialize_finish
+      end
 
-    # ptr to the schema of the root of the jsi_document
-    # @return [JSI::Ptr]
-    attr_reader :root_schema_ptr
+      jsi_initialized
+    end
 
-    # JSI Schemas describing this MetaschemaNode
+    # JSI Schemas describing this MetaSchemaNode
     # @return [JSI::SchemaSet]
     attr_reader :jsi_schemas
 
@@ -146,15 +226,10 @@ module JSI
       @indicated_schemas_map[]
     end
 
-    # see {Base#jsi_child}
-    def jsi_child(token, as_jsi: )
-      child_node = @root_descendent_node_map[ptr: jsi_ptr[token]]
-
-      jsi_child_as_jsi(jsi_node_content_child(token), child_node.jsi_schemas, as_jsi) do
-        child_node
-      end
+    # see {Base#jsi_child_node}
+    def jsi_child_node(token)
+      root_descendent_node(jsi_ptr[token])
     end
-    private :jsi_child
 
     # See {Base#jsi_default_child}
     def jsi_default_child(token, as_jsi: )
@@ -162,41 +237,31 @@ module JSI
     end
     private :jsi_default_child # internals for #[] but idk, could be public
 
-    # 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)
-      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
+    # @raise [NotImplementedError] not implemented for MetaSchemaNode
+    def jsi_modified_copy(**)
+      # this had an implementation previously (see git history). but for 2020-12, support for multiple
+      # mutually-descriptive schemas as well as dynamic scope makes instantiating a modified copy that
+      # preserves self-descriptive/mutually-descriptive relationships generally infeasible.
+      raise(NotImplementedError)
     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_schema_module.name_from_ancestor || 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 : nil),
-      ].compact
+    protected def jsi_dynamic_root_instantiate(**kw)
+      # self is a resource root being instantiated with overridden dynamic scope
+      #chkbug fail unless jsi_ptr.root? # jsi_schema_resource_ancestors not tracked
+      to_initialize_finish(MetaSchemaNode.new(**kw))
     end
 
     # see {Util::Private::FingerprintHash}
     # @api private
     def jsi_fingerprint
-      {class: self.class, jsi_document: jsi_document}.merge(our_initialize_params)
+      {
+        class: self.class,
+        jsi_document: jsi_document,
+        jsi_ptr: jsi_ptr,
+        jsi_base_uri: jsi_base_uri,
+        jsi_schema_dynamic_anchor_map: jsi_schema_dynamic_anchor_map,
+        **jsi_conf.for_fingerprint,
+      }.freeze
     end
 
     protected
@@ -206,55 +271,80 @@ module JSI
     private
 
     def jsi_memomaps_initialize
-      if jsi_ptr.root?
-        @root_descendent_node_map = jsi_memomap(key_by: proc { |i| i[:ptr] }, &method(:jsi_root_descendent_node_compute))
+      if equal?(@jsi_root_node)
+        @root_descendent_node_map = jsi_memomap(&method(:jsi_root_descendent_node_compute))
       else
         @root_descendent_node_map = @jsi_root_node.root_descendent_node_map
       end
     end
 
-    # note: does not include jsi_root_node
-    def our_initialize_params
-      {
-        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,
-        jsi_schema_registry: jsi_schema_registry,
-      }
-    end
-
-    # note: not for root node
-    def new_node(**params)
-      MetaschemaNode.new(jsi_document, jsi_root_node: jsi_root_node, **our_initialize_params, **params)
-    end
-
     def jsi_root_descendent_node_compute(ptr: )
-      #chkbug raise(Bug) unless jsi_ptr.root?
+      # note: self is jsi_root_node
+      #chkbug fail(Bug) unless equal?(jsi_root_node)
       if ptr.root?
         self
       else
-        new_node(
+        MetaSchemaNode.new(
+          jsi_document: jsi_document,
           jsi_ptr: ptr,
-          jsi_schema_base_uri: jsi_resource_ancestor_uri,
+          jsi_base_uri: jsi_next_base_uri,
+          # since MSN only supports document root as jsi_resource_root, and jsi_next_schema_dynamic_anchor_map
+          # is only passed to descendents that are resource roots, that is not used here.
+          jsi_schema_dynamic_anchor_map: jsi_schema_dynamic_anchor_map,
+          jsi_root_node: jsi_root_node,
         )
       end
     end
 
-    # @param bootstrap_schemas [Enumerable<BootstrapSchema>]
-    # @return [SchemaSet<MetaschemaNode>]
-    def bootstrap_schemas_to_msn(bootstrap_schemas)
-      SchemaSet.new(bootstrap_schemas) do |bootstrap_schema|
-        if bootstrap_schema.jsi_ptr == jsi_ptr
-          self
-        elsif bootstrap_schema.jsi_ptr.root?
-          @jsi_root_node
+    # @param ptr [Ptr]
+    # @return [MetaSchemaNode]
+    protected def root_descendent_node(ptr)
+      to_initialize_finish(@root_descendent_node_map[
+        ptr: ptr.resolve_against(jsi_document),
+      ])
+    end
+
+    def to_initialize_finish(node)
+      if @initialize_finished
+        node.jsi_initialize_finish
+      else
+        @to_initialize_finish.push(node)
+      end
+
+      node
+    end
+
+    # @param bootstrap_schema [MetaSchemaNode::BootstrapSchema]
+    # @return [MetaSchemaNode]
+    def bootstrap_schema_to_msn(bootstrap_schema)
+      dynamic_anchor_map = Schema::DynamicAnchorMap::EMPTY
+      bootstrap_schema.jsi_schema_dynamic_anchor_map.each do |anchor, (bootstrap_anchor_root, anchor_ptrs)|
+        msn_anchor_root = bootstrap_schema_to_msn(bootstrap_anchor_root)
+        dynamic_anchor_map = dynamic_anchor_map.merge({
+          anchor => [msn_anchor_root, anchor_ptrs].freeze,
+        }).freeze
+      end
+
+      if bootstrap_schema.jsi_document.equal?(jsi_document)
+        root_descendent_node(bootstrap_schema.jsi_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
+      else
+        jsi_registry || raise(ResolutionError, "no jsi_registry")
+        bootstrap_resource = bootstrap_schema.jsi_resource_root
+        resource_uri = bootstrap_resource.jsi_resource_uri || raise(ResolutionError, "no URI: #{bootstrap_resource}")
+        if jsi_registry.registered?(resource_uri)
+          resource = jsi_registry.find(resource_uri)
+          relative_ptr = bootstrap_schema.jsi_ptr.relative_to(bootstrap_resource.jsi_ptr)
+          resource.jsi_descendent_node(relative_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
         else
-          new_node(
-            jsi_ptr: bootstrap_schema.jsi_ptr,
-            jsi_schema_base_uri: bootstrap_schema.jsi_schema_base_uri,
-          )
+          root = to_initialize_finish(MetaSchemaNode.new(
+            jsi_document: bootstrap_schema.jsi_document,
+            jsi_ptr: Ptr[],
+            jsi_base_uri: nil,
+            # this seems like the best dynamic_anchor_map to pass
+            jsi_schema_dynamic_anchor_map: dynamic_anchor_map.without_node(nil, document: bootstrap_schema.jsi_document, ptr: Ptr[], registry: jsi_registry),
+            jsi_conf: jsi_conf,
+          ))
+          root.jsi_descendent_node(bootstrap_schema.jsi_ptr).jsi_with_schema_dynamic_anchor_map(dynamic_anchor_map)
         end
       end
     end

data/lib/jsi/ptr.rb

@@ -13,7 +13,7 @@ module JSI
       end
 
       # raised when a pointer refers to a path in a document that could not be resolved
-      class ResolutionError < Error
+      class ResolutionError < JSI::ResolutionError
       end
 
       POS_INT_RE = /\A[1-9]\d*\z/
@@ -25,6 +25,8 @@ module JSI
       def self.ary_ptr(ary_ptr)
         if ary_ptr.is_a?(Ptr)
           ary_ptr
+        elsif ary_ptr == Util::EMPTY_ARY
+          EMPTY
         else
           new(ary_ptr)
         end
@@ -59,9 +61,9 @@ module JSI
       #     => JSI::Ptr["foo bar"]
       #
       # Note: A fragment does not include a leading '#'. The string "#/foo" is a URI containing the
-      # fragment "/foo", which should be parsed by `Addressable::URI` before passing to this method, e.g.:
+      # fragment "/foo", which should be parsed by `JSI::URI` before passing to this method, e.g.:
       #
-      #     JSI::Ptr.from_fragment(Addressable::URI.parse("#/foo").fragment)
+      #     JSI::Ptr.from_fragment(JSI::URI["#/foo"].fragment)
       #     => JSI::Ptr["foo"]
       #
       # @param fragment [String] a fragment containing a pointer
@@ -69,7 +71,7 @@ module JSI
       # @raise [JSI::Ptr::PointerSyntaxError] when the fragment does not contain a pointer with
       #   valid pointer syntax
       def self.from_fragment(fragment)
-        from_pointer(Addressable::URI.unescape(fragment))
+        from_pointer(URI.unescape(fragment))
       end
 
       # parse a pointer string and instantiate as a JSI::Ptr
@@ -127,6 +129,24 @@ module JSI
         res
       end
 
+      # Resolves each token of this pointer in `document`, in particular resolving strings indicating
+      # array indices to integers.
+      # @param document [Object]
+      # @return [Ptr]
+      def resolve_against(document)
+        return(self) if tokens.empty?
+        node = document
+        resolved_tokens = nil
+        tokens.each_with_index do |token, i|
+          resolved_token, node = node_subscript_token_child(node, token)
+          next if resolved_token.equal?(token)
+          resolved_tokens ||= tokens.dup
+          resolved_tokens[i] = resolved_token
+        end
+        return(self) if !resolved_tokens
+        Ptr.new(resolved_tokens.freeze)
+      end
+
       # the pointer string representation of this pointer
       # @return [String]
       def pointer
@@ -136,13 +156,13 @@ module JSI
       # the fragment string representation of this pointer
       # @return [String]
       def fragment
-        Addressable::URI.escape(pointer).freeze
+        URI.escape(pointer).freeze
       end
 
       # a URI consisting of a fragment containing this pointer's fragment string representation
-      # @return [Addressable::URI]
+      # @return [URI]
       def uri
-        Addressable::URI.new(fragment: fragment).freeze
+        URI.new(fragment: fragment).freeze
       end
 
       # whether this pointer is empty, i.e. it has no tokens
@@ -165,10 +185,11 @@ module JSI
         tokens.size == 1 ? EMPTY : Ptr.new(tokens[0...-1].freeze)
       end
 
-      # whether this pointer contains the other_ptr - that is, whether this pointer is an ancestor
-      # of `other_ptr`, a descendent pointer. `contains?` is inclusive; a pointer does contain itself.
+      # whether this pointer is an ancestor of `other_ptr`, a descendent pointer.
+      # `ancestor_of?` is inclusive; a pointer is an ancestor of itself.
+      #
       # @return [Boolean]
-      def contains?(other_ptr)
+      def ancestor_of?(other_ptr)
         tokens == other_ptr.tokens[0...tokens.size]
       end
 
@@ -176,7 +197,8 @@ module JSI
       # @return [JSI::Ptr]
       # @raise [JSI::Ptr::Error] if the given ancestor_ptr is not an ancestor of this pointer
       def relative_to(ancestor_ptr)
-        unless ancestor_ptr.contains?(self)
+        return self if ancestor_ptr.empty?
+        unless ancestor_ptr.ancestor_of?(self)
           raise(Error, "ancestor_ptr #{ancestor_ptr.inspect} is not ancestor of #{inspect}")
         end
         ancestor_ptr.tokens.size == tokens.size ? EMPTY : Ptr.new(tokens[ancestor_ptr.tokens.size..-1].freeze)
@@ -187,6 +209,7 @@ module JSI
       # @return [JSI::Ptr]
       def +(ptr)
         if ptr.is_a?(Ptr)
+          return(ptr) if tokens.empty?
           ptr_tokens = ptr.tokens
         elsif ptr.respond_to?(:to_ary)
           ptr_tokens = ptr
@@ -201,10 +224,12 @@ module JSI
       # @return [JSI::Ptr]
       # @raise [ArgumentError] if n is not between 0 and the size of our tokens
       def take(n)
+        return(EMPTY) if n == 0
+        return(self) if n == tokens.size
         unless n.is_a?(Integer) && n >= 0 && n <= tokens.size
           raise(ArgumentError, "n not in range (0..#{tokens.size}): #{n.inspect}")
         end
-        n == tokens.size ? self : Ptr.new(tokens.take(n).freeze)
+        Ptr.new(tokens.take(n).freeze)
       end
 
       # appends the given token to this pointer's tokens and returns the result
@@ -237,16 +262,16 @@ module JSI
           Util.modified_copy(document, &block)
         else
           car = tokens[0]
-          cdr = Ptr.new(tokens[1..-1].freeze)
+          cdr = tokens.size == 1 ? EMPTY : Ptr.new(tokens[1..-1].freeze)
           token, document_child = node_subscript_token_child(document, car)
           modified_document_child = cdr.modified_document_copy(document_child, &block)
-          if modified_document_child.object_id == document_child.object_id
+          if modified_document_child.equal?(document_child)
             document
           else
             modified_document = document.respond_to?(:[]=) ? document.dup :
               document.respond_to?(:to_hash) ? document.to_hash.dup :
               document.respond_to?(:to_ary) ? document.to_ary.dup :
-              raise(Bug) # not possible; node_subscript_token_child would have raised
+              fail(Bug) # not possible; node_subscript_token_child would have raised
             modified_document[token] = modified_document_child
             modified_document
           end
@@ -259,12 +284,14 @@ module JSI
         -"#{self.class.name}[#{tokens.map(&:inspect).join(", ")}]"
       end
 
-      alias_method :to_s, :inspect
+      def to_s
+        inspect
+      end
 
       # see {Util::Private::FingerprintHash}
       # @api private
       def jsi_fingerprint
-        {class: Ptr, tokens: tokens}
+        {class: Ptr, tokens: tokens}.freeze
       end
       include Util::FingerprintHash::Immutable
 
@@ -273,6 +300,7 @@ module JSI
       private
 
       def node_subscript_token_child(value, token, *a, **kw)
+        token = token.jsi_node_content if token.is_a?(Schema::SchemaAncestorNode)
         if value.respond_to?(:to_ary)
           if token.is_a?(String) && (token == '0' || token =~ POS_INT_RE)
             token = token.to_i