attributor 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 102708c30b51b0ddb7a38488ca440ada38c2f3a8
-  data.tar.gz: 4e50cb2a981f4b1d6173e754789a25932153d7bd
+  metadata.gz: 93e65f034891a43eb2164a43a0bd5bdf7d2a0e22
+  data.tar.gz: dc626f0b5d2cb575f490a1e1d8af6c60d232830f
 SHA512:
-  metadata.gz: 47095d5c279287a05b302867f1e9d5518d511405d1a475e1ebd272f584c3f71284bb8d59eaab9da7ad79043a0d1179ff29514052de69a0ac48fecc9315ad35a4
-  data.tar.gz: 495d613202a0b19dd186cd302e5fdffdaeea8e40c059e4c7ba6b7b81a175e10bd06fbf6a8b1349c9fe12c88c93c8da5beca53cf8a7e25151eb9eecd4da5a3b17
+  metadata.gz: 514f798b6bcb84313fa6c840dcb0a4bf9533cb3ec7f29a1c9a8ca00db45d119e7122a2bea02289fe094a6ab8db41ff13af0bfb47fafe9568186243f44d25b3f6
+  data.tar.gz: 848e54a8cdf56ab1a498ea75fbddc3571c7723a1285cc8b8c1085a2fa55e6b0a75494968c83f8154bab58f04531a684ea05114970e83c45b53a7c10e6e6a2883

data/.gitignore

@@ -13,3 +13,5 @@ doc
 
 # For MacOS:
 .DS_Store
+
+Gemfile.lock

data/CHANGELOG.md

@@ -4,7 +4,18 @@ Attributor Changelog
 next
 ------
 
-* First new feature here
+* next thing here
+
+2.2.0
+------
+
+* Fix example generation for Hash and Collection to handle a non-Array context parameter.
+* Hash:
+  * Added additional options:
+    * `:case_insensitive_load` for string-keyed hashes. This allows loading hashes with keys that do not exactly match the case defined in the hash.
+    * Added `:allow_extras` option to allow handling of undefined keys when loading.
+  * Added `Hash#set` to encapsulate the above options and attribute loading.
+  * Added `extra` command in the `keys` DSL, which lets you define a key (whose value should be a Hash), to group any unspecified keys during load. 
 
 2.1.0
 ------
@@ -23,7 +34,7 @@ next
   * Enhanced error messages to report the correct context scope.
   * Make Attribute assignments in models to report a special context (not the attributor root) 
     * Instead of reporting "$." as the context , when doing model.field_name=value, they'll now report "assignment.of(field_name)" instead
-  * Truncate the lenght of values when reporting loading errors when they're long (i.e. >500 chars)
+  * Truncate the length of values when reporting loading errors when they're long (i.e. >500 chars)
 * `Model.attributes` may now be called more than once to set add or replace attributes. The exact behavior depends upon the types of the attributes being added or replaced. See [model_spec.rb](spec/types/model_spec.rb) for examples.
 * Greately enhanced Hash type with individual key specification (rather than
   simply defining the types of keys)

data/README.md

@@ -1,4 +1,7 @@
-# Attributor
+# Attributor [![TravisCI][travis-img-url]][travis-ci-url] 
+
+[travis-img-url]: https://travis-ci.org/rightscale/attributor.svg?branch=master
+[travis-ci-url]:https://travis-ci.org/rightscale/attributor
 
 An Attribute management, self documenting framework, designed for getting rid of most of your parameter handling boilerplate.
 While initially designed to be the backbone for parameter handling in REST services, attribute management can be applied in many other areas.

data/Rakefile

@@ -1,20 +1,12 @@
 # encoding: utf-8
-
-
 require 'bundler/setup'
-#begin
-#  Bundler.setup(:default, :development)
-#rescue Bundler::BundlerError => e
-#  $stderr.puts e.message
-#  $stderr.puts "Run `bundle install` to install missing gems"
-#  exit e.status_code
-#end
 require 'rake'
 
-require 'rake/notes/rake_task'
-
 require 'rspec/core'
 require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+require 'rake/notes/rake_task'
+
 
 desc "Run RSpec code examples with simplecov"
 RSpec::Core::RakeTask.new do |spec|

data/lib/attributor/attribute.rb

@@ -70,7 +70,7 @@ module Attributor
 
 
     TOP_LEVEL_OPTIONS = [ :description, :values, :default, :example, :required, :required_if ]
