jsi 0.8.2 → 0.9.0

data/lib/jsi/util/typelike.rb

@@ -5,6 +5,8 @@ module JSI
   #
   # this module is intended to be internal to JSI. no guarantees or API promises
   # are made for non-JSI classes including this module.
+  #
+  # @api private
   module Util::Hashlike
     include(Enumerable)
 
@@ -13,17 +15,14 @@ module JSI
 
     # methods which do not need to access the value.
     SAFE_KEY_ONLY_METHODS = %w(each_key empty? has_key? include? key? keys length member? size).map(&:freeze).freeze
-    SAFE_KEY_VALUE_METHODS = %w(< <= > >= any? assoc compact dig each_pair each_value fetch fetch_values has_value? invert key merge rassoc reject select to_h to_proc transform_values value? values values_at).map(&:freeze).freeze
-    DESTRUCTIVE_METHODS = %w(clear delete delete_if keep_if reject! replace select! shift).map(&:freeze).freeze
+    SAFE_KEY_VALUE_METHODS = %w(< <= > >= any? assoc compact dig each_pair each_value fetch fetch_values flatten has_value? invert key merge rassoc reject select filter to_h to_proc transform_values value? values values_at).map(&:freeze).freeze
+    DESTRUCTIVE_METHODS = %w(clear delete delete_if filter! flatten! keep_if reject! replace select! shift).map(&:freeze).freeze
     # these return a modified copy
-    safe_modified_copy_methods = %w(compact)
-    # select and reject will return a modified copy but need the yielded block variable value from #[]
-    safe_kv_block_modified_copy_methods = %w(select reject)
+    safe_modified_copy_methods = %w(compact slice except)
     SAFE_METHODS = SAFE_KEY_ONLY_METHODS | SAFE_KEY_VALUE_METHODS
     custom_methods = %w(merge) # defined below
     safe_to_hash_methods = SAFE_METHODS -
       safe_modified_copy_methods -
-      safe_kv_block_modified_copy_methods -
       custom_methods
     safe_to_hash_methods.each do |method_name|
       if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
@@ -49,16 +48,6 @@ module JSI
         end
       end
     end
-    safe_kv_block_modified_copy_methods.each do |method_name|
-      define_method(method_name) do |**kw, &b|
-        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) do |k, _v|
-            b.call(k, self[k, **kw])
-          end
-        end
-      end
-    end
 
     # 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
@@ -93,34 +82,22 @@ module JSI
       end
     end
 
-    # 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?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
-      -"\#{<#{object_group_str}>#{map { |k, v| " #{k.inspect} => #{v.inspect}" }.join(',')}}"
-    end
-
-    def to_s
-      inspect
-    end
-
     # pretty-prints a representation of this hashlike to the given printer
     # @return [void]
     def pretty_print(q)
       object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#{<#{object_group_str}>"
-      q.group(2) {
+      q.group {
+        q.nest(2) {
           q.breakable ' ' if !empty?
-          q.seplist(self, nil, :each_pair) { |k, v|
-            q.group {
+          q.seplist(self) { |k, v|
               q.pp k
               q.text ' => '
               q.pp v
-            }
           }
+        }
+        q.breakable('') if !empty?
       }
-      q.breakable '' if !empty?
       q.text '}'
     end
   end
@@ -129,6 +106,8 @@ module JSI
   #
   # this module is intended to be internal to JSI. no guarantees or API promises
   # are made for non-JSI classes including this module.
+  #
+  # @api private
   module Util::Arraylike
     include(Enumerable)
 
@@ -138,17 +117,14 @@ module JSI
     # methods which do not need to access the element.
     SAFE_INDEX_ONLY_METHODS = %w(each_index empty? length size).map(&:freeze).freeze
     # there are some ambiguous ones that are omitted, like #sort, #map / #collect.
-    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).map(&:freeze).freeze
+    SAFE_INDEX_ELEMENT_METHODS = %w(| & * + - <=> abbrev at bsearch bsearch_index combination compact count cycle difference dig drop drop_while fetch find_index first include? index intersection intersect? 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 union uniq values_at zip).map(&:freeze).freeze
     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).map(&:freeze).freeze
 
     # methods (well, method) that returns a modified copy and doesn't need any handling of block variable(s)
     safe_modified_copy_methods = %w(compact)
 
