attributor 5.5 → 6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 30cd524aa1a60bb34487915e2201e20b075f8eaf
-  data.tar.gz: 4a9776a1a772b00636a46caec55f583aa75d54f4
+SHA256:
+  metadata.gz: 1a27077cb0a67b6ab8fdde19c88a993ba648c6deb38d5a83766df49b7199338d
+  data.tar.gz: 99bf9996744d757817fd167fa510b462fab6ee1dd3b52992594d06768966bd53
 SHA512:
-  metadata.gz: a5a4832825c92b5530352b626ae281c134aa215f167c633a7912b22cee2927fde696d07b92bfd6159b0e88db4dc69b19b38a289181cb523e0c961005608e4f86
-  data.tar.gz: a44680f8509acf463ac0c4a22a872db8456300745d01b5c4a31a597bd17760d995e5d6ce26120d998f8df5c4c06fe2d11e7e00c35959f6c987860059425af663
+  metadata.gz: e91ad1a7759be0e56c66f53bafbe6d22f1a2ce724fc777ade2649987d6bf19d184eb0fc5f43d00dcbf2310bbae72359199f34d25c38aa65cc69f38cc28d33a55
+  data.tar.gz: 947764564827d2d05e967f60ccc100d42eedf219fddab8ffff56bb8f61c0264c67e9bdd77d3a3585b99d80e5e54f22ef2a6e3424c3ba83549df0932874b0c0af

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 # Attributor Changelog
 
 ## next
+- added support for enum's out of values in json_schema generation
+
+## 6.1 (1/7/2022)
+- added support for enum's out of values in json_schema generation
+
+## 6.0 (22/11/2021)
+- removed `required_if` support and all of the necessary code. 
+- changed the semantics of the `required:` option in attributes, to really mean if the "key" is required to be passed in or not (i.e., check if the key is null, not if its value is null)
+- Introduced a new option`null: true|false` to allow for the value of an attribute to be nullable or not when the attribute is passed in.
+  * The default behavior for an attribute nullability currently `null: false` (but it can be easily changed by overriding the `Attributor::Attribute.default_for_null` function to return `true`)
+## 5.7 (1/7/2021)
+
+- added `custom_option` to Attributor::Attribute class, accepting a name and Attribute arguments that will be used to validate the option value(s) provided.
+
+## 5.6 (11/02/2020)
+
+- Small fixes for dumping JSON-schema default values if they're Proc's or dumpable objects
 
 ## 5.5 (21/08/2020)
 

data/lib/attributor/attribute.rb

@@ -17,18 +17,30 @@ module Attributor
       FakeParent
     end
   end
+
   # It is the abstract base class to hold an attribute, both a leaf and a container (hash/Array...)
   # TODO: should this be a mixin since it is an abstract class?
   class Attribute
     attr_reader :type, :options
 
+    @custom_options = {}
+
+    class << self
+      attr_accessor :custom_options
+    end    
+
+    def self.custom_option(name, attr_type, options = {}, &block)
+      if TOP_LEVEL_OPTIONS.include?(name) || INTERNAL_OPTIONS.include?(name)
+        raise ArgumentError, "can not define custom_option with name #{name.inspect}, it is reserved by Attributor"
+      end
+      self.custom_options[name] = Attributor::Attribute.new(attr_type, options, &block)
+    end
+
     # @options: metadata about the attribute
     # @block: code definition for struct attributes (nil for predefined types or leaf/simple types)
     def initialize(type, options = {}, &block)
       @type = Attributor.resolve_type(type, options, block)
-
-      @options = options
-      @options = @type.options.merge(@options) if @type.respond_to?(:options)
+      @options = @type.respond_to?(:options) ?  @type.options.merge(options) : options
 
       check_options!
     end
@@ -82,18 +94,16 @@ module Attributor
 
     def validate_type(value, context)
       # delegate check to type subclass if it exists
