attributor 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 28036c8d33153157e7118cae29dd5d0736248cb2
-  data.tar.gz: ea81f5e962a1f8f63f34dad0e41e4bd1899aebb2
+  metadata.gz: 91fa7d928579dfcb275a39160a5a97b3e2ed3714
+  data.tar.gz: f2e689081dfe7e08ff69dd6d5d497fbf9fbadf64
 SHA512:
-  metadata.gz: dacc030e86045803473c59ad89fce1d3ae1e7dd12fab67d42dbcde02e23477861e4cd45b0fdd3fd0d9628daec92b57d812d55f3ed2b60d10f86a2372446ff8c3
-  data.tar.gz: 27c876734a439ff0df35a2970dbd57b90821b16ab9710d99391b2948be0052ffb91d18b2730d99fbbb827739ad742aaedffa2c66b5a388de12b90e9e84ec58b5
+  metadata.gz: cb003537a99b92977798f35b5b8655e6baaec686e9beb03bb7093413c6fcc99b2bfe00587532ebc8957c30ff9a8de04311bcb45b9be7fdfaa038b9206f6e2701
+  data.tar.gz: 6ae7ade75b1cf99da3a1c317e26e758f92657617f158c47d4778471bee2b5d2e14e623dd111539994404263e4dc2c9bc19b7490af21ad84adba926d114157391

data/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## next
 
+## 4.2.0
+
+* Added an "anonymous" DSL for base `Attributor::Type` which is reported in its `.describe` call.
+  * This is a simple documentation bit, that might help the clients to document the type properly (i.e. treat it as if the type was anonymously defined whenever is used, rather than reachable by id/name from anywhere)
+
+* Built advanced attribute requirements for `Struct`,`Model` and `Hash` types. Those requirements allow you to define things like:
+  * A list of attributes that are required (equivalent to defining the required: true bit at each of the attributes)
+  * At most (n) attributes from a group can be passed in
+  * At least (n) attributes from a group are required
+  * Exactly (n) attributes from a group are required
+  * Example:
+  ```
+  requires ‘id’, ‘name’
+  requires.all ‘id’, ‘name’  # Equivalent to above
+  requires.all.of ‘id’, ‘name’  # Equivalent to above again
+  requires.at_most(2).of 'consistency', 'availability', 'partitioning'
+  requires.at_least(1).of ‘rock’, ‘pop’
+  requires.exactly(2).of ‘one’, ‘two’, ’three’
+  ```
+  * Same example expressed inside a block if so desired
+  ```
+  requires do
+    all 'id', 'name
+    all.of 'id', 'name # Equivalent
+    at_most(2).of 'consistency', 'availability', 'partitioning'
+    …
+  end
+  ```
+
 ## 4.1.0
 
 * Added a `Class` type (useful to avoid demodulization coercions etc...)

data/lib/attributor.rb

@@ -11,6 +11,7 @@ module Attributor
   require_relative 'attributor/attribute'
   require_relative 'attributor/type'
   require_relative 'attributor/dsl_compiler'
+  require_relative 'attributor/hash_dsl_compiler'
   require_relative 'attributor/attribute_resolver'
 
   require_relative 'attributor/example_mixin'

data/lib/attributor/hash_dsl_compiler.rb

