attributor 2.6.1 → 3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ab74d0c797f7d246ba2e19564b9a215fcb1e8e73
-  data.tar.gz: 780a566c96c190af27f559aaf9052ccddcc5d237
+  metadata.gz: a9b60ce0b5ac69797dca8bc43ce9164e8a666eeb
+  data.tar.gz: d87a417b41105b3ed4ae10098bd14542d88d7f96
 SHA512:
-  metadata.gz: df140c8719de7cbc33cf48c2b92d3b5afb3fc15119a84bacc1e414757e2a54288e72fc46ddce64485ac87ed927cca93ce7a387398064d5dfac235af4eccfae94
-  data.tar.gz: 5128f01b9a28a1b7e2e112d23bd82037600af17b127f6f4c9ad8911d00d04ffe829a10c5bc0288dbcd9517d379052b0680db0b4892cbf7ec4c0976fbf48335f3
+  metadata.gz: 660346014295ff874c70f0cc79931b98c109c0034e1b235f516108aa5857fa71688a2a2fcd7aab8c9636c91b87a64d1b82d09ae1a7d247b0bf7a23cf232a80d2
+  data.tar.gz: 174c4d2859d2ad0611c55b3c16c70eaa80440fcdee5308fe84a917192d624383e65bfae19c5bd593732ac59ba0d13d908e4c018406f0256fe0f1c30864911fc1

data/.travis.yml

@@ -1,7 +1,8 @@
 sudo: false
 language: ruby
 rvm:
-  - "2.1.5"
+  - 2.1.5
+  - 2.2.2
 script: bundle exec rspec spec
 branches:
   only:

data/CHANGELOG.md