-      unless type.valid_type?(value)
-        msg = "Attribute #{Attributor.humanize_context(context)} received value: "
-        msg += "#{Attributor.errorize_value(value)} is of the wrong type "
-        msg += "(got: #{value.class.name}, expected: #{type.name})"
-        return [msg]
-      end
-      []
+      return [] if value.nil? || type.valid_type?(value)
+
+      msg = "Attribute #{Attributor.humanize_context(context)} received value: "
+      msg += "#{Attributor.errorize_value(value)} is of the wrong type "
+      msg += "(got: #{value.class.name}, expected: #{type.name})"
+      [msg]
     end
 
-    TOP_LEVEL_OPTIONS = [:description, :values, :default, :example, :required, :required_if, :custom_data].freeze
+    TOP_LEVEL_OPTIONS = [:description, :values, :default, :example, :required, :null, :custom_data].freeze
     INTERNAL_OPTIONS = [:dsl_compiler, :dsl_compiler_options].freeze # Options we don't want to expose when describing attributes
-    JSON_SCHEMA_UNSUPPORTED_OPTIONS = [ :required, :required_if ].freeze
     def describe(shallow=true, example: nil)
       description = { }
       # Clone the common options
@@ -161,7 +171,10 @@ module Attributor
 
       description[:description] = self.options[:description] if self.options[:description]
       description[:enum] = self.options[:values] if self.options[:values]
-      description[:default] = self.options[:default] if self.options[:default]
+      if the_default = self.options[:default]
+        the_object = the_default.is_a?(Proc) ? the_default.call : the_default
+        description[:default] = the_object.is_a?(Attributor::Dumpable) ? the_object.dump : the_object
+      end
       #TODO      description[:title] = "TODO: do we want to use a title??..."
 
       # Change the reference option to the actual class name.
@@ -172,6 +185,11 @@ module Attributor
       # TODO: not sure if that's correct (we used to get it from the described hash...
       description[:example] = self.dump(example) if example
 
+      # add custom options as x-optionname
+      self.class.custom_options.each do |name, _|
+        description["x-#{name}".to_sym] = self.options[name] if self.options.key?(name)
+      end
+
       description
     end
 
@@ -206,78 +224,38 @@ module Attributor
       type.attributes if @type_has_attributes ||= type.respond_to?(:attributes)
     end
 
+    # Default value for a non-specified null: option 
+    def self.default_for_null
+      false
+    end
+
+    # It is only nullable if there is an explicit null: true (or if it's not passed/set, and the default is true)
+    def self.nullable_attribute?(options)
+      !options.key?(:null) ? default_for_null : options[:null]
+    end
+
     # Validates stuff and checks dependencies
     def validate(object, context = Attributor::DEFAULT_ROOT_CONTEXT)
       raise "INVALID CONTEXT!! #{context}" unless context
       # Validate any requirements, absolute or conditional, and return.
 
-      if object.nil? # == Attributor::UNSET
-        # With no value, we can only validate whether that is acceptable or not and return.
-        # Beyond that, no further validation should be done.
-        return validate_missing_value(context)
-      end
-
-      # TODO: support validation for other types of conditional dependencies based on values of other attributes
-
-      errors = validate_type(object, context)
-
-      # End validation if we don't even have the proper type to begin with
-      return errors if errors.any?
-
-      if options[:values] && !options[:values].include?(object)
-        errors << "Attribute #{Attributor.humanize_context(context)}: #{Attributor.errorize_value(object)} is not within the allowed values=#{options[:values].inspect} "
-      end
-
-      errors + type.validate(object, context, self)
-    end
-
-    def validate_missing_value(context)
-      raise "INVALID CONTEXT!!! (got: #{context.inspect})" unless context.is_a? Enumerable
-
-      # Missing attribute was required if :required option was set
-      return ["Attribute #{Attributor.humanize_context(context)} is required"] if options[:required]
-
-      # Missing attribute was not required if :required_if (and :required)
-      # option was NOT set
-      requirement = options[:required_if]
-      return [] unless requirement
-
-      case requirement
-      when ::String
-        key_path = requirement
-        predicate = nil
-      when ::Hash
-        # TODO: support multiple dependencies?
-        key_path = requirement.keys.first
-        predicate = requirement.values.first
+      errors = []
+      if object.nil? && !self.class.nullable_attribute?(options)
+        errors << "Attribute #{Attributor.humanize_context(context)} is not nullable"
       else
