shape_of 2.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9934786c810465f0edc75a35faa47a305da950a63c337ec1c33b7184c1dd103e
-  data.tar.gz: bf6c05010803284ccb2a6be09d410d903d3693e53ec006be85089a1c0522257c
+  metadata.gz: 9a8e5e89c8b1a515b043085f63fd764221ece2ecafd1c91f471250e9d62a3b36
+  data.tar.gz: d676fa033eeb7da482e60789042c080ef95d317e4aa05d4452547166126191ef
 SHA512:
-  metadata.gz: 19c075c5e72d649267aab15fcdf3872a104ac8ac2534e95159f121ca15cdd2add334f0010f53bd82b64c5ce09b1910717e04e7a6374febb86b143936d05afa4d
-  data.tar.gz: 4166c74b3c7df3ae858b2edeb1239c306e05479c96a0536b08815b279c82209f563f2f469a7ab6d1254c12f249d6014d484f12077e4a6471aa223ef0a15d2578
+  metadata.gz: c1d4be16b5e9b2fa80b08999860ea45ac44ee11fb17c7092ccdf4d1c82b1e17f2c40064aae3d7b8cdf7f222ecc14d5785b2a8aa1bdc411a8f1765fbc8fa1faf2
+  data.tar.gz: 5fbd3d63b7a00d38dac0e7b9521ebd44ec7f24eaa25b4786e40dd7e549d34b6ec066f8e5f64ac031586c33f24f2060643acc5d64e0992189298b592b0c6758e1

data/lib/shape_of.rb

@@ -84,37 +84,125 @@
 # hash_shape.shape_of?({ value: [{}] }) # => false
 # ```
 #
+require 'pp'
+
 module ShapeOf
+  # Used in Assertions, and can also be used separately. It is used to keep track of places where the shape of
+  # data does not match, so that you can have greater insight than just a simple true/false.
+  class Validator
+    attr_reader :shape, :object
+
+    def initialize(shape:, object:)
+      @current_error_key_nesting = [:base] # stack of the current error key.
+      @errors = {}
+      @object = object
+      @shape = shape
+
+      validate
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    def errors
+      @errors[:base]
+    end
+
+    def error_message
+      errors.pretty_inspect
+    end
+
+    def add_error(message)
+      create_nested_error_structure
+
+      @errors.dig(*@current_error_key_nesting)[:errors] << message.dup
+    end
+
+    def push_key(key)
+      @current_error_key_nesting.push(key.dup)
+    end
+
+    def pop_key
+      @current_error_key_nesting.pop
+    end
+
+    private
+
+    def create_nested_error_structure
+      errors = @errors
+      @current_error_key_nesting.each do |key|
+        errors[key] ||= {}
+        errors = errors[key]
+      end
+      @errors.dig(*@current_error_key_nesting)[:errors] ||= []
+    end
+
+    def validate
+      shape.shape_of?(object, validator: self)
+    end
+  end
+
   # To be included in a MiniTest test class
   module Assertions
-    def assert_shape_of(object, shape)
+    # For backward compatibility, this is "off" by default, and the order in the assertions are reverse.
+    @proper_expected_actual_order = false
+    def self.use_proper_expected_actual_order!
+      @proper_expected_actual_order = true
+    end
+
+    def assert_shape_of(arg1, arg2)
+      shape = object = nil
+      if @proper_expected_actual_order
+        shape = arg1
+        object = arg2
+      else
+        shape = arg2
+        object = arg1
+      end
+
+      validator = nil
       if shape.respond_to? :shape_of?
-        assert_operator shape, :shape_of?, object
+        validator = Validator.new(shape: shape, object: object)
       elsif shape.instance_of? ::Array
-        assert_operator Array[shape.first], :shape_of?, object
+        validator = Validator.new(shape: Array[shape.first], object: object)
       elsif shape.instance_of? ::Hash
-        assert_operator Hash[shape], :shape_of?, object
+        validator = Validator.new(shape: Hash[shape], object: object)
       else
         raise TypeError, "Expected #{Shape.inspect}, an #{::Array.inspect}, or a #{::Hash.inspect} as the shape"
       end
+
+      assert validator.valid?, validator.error_message
     end
 