-    # methods that return a modified copy and do need handling of block variables
-    safe_el_block_methods = %w(reject select)
-
     SAFE_METHODS = SAFE_INDEX_ONLY_METHODS | SAFE_INDEX_ELEMENT_METHODS
-    safe_to_ary_methods = SAFE_METHODS - safe_modified_copy_methods - safe_el_block_methods
+    safe_to_ary_methods = SAFE_METHODS - safe_modified_copy_methods
     safe_to_ary_methods.each do |method_name|
       if Util::LAST_ARGUMENT_AS_KEYWORD_PARAMETERS
         define_method(method_name) { |*a, &b| to_ary.public_send(method_name, *a, &b) }
@@ -173,17 +149,6 @@ module JSI
         end
       end
     end
-    safe_el_block_methods.each do |method_name|
-      define_method(method_name) do |**kw, &b|
-        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) do |_e|
-            b.call(self[i, **kw]).tap { i += 1 }
-          end
-        end
-      end
-    end
 
     # see [Array#assoc](https://ruby-doc.org/core/Array.html#method-i-assoc)
     def assoc(obj)
@@ -199,30 +164,20 @@ module JSI
       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?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
-      -"\#[<#{object_group_str}>#{map { |e| ' ' + e.inspect }.join(',')}]"
-    end
-
-    def to_s
-      inspect
-    end
-
     # pretty-prints a representation of this arraylike to the given printer
     # @return [void]
     def pretty_print(q)
       object_group_str = (respond_to?(:jsi_object_group_text, true) ? jsi_object_group_text : [self.class]).join(' ')
       q.text "\#[<#{object_group_str}>"