-        # should never get here if the option validation worked...
-        raise AttributorException, "unknown type of dependency: #{requirement.inspect} for #{Attributor.humanize_context(context)}"
-      end
-
-      # chop off the last part
-      requirement_context = context[0..-2]
-      requirement_context_string = requirement_context.join(Attributor::SEPARATOR)
+        errors.push *validate_type(object, context)
 
-      # FIXME: we're having to reconstruct a string context just to use the resolver...smell.
-      if AttributeResolver.current.check(requirement_context_string, key_path, predicate)
-        message = "Attribute #{Attributor.humanize_context(context)} is required when #{key_path} "
-
-        # give a hint about what the full path for a relative key_path would be
-        unless key_path[0..0] == Attributor::AttributeResolver::ROOT_PREFIX
-          message << "(for #{Attributor.humanize_context(requirement_context)}) "
+        # If the value is null we skip value validation:
+        # a) If null wasn't allowed, it would have failed above.
+        # b) If null was allowed, we always allow that as a valid value
+        if !object.nil? && options[:values] && !options[:values].include?(object)
+          errors << "Attribute #{Attributor.humanize_context(context)}: #{Attributor.errorize_value(object)} is not within the allowed values=#{options[:values].inspect} "
         end
-
-        message << if predicate
-                     "matches #{predicate.inspect}."
-                   else
-                     'is present.'
-                   end
-
-        [message]
-      else
-        []
       end
+
+      return errors if errors.any?
+      
+      object.nil? ? errors : errors + type.validate(object, context, self)
     end
 
     def check_options!
@@ -293,6 +271,8 @@ module Attributor
 
     # TODO: override in type subclass
     def check_option!(name, definition)
+      return check_custom_option(name, definition) if self.class.custom_options.include? name
+
       case name
       when :values
         raise AttributorException, "Allowed set of values requires an array. Got (#{definition})" unless definition.is_a? ::Array
@@ -304,9 +284,8 @@ module Attributor
       when :required
         raise AttributorException, 'Required must be a boolean' unless definition == true || definition == false
         raise AttributorException, 'Required cannot be enabled in combination with :default' if definition == true && options.key?(:default)
-      when :required_if
-        raise AttributorException, 'Required_if must be a String, a Hash definition or a Proc' unless definition.is_a?(::String) || definition.is_a?(::Hash) || definition.is_a?(::Proc)
-        raise AttributorException, 'Required_if cannot be specified together with :required' if options[:required]
+      when :null
+        raise AttributorException, 'Null must be a boolean' unless definition == true || definition == false        
       when :example
         unless definition.is_a?(::Regexp) || definition.is_a?(::String) || definition.is_a?(::Array) || definition.is_a?(::Proc) || definition.nil? || type.valid_type?(definition)
           raise AttributorException, "Invalid example type (got: #{definition.class.name}). It must always match the type of the attribute (except if passing Regex that is allowed for some types)"
@@ -319,5 +298,14 @@ module Attributor
 
       :ok # passes
     end
+
+    def check_custom_option(name, definition) 
+      attribute = self.class.custom_options.fetch(name) 
+
+      errors = attribute.validate(definition)
+      raise AttributorException, "Custom option #{name.inspect} is invalid: #{errors.inspect}" if errors.any?
+
+      :ok
+    end
   end
 end

data/lib/attributor/hash_dsl_compiler.rb

@@ -35,30 +35,31 @@ module Attributor
           rest = attr_names - keys
           unless rest.empty?
             rest.each do |attr|
-              result.push "Key #{attr} is required for #{Attributor.humanize_context(context)}."
+              sub_context = Attributor::Hash.generate_subcontext(context, attr)
+              result.push "Attribute #{Attributor.humanize_context(sub_context)} is required."
             end
           end
         when :exactly
           included = attr_names & keys
           unless included.size ==  number