@@ -1,11 +1,26 @@
-Attributor Changelog
-============================
-
-next
-----
-
-2.6.1
------
+# Attributor Changelog
+
+## 3.0.0
+
+* Small enhancements on `describe` for types
+  * avoid creating empty `:attributes` key for `Model`
+  * ensure embedding `key_type` in `Hash` using `shallow` mode
+* Added `Hash#delete`.
+* Changed the schema for describing `Hash` to use `attributes` instead of `keys`
+  * It makes more sense, and it is compatible with Model and Structs too.
+* Undefine JRuby package helper methods in `Model` (org, java...)
+* Added support to `Collection.load` for any value that responds to `to_a`
+* Fixed `Collection.validate` to complain when value object is not a valida type
+* Fixed bug where defining an attribute that references a `Collection` would not properly support defining sub-attributes in a provided block.
+* Enhanced the type/attribute `describe` methods of types so that they generate an example if an `example` argument is passed in.
+  * Complex (sub-structured) types will not output examples, only 'leaf' ones.
+* Improved handling of exceptions during attribute definitions for `Hash`/`Model` that would previously leave the set of attributes in an undefined state. Now, any attempts to use the type will throw an `InvalidDefinition` exception and include the original exception. (#127)
+* Removed `undef :empty?` from `Model`
+* Made `Collection` a subclass of Array, and `load` create new instances of it.
+* Built in proper loading and validation of any `Attribute#example` when the `:example` option is used.
+
+
+## 2.6.1
 
 * Add the `:custom_data` option for attributes. This is a hash that is passed through to `describe` - Attributor does no processing or handling of this option.
 * Added `Type.family` which returns a more-generic "family name". It's defined for all built-in types, and is included in `Type.describe`.
@@ -14,8 +29,7 @@ next
   * Fix common hash methods created for example instances (to play well with lazy attributes)
   * Avoid storing the `Hash#insensitive_map` unless insensitivity enabled
 
-2.6.0
------
+## 2.6.0
 
 * Fixed bug in `example_mixin` where lazy_attributes were not evaluated.
 * Fixed bug in `Hash` where the class would refuse to load from another `Attributor::Hash` when there were no keys defined and they were seemingly compatible.
@@ -27,8 +41,8 @@ next
 * Added `Hash#merge` that works with two identically-typed hashes
 * Added `Hash#each_pair` for better duck-type compatibility with ::Hash.
 
-2.5.0
-----
+
+## 2.5.0
 
 * Partial support for defining `:default` values through Procs.
   * Note: this is only "partially" supported the `parent` argument of the Proc will NOT contain the correct attribute parent yet. It will contain a fake class, that will loudly complain about any attempt to use any of its methods.
@@ -38,17 +52,16 @@ next
 * `Time`, `DateTime`, and `Date` now all return ISO 8601 formatted values from `.dump` (via calling `iso8601` on the value).
 * Added `Type.id`, a unique value based on the type's class name.
 
-2.4.0
-------
 
-* `Model` is now a subclass of `Hash`. 
+## 2.4.0
+
+* `Model` is now a subclass of `Hash`.
   * The interface for `Model` instances is almost entirely unchanged, except for the addition of `Hash`-like methods (i.e., you can now do `some_model[:key]` to access attributes).
   * This fixes numerous incompatabilities between models and hashes, as well as confusing differences between the behavior when loading a model vs a hash.
 * `String.load` now raises `IncompatibleTypeError` for `Enumerable` values.
-* Added `Symbol` type, use with caution as it will automatically call `#to_sym` on anything loaded. 
+* Added `Symbol` type, use with caution as it will automatically call `#to_sym` on anything loaded.
 
-2.3.0
-------
+## 2.3.0
 
 * Added `recurse` option to `Type.load` that is used by `Model` and `Hash` to force the loading of values (specifically, so that default values are assigned) even if the loaded value is `nil`.
 * Fix `Attributor::CSV` to dump `String` values and generate `String` examples.
@@ -59,16 +72,15 @@ next
 * Added `Hash#get`, for retrieving keys using the same logic the `case_insensitive_load` and `allow_extra` with defined `extra` key.
 
 
-2.2.1
-------
+## 2.2.1
 
 * Dumping attributes will now load the values if they're not in the native type.
 * `Model.valid_type?` now accepts hashes.
 * `Hash`:
   * Added `:has_key?` to delegation
 
-2.2.0
-------
+
+## 2.2.0
 
 * Fix example generation for Hash and Collection to handle a non-Array context parameter.
 * Hash:
@@ -78,8 +90,8 @@ next
   * 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
-------
+
+## 2.1.0
 
 * Structs now inherit type-level options from their reference.
 * Add Collection subclasses for CSVs and Ids
@@ -103,8 +115,8 @@ next
 * Introduced a new FileUpload type. This can be easily used in Web servers to map incoming multipart file uploads.
 * Introduced a new Tempfile type.
 
-2.0.0
-------
+
+## 2.0.0
 
 * Added new exception subtypes (load methods return more precise errors now)
 * Changed ```Attributor::Model``` to be a class instead of module.

data/lib/attributor.rb

@@ -14,7 +14,7 @@ module Attributor
   require_relative 'attributor/attribute_resolver'
 
   require_relative 'attributor/example_mixin'
-  
+
   require_relative 'attributor/extensions/randexp'
 
 
@@ -45,16 +45,16 @@ module Attributor
   end
 
   def self.humanize_context( context )
-    raise "NIL CONTEXT PASSED TO HUMANZE!!" unless context
+    return "" unless context
 
     if context.kind_of? ::String
       context = Array(context)
     end
 
     unless context.is_a? Enumerable
-      raise "INVALID CONTEXT!!! (got: #{context.inspect})" 
+      raise "INVALID CONTEXT!!! (got: #{context.inspect})"
     end
-    
+
     begin
       return context.join('.')
     rescue Exception => e
@@ -73,10 +73,10 @@ module Attributor
 
   require_relative 'attributor/families/numeric'
   require_relative 'attributor/families/temporal'
-  
+
   require_relative 'attributor/types/container'
   require_relative 'attributor/types/object'
-  
+
   require_relative 'attributor/types/bigdecimal'
   require_relative 'attributor/types/integer'
   require_relative 'attributor/types/string'
@@ -90,7 +90,7 @@ module Attributor
   require_relative 'attributor/types/hash'
   require_relative 'attributor/types/model'
   require_relative 'attributor/types/struct'
-  
+
 
   require_relative 'attributor/types/csv'
   require_relative 'attributor/types/ids'
@@ -98,5 +98,6 @@ module Attributor
   # TODO: move these to 'optional types' or 'extra types'... location
   require_relative 'attributor/types/tempfile'
   require_relative 'attributor/types/file_upload'
+  require_relative 'attributor/types/uri'
 
 end

data/lib/attributor/attribute.rb

@@ -3,14 +3,14 @@
 module Attributor
 
   class FakeParent < ::BasicObject
-    
+
     def method_missing(name, *args)
       ::Kernel.warn "Warning, you have tried to access the '#{name}' method of the 'parent' argument of a Proc-defined :default values." +
                     "Those Procs should completely ignore the 'parent' attribute for the moment as it will be set to an " +
                     "instance of a useless class (until the framework can provide such functionality)"
       nil
     end
-    
+
     def class
       FakeParent
     end
@@ -80,7 +80,7 @@ module Attributor
     end
 
     def dump(value, **opts)
-      type.dump(value, opts)
+      type.dump(value, **opts)
     end
 
 
@@ -98,7 +98,7 @@ module Attributor
 
     TOP_LEVEL_OPTIONS = [ :description, :values, :default, :example, :required, :required_if, :custom_data ]
     INTERNAL_OPTIONS = [:dsl_compiler,:dsl_compiler_options] # Options we don't want to expose when describing attributes
-    def describe(shallow=true)
+    def describe(shallow=true, example: nil )
       description = { }
       # Clone the common options
       TOP_LEVEL_OPTIONS.each do |option_name|
@@ -109,6 +109,7 @@ module Attributor
       if ( ex_def = description.delete(:example) )
         description[:example_definition] = ex_def
       end
+
       special_options = self.options.keys - TOP_LEVEL_OPTIONS - INTERNAL_OPTIONS
       description[:options] = {} unless special_options.empty?
       special_options.each do |opt_name|
@@ -119,40 +120,55 @@ module Attributor
         description[:options][:reference] = reference.name
       end
 
-      description[:type] = self.type.describe(shallow)
+      description[:type] = self.type.describe(shallow, example: example )
+      # Move over any example from the type, into the attribute itself
+      if ( ex = description[:type].delete(:example) )
+        description[:example] = self.dump( ex ).to_s
+      end
+
       description
     end
 
 
+    def example_from_options(parent, context)
+      val = self.options[:example]
+      generated = case val
+      when ::Regexp
+        val.gen
+      when ::Array
+        # TODO: handle arrays of non native types, i.e. arrays of regexps.... ?
+        val.pick
+      when ::Proc
+        if val.arity == 2
+          val.call(parent, context)
+        elsif val.arity == 1
+          val.call(parent)
+        else
+          val.call
+        end
+      when nil
+        nil
+      else
+        val
+      end
+      self.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 )
       if context
         ctx = Attributor.humanize_context(context)
         seed, _ = Digest::SHA1.digest(ctx).unpack("QQ")
         Random.srand(seed)