@@ -0,0 +1,141 @@
+require_relative 'dsl_compiler'
+
+
+module Attributor
+
+  class HashDSLCompiler < DSLCompiler
+
+    # A class that encapsulates the definition of a requirement for Hash attributes
+    # It implements the validation against incoming values and it describes its format for documentation purposes
+    class Requirement
+      attr_reader :type
+      attr_reader :number
+      attr_reader :attr_names
+      attr_reader :description
+
+      def initialize(description: nil, **spec)
+        @description = description
+        @type = spec.keys.first
+        case type
+        when :all
+          self.of(*spec[type])
+        when :exclusive
+          self.of(*spec[type])
+        else
+          @number = spec[type]
+        end
+      end
+      def of( *args)
+        @attr_names = args
+        self
+      end
+
+      def validate( object,context=Attributor::DEFAULT_ROOT_CONTEXT,_attribute)
+        result = []
+        case type
+        when :all
+          rest = attr_names - object.keys
+          unless rest.empty?
+            rest.each do |attr|
+              result.push "Key #{attr} is required for #{Attributor.humanize_context(context)}."
+            end
+          end
+        when :exactly
+          included = attr_names & object.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}"
+          end
+        when :at_most
+          rest = attr_names & object.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}"
+          end
+        when :at_least
+          rest = attr_names & object.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}"
+          end
+        when :exclusive
+          intersection = attr_names & object.keys
+          if intersection.size > 1
+            result.push "keys #{intersection.inspect} are mutually exclusive for #{Attributor.humanize_context(context)}."
+          end
+        end
+        result
+      end
+
+      def describe(shallow=false, example: nil)
+        hash = {type: type, attributes: attr_names}
+        hash[:count] = number unless number.nil?
+        hash[:description] = description unless description.nil?
+        hash
+      end
+    end
+
+
+    # A class that encapsulates the available DSL under the `requires` keyword.
+    # In particular it allows to define requirements like:
+    # requires.all :attr1, :attr2, :attr3
+    # requires.exclusive :attr1, :attr2, :attr3
+    # requires.at_most(2).of :attr1, :attr2, :attr3
+    # requires.at_least(2).of :attr1, :attr2, :attr3
+    # requires.exactly(2).of :attr1, :attr2, :attr3
+    # Note: all and exclusive can also use .of , it is equivalent
+    class RequiresDSL
+      attr_accessor :target
+      attr_accessor :options
+      def initialize(target, **opts)
+        self.target = target
+        self.options = opts
+      end
+      def all(*attr_names, **opts)
+        req = Requirement.new( options.merge(opts).merge(all: attr_names) )
+        target.add_requirement req
+        req
+      end
+      def at_most(number)
+        req = Requirement.new(  options.merge(at_most: number) )
+        target.add_requirement req
+        req
+      end
+      def at_least(number)
+        req = Requirement.new(  options.merge(at_least: number) )
+        target.add_requirement req
+        req
+      end
+      def exactly(number)
+        req = Requirement.new(  options.merge(exactly: number) )
+        target.add_requirement req
+        req
+      end
+      def exclusive(*attr_names, **opts)
+        req = Requirement.new(  options.merge(opts).merge(exclusive: attr_names) )
+        target.add_requirement req
+        req
+      end
+    end
+
+    def _requirements_dsl
+      @requirements_dsl ||= RequiresDSL.new(@target)
+    end
+
+    def requires(*spec,**opts,&block)
+      if spec.empty?
+        unless opts.empty?
+          self._requirements_dsl.options.merge(opts)
+        end
+        if block_given?
+          self._requirements_dsl.instance_eval(&block)
+        else
+          self._requirements_dsl
+        end
+      else
+        self._requirements_dsl.all(*spec,opts)
+      end
+    end
+
+
+  end
+end

data/lib/attributor/type.rb

@@ -15,6 +15,20 @@ module Attributor
         false
       end
 
+      # Allow a type to be marked as if it was anonymous (i.e. not referenceable by name)
+      def anonymous_type(val=true)
+        @_anonymous = val
+      end
+
+      def anonymous?
+        if @_anonymous == nil
+          self.name == nil # if nothing is set, consider it anonymous if the class does not have a name
+        else
+          @_anonymous
+        end
+      end
+
+
       # Generic decoding and coercion of the attribute.
       def load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
         return nil if value.nil?
@@ -104,6 +118,7 @@ module Attributor
           family: self.family,
           id: self.id
         }
+        hash[:anonymous] = @_anonymous unless @_anonymous.nil?
         hash[:example] = example if example
         hash
       end

data/lib/attributor/types/hash.rb

@@ -29,6 +29,7 @@ module Attributor
       attr_reader :key_attribute
       attr_reader :insensitive_map
       attr_accessor :extra_keys
+      attr_reader :requirements
     end
 
     @key_type = Object
@@ -38,7 +39,7 @@ module Attributor
     @value_attribute = Attribute.new(@value_type)
 
     @error = false
-
+    @requirements = []
 
     def self.key_type=(key_type)
       @key_type = Attributor.resolve_type(key_type)
@@ -72,6 +73,7 @@ module Attributor
         @value_type = v
         @key_attribute = Attribute.new(@key_type)
         @value_attribute = Attribute.new(@value_type)
+        @requirements = []
 
         @error = false
       end
@@ -116,7 +118,7 @@ module Attributor
     end
 
     def self.dsl_class
