attributor 5.4 → 6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb9d8a77a4e71c5f44cc2eaa6559c7d40882c88ec675b0400170d961386d66c1
-  data.tar.gz: 0b4d4bec370cbca4fa15d61dd08b0bc9b2cdcb8f1f0d39d21287e7471f60075e
+  metadata.gz: 108abdb1d351f95b78cfae24b61bf8e5bf3943626d8badb691e28ce0df23c45d
+  data.tar.gz: 96f4e678e7bccb85526a7a3788aa2df538902200fcb50b49e0de3a36c5d3778d
 SHA512:
-  metadata.gz: 78a4367ada6bebcb2a164da33b08e05bd0c20207d11df7631b700346bb3e4ec74df47bef3373178cbd619a2f0252609c59586a1fb46c0913830a57b547361b67
-  data.tar.gz: e2a0fa2ecb088ff61c184624fcadfcc992d1fd60c5694727e8ffd594be1188ee6d60e2b14d7cc1daab4a9e8fbd67b584612d3be6e7574fbda4cfca004a182e00
+  metadata.gz: 54217688f13fad04f249aa351062afd490dd3962278f7dbdcc5d31e05bd5df3151fc51a704208a1502d8d9cf67a2382ca10b85f331c577610223a39c7b96caa9
+  data.tar.gz: 8eb61d8a53f01d2529d1d2f15c77cd9b55a6a0f53f9a9f83db61ee87ae6091761c330ca026759146e05b73b43625fa5f51236e50a98cbee5aa55afe94b6f1c25

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## next
 
+## 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)
+
+- JSON-schema support. Enhanced all of the types to suppport describing themselves as JSON-schema format (`.as_json_schema`). This description includes a few `x-*` extensions to capture some information that Attributor supports, that JSON-schema does not.
+
 ## 5.3 (24/04/2020)
 
 - Fixed deprecation warnings in Ruby 2.7

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,23 +94,21 @@ 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
-
-    def describe(shallow = true, example: nil)
-      description = {}
+    def describe(shallow=true, example: nil)
+      description = { }
       # Clone the common options
       TOP_LEVEL_OPTIONS.each do |option_name|
-        description[option_name] = options[option_name] if options.key? option_name
+        description[option_name] = self.describe_option(option_name) if self.options.has_key? option_name
       end
 
       # Make sure this option definition is not mistaken for the real generated example
@@ -109,7 +119,7 @@ module Attributor
       special_options = options.keys - TOP_LEVEL_OPTIONS - INTERNAL_OPTIONS
       description[:options] = {} unless special_options.empty?
       special_options.each do |opt_name|
-        description[:options][opt_name] = options[opt_name]
+        description[:options][opt_name] = self.describe_option(opt_name)
       end
       # Change the reference option to the actual class name.
       if (reference = options[:reference])
@@ -146,8 +156,45 @@ module Attributor
       load(generated, context)
     end
 
-    def example(context = nil, parent: nil, values: {})
-      raise ArgumentError, 'attribute example cannot take a context of type String' if context.is_a? ::String
+    def describe_option( option_name )
+      self.type.describe_option( option_name, self.options[option_name] )
+    end
+
+    # FiXME: pass and utilize the "shallow" parameter
+    #required
+    #options
+    #type
+    #example
+    # UTILIZE THIS SITE! http://jsonschema.net/#/
+    def as_json_schema(shallow: true, example: nil)
+      description = self.type.as_json_schema(shallow: shallow, example: example, attribute_options: self.options )
+
+      description[:description] = self.options[:description] if self.options[:description]
+      description[:enum] = self.options[:values] if self.options[:values]
+      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.
+      if ( reference = self.options[:reference] )
+        description[:'x-reference'] = reference.name
+      end
+
+      # 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
+
+    def example(context=nil, parent: nil, values:{})
+      raise ArgumentError, "attribute example cannot take a context of type String" if (context.is_a? ::String )
       if context
         ctx = Attributor.humanize_context(context)
         seed, = Digest::SHA1.digest(ctx).unpack('QQ')
@@ -177,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
+        errors.push *validate_type(object, context)
 
-      # chop off the last part
-      requirement_context = context[0..-2]
-      requirement_context_string = requirement_context.join(Attributor::SEPARATOR)
-
-      # 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!
@@ -264,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
@@ -275,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)"
@@ -290,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/extras/field_selector.rb

@@ -12,6 +12,10 @@ module Attributor
 
     include Attributor::Type
 
+    def self.json_schema_type
+      :string
+    end
+
     def self.native_type
       ::Hash
     end

data/lib/attributor/families/numeric.rb

@@ -1,15 +1,28 @@
 # Abstract type for the 'numeric' family
 
 module Attributor
-  class Numeric
+  module Numeric
+    extend ActiveSupport::Concern
     include Type
 
-    def self.native_type
-      raise NotImplementedError
-    end
+    module ClassMethods
+      
+      def native_type
+        raise NotImplementedError
+      end
+
+      def family
+        'numeric'
+      end
 