+      else
+        context = Attributor::DEFAULT_ROOT_CONTEXT
       end
 
       if self.options.has_key? :example
-        val = self.options[:example]
-        case val
-        when ::Regexp
-          self.load(val.gen,context)
-        when ::Array
-          # TODO: handle arrays of non native types, i.e. arrays of regexps.... ?
-          val.pick
-        when ::Proc
-          if val.arity == 2
-            val.call(parent, context)
-          elsif val.arity == 1
-            val.call(parent)
-          else
-            val.call
-          end
-        when nil
-          nil
-        else
-          self.load(val)
-        end
+        loaded = example_from_options(parent, context)
+        errors = self.validate(loaded, context)
+        raise AttributorException, "Error generating example for #{Attributor.humanize_context(context)}. Errors: #{errors.inspect}" if errors.any?
+        loaded
       else
         if (option_values = self.options[:values])
           option_values.pick

data/lib/attributor/dsl_compiler.rb

@@ -100,7 +100,13 @@ module Attributor
       # determine attribute type to use
       if attr_type.nil?
         if block_given?
-          attr_type = Attributor::Struct
+          attr_type = if inherited_attribute && inherited_attribute.type < Attributor::Collection
+            # override the reference to be the member_attribute's type for collections
+            opts[:reference] = inherited_attribute.type.member_attribute.type
+            Attributor::Collection.of(Struct)
+          else
+            Attributor::Struct
+          end
         elsif inherited_attribute
           attr_type = inherited_attribute.type
         else

data/lib/attributor/type.rb

@@ -10,9 +10,9 @@ module Attributor
 
 
     module ClassMethods
-  
-      # Does this type support the generation of subtypes? 
-      def constructable? 
+
+      # Does this type support the generation of subtypes?
+      def constructable?
         false
       end
 
@@ -20,7 +20,7 @@ module Attributor
       def load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
         return nil if value.nil?
         unless value.is_a?(self.native_type)
-          raise Attributor::IncompatibleTypeError, context: context, value_type: value.class, type: self 
+          raise Attributor::IncompatibleTypeError, context: context, value_type: value.class, type: self
         end
 
         value
@@ -89,7 +89,7 @@ module Attributor
 
 
       def generate_subcontext(context, subname)