-    INTERNAL_OPTIONS = [:dsl_compiler] # Options we don't want to expose when describing attributes
+    INTERNAL_OPTIONS = [:dsl_compiler,:dsl_compiler_options] # Options we don't want to expose when describing attributes
     def describe(shallow=true)
       description = { } 
       # Clone the common options

data/lib/attributor/dsl_compiler.rb

@@ -45,6 +45,17 @@ module Attributor
       target.keys[name] = define(name, attr_type, **opts, &block)
     end
 
+    def extra(name, attr_type=nil, **opts, &block)
+      if attr_type.nil?
+        attr_type = Attributor::Hash.of(key: target.key_type, value: target.value_type)
+      end
+      target.extra_keys = name
+      target.options[:allow_extra] = true
+      opts[:default] ||= {}
+      attr_type.options[:allow_extra] = true
+      key(name, attr_type, **opts, &block)
+    end
+
     # Creates an Attributor:Attribute with given definition.
     #
     # @overload define(name, type, opts, &block)

data/lib/attributor/type.rb

@@ -1,10 +1,3 @@
-# Will need eventually, but not right now:
-#   Hash
-#   Array
-#     CSV
-#     Ids
-
-
 module Attributor
 
   # It is the abstract base class to hold an attribute, both a leaf and a container (hash/Array...)

data/lib/attributor/types/collection.rb

@@ -43,7 +43,8 @@ module Attributor
       result = []
       size = rand(3) + 1
       context ||= ["Collection-#{result.object_id}"]
-
+      context = Array(context)
+      
       size.times do |i|
         subcontext = context + ["at(#{i})"]
         result << self.member_attribute.example(subcontext)
@@ -84,7 +85,7 @@ module Attributor
       #puts "Collection: #{self.type}"      
       hash = super(shallow)
       hash[:options] = {} unless hash[:options]
-      hash[:options][:member_attribute] = self.member_attribute.describe
+      hash[:member_attribute] = self.member_attribute.describe
       hash
     end
 

data/lib/attributor/types/hash.rb

@@ -9,27 +9,50 @@ module Attributor
       attr_reader :key_type, :value_type, :options
       attr_reader :value_attribute
       attr_reader :key_attribute
+      attr_reader :insensitive_map
+      attr_accessor :extra_keys
     end
 
     @key_type = Object
     @value_type = Object
-    
 
     @key_attribute = Attribute.new(@key_type)
     @value_attribute = Attribute.new(@value_type)
 
+    def self.key_type=(key_type)
+      resolved_key_type = Attributor.resolve_type(key_type)
+      unless resolved_key_type.ancestors.include?(Attributor::Type)
+        raise Attributor::AttributorException.new("Hashes only support key types that are Attributor::Types. Got #{resolved_key_type.name}")
+      end
+
+      @key_type = resolved_key_type
+      @key_attribute = Attribute.new(@key_type)
+      @concrete=true
+    end
+
+    def self.value_type=(value_type)
+      resolved_value_type = Attributor.resolve_type(value_type)
+      unless resolved_value_type.ancestors.include?(Attributor::Type)
+        raise Attributor::AttributorException.new("Hashes only support value types that are Attributor::Types. Got #{resolved_value_type.name}")
+      end
+
+      @value_type = resolved_value_type
+      @value_attribute = Attribute.new(@value_type)
+      @concrete=true
+    end
+
+
     @saved_blocks = []
-    @options = {}
+    @options = {allow_extra: false}
     @keys = {}
 
-
     def self.inherited(klass)
       k = self.key_type
       v = self.value_type
 
       klass.instance_eval do
         @saved_blocks = []
-        @options = {}
+        @options = {allow_extra: false}
         @keys = {}
         @key_type = k
         @value_type = v
@@ -38,6 +61,10 @@ module Attributor
       end
     end
 
+    def self.attributes(**options, &key_spec)
+      self.keys(options, &key_spec)
+    end
+
     def self.keys(**options, &key_spec)
       if block_given?
         @saved_blocks << key_spec
@@ -57,6 +84,12 @@ module Attributor
       blocks = @saved_blocks.shift(@saved_blocks.size)
       compiler = dsl_class.new(self, opts)
       compiler.parse(*blocks)