-            result.push "Exactly #{number} of the following keys #{attr_names} are required for #{Attributor.humanize_context(context)}. Found #{included.size} instead: #{included.inspect}"
+            result.push "Exactly #{number} of the following attributes #{attr_names} are required for #{Attributor.humanize_context(context)}. Found #{included.size} instead: #{included.inspect}"
           end
         when :at_most
           rest = attr_names & keys
           if rest.size > number
             found = rest.empty? ? 'none' : rest.inspect
-            result.push "At most #{number} keys out of #{attr_names} can be passed in for #{Attributor.humanize_context(context)}. Found #{found}"
+            result.push "At most #{number} attributes out of #{attr_names} can be passed in for #{Attributor.humanize_context(context)}. Found #{found}"
           end
         when :at_least
           rest = attr_names & keys
           if rest.size < number
             found = rest.empty? ? 'none' : rest.inspect
-            result.push "At least #{number} keys out of #{attr_names} are required to be passed in for #{Attributor.humanize_context(context)}. Found #{found}"
+            result.push "At least #{number} attributes out of #{attr_names} are required to be passed in for #{Attributor.humanize_context(context)}. Found #{found}"
           end
         when :exclusive
           intersection = attr_names & keys
           if intersection.size > 1
-            result.push "keys #{intersection.inspect} are mutually exclusive for #{Attributor.humanize_context(context)}."
+            result.push "Attributes #{intersection.inspect} are mutually exclusive for #{Attributor.humanize_context(context)}."
           end
         end
         result

data/lib/attributor/type.rb

@@ -135,6 +135,9 @@ module Attributor
         if hash[:type] == :string && the_format = json_schema_string_format
           hash[:format] = the_format
         end
+        # Common options
+        hash[:enum] = attribute_options[:values] if attribute_options[:values]
+  
         hash
       end
 

data/lib/attributor/types/collection.rb

@@ -125,7 +125,10 @@ module Attributor
       hash = super
       opts = self.options.merge( attribute_options )
       hash[:description] = opts[:description] if opts[:description]
-      hash[:default] = opts[:default] if opts[:default]
+      if the_default = opts[:default]
+        the_object = the_default.is_a?(Proc) ? the_default.call : the_default
+        hash[:description] = the_object.is_a?(Attributor::Dumpable) ? the_object.dump : the_object
+      end
 
       #hash[:examples] = [ example.dump ] if example
       member_example = example && example.first

data/lib/attributor/types/hash.rb

@@ -426,7 +426,6 @@ module Attributor
       unless object.is_a?(self)
         raise ArgumentError, "#{name} can not validate object of type #{object.class.name} for #{Attributor.humanize_context(context)}."
       end
-
       object.validate(context)
     end
 
@@ -514,7 +513,6 @@ module Attributor
         end
       end
       # TODO: minProperties and maxProperties and patternProperties
-      # TODO: map our required_if (and possible our above requirements 'at_least...' to json schema dependencies)
       hash
     end
 
@@ -613,6 +611,12 @@ module Attributor
       context = [context] if context.is_a? ::String
 
       if self.class.keys.any?
+        extra_keys = @contents.keys - self.class.keys.keys
+        if extra_keys.any? && !self.class.options[:allow_extra]
+          return extra_keys.collect do |k|
+            "#{Attributor.humanize_context(context)} can not have key: #{k.inspect}"
+          end
+        end
         self.validate_keys(context)
       else
         self.validate_generic(context)
@@ -622,30 +626,34 @@ module Attributor
     end
 
     def validate_keys(context)
-      extra_keys = @contents.keys - self.class.keys.keys
-      if extra_keys.any? && !self.class.options[:allow_extra]
-        return extra_keys.collect do |k|
-          "#{Attributor.humanize_context(context)} can not have key: #{k.inspect}"
-        end
-      end
-
       errors = []
-      keys_with_values = []
+      keys_provided = []
 
       self.class.keys.each do |key, attribute|
         sub_context = self.class.generate_subcontext(context, key)
 
-        value = @contents[key]
-        keys_with_values << key unless value.nil?
+        value = _get_attr(key)
+        keys_provided << key if @contents.key?(key)
 
         if value.respond_to?(:validating) # really, it's a thing with sub-attributes
           next if value.validating
         end