-      @options[:dsl_compiler] || DSLCompiler
+      @options[:dsl_compiler] || HashDSLCompiler
     end
 
     def self.native_type
@@ -140,6 +142,16 @@ module Attributor
       true
     end
 
+    def self.add_requirement(req)
+      @requirements << req
+      return unless req.attr_names
+      non_existing = req.attr_names - self.attributes.keys
+      unless non_existing.empty?
+        raise "Invalid attribute name(s) found (#{non_existing.join(', ')}) when defining a requirement of type #{req.type} for #{Attributor.type_name(self)} ." +
+        "The only existing attributes are #{self.attributes.keys}"
+      end
+
+    end
 
     def self.construct(constructor_block, **options)
       return self if constructor_block.nil?
@@ -427,11 +439,26 @@ module Attributor
       if self.keys.any?
         # Spit keys if it's the root or if it's an anonymous structures
         if ( !shallow || self.name == nil)
-          # FIXME: change to :keys when the praxis doc browser supports displaying those. or josep's demo is over.
+          required_names = []
+          # FIXME: change to :keys when the praxis doc browser supports displaying those
           hash[:attributes] = self.keys.each_with_object({}) do |(sub_name, sub_attribute), sub_attributes|
+            required_names << sub_name if sub_attribute.options[:required] == true
             sub_example = example.get(sub_name) if example
             sub_attributes[sub_name] = sub_attribute.describe(true, example: sub_example)
           end
+          hash[:requirements] = self.requirements.each_with_object([]) do |req, list|
+            described_req = req.describe(shallow)
+            if described_req[:type] == :all
+              # Add the names of the attributes that have the required flag too
+              described_req[:attributes] |= required_names
+              required_names = []
+            end
+            list << described_req
+          end
+          # Make sure we create an :all requirement, if there wasn't one so we can add the required: true attributes
+          unless required_names.empty?
+            hash[:requirements] << {type: :all, attributes: required_names }
+          end
         end
       else
         hash[:value] = {type: value_type.describe(true)}
@@ -538,7 +565,7 @@ module Attributor
           end
         end
 
-        self.class.keys.each_with_object(Array.new) do |(key, attribute), errors|
+        ret = self.class.keys.each_with_object(Array.new) do |(key, attribute), errors|
           sub_context = self.class.generate_subcontext(context,key)
 
           value = @contents[key]
@@ -550,7 +577,7 @@ module Attributor
           errors.push *attribute.validate(value, sub_context)
         end
       else
-        @contents.each_with_object(Array.new) do |(key, value), errors|
+        ret = @contents.each_with_object(Array.new) do |(key, value), errors|
           # FIXME: the sub contexts and error messages don't really make sense here
           unless key_type == Attributor::Object
             sub_context = context + ["key(#{key.inspect})"]
@@ -563,6 +590,13 @@ module Attributor
           end
         end
       end
+      unless self.class.requirements.empty?
+        self.class.requirements.each_with_object(ret) do |req, errors|
+          validation_errors = req.validate( @contents , context)
+          errors.push *validation_errors unless validation_errors.empty?
+        end
+      end
+      ret
     end
 
 

data/lib/attributor/types/model.rb

@@ -43,6 +43,7 @@ module Attributor
         @key_attribute = ka
         @value_attribute = va
 
+        @requirements = []
         @error = false
       end
     end

data/lib/attributor/version.rb

@@ -1,3 +1,3 @@
 module Attributor
-  VERSION = "4.1.0"
+  VERSION = "4.2.0"
 end

data/spec/hash_dsl_compiler_spec.rb

