jsi 0.4.0 → 0.6.0

data/lib/jsi/typelike_modules.rb

@@ -3,10 +3,9 @@
 module JSI
   # a module relating to objects that act like Hash or Array instances
   module Typelike
-    # yields the content of the given param `object`. for objects which have a
-    # #modified_copy method of their own (JSI::Base, JSI::JSON::Node) that
-    # method is invoked with the given block. otherwise the given object itself
-    # is yielded.
+    # yields the content of the given param `object`. for objects which have a #jsi_modified_copy
+    # method of their own (JSI::Base, JSI::MetaschemaNode) that method is invoked with the given
+    # block. otherwise the given object itself is yielded.
     #
     # the given block must result in a modified copy of its block parameter
     # (not destructively modifying the yielded content).
@@ -15,8 +14,8 @@ module JSI
     #   in a (nondestructively) modified copy of this.
     # @return [object.class] modified copy of the given object
     def self.modified_copy(object, &block)
-      if object.respond_to?(:modified_copy)
-        object.modified_copy(&block)
+      if object.respond_to?(:jsi_modified_copy)
+        object.jsi_modified_copy(&block)
       else
         return yield(object)
       end
@@ -27,8 +26,8 @@ module JSI
     # will raise TypeError if an object is given that is not a type that seems
     # to be expressable as json.
     #
-    # similar effect could be achieved by requiring 'json/add/core' and using
-    # #as_json, but I don't much care for how it represents classes that are
+    # similar effect could be achieved by requiring 'json/add/core' and using #as_json,
+    # but I don't much care for how it represents classes that are
     # not naturally expressable in JSON, and prefer not to load its
     # monkey-patching.
     #
@@ -39,7 +38,7 @@ module JSI
     #   array of object) cannot be expressed as json
     def self.as_json(object, *opt)
       if object.is_a?(JSI::PathedNode)
-        as_json(object.node_content, *opt)
+        as_json(object.jsi_node_content, *opt)
       elsif object.respond_to?(:to_hash)
         (object.respond_to?(:map) ? object : object.to_hash).map do |k, v|
           unless k.is_a?(Symbol) || k.respond_to?(:to_str)
@@ -86,7 +85,7 @@ module JSI
     end
     safe_modified_copy_methods.each do |method_name|
       define_method(method_name) do |*a, &b|
-        modified_copy do |object_to_modify|
+        jsi_modified_copy do |object_to_modify|
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
           responsive_object.public_send(method_name, *a, &b)
         end
@@ -94,19 +93,19 @@ module JSI
     end
     safe_kv_block_modified_copy_methods.each do |method_name|
       define_method(method_name) do |*a, &b|
-        modified_copy do |object_to_modify|
+        jsi_modified_copy do |object_to_modify|
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_hash
-          responsive_object.public_send(method_name, *a) do |k, _v|
-            b.call(k, self[k])
+          responsive_object.public_send(method_name) do |k, _v|
+            b.call(k, self[k, *a])
           end
         end
       end
     end
 
-    # the same as Hash#update
+    # like [Hash#update](https://ruby-doc.org/core/Hash.html#method-i-update)
     # @param other [#to_hash] the other hash to update this hash from
     # @yield [key, oldval, newval] for entries with duplicate keys, the value of each duplicate key
-    #   is determined by calling the block with the key, its value in hsh and its value in other_hash.
+    #   is determined by calling the block with the key, its value in self and its value in other.
     # @return self, updated with other
     # @raise [TypeError] when `other` does not respond to #to_hash
     def update(other, &block)
@@ -115,7 +114,7 @@ module JSI
       end
       self_respondingto_key = self.respond_to?(:key?) ? self : to_hash
       other.to_hash.each_pair do |key, value|
-        if block_given? && self_respondingto_key.key?(key)
+        if block && self_respondingto_key.key?(key)
           value = yield(key, self[key], value)
         end
         self[key] = value
@@ -125,33 +124,34 @@ module JSI
 
     alias_method :merge!, :update
 
-    # the same as Hash#merge
+    # like [Hash#merge](https://ruby-doc.org/core/Hash.html#method-i-merge)
     # @param other [#to_hash] the other hash to merge into this
     # @yield [key, oldval, newval] for entries with duplicate keys, the value of each duplicate key