+
+      @insensitive_map = self.keys.keys.each_with_object({}) do |k, map|
+        map[k.downcase] = k
+      end
+
+      compiler
     end
 
     def self.dsl_class
@@ -73,42 +106,24 @@ module Attributor
 
     # @example Hash.of(key: String, value: Integer)
     def self.of(key: @key_type, value: @value_type)
-      if key
-        resolved_key_type = Attributor.resolve_type(key)
-        unless resolved_key_type.ancestors.include?(Attributor::Type)
-          raise Attributor::AttributorException.new("Hashes only support key types that are Attributor::Types. Got #{resolved_key_type.name}")
-        end
-        
-      end
-
-      if value
-        resolved_value_type = Attributor.resolve_type(value)
-        unless resolved_value_type.ancestors.include?(Attributor::Type)
-          raise Attributor::AttributorException.new("Hashes only support value types that are Attributor::Types. Got #{resolved_value_type.name}")
-        end
-      end
-
-
-    
-
       Class.new(self) do
-        @key_type = resolved_key_type
-        @value_type = resolved_value_type
-        
-        @key_attribute = Attribute.new(@key_type)
-        @value_attribute = Attribute.new(@value_type)
-        @concrete = true
+        self.key_type = key
+        self.value_type = value
         @keys = {}
       end
     end
 
 
-    def self.construct(constructor_block,  **options)
+    def self.construct(constructor_block, **options)
       return self if constructor_block.nil?
 
       unless @concrete
         return self.of(key:self.key_type, value: self.value_type)
-                   .construct(constructor_block,**options)
+          .construct(constructor_block,**options)
+      end
+
+      if options[:case_insensitive_load] && !(self.key_type <= String)
+        raise Attributor::AttributorException.new(":case_insensitive_load may not be used with keys of type #{self.key_type.name}")
       end
 
       self.keys(options, &constructor_block)
@@ -120,7 +135,8 @@ module Attributor
       return self.new if (key_type == Object && value_type == Object)
 
       hash = ::Hash.new
-      # Let's not bother to generate any hash contents if there's absolutely no type defined
+      context ||= ["#{Hash}-#{rand(10000000)}"]
+      context = Array(context)
 
       if self.keys.any?
         self.keys.each do |sub_name, sub_attribute|
@@ -128,12 +144,8 @@ module Attributor
           hash[sub_name] = sub_attribute.example(subcontext)
         end
       else
-
         size = rand(3) + 1
 
-        context ||= ["#{Hash}-#{rand(10000000)}"]
-        context = Array(context)
-
         size.times do |i|
           example_key = key_type.example(context + ["at(#{i})"])
           subcontext = context + ["at(#{example_key})"]
@@ -158,12 +170,17 @@ module Attributor
 
     def self.check_option!(name, definition)
       case name
-      when :key_type
-        :ok
-      when :value_type
-        :ok
       when :reference
         :ok # FIXME ... actually do something smart
+      when :dsl_compiler
+        :ok
+      when :case_insensitive_load
+        unless self.key_type <= String
+          raise Attributor::AttributorException, ":case_insensitive_load may not be used with keys of type #{self.key_type.name}"
+        end
+        :ok
+      when :allow_extra
+        :ok
       else
         :unknown
       end
@@ -195,23 +212,57 @@ module Attributor
     end
 
     def self.generate_subcontext(context, key_name)
-      context + ["get(#{key_name.inspect})"]
+      context + ["key(#{key_name.inspect})"]
+    end
+
+    def generate_subcontext(context, key_name)
+      self.class.generate_sub_context(context,key_name)
+    end
+
+    def set(key, value, context: self.generate_subcontext(Attributor::DEFAULT_ROOT_CONTEXT,key))
+      key = self.class.key_attribute.load(key, context)
+
+      if (attribute = self.class.keys[key])
+        return self[key] = attribute.load(value, context)
+      end
+
+      if self.class.options[:case_insensitive_load]
+        key = self.class.insensitive_map[key.downcase]
+        return self.set(key, value, context: context)
+      end
+
+      if self.class.options[:allow_extra]
+        if self.class.extra_keys.nil?
+          return self[key] = self.class.value_attribute.load(value, context)
+        else
+          return self[self.class.extra_keys].set(key, value, context: context)
+        end
+      end
+
+      raise AttributorException, "Unknown key received: #{key.inspect} while loading #{Attributor.humanize_context(context)}"
     end
 
     def self.from_hash(object,context)
       hash = self.new
 