@@ -0,0 +1,177 @@
+require File.join(File.dirname(__FILE__), 'spec_helper.rb')
+
+
+describe Attributor::HashDSLCompiler do
+
+  let(:target) { double("model", attributes: {}) }
+
+  let(:dsl_compiler_options) { {} }
+  subject(:dsl_compiler) { Attributor::HashDSLCompiler.new(target, dsl_compiler_options) }
+
+  it 'returns the requirements DSL attached to the right target' do
+    req_dsl = dsl_compiler._requirements_dsl
+    req_dsl.should be_kind_of( Attributor::HashDSLCompiler::RequiresDSL )
+    req_dsl.target.should be(target)
+  end
+
+  context 'requires' do
+
+    context 'without any arguments' do
+      it 'without params returns the underlying compiler to chain internal methods' do
+        subject.requires.should be_kind_of( Attributor::HashDSLCompiler::RequiresDSL )
+      end
+    end
+
+    context 'with params only (and some options)' do
+      it 'takes then array to mean all attributes are required' do
+        target.should_receive(:add_requirement)
+        requirement = subject.requires :one, :two , description: "These are very required"
+        requirement.should be_kind_of( Attributor::HashDSLCompiler::Requirement )
+        requirement.type.should be(:all)
+      end
+    end
+    context 'with a block only (and some options)' do
+      it 'evals it in the context of the Compiler' do
+        proc = Proc.new {}
+        dsl = dsl_compiler._requirements_dsl
+        dsl.should_receive(:instance_eval)#.with(&proc) << Does rspec 2.99 support block args?
+        subject.requires description: "These are very required", &proc
+      end
+    end
+
+
+  end
+
+  context 'RequiresDSL' do
+
+    subject(:dsl){ Attributor::HashDSLCompiler::RequiresDSL.new(target) }
+    it 'stores the received target' do
+      subject.target.should be(target)
+    end
+
+    context 'has DSL methods' do
+      let(:req){ double("requirement") }
+      let(:attr_names){ [:one, :two, :tree] }
+      let(:number){ 2 }
+      let(:req_class){ Attributor::HashDSLCompiler::Requirement }
+      before do
+        target.should_receive(:add_requirement).with(req)
+      end
+      it 'responds to .all' do
+        req_class.should_receive(:new).with( all: attr_names ).and_return(req)
+        subject.all(*attr_names)
+      end
+      it 'responds to .at_most(n)' do
+        req_class.should_receive(:new).with( at_most: number ).and_return(req)
+        subject.at_most(number)
+      end
+      it 'responds to .at_least(n)' do
+        req_class.should_receive(:new).with( at_least: number ).and_return(req)
+        subject.at_least(number)
+      end
+      it 'responds to .exactly(n)' do
+        req_class.should_receive(:new).with( exactly: number ).and_return(req)
+        subject.exactly(number)
+      end
+      it 'responds to .exclusive' do
+        req_class.should_receive(:new).with( exclusive: attr_names ).and_return(req)
+        subject.exclusive(*attr_names)
+      end
+
+    end
+  end
+
+  context 'Requirement' do
+
+    let(:attr_names){ [:one, :two, :tree] }
+    let(:req_class){ Attributor::HashDSLCompiler::Requirement }
+
+    context 'initialization' do
+      it 'calls .of for exclusive' do
+        req_class.any_instance.should_receive(:of).with(*attr_names)
+        req_class.new(exclusive: attr_names)
+      end
+      it 'calls .of for all' do
+        req_class.any_instance.should_receive(:of).with(*attr_names)
+        req_class.new(all: attr_names)
+      end
+      it 'saves the number for the rest' do
+        req_class.new(exactly:  1).number.should be(1)
+        req_class.new(exactly:  1).type.should be(:exactly)
+        req_class.new(at_most:  2).number.should be(2)
+        req_class.new(at_most:  2).type.should be(:at_most)
+        req_class.new(at_least: 3).number.should be(3)
+        req_class.new(at_least: 3).type.should be(:at_least)
+      end
+      it 'understands and saves a :description' do
+        req = req_class.new(exactly:  1, description: "Hello")
+        req.number.should be(1)
+        req.description.should eq("Hello")
+      end
+    end
+
+    context 'Requirement#validate' do
+      let(:requirement){ req_class.new(arguments) }
+      let(:subject){ requirement.validate(value,["$"],nil)}
+
+      context 'for :all' do
+        let(:arguments){ { all: [:one, :two, :three] } }
+        let(:value){ {one: 1}}
+        let(:validation_error){ ["Key two is required for $.", "Key three is required for $."] }
+        it { subject.should include(*validation_error) }
+      end
+      context 'for :exactly' do
+        let(:requirement) { req_class.new(exactly: 1).of(:one,:two) }
+        let(:value){ {one: 1, two: 2}}
+        let(:validation_error){ "Exactly 1 of the following keys [:one, :two] are required for $. Found 2 instead: [:one, :two]" }
+        it { subject.should include(validation_error) }
+      end
+      context 'for :at_least' do
+        let(:requirement) { req_class.new(at_least: 2).of(:one,:two,:three) }
+        let(:value){ {one: 1}}
+        let(:validation_error){ "At least 2 keys out of [:one, :two, :three] are required to be passed in for $. Found [:one]" }
+        it { subject.should include(validation_error) }
+      end
+      context 'for :at_most' do
+        let(:requirement) { req_class.new(at_most: 1).of(:one,:two,:three) }
+        let(:value){ {one: 1, two: 2}}
+        let(:validation_error){ "At most 1 keys out of [:one, :two, :three] can be passed in for $. Found [:one, :two]" }
+        it { subject.should include(validation_error) }
+      end
+      context 'for :exclusive' do
+        let(:arguments){ { exclusive: [:one, :two] } }
+        let(:value){ {one: 1, two: 2}}
+        let(:validation_error){ "keys [:one, :two] are mutually exclusive for $." }
+        it { subject.should include(validation_error) }
+      end
+    end
+
+    context 'Requirement#describe' do
+
+      it 'should work for :all' do
+        req = req_class.new(all: attr_names).describe
+        req.should eq( type: :all, attributes: [:one, :two, :tree] )
+      end
+      it 'should work for :exclusive n' do
+        req = req_class.new(exclusive: attr_names).describe
+        req.should eq( type: :exclusive, attributes: [:one, :two, :tree] )
+      end
+      it 'should work for :exactly' do
+        req = req_class.new(exactly: 1).of(*attr_names).describe
+        req.should include( type: :exactly,  count: 1, attributes: [:one, :two, :tree] )
+      end
+      it 'should work for :at_most n' do
+        req = req_class.new(at_most: 1).of(*attr_names).describe
+        req.should include( type: :at_most,  count: 1, attributes: [:one, :two, :tree] )
+      end
+      it 'should work for :at_least n' do
+        req = req_class.new(at_least: 1).of(*attr_names).describe
+        req.should include( type: :at_least,  count: 1, attributes: [:one, :two, :tree] )
+      end
+      it 'should report a description' do
+        req = req_class.new(at_least: 1, description: "no more than 1").of(*attr_names).describe
+        req.should include( type: :at_least,  count: 1, attributes: [:one, :two, :tree], description: "no more than 1" )
+      end
+    end
+  end
+end