-    #   is determined by calling the block with the key, its value in hsh and its value in other_hash.
+    #   is determined by calling the block with the key, its value in self and its value in other.
     # @return duplicate of this hash with the other hash merged in
     # @raise [TypeError] when `other` does not respond to #to_hash
     def merge(other, &block)
       dup.update(other, &block)
     end
 
-    # @return [String] basically the same #inspect as Hash, but has the
-    #   class name and, if responsive, self's #object_group_text
+    # basically the same #inspect as Hash, but has the class name and, if responsive,
+    # self's #jsi_object_group_text
+    # @return [String]
     def inspect
-      object_group_str = (respond_to?(:object_group_text) ? self.object_group_text : [self.class]).join(' ')
-      "\#{<#{object_group_str}>#{empty? ? '' : ' '}#{self.map { |k, v| "#{k.inspect} => #{v.inspect}" }.join(', ')}}"
+      object_group_str = (respond_to?(:jsi_object_group_text) ? self.jsi_object_group_text : [self.class]).join(' ')
+      "\#{<#{object_group_str}>#{self.map { |k, v| " #{k.inspect} => #{v.inspect}" }.join(',')}}"
     end
 
     alias_method :to_s, :inspect
 
-    # pretty-prints a representation this node to the given printer
+    # pretty-prints a representation of this hashlike to the given printer
     # @return [void]
     def pretty_print(q)