-      object.each do |k,v|
-        hash_key = @key_type.load(k)
+      # if the hash definition includes named extra keys, initialize
+      # its value from the object in case it provides some already.
+      # this is to ensure it exists when we handle any extra keys
+      # that may exist in the object later
+      if self.extra_keys
+        sub_context = self.generate_subcontext(context,self.extra_keys)
+        v = object.fetch(self.extra_keys, {})
+        hash.set(self.extra_keys, v, context: sub_context)
+      end
 
-        hash_attribute = self.keys.fetch(hash_key) do
-          raise AttributorException, "Unknown key received: #{k.inspect} while loading #{Attributor.humanize_context(context)}"
-        end
+      object.each do |k,v|
+        next if k == self.extra_keys
 
-        sub_context = self.generate_subcontext(context,hash_key)
-        hash[hash_key] = hash_attribute.load(v, sub_context)
+        sub_context = self.generate_subcontext(Attributor::DEFAULT_ROOT_CONTEXT,k)
+        hash.set(k, v, context: sub_context)
       end
 
+      # handle default values for missing keys
       self.keys.each do |key_name, attribute|
         next if hash.key?(key_name)
         sub_context = self.generate_subcontext(context,key_name)
@@ -262,8 +313,6 @@ module Attributor
 
     def initialize(contents={})
       @contents = contents
-      
-      
     end
 
     def key_type
@@ -293,7 +342,7 @@ module Attributor
 
       if self.class.keys.any?
         extra_keys = @contents.keys - self.class.keys.keys
-        if extra_keys.any?
+        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
@@ -315,12 +364,12 @@ module Attributor
           # FIXME: the sub contexts and error messages don't really make sense here
           unless key_type == Attributor::Object
             sub_context = context + ["key(#{key.inspect})"]
-            errors.push *key_attribute.validate(key, sub_context) 
-          end            
+            errors.push *key_attribute.validate(key, sub_context)
+          end
 
           unless value_type == Attributor::Object
             sub_context = context + ["value(#{value.inspect})"]
-            errors.push *value_attribute.validate(value, sub_context)  
+            errors.push *value_attribute.validate(value, sub_context)
           end
         end
       end

data/lib/attributor/types/model.rb

@@ -7,7 +7,7 @@ module Attributor
     # FIXME: this is not the way to fix this. Really we should add finalize! to Models.
     undef :timeout
     undef :format
-
+    undef :test rescue nil
 
     def self.inherited(klass)
       klass.instance_eval do

data/lib/attributor/version.rb

@@ -1,3 +1,3 @@
 module Attributor
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 end

data/spec/support/types.rb

@@ -17,5 +17,3 @@ class IntegerAttributeType
   end
 
 end
-
-

data/spec/types/collection_spec.rb

@@ -282,5 +282,13 @@ describe Attributor::Collection do
         value.all? { |element| member_type.valid_type?(element) }.should be_true
       end
     end
+    context "passing a non array context" do
+      it 'still is handled correctly ' do
+        expect{
+          type.example("SimpleString")
+        }.to_not raise_error
+      end
+    end
+    
   end
 end

data/spec/types/hash_spec.rb

@@ -6,6 +6,16 @@ describe Attributor::Hash do
   subject(:type) { Attributor::Hash }
 
   its(:native_type) { should be(type) }
+  its(:key_type) { should be(Attributor::Object) }
+  its(:value_type) { should be(Attributor::Object) }
+
+  context 'default options' do
+    subject(:options) { type.options }
+    it 'has allow_extra false' do
+      options[:allow_extra].should be(false)
+    end
+  end
+
 
   context '.example' do
     context 'for a simple hash' do
@@ -25,6 +35,17 @@ describe Attributor::Hash do
         example.values.all? {|v| v.kind_of? Integer}.should be(true)
       end
     end
+    context 'using a non array context' do
+      it 'should work for hashes with key/value types' do
+        expect{ Attributor::Hash.of(key:String,value:String).example("Not an Array") }.to_not raise_error
+      end
+      it 'should work for hashes with keys defined' do
+        block = proc { key 'a string', String }
+        hash = Attributor::Hash.of(key:String).construct(block)
+
+        expect{ hash.example("Not an Array") }.to_not raise_error
+      end
+    end
   end
 
   context '.load' do