data/spec/type_spec.rb

@@ -33,6 +33,22 @@ describe Attributor::Type do
   its(:native_type) { should be(::String) }
   its(:id) { should eq('Testing')}
 
+  context 'anonymous' do
+    its(:anonymous?) { should be(false) }
+    it 'is true for nameless-types' do
+      klass = Class.new do
+        include Attributor::Type
+      end
+      expect( klass.anonymous? ).to be(true)
+    end
+    it 'can be set to true explicitly' do
+      klass = Class.new(test_type) do
+        anonymous_type
+      end
+      expect( klass.anonymous? ).to be(true)
+    end
+  end
+
   context 'load' do
     let(:value) { nil }
     let(:context) { nil }
@@ -166,6 +182,20 @@ describe Attributor::Type do
       end
     end
 
+    context 'when anonymous' do
+
+      it 'reports true in the output when set (to true default)' do
+        anon_type = Class.new(test_type) { anonymous_type }
+        anon_type.describe.should have_key(:anonymous)
+        anon_type.describe[:anonymous].should be(true)
+      end
+      it 'reports false in the output when set false explicitly' do
+        anon_type = Class.new(test_type) { anonymous_type false }
+        anon_type.describe.should have_key(:anonymous)
+        anon_type.describe[:anonymous].should be(false)
+      end
+
+    end
   end
 
 end

data/spec/types/hash_spec.rb

@@ -8,8 +8,9 @@ describe Attributor::Hash do
   its(:native_type) { should be(type) }
   its(:key_type) { should be(Attributor::Object) }
   its(:value_type) { should be(Attributor::Object) }
+  its(:dsl_class) { should be(Attributor::HashDSLCompiler) }
 
-context 'attributes' do
+  context 'attributes' do
     context 'with an exception from the definition block' do
       subject(:broken_model) do
         Class.new(Attributor::Model) do
@@ -413,6 +414,26 @@ context 'attributes' do
 
   end
 