-      q.group(2) {
+      q.group {
+        q.nest(2) {
           q.breakable ' ' if !empty?
-          q.seplist(self, nil, :each) { |e|
+          q.seplist(self) { |e|
             q.pp e
           }
+        }
+        q.breakable('') if !empty?
       }
-      q.breakable '' if !empty?
       q.text ']'
     end
   end

data/lib/jsi/util.rb

@@ -1,10 +1,48 @@
 # frozen_string_literal: true
 
+require("delegate")
+
 module JSI
   # JSI::Util contains public utilities
   module Util
     autoload :Private, 'jsi/util/private'
 
+    # common methods of inspecting / pretty-printing
+    # @private (not in Util::Private due to dependency order)
+    module Pretty
+      # @return [String]
+      def inspect
+        out = String.new
+        PP.singleline_pp(self, out)
+        out.freeze
+      end
+
+      # @return [String]
+      def to_s
+        inspect
+      end
+
+      private
+
+      def jsi_pp_object_group(q, pres = [self.class.name].freeze, empty: false)
+        q.text('#<')
+        pres.each_with_index do |pre, i|
+          q.text(' ') if i != 0
+          q.text(pre.to_s)
+        end
+        if block_given? && !empty
+          q.group do
+            q.nest(2) do
+              q.breakable(' ')
+              yield
+            end
+            q.breakable('')
+          end
+        end
+        q.text('>')
+      end
+    end
+
     include Private
 
     extend self
@@ -32,7 +70,7 @@ module JSI
 
     # A structure like the given `object`, recursively coerced to JSON-compatible types.
     #
-    # - Structures of Hash, Array, and basic types of String/number/boolean/nil are returned as-is.
+    # - Structures of Hash, Array, and simple types of String/number/boolean/nil are returned as-is.
     # - If the object responds to `#as_json`, that method is used, passing any given options.
     # - If the object supports [implicit conversion](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html)
     #   with `#to_hash`, `#to_ary`, `#to_str`, or `#to_int`, that is used.
@@ -46,7 +84,7 @@ module JSI
       type_err = proc { raise(TypeError, "cannot express object as json: #{object.pretty_inspect.chomp}") }
       if object.respond_to?(:as_json)
         options.empty? ? object.as_json : object.as_json(**options) # TODO remove eventually (keyword argument compatibility)
-      elsif object.is_a?(Addressable::URI)
+      elsif object.is_a?(URI)
         object.to_s
       elsif object.respond_to?(:to_hash) && (object_to_hash = object.to_hash).is_a?(Hash)
         result = {}
@@ -67,7 +105,7 @@ module JSI
         object
       elsif object.is_a?(Symbol)
         object.to_s
-      elsif object.is_a?(Set)
+      elsif object.is_a?(::Set)
         as_json(object.to_a, **options)
       elsif object.respond_to?(:to_str) && (object_to_str = object.to_str).is_a?(String)
         object_to_str
@@ -85,10 +123,15 @@ module JSI
     # - Otherwise, JSON is generated using {as_json} to coerce to compatible types.
     # @return [String]
     def to_json(object, options = {})
+      options_state = options.class.name =~ /\AJSON:.*:Generator::State\z/
       if USE_TO_JSON_METHOD[object.class]
-        options.empty? ? object.to_json : object.to_json(**options) # TODO remove eventually (keyword argument compatibility)
+        (options_state || !options.empty?) ? object.to_json(options) : object.to_json # TODO remove eventually (keyword argument compatibility)
       else
-        JSON.generate(as_json(object, **options))
+        if options_state
+          JSON.generate(as_json(object), options)
+        else
+          JSON.generate(as_json(object, **options))
+        end
       end
     end
 
@@ -120,7 +163,7 @@ module JSI
     end
 
     def deep_stringify_symbol_keys(object)
-      if object.respond_to?(:to_hash) && !object.is_a?(Addressable::URI)
+      if object.respond_to?(:to_hash) && !object.is_a?(URI)
         JSI::Util.modified_copy(object) do |hash|
           out = {}
           (hash.respond_to?(:each) ? hash : hash.to_hash).each do |k, v|
@@ -143,7 +186,9 @@ module JSI
     # the given object is not modified.
     def deep_to_frozen(object, not_implemented: nil)
       dtf = proc { |o| deep_to_frozen(o, not_implemented: not_implemented) }
-      if object.instance_of?(Hash)
+      if object.is_a?(Delegator)
+        object.class.new(dtf[object.__getobj__]).freeze
+      elsif object.instance_of?(Hash)
         out = {}
         identical = object.frozen?
         object.each do |k, v|
@@ -197,32 +242,5 @@ module JSI
         end
       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.
-    #
-    # @api private
-    # @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
-      elsif modules.is_a?(Enumerable)
-        set = Set.new(modules).freeze
-      else
-        raise(TypeError, "not given an Enumerable of Modules")
-      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
   end
 end

data/lib/jsi/validation/error.rb

@@ -2,13 +2,15 @@
 
 module JSI
   module Validation
-    Error = Util::AttrStruct[*%w(
+    Error = Struct.subclass(*%i(
       message
       keyword
+      additional
       schema
       instance_ptr
       instance_document
-    )]
+      nested_errors
+    ))
 
     # a validation error of a schema instance against a schema
     #
@@ -19,6 +21,9 @@ module JSI
     #   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 additional
+    #   additional contextual information about the error
+    #   @return [Hash]
     # @!attribute schema
     #   the schema against which the instance failed to validate
     #   @return [JSI::Schema]
@@ -28,11 +33,45 @@ module JSI
     # @!attribute instance_document
     #   document containing the instance at instance_ptr
     #   @return [Object]
+    # @!attribute nested_errors
+    #   @return [Set<Validation::Error>]
     class Error
       def initialize(attributes = {})
         super
         freeze
       end
+
+      # @yield [Validation::Error]
+      def each_validation_error(&block)
+        return(to_enum(__method__)) if !block_given?
+        nested_errors.each { |nested_error| nested_error.each_validation_error(&block) }
+        yield(self)
+        nil
+      end
+
+      # @return [Object]
+      def instance
+        instance_ptr.evaluate(instance_document)
+      end
+
+      def pretty_print(q)
+        info = {
+          message: message,
+          instance: instance,
+          instance_ptr: instance_ptr,
+          keyword: keyword,
+          additional: additional,
+          'schema uri': schema.schema_uri || schema.jsi_ptr.uri,
+          nested_errors: nested_errors,
+        }
+        jsi_pp_object_group(q) do
+          q.seplist(info) do |k, v|
+            q.text(k.to_s)
+            q.text(': ')
+            q.pp(v)
+          end
+        end
+      end
     end
   end
 end

data/lib/jsi/validation/result.rb

@@ -4,31 +4,20 @@ module JSI
   module Validation
     # a result of validating an instance against schemas which describe it.
     class Result
-      Builder = Util::AttrStruct[*%w(
+      Builder = Schema::Cxt.subclass(*%i(
         result
-        schema
         instance_ptr
         instance_document
         validate_only
         visited_refs
-      )]
+      ))
 
       # @private
-      # a structure used to build a Result. virtual base class.
-      class Builder
+      # context to build a Validation::Result
+      class Builder < Schema::Cxt
         def instance
-          instance_ptr.evaluate(instance_document)
-        end
-
-        def schema_issue(*_)
-        end
-
-        def schema_error(message, keyword = nil)
-          schema_issue(:error, message, keyword)
-        end
-
-        def schema_warning(message, keyword = nil)
-          schema_issue(:warning, message, keyword)
+          return @instance if instance_variable_defined?(:@instance)
+          @instance = instance_ptr.evaluate(instance_document)
         end
 
         # @param subschema_ptr [JSI::Ptr, #to_ary]
@@ -40,7 +29,6 @@ module JSI
             validate_only: validate_only,
             visited_refs: visited_refs,
           )
-          merge_schema_issues(subresult)
           subresult
         end
 
@@ -53,134 +41,180 @@ module JSI
             instance_document,
             validate_only: validate_only,
           )