-    def self.family
-      'numeric'
+      def as_json_schema( shallow: false, example: nil, attribute_options: {} )
+        h = super
+        opts = ( self.respond_to?(:options) ) ? self.options.merge( attribute_options ) : attribute_options
+        h[:minimum] = opts[:min] if opts[:min]
+        h[:maximum] = opts[:max] if opts[:max]
+        # We're not explicitly setting false to exclusiveMinimum and exclusiveMaximum (as that's the default)
+        h
+      end
     end
   end
 end

data/lib/attributor/families/temporal.rb

@@ -1,19 +1,26 @@
 # Abstract type for the 'temporal' family
 
 module Attributor
-  class Temporal
+  module Temporal
+    extend ActiveSupport::Concern
     include Type
 
-    def self.native_type
-      raise NotImplementedError
-    end
+    module ClassMethods
+      def native_type
+        raise NotImplementedError
+      end
 
-    def self.family
-      'temporal'
-    end
+      def family
+        'temporal'
+      end
+
+      def dump(value, **_opts)
+        value && value.iso8601
+      end
 
-    def self.dump(value, **_opts)
-      value && value.iso8601
+      def json_schema_type
+        :string
+      end
     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

@@ -2,9 +2,7 @@ module Attributor
   # 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?
   module Type
-    def self.included(klass)
-      klass.extend(ClassMethods)
-    end
+    extend ActiveSupport::Concern
 
     module ClassMethods
       # Does this type support the generation of subtypes?
@@ -124,6 +122,31 @@ module Attributor
       def family
         'any'
       end
+
+      # Default no format in case it's a string type
+      def json_schema_string_format
+        nil
+      end
+  
+      def as_json_schema( shallow: false, example: nil, attribute_options: {} )
+        type_name = self.ancestors.find { |k| k.name && !k.name.empty? }.name
+        hash = { type: json_schema_type, 'x-type_name': type_name.gsub( Attributor::MODULE_PREFIX_REGEX, '' )}
+        # Add a format, if the type has defined
+        if hash[:type] == :string && the_format = json_schema_string_format
+          hash[:format] = the_format
+        end
+        hash
+      end
+
+      def describe_option( option_name, option_value )
+        return case option_name
+        when :description
+          option_value
+        else
+          option_value  # By default, describing an option returns the hash with the specification
+        end
+      end
+
     end
   end
 end

data/lib/attributor/types/bigdecimal.rb

@@ -1,7 +1,8 @@
 require 'bigdecimal'
 
 module Attributor
-  class BigDecimal < Numeric
+  class BigDecimal 
+    include Numeric
     def self.native_type
       ::BigDecimal
     end
@@ -16,5 +17,9 @@ module Attributor
       return BigDecimal(value, 10) if value.is_a?(::Float)
       BigDecimal(value)
     end
+
+    def self.json_schema_type
+      :number
+    end
   end
 end

data/lib/attributor/types/boolean.rb

@@ -26,5 +26,10 @@ module Attributor
     def self.family
       'boolean'
     end
+
+    def self.json_schema_type
+      :boolean
+    end
+
   end
 end

data/lib/attributor/types/collection.rb

@@ -117,6 +117,25 @@ module Attributor
       hash
     end
 
+    def self.json_schema_type
+      :array
+    end
+
+    def self.as_json_schema( shallow: false, example: nil, attribute_options: {} )
+      hash = super
+      opts = self.options.merge( attribute_options )
+      hash[:description] = opts[:description] if opts[:description]
+      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
+      hash[:items] = member_attribute.as_json_schema(example: member_example)
+      hash
+    end
+
     def self.constructable?
       true
     end

data/lib/attributor/types/csv.rb

@@ -37,5 +37,9 @@ module Attributor
     def self.family
       Collection.family
     end
+
+    def self.json_schema_type
+      :string
+    end
   end
 end

data/lib/attributor/types/date.rb

@@ -1,7 +1,9 @@
 require 'date'
 
 module Attributor
-  class Date < Temporal
+  class Date
+    include Temporal
+
     def self.native_type
       ::Date
     end
@@ -27,5 +29,9 @@ module Attributor
         raise CoercionError.new(context: context, from: value.class, to: self, value: value)
       end
     end
+
+    def self.json_schema_string_format
+      :date
+    end
   end
 end

data/lib/attributor/types/date_time.rb

@@ -5,7 +5,9 @@ require_relative '../exceptions'
 require 'date'
 
 module Attributor
-  class DateTime < Temporal
+  class DateTime
+    include Temporal
+
     def self.native_type
       ::DateTime
     end
@@ -27,5 +29,9 @@ module Attributor
         raise Attributor::DeserializationError.new(context: context, from: value.class, encoding: 'DateTime', value: value)
       end
     end
+
+    def self.json_schema_string_format
+      :'date-time'
+    end
   end
 end

data/lib/attributor/types/float.rb

@@ -2,8 +2,9 @@
 # See: http://ruby-doc.org/core-2.1.0/Float.html
 
 module Attributor
+
   class Float
-    include Type
+    include Numeric
 
     def self.native_type
       ::Float
@@ -22,8 +23,8 @@ module Attributor
       super
     end
 
-    def self.family
-      'numeric'
+    def self.json_schema_type
+      :number
     end
   end
 end