+  context '.add_requirement' do
+    let(:req_type){ :all }
+    let(:req){ double("requirement", type: req_type, attr_names: req_attributes)}
+    context 'with valid attributes' do
+      let(:req_attributes){ [:name] }
+      it 'successfully saves it in the class' do
+        HashWithStrings.add_requirement(req)
+        HashWithStrings.requirements.should include(req)
+      end
+    end
+    context 'with attributes not defined in the class' do
+      let(:req_attributes){ [:name, :invalid, :notgood] }
+      it 'it complains loudly' do
+        expect{
+          HashWithStrings.add_requirement(req)
+        }.to raise_error("Invalid attribute name(s) found (invalid, notgood) when defining a requirement of type all for HashWithStrings .The only existing attributes are [:name, :something]")
+      end
+    end
+  end
+
   context '.dump' do
 
     let(:value) { {one: 1, two: 2} }
@@ -505,6 +526,137 @@ context 'attributes' do
 
     end
 
+
+    context 'with requirements defined' do
+      let(:type) { Attributor::Hash.construct(block) }
+
+      context 'using requires' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires 'consistency', 'availability'
+            requires.all 'name' # Just to show that it is equivalent to 'requires'
+          end
+        end
+
+        it 'complains not all the listed elements are set (false or true)' do
+          errors = type.new('name' => 'CAP').validate
+          errors.should have(2).items
+          ['consistency','availability'].each do |name|
+            errors.should include("Key #{name} is required for $.")
+          end
+        end
+      end
+
+      context 'using at_least(n)' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires.at_least(2).of 'consistency', 'availability', 'partitioning'
+          end
+        end
+
+        it 'complains if less than 2 in the group are set (false or true)' do
+          errors = type.new('name' => 'CAP', 'consistency' => false).validate
+          errors.should have(1).items
+          errors.should include(
+            "At least 2 keys out of [\"consistency\", \"availability\", \"partitioning\"] are required to be passed in for $. Found [\"consistency\"]"
+          )
+        end
+      end
+
+      context 'using at_most(n)' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires.at_most(2).of 'consistency', 'availability', 'partitioning'
+          end
+        end
+
+        it 'complains if more than 2 in the group are set (false or true)' do
+          errors = type.new('name' => 'CAP', 'consistency' => false, 'availability' => true, 'partitioning' => false).validate
+          errors.should have(1).items
+          errors.should include("At most 2 keys out of [\"consistency\", \"availability\", \"partitioning\"] can be passed in for $. Found [\"consistency\", \"availability\", \"partitioning\"]")
+        end
+      end
+
+      context 'using exactly(n)' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires.exactly(1).of 'consistency', 'availability', 'partitioning'
+          end
+        end
+
+        it 'complains if less than 1 in the group are set (false or true)' do
+          errors = type.new('name' => 'CAP').validate
+          errors.should have(1).items
+          errors.should include("Exactly 1 of the following keys [\"consistency\", \"availability\", \"partitioning\"] are required for $. Found 0 instead: []")
+        end
+        it 'complains if more than 1 in the group are set (false or true)' do
+          errors = type.new('name' => 'CAP', 'consistency' => false, 'availability' => true).validate
+          errors.should have(1).items
+          errors.should include("Exactly 1 of the following keys [\"consistency\", \"availability\", \"partitioning\"] are required for $. Found 2 instead: [\"consistency\", \"availability\"]")
+        end
+      end
+
+      context 'using exclusive' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires.exclusive 'consistency', 'availability', 'partitioning'
+          end
+        end
+
+        it 'complains if two or more in the group are set (false or true)' do
+          errors = type.new('name' => 'CAP', 'consistency' => false, 'availability' => true).validate
+          errors.should have(1).items
+          errors.should include("keys [\"consistency\", \"availability\"] are mutually exclusive for $.")
+        end
+      end
+
+      context 'through a block' do
+        let(:block) do
+          proc do
+            key 'name', String
+            key 'consistency', Attributor::Boolean
+            key 'availability', Attributor::Boolean
+            key 'partitioning', Attributor::Boolean
+            requires do
+              all 'name'
+              all.of 'name' # Equivalent to .all
+              at_least(1).of 'consistency', 'availability', 'partitioning'
+            end
+            # Silly example, just to show that block and inline requires can be combined
+            requires.at_most(3).of 'consistency', 'availability', 'partitioning'
+          end
+        end
+
+        it 'complains not all the listed elements are set (false or true)' do
+          errors = type.new('name' => 'CAP').validate
+          errors.should have(1).items
+          errors.should include(
+            "At least 1 keys out of [\"consistency\", \"availability\", \"partitioning\"] are required to be passed in for $. Found none"
+          )
+        end
+      end
+    end
+
   end
 
   context 'in an Attribute' do