-          merge_schema_issues(subresult)
           subresult
         end
 
-        # @param other_result [JSI::Validation::Result]
-        # @return [void]
-        def merge_schema_issues(other_result)
-          unless validate_only
-            # schema_issues are always merged from subschema results (not depending on validation results)
-            result.schema_issues.merge(other_result.schema_issues)
+        # @param results [Enumerable<Validation::Result>]
+        def inplace_results_validate(*a, results: , **kw)
+          results.select(&:valid?).each do |inplace_result|
+            result.evaluated_tokens.merge(inplace_result.evaluated_tokens)
           end
-          nil
+          validate(*a, **kw,
+            results: results,
+          )
+        end
+
+        # @param child_results [Hash<Object, Validation::Result>] token => child result
+        def child_results_validate(*a, child_results: , **kw)
+          result.evaluated_tokens.merge(child_results.each_key.select { |t| child_results[t].valid? })
+          validate(*a, **kw,
+            results: child_results.each_value,
+          )
         end
       end
     end
 
     class Result
+      include(Util::Pretty)
+
       # is the instance valid against its schemas?
       # @return [Boolean]
       def valid?
         #chkbug raise(NotImplementedError)
       end
 
+      # @raise [JSI::Invalid]
+      # @return [nil]
+      def valid!
+        raise(JSI::Invalid, self) if !valid?
+      end
+
+      def pretty_print(q)
+        pretty_print_valid(q)
+      end
+
       include Util::FingerprintHash
+
+      private
+
+      def pretty_print_valid(q, &block)
+        jsi_pp_object_group(q, [self.class.name, valid? ? "(VALID)" : "(INVALID)"].freeze, &block)
+      end
     end
 
     # a full result of validating an instance against its schemas, with each validation error
-    class FullResult < Result
+    class Result::Full < Result
       # @private
       class Builder < Result::Builder
         def validate(
             valid,
-            message,
+            message_key,
+            message_default,
             keyword: nil,
-            results: Util::EMPTY_ARY
+            results: Util::EMPTY_ARY,
+            **additional
         )
-          results.each { |res| result.schema_issues.merge(res.schema_issues) }
           if !valid