-      object_group_str = (respond_to?(:object_group_text) ? object_group_text : [self.class]).join(' ')
+      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#{<#{object_group_str}>"
       q.group_sub {
         q.nest(2) {
-          q.breakable(any? { true } ? ' ' : '')
+          q.breakable(empty? ? '' : ' ')
           q.seplist(self, nil, :each_pair) { |k, v|
             q.group {
               q.pp k
@@ -177,7 +177,7 @@ module JSI
     # methods which do not need to access the element.
     SAFE_INDEX_ONLY_METHODS = %w(each_index empty? length size)
     # there are some ambiguous ones that are omitted, like #sort, #map / #collect.
-    SAFE_INDEX_ELEMENT_METHODS = %w(| & * + - <=> abbrev assoc at bsearch bsearch_index combination compact count cycle dig drop drop_while fetch find_index first include? index join last pack permutation product reject repeated_combination repeated_permutation reverse reverse_each rindex rotate sample select shelljoin shuffle slice sort take take_while transpose uniq values_at zip)
+    SAFE_INDEX_ELEMENT_METHODS = %w(| & * + - <=> abbrev at bsearch bsearch_index combination compact count cycle dig drop drop_while fetch find_index first include? index join last pack permutation product reject repeated_combination repeated_permutation reverse reverse_each rindex rotate sample select shelljoin shuffle slice sort take take_while transpose uniq values_at zip)
     DESTRUCTIVE_METHODS = %w(<< clear collect! compact! concat delete delete_at delete_if fill flatten! insert keep_if map! pop push reject! replace reverse! rotate! select! shift shuffle! slice! sort! sort_by! uniq! unshift)
 
     # methods (well, method) that returns a modified copy and doesn't need any handling of block variable(s)
@@ -193,7 +193,7 @@ module JSI
     end
     safe_modified_copy_methods.each do |method_name|
       define_method(method_name) do |*a, &b|
-        modified_copy do |object_to_modify|
+        jsi_modified_copy do |object_to_modify|
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
           responsive_object.public_send(method_name, *a, &b)
         end
@@ -201,33 +201,48 @@ module JSI
     end
     safe_el_block_methods.each do |method_name|
       define_method(method_name) do |*a, &b|
-        modified_copy do |object_to_modify|
+        jsi_modified_copy do |object_to_modify|
           i = 0
           responsive_object = object_to_modify.respond_to?(method_name) ? object_to_modify : object_to_modify.to_ary
-          responsive_object.public_send(method_name, *a) do |_e|
-            b.call(self[i]).tap { i += 1 }
+          responsive_object.public_send(method_name) do |_e|
+            b.call(self[i, *a]).tap { i += 1 }
           end
         end
       end
     end
 
-    # @return [String] basically the same #inspect as Array, but has the
-    #   class name and, if responsive, self's #object_group_text
+    # see [Array#assoc](https://ruby-doc.org/core/Array.html#method-i-assoc)
+    def assoc(obj)
+      # note: assoc implemented here (instead of delegated) due to inconsistencies in whether
+      # other implementations expect each element to be an Array or to respond to #to_ary
+      detect { |e| e.respond_to?(:to_ary) and e[0] == obj }
+    end
+
+    # see [Array#rassoc](https://ruby-doc.org/core/Array.html#method-i-rassoc)
+    def rassoc(obj)
+      # note: rassoc implemented here (instead of delegated) due to inconsistencies in whether
+      # other implementations expect each element to be an Array or to respond to #to_ary
+      detect { |e| e.respond_to?(:to_ary) and e[1] == obj }
+    end
+
+    # basically the same #inspect as Array, but has the class name and, if responsive,
+    # self's #jsi_object_group_text
+    # @return [String]
     def inspect
-      object_group_str = (respond_to?(:object_group_text) ? object_group_text : [self.class]).join(' ')
-      "\#[<#{object_group_str}>#{empty? ? '' : ' '}#{self.map { |e| e.inspect }.join(', ')}]"
+      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
+      "\#[<#{object_group_str}>#{self.map { |e| ' ' + e.inspect }.join(',')}]"
     end
 
     alias_method :to_s, :inspect
 
-    # pretty-prints a representation this node to the given printer
+    # pretty-prints a representation of this arraylike to the given printer
     # @return [void]
     def pretty_print(q)
-      object_group_str = (respond_to?(:object_group_text) ? object_group_text : [self.class]).join(' ')
+      object_group_str = (respond_to?(:jsi_object_group_text) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#[<#{object_group_str}>"
       q.group_sub {
         q.nest(2) {
-          q.breakable(any? { true } ? ' ' : '')
+          q.breakable(empty? ? '' : ' ')
           q.seplist(self, nil, :each) { |e|
             q.pp e
           }

data/lib/jsi/util/attr_struct.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module JSI
+  module Util
+    # like a Struct, but stores all the attributes in one @attributes Hash, instead of individual instance
+    # variables for each attribute.
+    # this tends to be easier to work with and more flexible. keys which are symbols are converted to strings.
+    class AttrStruct
+      class AttrStructError < StandardError
+      end
+
+      class UndefinedAttributeKey < AttrStructError
+      end
+
+      class << self
+        # creates a AttrStruct subclass with the given attribute keys.
+        # @param attribute_keys [Enumerable<String, Symbol>]
+        def [](*attribute_keys)
+          unless self == AttrStruct
+            # :nocov:
+            raise(NotImplementedError, "AttrStruct multiple inheritance not supported")
+            # :nocov:
+          end
+
+          bad = attribute_keys.reject { |key| key.respond_to?(:to_str) || key.is_a?(Symbol) }
+          unless bad.empty?
+            raise ArgumentError, "attribute keys must be String or Symbol; got keys: #{bad.map(&:inspect).join(', ')}"
+          end
+          attribute_keys = attribute_keys.map { |key| key.is_a?(Symbol) ? key.to_s : key }
+
+          Class.new(AttrStruct).tap do |klass|
+            klass.define_singleton_method(:attribute_keys) { attribute_keys }
+            klass.send(:define_method, :attribute_keys) { attribute_keys }
+            attribute_keys.each do |attribute_key|
+              # reader
+              klass.send(:define_method, attribute_key) do
+                @attributes[attribute_key]
+              end
+
+              # writer
+              klass.send(:define_method, "#{attribute_key}=") do |value|
+                @attributes[attribute_key] = value
+              end
+            end
+          end
+        end
+      end
+
+      def initialize(attributes = {})
+        unless attributes.respond_to?(:to_hash)
+          raise(TypeError, "expected attributes to be a Hash; got: #{attributes.inspect}")
+        end
+        attributes = attributes.map { |k, v| {k.is_a?(Symbol) ? k.to_s : k => v} }.inject({}, &:update)
+        bad = attributes.keys.reject { |k| self.attribute_keys.include?(k) }
+        unless bad.empty?
+          raise UndefinedAttributeKey, "undefined attribute keys: #{bad.map(&:inspect).join(', ')}"
+        end
+        @attributes = attributes
+      end
+
+      def [](key)
+        key = key.to_s if key.is_a?(Symbol)
+        @attributes[key]
+      end
+
+      def []=(key, value)
+        key = key.to_s if key.is_a?(Symbol)
+        unless self.attribute_keys.include?(key)
+          raise UndefinedAttributeKey, "undefined attribute key: #{key.inspect}"
+        end
+        @attributes[key] = value
+      end
+
+      # @return [String]
+      def inspect
+        "\#<#{self.class.name}#{@attributes.empty? ? '' : ' '}#{@attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')}>"
+      end
+
+      # pretty-prints a representation of self to the given printer
+      # @return [void]
+      def pretty_print(q)
+        q.text '#<'
+        q.text self.class.name
+        q.group_sub {
+          q.nest(2) {
+            q.breakable(@attributes.empty? ? '' : ' ')
+            q.seplist(@attributes, nil, :each_pair) { |k, v|
+              q.group {
+                q.text k
+                q.text ': '
+                q.pp v
+              }
+            }
+          }
+        }
+        q.breakable ''
+        q.text '>'
+      end
+
+      include FingerprintHash
+      def jsi_fingerprint
+        {class: self.class, attributes: @attributes}
+      end
+    end
+  end
+end

data/lib/jsi/util.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 module JSI
-  # JSI::Util classes, modules, constants, and methods are INTERNAL and will be added and removed without warning.
-  # do not rely on them.
+  # JSI::Util classes, modules, constants, and methods are internal, and will be added and removed without warning.
+  #
+  # @api private
   module Util
-    # a proc which does nothing
-    NOOP = -> (*_) { }
+    autoload :AttrStruct, 'jsi/util/attr_struct'
 
-    # returns a version of the given hash, in which any symbol keys are
+    # a hash copied from the given hashlike, in which any symbol keys are
     # converted to strings. behavior on collisions is undefined (but in the
     # future could take a block like
     # ActiveSupport::HashWithIndifferentAccess#update)
@@ -54,24 +54,63 @@ module JSI
       end
     end
 
+    # ensures the given param becomes a frozen Set of Modules.
+    # returns the param if it is already that, otherwise initializes and freezes such a Set.
+    #
+    # @param modules [Set, Enumerable] the object to ensure becomes a frozen Set of Modules
+    # @return [Set] frozen Set containing the given modules
+    # @raise [ArgumentError] when the modules param is not an Enumerable
+    # @raise [Schema::NotASchemaError] when the modules param contains objects which are not Schemas
+    def ensure_module_set(modules)
+      if modules.is_a?(Set) && modules.frozen?
+        set = modules
+      else
+        set = Set.new(modules).freeze
+      end
+      not_modules = set.reject { |s| s.is_a?(Module) }
+      if !not_modules.empty?
+        raise(TypeError, [
+          "ensure_module_set given non-Module objects:",
+          *not_modules.map { |ns| ns.pretty_inspect.chomp },
+        ].join("\n"))
+      end
+
+      set
+    end
+
+    # is the given name ok to use as a ruby method name?
+    def ok_ruby_method_name?(name)
+      # must be a string
+      return false unless name.respond_to?(:to_str)
+      # must not begin with a digit
+      return false if name =~ /\A[0-9]/
+      # must not contain characters special to ruby syntax
+      return false if name =~ /[\\\s\#;\.,\(\)\[\]\{\}'"`%\+\-\/\*\^\|&=<>\?:!@\$~]/
+
+      return true
+    end
+
     # this is the Y-combinator, which allows anonymous recursive functions. for a simple example,
     # to define a recursive function to return the length of an array:
     #
-    #    length = ycomb do |len|
-    #      proc { |list| list == [] ? 0 : 1 + len.call(list[1..-1]) }
-    #    end
+    #     length = ycomb do |len|
+    #       proc { |list| list == [] ? 0 : 1 + len.call(list[1..-1]) }
+    #     end
+    #
+    #     length.call([0])
+    #     # => 1
     #
-    # see https://secure.wikimedia.org/wikipedia/en/wiki/Fixed_point_combinator#Y_combinator
-    # and chapter 9 of the little schemer, available as the sample chapter at http://www.ccs.neu.edu/home/matthias/BTLS/
+    # see https://en.wikipedia.org/wiki/Fixed-point_combinator#Y_combinator
+    # and chapter 9 of the little schemer, available as the sample chapter at
+    # https://felleisen.org/matthias/BTLS-index.html
     def ycomb
       proc { |f| f.call(f) }.call(proc { |f| yield proc { |*x| f.call(f).call(*x) } })
     end
-    module_function :ycomb
 
     module FingerprintHash
       # overrides BasicObject#==
       def ==(other)
-        object_id == other.object_id || (other.respond_to?(:jsi_fingerprint) && other.jsi_fingerprint == self.jsi_fingerprint)
+        __id__ == other.__id__ || (other.respond_to?(:jsi_fingerprint) && other.jsi_fingerprint == self.jsi_fingerprint)
       end
 
       alias_method :eql?, :==
@@ -82,26 +121,103 @@ module JSI
       end
     end
 
-    module Memoize
-      def jsi_memoize(key, *args_)
-        @jsi_memos ||= {}
-        @jsi_memos[key] ||= Hash.new do |h, args|
-          h[args] = yield(*args)
-        end
-        @jsi_memos[key][args_]
+    class MemoMap
+      Result = Util::AttrStruct[*%w(
+        value
+        inputs
+        inputs_hash
+      )]
+
+      class Result
       end
 
-      def jsi_clear_memo(key, *args)
-        @jsi_memos ||= {}
-        if @jsi_memos[key]
-          if args.empty?
-            @jsi_memos[key].clear
+      def initialize(key_by: nil, &block)
+        @key_by = key_by
+        @block = block
+
+        # each result has its own mutex to update its memoized value thread-safely
+        @result_mutexes = {}
+        # another mutex to thread-safely initialize each result mutex
+        @result_mutexes_mutex = Mutex.new
+
+        @results = {}
+      end
+
+      def [](*inputs)
+        if @key_by
+          key = @key_by.call(*inputs)
+        else
+          key = inputs
+        end
+        result_mutex = @result_mutexes_mutex.synchronize do
+          @result_mutexes[key] ||= Mutex.new
+        end
+
+        result_mutex.synchronize do
+          inputs_hash = inputs.hash
+          if @results.key?(key) && inputs_hash == @results[key].inputs_hash && inputs == @results[key].inputs
+            @results[key].value
           else
-            @jsi_memos[key].delete(args)
+            value = @block.call(*inputs)
+            @results[key] = Result.new(value: value, inputs: inputs, inputs_hash: inputs_hash)
+            value
           end
         end
       end
     end
+
+    module Memoize
+      def self.extended(object)
+        object.send(:jsi_initialize_memos)
+      end
+
+      private
+
+      def jsi_initialize_memos
+        @jsi_memomaps_mutex = Mutex.new
+        @jsi_memomaps = {}
+      end
+
+      # @return [Util::MemoMap]
+      def jsi_memomap(name, **options, &block)
+        raise(Bug, 'must jsi_initialize_memos') unless @jsi_memomaps
+        unless @jsi_memomaps.key?(name)
+          @jsi_memomaps_mutex.synchronize do
+            # note: this ||= appears redundant with `unless @jsi_memomaps.key?(name)`,
+            # but that check is not thread safe. this check is.
+            @jsi_memomaps[name] ||= Util::MemoMap.new(**options, &block)
+          end
+        end
+        @jsi_memomaps[name]
+      end
+
+      def jsi_memoize(name, *inputs, &block)
+        jsi_memomap(name, &block)[*inputs]
+      end
+    end
+
+    module Virtual
+      class InstantiationError < StandardError
+      end
+
+      # this virtual class is not intended to be instantiated except by its subclasses, which override #initialize
+      def initialize
+        # :nocov:
+        raise(InstantiationError, "cannot instantiate virtual class #{self.class}")
+        # :nocov:
+      end
+
+      # virtual_method is used to indicate that the method calling it must be implemented on the (non-virtual) subclass
+      def virtual_method
+        # :nocov:
+        raise(Bug, "class #{self.class} must implement #{caller_locations.first.label}")
+        # :nocov:
+      end
+    end
+
+    public
+
+    extend self
   end
   public
   extend Util

data/lib/jsi/validation/error.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module JSI
+  module Validation
+    Error = Util::AttrStruct[*%w(
+      message
+      keyword
+      schema
+      instance_ptr
+      instance_document
+    )]
+
+    # a validation error of a schema instance against a schema
+    #
+    # @!attribute message
+    #   a message describing the error
+    #   @return [String]
+    # @!attribute keyword
+    #   the keyword of the schema which failed to validate.
+    #   this may be absent if the error is not from a schema keyword (i.e, `false` schema).
+    #   @return [String]
+    # @!attribute schema
+    #   the schema against which the instance failed to validate
+    #   @return [JSI::Schema]
+    # @!attribute instance_ptr
+    #   pointer to the instance in instance_document
+    #   @return [JSI::Ptr]
+    # @!attribute instance_document
+    #   document containing the instance at instance_ptr
+    #   @return [Object]
+    class Error
+    end
+  end
+end