-    def refute_shape_of(object, shape)
+    def refute_shape_of(arg1, arg2)
+      shape = object = nil
+      if @proper_expected_actual_order
+        shape = arg1
+        object = arg2
+      else
+        shape = arg2
+        object = arg1
+      end
+
+      validator = nil
       if shape.respond_to? :shape_of?
-        refute_operator shape, :shape_of?, object
+        validator = Validator.new(shape: shape, object: object)
       elsif shape.instance_of? ::Array
-        refute_operator Array[shape.first], :shape_of?, object
+        validator = Validator.new(shape: Array[shape.first], object: object)
       elsif shape.instance_of? ::Hash
-        refute_operator Hash[shape], :shape_of?, object
+        validator = Validator.new(shape: Hash[shape], object: object)
       else
         raise TypeError, "Expected #{Shape.inspect}, an #{::Array.inspect}, or a #{::Hash.inspect} as the shape"
       end
+
+      refute validator.valid?, "#{shape} is shape_of? #{object}"
     end
   end
 
   # Generic shape which all shapes subclass from
   class Shape
-    def self.shape_of?(*)
+    def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
       raise NotImplementedError
     end
 
@@ -127,15 +215,18 @@ module ShapeOf
     end
   end
 
-  # Array[Shape] denotes that it is an array of shapes.
+  # Array[shape] denotes that it is an array of shapes.
   # It checks every element in the array and verifies that the element is in the correct shape.
-  # This, along with Array, are the core components of this module.
+  # This, along with Hash, are the core components of this module.
   # Note that a ShapeOf::Array[Integer].shape_of?([]) will pass because it is vacuously true for an empty array.
   class Array < Shape
     @internal_class = ::Array
 
-    def self.shape_of?(object)
-      object.instance_of? @internal_class
+    def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
+      is_instance_of = object.instance_of?(@internal_class)
+      validator.add_error(object.inspect + " is not instance of " + @internal_class.inspect) unless is_instance_of
+
+      is_instance_of
     end
 
     def self.[](shape)
@@ -156,33 +247,54 @@ module ShapeOf
           @class_name
         end
 
-        def self.shape_of?(array)
-          super && array.all? do |elem|
-            if @shape.respond_to? :shape_of?
-              @shape.shape_of? elem
+        def self.shape_of?(array, validator: Validator.new(shape: self, object: array))
+          return false unless super
+
+          idx = 0
+          each_is_shape_of = true
+          array.each do |elem|
+            validator.push_key("idx_#{idx}".to_sym)
+
+            is_shape_of = if @shape.respond_to? :shape_of?
+              @shape.shape_of?(elem, validator: validator)
             elsif @shape.is_a? ::Array
-              Array[@shape].shape_of? elem
+              Array[@shape.first].shape_of?(elem, validator: validator)
             elsif @shape.is_a? ::Hash
-              Hash[@shape].shape_of? elem
+              Hash[@shape].shape_of?(elem, validator: validator)
             elsif @shape.is_a? Class
-              elem.instance_of? @shape
+              is_instance_of = elem.instance_of?(@shape)
+              validator.add_error(elem.inspect + " is not instance of " + @shape.inspect) unless is_instance_of
+
+              is_instance_of
             else
-              elem == @shape
+              is_equal_to = elem == @shape
+              validator.add_error(elem.inspect + " is not equal to (==) " + @shape.inspect) unless is_equal_to
+
+              is_equal_to
             end
+
+            validator.pop_key
+            idx += 1
+            each_is_shape_of &&= is_shape_of
           end
+          each_is_shape_of
         end
       end
     end
   end
 
-  # Hash[key: Shape, ...] denotes it is a hash of shapes with a very specific structure. Hash (without square brackets) is just a hash with any shape.
+  # Hash[key: shape, ...] denotes it is a hash of shapes with a very specific structure.
+  # Hash (without square brackets) is just a hash with any shape.
   # This, along with Array, are the core components of this module.
   # Note that the keys are converted to strings for comparison for both the shape and object provided.
   class Hash < Shape
     @internal_class = ::Hash
 