-            results.each { |res| result.validation_errors.merge(res.validation_errors) }
-            result.validation_errors << Validation::Error.new({
-              message: message,
+            result.nested_validation_errors << Validation::Error.new({
+              message: JSI.t(message_key, default: message_default, **additional),
               keyword: keyword,
+              additional: additional,
               schema: schema,
               instance_ptr: instance_ptr,
               instance_document: instance_document,
+              nested_errors: results.map(&:nested_validation_errors).inject(Set[], &:merge).freeze,
             })
           end
         end
-
-        def schema_issue(level, message, keyword = nil)
-          result.schema_issues << Schema::Issue.new({
-            level: level,
-            message: message,
-            keyword: keyword,
-            schema: schema,
-          })
-        end
       end
     end
 
-    class FullResult
+    class Result::Full
       def initialize
-        @validation_errors = Set.new
-        @schema_issues = Set.new
+        @nested_validation_errors = Set.new
+        @evaluated_tokens = Set.new
       end
 
-      attr_reader :validation_errors
-      attr_reader :schema_issues
+      # @return [Set<Validation::Error>]
+      attr_reader(:nested_validation_errors)
+
+      # @yield [Validation::Error]
+      def each_validation_error(&block)
+        return(to_enum(__method__)) if !block_given?
+        nested_validation_errors.each do |validation_error|
+          validation_error.each_validation_error(&block)
+        end
+        nil
+      end
+
+      # @deprecated after v0.8
+      # iterating (recursively) is better done with #each_validation_error
+      def validation_errors
+        each_validation_error.to_set
+      end
+
+      # @return [Set]
+      attr_reader(:evaluated_tokens)
 
       def valid?
-        validation_errors.empty?
+        nested_validation_errors.empty?
       end
 
       def freeze
-        @schema_issues.each(&:freeze)
-        @validation_errors.freeze
-        @schema_issues.freeze
+        @nested_validation_errors.freeze
+        @evaluated_tokens.freeze
         super
       end
 
       def merge(result)
-        unless result.is_a?(FullResult)
-          raise(TypeError, "not a #{FullResult.name}: #{result.pretty_inspect.chomp}")
-        end
-        validation_errors.merge(result.validation_errors)
-        schema_issues.merge(result.schema_issues)
+        raise(TypeError, "not a #{Result::Full}: #{result.pretty_inspect.chomp}") unless result.is_a?(Result::Full)
+        nested_validation_errors.merge(result.nested_validation_errors)
+        evaluated_tokens.merge(result.evaluated_tokens)
         self
       end
 
+      def pretty_print(q)
+        pretty_print_valid(q) do
+          q.text('validation errors: ')
+          q.pp(nested_validation_errors)
+        end
+      end
+
       # see {Util::Private::FingerprintHash}
       # @api private
       def jsi_fingerprint
         {
           class: self.class,
-          validation_errors: validation_errors,
-          schema_issues: schema_issues,
+          nested_validation_errors: nested_validation_errors,
+          evaluated_tokens: evaluated_tokens,
         }.freeze
       end
     end
 
-    # a result indicating only whether an instance is valid against its schemas
-    class ValidityResult < Result
+    # A result indicating validation success of an instance against a schema
+    class Result::Valid < Result
       # @private
       class Builder < Result::Builder
         def validate(
             valid,
-            message,
+            message_key,
+            message_default,
             keyword: nil,
-            results: Util::EMPTY_ARY
+            results: Util::EMPTY_ARY,
+            **additional
         )
           if !valid
             throw(:jsi_validation_result, INVALID)
           end
         end
-
-        def schema_issue(*_)
-          # noop
-        end
       end
     end
 
-    class ValidityResult
-      def initialize(valid)
-        @valid = valid
+    class Result::Valid
+      def initialize
+        @evaluated_tokens = Set.new
       end
 
+      # @return [Set]
+      attr_reader(:evaluated_tokens)
+
       def valid?
-        @valid
+        true
+      end
+
+      def freeze
+        @evaluated_tokens.freeze
+        super
       end
 
       # see {Util::Private::FingerprintHash}
@@ -188,9 +222,22 @@ module JSI
       def jsi_fingerprint
         {
           class: self.class,
-          valid: valid?,
+          evaluated_tokens: evaluated_tokens,
         }.freeze
       end
     end
+
+    # A result indicating validation failure of an instance against a schema
+    class Result::Invalid < Result
+      def valid?
+        false
+      end
+
+      # see {Util::Private::FingerprintHash}
+      # @api private
+      def jsi_fingerprint
+        self.class
+      end
+    end
   end
 end