@@ -124,7 +145,7 @@ describe Attributor::Hash do
     subject(:type) { Attributor::Hash.construct(block) }
 
     it { should_not be(Attributor::Hash)
-    }
+         }
 
     context 'loading' do
       let(:date) { DateTime.parse("2014-07-15") }
@@ -192,11 +213,18 @@ describe Attributor::Hash do
   end
 
   context '.check_option!' do
-    it 'accepts key_type:' do
-      subject.check_option!(:key_type, String).should == :ok
-    end
-    it 'accepts value_type'  do
-      subject.check_option!(:value_type, Object).should == :ok
+    context ':case_insensitive_load' do
+
+      it 'is valid when key_type is a string' do
+        Attributor::Hash.of(key:String).check_option!(:case_insensitive_load, true).should == :ok
+      end
+
+      it 'is invalid when key_type is non-string' do
+        expect {
+          Attributor::Hash.of(key:Integer).check_option!(:case_insensitive_load, true)
+        }.to raise_error(Attributor::AttributorException, /:case_insensitive_load may not be used/)
+      end
+
     end
     it 'rejects unknown options'  do
       subject.check_option!(:bad_option, Object).should == :unknown
@@ -271,7 +299,7 @@ describe Attributor::Hash do
         end
       end
 
-      let(:type) { Attributor::Hash.construct(block) } 
+      let(:type) { Attributor::Hash.construct(block) }
 
       let(:values) { {'integer' => 'one', 'datetime' => 'now' } }
       subject(:hash) { type.new(values) }
@@ -279,7 +307,7 @@ describe Attributor::Hash do
       it 'validates the keys' do
         errors = hash.validate
         errors.should have(3).items
-        errors.should include("Attribute $.get(\"not-optional\") is required")
+        errors.should include("Attribute $.key(\"not-optional\") is required")
       end
 
     end
@@ -369,4 +397,85 @@ describe Attributor::Hash do
     end
   end
 
+  context 'with case_insensitive_load option for string keys' do
+    let(:block) do
+      proc do
+        key 'downcase', Integer
+        key 'UPCASE', Integer
+        key 'CamelCase', Integer
+      end
+    end
+
+    let(:type) { Attributor::Hash.of(key: String).construct(block, case_insensitive_load: true) }
+
+    let(:input) { {'DOWNCASE' => 1, 'upcase' => 2, 'CamelCase' => 3} }
+
+    subject(:output) { type.load(input) }
+
+    it 'maps the incoming keys to defined keys, regardless of case' do
+      output['downcase'].should eq(1)
+      output['UPCASE'].should eq(2)
+      output['CamelCase'].should eq(3)
+    end
+
+  end
+
+  context 'with allow_extra keys option' do
+    let(:type) do
+      Class.new(Attributor::Hash) do
+        self.value_type = String
+
+        keys allow_extra: true do
+          key :one, String
+          key :two, String, default: 'two'
+        end
+      end
+    end
+
+    let(:input) { {one: 'one', three: 3} }
+    subject(:output) { type.load(input) }
+
+    context 'that should be saved at the top level' do
+      its(:keys) { should =~ [:one, :two, :three] }
+
+      it 'loads the extra keys' do
+        output[:one].should eq('one')
+        output[:two].should eq('two')
+        output[:three].should eq('3')
+      end
+      
+      its( :validate ){ should be_empty }
+    end
+
+    context 'that should be grouped into a sub-hash' do
+      before do
+        type.keys do
+          extra :options, Attributor::Hash.of(value: Integer)
+        end
+      end
+
+      its(:keys) { should =~ [:one, :two, :options] }
+      it 'loads the extra keys into :options sub-hash' do
+        output[:one].should eq('one')
+        output[:two].should eq('two')
+        output[:options].should eq({three: 3})
+      end
+      its( :validate ){ should be_empty }
+
+      context 'with an options value already provided' do
+        its(:keys) { should =~ [:one, :two, :options] }
+        let(:input) { {one: 'one', three: 3, options: {four: 4}} }
+
+        it 'loads the extra keys into :options sub-hash' do
+          output[:one].should eq('one')
+          output[:two].should eq('two')
+          output[:options].should eq({three: 3, four: 4})
+        end
+        its( :validate ){ should be_empty }
+
+      end
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: attributor
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Josep M. Blanquer
@@ -318,7 +318,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A powerful attribute and type management library for Ruby