-    def self.shape_of?(object)
-      object.instance_of? @internal_class
+    def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
+      is_instance_of = object.instance_of?(@internal_class)
+      validator.add_error(object.inspect + " is not instance of " + @internal_class.inspect) unless is_instance_of
+
+      is_instance_of
     end
 
     def self.[](shape = {})
@@ -205,32 +317,57 @@ module ShapeOf
           @class_name
         end
 
-        def self.shape_of?(hash)
+        def self.shape_of?(hash, validator: Validator.new(shape: self, object: hash))
           return false unless super
 
+          each_is_shape_of = true
           rb_hash = stringify_rb_hash_keys(hash)
 
           rb_hash.keys.each do |key|
-            return false unless @shape.key?(key)
+            has_key = @shape.key?(key)
+            unless has_key
+              validator.push_key(key)
+              validator.add_error("unexpected key")
+              validator.pop_key
+              each_is_shape_of = false
+            end
           end
 
           @shape.each do |key, shape|
-            return false unless rb_hash.key?(key) || shape.respond_to?(:required?) && !shape.required?
+            unless rb_hash.key?(key) || shape.respond_to?(:required?) && !shape.required?
+              validator.push_key(key)
+              validator.add_error("required key not present")
+              validator.pop_key
+              each_is_shape_of = false
+            end
           end
 
-          rb_hash.all? do |key, elem|
-            if @shape[key].respond_to? :shape_of?
-              @shape[key].shape_of? elem
-            elsif @shape[key].is_a? ::Array
-              Array[@shape[key]].shape_of? elem
-            elsif @shape[key].is_a? ::Hash
-              Hash[@shape[key]].shape_of? elem
-            elsif @shape[key].is_a? Class
-              elem.instance_of? @shape[key]
+          rb_hash.each do |key, elem|
+            shape_elem = @shape[key]
+            validator.push_key(key)
+
+            is_shape_of = if shape_elem.respond_to? :shape_of?
+              shape_elem.shape_of?(elem, validator: validator)
+            elsif shape_elem.is_a? ::Array
+              Array[shape_elem.first].shape_of?(elem, validator: validator)
+            elsif shape_elem.is_a? ::Hash
+              Hash[shape_elem].shape_of?(elem, validator: validator)
+            elsif shape_elem.is_a? Class
+              is_instance_of = elem.instance_of?(shape_elem)
+              validator.add_error(elem.inspect + " is not instance of " + shape_elem.inspect) unless is_instance_of
+
+              is_instance_of
             else
-              elem == @shape[key]
+              is_equal_to = elem == shape_elem
+              validator.add_error(elem.inspect + " is not equal to (==) " + shape_elem.inspect) unless is_equal_to
+
+              is_equal_to
             end
+
+            validator.pop_key
+            each_is_shape_of &&= is_shape_of
           end
+          each_is_shape_of
         end
       end
     end
@@ -238,11 +375,11 @@ module ShapeOf
     private
 
     def self.stringify_rb_hash_keys(rb_hash)
-      rb_hash.to_a.map { |k, v| [k.to_s, v] }.to_h
+      rb_hash.transform_keys(&:to_s)
     end
   end
 
-  # Union[Shape1, Shape2, ...] denotes that it can be of one the provided shapes
+  # Union[shape1, shape2, ...] denotes that it can be of one the provided shapes.
   class Union < Shape
     def self.[](*shapes)
       Class.new(self) do
@@ -261,26 +398,43 @@ module ShapeOf
           @class_name
         end
 
-        def self.shape_of?(object)
-          @shapes.any? do |shape|
+        def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
+          is_any_shape_of_shape_or_hash_or_array = false
+          is_any_shape_of = @shapes.any? do |shape|
             if shape.respond_to? :shape_of?
-              shape.shape_of? object
+              is_any_shape_of_shape_or_hash_or_array ||= shape.shape_of?(object)
             elsif shape.is_a? ::Hash
-              Hash[shape].shape_of? object
+              is_any_shape_of_shape_or_hash_or_array ||= Hash[shape].shape_of?(object)
             elsif shape.is_a? ::Array
-              Array[shape].shape_of? object
+              is_any_shape_of_shape_or_hash_or_array ||= Array[shape].shape_of?(object)
             elsif shape.is_a? Class