-        context + [subname] 
+        context + [subname]
       end
 
       def dsl_compiler
@@ -105,15 +105,17 @@ module Attributor
       end
 
       # Default describe for simple types...only their name (stripping the base attributor module)
-      def describe(root=false)
+      def describe(root=false, example: nil)
         type_name = self.ancestors.find { |k| k.name && !k.name.empty? }.name
-        {
+        hash = {
           name: type_name.gsub(Attributor::MODULE_PREFIX_REGEX, ''),
           family: self.family,
           id: self.id
         }
+        hash[:example] = example if example
+        hash
       end
-      
+
       def id
         return nil if self.name.nil?
         self.name.gsub('::'.freeze,'-'.freeze)

data/lib/attributor/types/collection.rb

@@ -3,7 +3,7 @@
 
 module Attributor
 
-  class Collection
+  class Collection < Array
     include Container
 
     # @param type [Attributor::Type] optional, defines the type of all collection members
@@ -21,14 +21,31 @@ module Attributor
       end
     end
 
+    @options = {}
+
+    def self.inherited(klass)
+      klass.instance_eval do
+        @options = {}
+      end
+    end
+
+    def self.options
+      @options
+    end
+
+
     def self.native_type
-      return ::Array
+      self
+    end
+
+    def self.valid_type?(type)
+      type.kind_of?(self) || type.kind_of?(::Enumerable)
     end
 
     def self.family
       'array'
     end
-    
+
     def self.member_type
       @member_type ||= Attributor::Object
     end
@@ -51,16 +68,20 @@ module Attributor
       context ||= ["Collection-#{result.object_id}"]
       context = Array(context)
 
+      # avoid infinite recursion in example generation
+      example_depth = context.size
+      size = 0 if example_depth > Hash::MAX_EXAMPLE_DEPTH
+
       size.times do |i|
         subcontext = context + ["at(#{i})"]
         result << self.member_attribute.example(subcontext)
       end
 
-      result
+      self.new(result)
     end
 
 
-    # The incoming value should be an array here, so the only decoding that we need to do
+    # The incoming value should be array-like here, so the only decoding that we need to do
     # is from the members (if there's an :member_type defined option).
     def self.load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
       if value.nil?
@@ -69,11 +90,13 @@ module Attributor
         loaded_value = value
       elsif value.is_a?(::String)
         loaded_value = decode_string(value,context)
+      elsif value.respond_to?(:to_a)
+        loaded_value = value.to_a
       else
         raise Attributor::IncompatibleTypeError, context: context, value_type: value.class, type: self
       end
 
-      return loaded_value.collect { |member| self.member_attribute.load(member,context) }
+      self.new(loaded_value.collect { |member| self.member_attribute.load(member,context) })
     end
 
 
@@ -87,20 +110,21 @@ module Attributor
       values.collect { |value| member_attribute.dump(value,opts) }
     end
 
-    def self.describe(shallow=false)
+    def self.describe(shallow=false, example: nil)
       hash = super(shallow)
       hash[:options] = {} unless hash[:options]
-      hash[:member_attribute] = self.member_attribute.describe
+      member_example = example.first if example
+      hash[:member_attribute] = self.member_attribute.describe(true, example: member_example )
       hash
     end
 
 
-    def self.constructable? 
+    def self.constructable?
       true
     end
 
-    def self.construct(constructor_block, options)
 
+    def self.construct(constructor_block, options)
       member_options =  (options[:member_options]  || {} ).clone
       if options.has_key?(:reference) && !member_options.has_key?(:reference)
         member_options[:reference] = options[:reference]
@@ -131,6 +155,16 @@ module Attributor
 
     # @param values [Array] Array of values to validate
     def self.validate(values, context=Attributor::DEFAULT_ROOT_CONTEXT, attribute=nil)
+
+      unless self.valid_type?(values)
+        descriptive_type =if self.member_type != Object
+          "Collection.of(#{self.member_type})"
+        else
+          self
+        end
+        raise Attributor::IncompatibleTypeError, context: context, value_type: values.class, type: descriptive_type
+      end
+
       values.each_with_index.collect do |value, i|
         subcontext = context + ["at(#{i})"]
         self.member_attribute.validate(value, subcontext)
@@ -142,5 +176,10 @@ module Attributor
       errors
     end
 
+
+    def dump(**opts)
+      self.collect { |value| self.class.member_attribute.dump(value,opts) }
+    end
+
   end
 end