@@ -539,6 +691,13 @@ context 'attributes' do
           key '1', Integer, min: 1, max: 20
           key 'some_date', DateTime
           key 'defaulted', String, default: 'default value'
+          requires do
+            all.of '1','some_date'
+            exclusive 'some_date', 'defaulted'
+            at_least(1).of 'a string', 'some_date'
+            at_most(2).of 'a string', 'some_date'
+            exactly(1).of 'a string', 'some_date'
+          end
         end
       end
 
@@ -548,7 +707,9 @@ context 'attributes' do
         description[:name].should eq('Hash')
         description[:key].should eq(type:{name: 'String', id: 'Attributor-String', family: 'string'})
         description.should_not have_key(:value)
+      end
 
+      it 'describes the type attributes correctly' do
         attrs = description[:attributes]
 
         attrs['a string'].should eq(type: {name: 'String', id: 'Attributor-String', family: 'string'} )
@@ -557,6 +718,49 @@ context 'attributes' do
         attrs['defaulted'].should eq(type: {name: 'String', id: 'Attributor-String', family: 'string'}, default: 'default value')
       end
 
+      it 'describes the type requirements correctly' do
+
+        reqs = description[:requirements]
+        reqs.should be_kind_of(Array)
+        reqs.size.should be(5)
+        reqs.should include( type: :all, attributes: ['1','some_date'] )
+        reqs.should include( type: :exclusive, attributes: ['some_date','defaulted'] )
+        reqs.should include( type: :at_least, attributes: ['a string','some_date'], count: 1 )
+        reqs.should include( type: :at_most, attributes: ['a string','some_date'], count: 2 )
+        reqs.should include( type: :exactly, attributes: ['a string','some_date'], count: 1 )
+      end
+
+      context 'merging requires.all with attribute required: true' do
+        let(:block) do
+          proc do
+            key 'required string', String, required: true
+            key '1', Integer
+            key 'some_date', DateTime
+            requires do
+              all.of 'some_date'
+            end
+          end
+        end
+        it 'includes attributes with required: true into the :all requirements' do
+          req_all = description[:requirements].select{|r| r[:type] == :all}.first
+          req_all[:attributes].should include( 'required string','some_date' )
+        end
+      end
+
+      context 'creates the :all requirement when any attribute has required: true' do
+        let(:block) do
+          proc do
+            key 'required string', String, required: true
+            key 'required integer', Integer, required: true
+          end
+        end
+        it 'includes attributes with required: true into the :all requirements' do
+          req_all = description[:requirements].select{|r| r[:type] == :all}.first
+          req_all.should_not be(nil)
+          req_all[:attributes].should include( 'required string','required integer' )
+        end
+      end
+
       context 'with an example' do
         let(:example){ type.example }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attributor
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - Josep M. Blanquer
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-19 00:00:00.000000000 Z
+date: 2015-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -293,6 +293,7 @@ files:
 - lib/attributor/extras/field_selector/transformer.rb
 - lib/attributor/families/numeric.rb
 - lib/attributor/families/temporal.rb
+- lib/attributor/hash_dsl_compiler.rb
 - lib/attributor/type.rb
 - lib/attributor/types/bigdecimal.rb
 - lib/attributor/types/boolean.rb
@@ -323,6 +324,7 @@ files:
 - spec/dsl_compiler_spec.rb
 - spec/extras/field_selector/field_selector_spec.rb
 - spec/families_spec.rb
+- spec/hash_dsl_compiler_spec.rb
 - spec/spec_helper.rb
 - spec/support/hashes.rb
 - spec/support/models.rb
@@ -378,6 +380,7 @@ test_files:
 - spec/dsl_compiler_spec.rb
 - spec/extras/field_selector/field_selector_spec.rb
 - spec/families_spec.rb
+- spec/hash_dsl_compiler_spec.rb
 - spec/spec_helper.rb
 - spec/support/hashes.rb
 - spec/support/models.rb