-              object.instance_of? shape
+              object.instance_of?(shape)
             else
               object == shape
             end
           end
+
+          if !is_any_shape_of && !is_any_shape_of_shape_or_hash_or_array
+            shape_shapes = @shapes.select { |shape| shape.respond_to?(:shape_of?) }
+            class_shapes = @shapes.select do |shape|
+              !shape.respond_to?(:shape_of?) && !shape.is_a?(::Hash) && !shape.is_a?(::Array) && shape.is_a?(Class)
+            end
+            object_shapes = @shapes.select do |shape|
+              !shape.respond_to?(:shape_of?) && !shape.is_a?(::Hash) && !shape.is_a?(::Array) && !shape.is_a?(Class)
+            end
+            validator.add_error(object.inspect + " is not shape of any of (" + shape_shapes.map(&:inspect).join(", ") +
+                                ") or is not instance of any of (" + class_shapes.map(&:inspect).join(", ") +
+                                ") or is not equal to (==) any of (" + object_shapes.map(&:inspect).join(", ") + ")")
+          end
+
+          is_any_shape_of
         end
       end
     end
   end
 
-  # Optional[Shape] denotes that the usual type is a Shape, but is optional (meaning if it is nil or the key is not present in the Hash, it's still true)
+  # Optional[shape] denotes that the usual type is a shape, but is optional
+  # (meaning if it is nil or the key is not present in the Hash, it's still true)
   class Optional < Shape
     def self.[](shape)
       raise TypeError, "Shape cannot be nil" if shape.nil? || shape == NilClass
@@ -299,15 +453,17 @@ module ShapeOf
     end
   end
 
+  # Anything matches unless key does not exist in the Hash.
   class Any < Shape
-    def self.shape_of?(object)
+    def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
       true
     end
   end
 
-  # Nothing only passes when the key does not exist in the Hash.
+  # Only passes when the key does not exist in the Hash.
   class Nothing < Shape
-    def self.shape_of?(object)
+    def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
+      validator.add_error("key present when not allowed")
       false
     end
 
@@ -316,6 +472,9 @@ module ShapeOf
     end
   end
 
+  # Matches a Regexp against a String using Regexp#match?.
+  # Pretty much a wrapper around Regexp because a Regexp instance will be tested for equality
+  # in the ShapeOf::Hash and ShapeOf::Array since it's not a class.
   class Pattern < Shape
     def self.[](shape)
       raise TypeError, "Shape must be #{Regexp.inspect}, was #{shape.inspect}" unless shape.instance_of? Regexp
@@ -336,19 +495,26 @@ module ShapeOf
           @class_name
         end
 
-        def self.shape_of?(object)
-          raise TypeError, "expected #{String.inspect}, was instead #{object.inspect}" unless object.instance_of?(String)
+        def self.shape_of?(object, validator: Validator.new(shape: self, object: object))
+          unless object.instance_of?(String)
+            validator.add_error(object.inspect + " is not instance of " + String.inspect)
+            return false
+          end
 
-          @shape.match?(object)
+          does_regexp_match = @shape.match?(object)
+          validator.add_error(object.inspect + " does not match " + @shape.inspect) unless does_regexp_match
+          does_regexp_match
         end
       end
     end
   end
 
+  # Union[Integer, Float, Rational, Complex]
   Numeric = Union[Integer, Float, Rational, Complex].tap do |this|
     this.instance_variable_set(:@class_name, this.name.sub(/Union.*/, 'Numeric'))
   end
 
+  # Union[TrueClass, FalseClass]
   Boolean = Union[TrueClass, FalseClass].tap do |this|
     this.instance_variable_set(:@class_name, this.name.sub(/Union.*/, 'Boolean'))
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shape_of
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - John Isom
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2022-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -38,7 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1'
-description:
+description: 
 email: john@johnisom.dev
 executables: []
 extensions: []
@@ -49,7 +49,7 @@ homepage: https://github.com/johnisom/shape_of
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -64,8 +64,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.17
-signing_key:
+rubygems_version: 3.2.22
+signing_key: 
 specification_version: 4
 summary: A shape/type checker for Ruby objects.
 test_files: []