-
-        errors.concat attribute.validate(value, sub_context)
+        # Isn't this handled by the requirements validation? NO! we might want to combine
+        if attribute.options[:required] && !@contents.key?(key)
+          errors.concat ["Attribute #{Attributor.humanize_context(sub_context)} is required."]
+        end
+        if @contents[key].nil?
+          if !Attribute.nullable_attribute?(attribute.options) && @contents.key?(key)
+            errors.concat ["Attribute #{Attributor.humanize_context(sub_context)} is not nullable."]
+          end
+          # No need to validate the attribute further if the key wasn't passed...(or we would get nullable errors etc..cause the attribute has no
+          # context if its containing key was even passed (and there might not be a containing key for a top level attribute anyways))
+        else
+          errors.concat attribute.validate(value, sub_context)
+        end
       end
       self.class.requirements.each do |requirement|
-        validation_errors = requirement.validate(keys_with_values, context)
+        validation_errors = requirement.validate(keys_provided, context)
         errors.concat(validation_errors) unless validation_errors.empty?
       end
       errors
@@ -661,7 +669,7 @@ module Attributor
 
         unless value_type == Attributor::Object
           sub_context = context + ["value(#{value.inspect})"]
-          errors.concat value_attribute.validate(value, sub_context)
+        errors.concat value_attribute.validate(value, sub_context)
         end
       end
     end

data/lib/attributor/types/model.rb

@@ -129,27 +129,9 @@ module Attributor
       @validating = true
 
       context = [context] if context.is_a? ::String
-      keys_with_values = []
-      errors = []
-
-      self.class.attributes.each do |sub_attribute_name, sub_attribute|
-        sub_context = self.class.generate_subcontext(context, sub_attribute_name)
-
-        value = __send__(sub_attribute_name)
-        keys_with_values << sub_attribute_name unless value.nil?
-
-        if value.respond_to?(:validating) # really, it's a thing with sub-attributes
-          next if value.validating
-        end
-
-        errors.concat sub_attribute.validate(value, sub_context)
-      end
-      self.class.requirements.each do |req|
-        validation_errors = req.validate(keys_with_values, context)
-        errors.concat(validation_errors) unless validation_errors.empty?
-      end
-
-      errors
+      # Use the common, underlying attribute validation of the hash (which will use our _get_attr)
+      # to know how to retrieve a value from a model (instead of a hash)
+      validate_keys(context)
     ensure
       @validating = false
     end
@@ -198,4 +180,10 @@ module Attributor
       @dumping = false
     end
   end
+
+  # Override the generic way to get a value from an instance (models need to call the method)
+  def _get_attr(k)
+    __send__(k)
+  end    
+
 end

data/lib/attributor/version.rb

@@ -1,3 +1,3 @@
 module Attributor
-  VERSION = '5.5'.freeze
+  VERSION = '6.1'.freeze
 end

data/lib/attributor.rb

@@ -13,7 +13,6 @@ module Attributor
   require_relative 'attributor/type'
   require_relative 'attributor/dsl_compiler'
   require_relative 'attributor/hash_dsl_compiler'
-  require_relative 'attributor/attribute_resolver'
   require_relative 'attributor/smart_attribute_selector'
 
   require_relative 'attributor/example_mixin'
@@ -22,7 +21,8 @@ module Attributor
 
   # hierarchical separator string for composing human readable attributes
   SEPARATOR = '.'.freeze
-  DEFAULT_ROOT_CONTEXT = ['$'].freeze
+  ROOT_PREFIX = '$'.freeze
+  DEFAULT_ROOT_CONTEXT = [ROOT_PREFIX].freeze
 
   # @param type [Class] The class of the type to resolve
   #
@@ -56,10 +56,6 @@ module Attributor
 
     context = Array(context) if context.is_a? ::String
 
-    unless context.is_a? Enumerable
-      raise "INVALID CONTEXT!!! (got: #{context.inspect})"
-    end
-
     begin
       return context.join('.')
     rescue e