attributor 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 102708c30b51b0ddb7a38488ca440ada38c2f3a8
+  data.tar.gz: 4e50cb2a981f4b1d6173e754789a25932153d7bd
+SHA512:
+  metadata.gz: 47095d5c279287a05b302867f1e9d5518d511405d1a475e1ebd272f584c3f71284bb8d59eaab9da7ad79043a0d1179ff29514052de69a0ac48fecc9315ad35a4
+  data.tar.gz: 495d613202a0b19dd186cd302e5fdffdaeea8e40c059e4c7ba6b7b81a175e10bd06fbf6a8b1349c9fe12c88c93c8da5beca53cf8a7e25151eb9eecd4da5a3b17

data/.gitignore

@@ -0,0 +1,15 @@
+# simplecov generated
+coverage
+
+# rbenv
+.ruby-version
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# For MacOS:
+.DS_Store

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format=Fuubar

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - "2.1.2"
+script: bundle exec rspec spec

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+Attributor Changelog
+============================
+
+next
+------
+
+* First new feature here
+
+2.1.0
+------
+
+* Structs now inherit type-level options from their reference.
+* Add Collection subclasses for CSVs and Ids
+  * CSV type for Collection of values serialized as comma-separated strings.
+  * Ids type. A helper for creating CSVs with members matching a given a type's :identity option.
+* Allow instances of Models to be initialized with initial data. 
+  * Supported formats for the data are equivalent to the loading formats (i.e. ruby Hash, a JSON string or another instance of the same model type).
+* Improved context reporting in errors
+  * Added contextual information while loading and dumping attributes.
+    * `load` takes a new `context` argument (defaulting to a system-wide root) in the form of an array of parent segments.
+    * `validate` takes a `context` argument that (instead of a string) is now an array of parent segments.
+    * `dump` takes a `context:` option parameter of the same type
+  * 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)
+* `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)
+  * Loaded Hash types now return instances of the class rather than a simple Ruby Hash.
+* 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
+------
+
+* Added new exception subtypes (load methods return more precise errors now)
+* Changed ```Attributor::Model``` to be a class instead of module.
+* Improved handling of ```Attributor::Model``` examples:
+  * Support creating examples with specific values. i.e.:
+  ```ruby
+    person = Person.example(name: "Bob")
+    person.name # => "Bob"
+  ```
+  * Example values are now lazily initialized when used.
+  * Terminate sub-attribute generation after ```Attributor::Model::MAX_EXAMPLE_DEPTH``` levels to prevent infinite generation.
+* Added additional options for Attribute :example values:
+  * explicit nil values
+  * procs that take 2 arguments now receive the context as the second argument.
+* Circular references are now detected and handled in validation and dumping.
+* Fixed bug with Model attribute accessors when using false values.
+

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Guardfile

@@ -0,0 +1,12 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/attributor/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+  watch('lib/attributor/base.rb') { "spec" }
+  watch('spec/support/models.rb') { "spec" }
+  watch('lib/attributor.rb') { 'spec' }
+end
+

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 RightScale
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# 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.
+
+With Attributor you can:
+* Express complex and type-rich attribute structures using an elegant ruby DSL
+* Process incoming values against those designs:
+    * By verifying they follow constraints and available options specified in your design
+    * By coercing values into the specified types when there's a type impedance mismatch
+    * By checking presence requirements and conditional dependencies
+    * and all with a powerful error reporting system that describes with great detail what errors were encountered
+* Export structured information (in JSON) about your attribute definitions which allows you to:
+    * easily consume it to generate human consumable documentation about parameter expectations
+    * easily aggregate it across different systems.
+
+
+## General Help
+
+### Running specs:
+
+    `bundle exec rake spec`
+
+Note: This should also compute code coverage. See below for details on viewing code coverage.
+
+### Generating documentation:
+
+    `bundle exec yard`
+
+### Computing documentation coverage:
+
+    `bundle exec yardstick 'lib/**/*.rb'`
+
+### Computing code coverage:
+
+    `bundle exec rake spec`
+
+    `open coverage/index.html`
+
+
+## Contributing to attributor
+
+* Check out the latest "master" branch to make sure the feature hasn't been
+  implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it
+  and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it.
+  ** This is important to ensure it's not broken in a future version. **
+* Please try not to mess with the Rakefile, version, or history.
+  If you want your own version, or if it is otherwise necessary, that is fine,
+  but please isolate to its own commit so we can cherry-pick around it.
+
+
+
+## License
+
+This software is released under the [MIT License](http://www.opensource.org/licenses/MIT). Please see  [LICENSE](LICENSE) for further details.
+
+Copyright (c) 2014 RightScale

data/Rakefile

@@ -0,0 +1,28 @@
+# 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'
+
+desc "Run RSpec code examples with simplecov"
+RSpec::Core::RakeTask.new do |spec|
+  spec.rspec_opts = ["-c"]
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+task :default => :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/attributor.gemspec

@@ -0,0 +1,40 @@
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'attributor/version'
+
+Gem::Specification.new do |spec|
+  spec.name = "attributor"
+  spec.version       = Attributor::VERSION
+  spec.authors = ["Josep M. Blanquer","Dane Jensen"]
+  spec.date = "2014-08-15"
+  spec.summary = "A powerful attribute and type management library for Ruby"
+  spec.email = ["blanquer@gmail.com","dane.jensen@gmail.com"]
+  
+  spec.homepage = "https://github.com/rightscale/attributor"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">=2.1"
+  
+  spec.require_paths = ["lib"]
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  
+  spec.add_runtime_dependency(%q<hashie>, ["~> 3"])
+  spec.add_runtime_dependency(%q<randexp>, ["~> 0"])
+  spec.add_development_dependency(%q<rspec>, ["< 2.99"])
+  spec.add_development_dependency(%q<yard>, ["~> 0.8.7"])
+  spec.add_development_dependency(%q<backports>, ["~> 3"])
+  spec.add_development_dependency(%q<yardstick>, ["~> 0"])
+  spec.add_development_dependency(%q<redcarpet>, ["< 3.0"])
+  spec.add_development_dependency(%q<bundler>, [">= 0"])
+  spec.add_development_dependency(%q<rake-notes>, ["~> 0"])
+  spec.add_development_dependency(%q<simplecov>, ["~> 0"])
+  spec.add_development_dependency(%q<guard>, ["~> 2"])
+  spec.add_development_dependency(%q<guard-rspec>, ["~> 4"])
+  spec.add_development_dependency(%q<pry>, ["~> 0"])
+  spec.add_development_dependency(%q<pry-byebug>, ["~> 1"])
+  spec.add_development_dependency(%q<pry-stack_explorer>, ["~> 0"])
+  spec.add_development_dependency(%q<fuubar>, ["~> 1"])
+end
+

data/lib/attributor.rb

@@ -0,0 +1,89 @@
+require 'json'
+require 'randexp'
+
+require 'hashie'
+
+require 'digest/sha1'
+
+module Attributor
+
+  require_relative 'attributor/exceptions'
+  require_relative 'attributor/attribute'
+  require_relative 'attributor/type'
+  require_relative 'attributor/dsl_compiler'
+  require_relative 'attributor/attribute_resolver'
+
+
+  require_relative 'attributor/extensions/randexp'
+
+
+
+  # List of all basic types (i.e. not collections, structs or models)
+
+  # hierarchical separator string for composing human readable attributes
+  SEPARATOR = '.'.freeze
+  DEFAULT_ROOT_CONTEXT = ['$'].freeze
+
+  # @param type [Class] The class of the type to resolve
+  #
+  def self.resolve_type(attr_type, options={}, constructor_block=nil)
+    if attr_type < Attributor::Type
+      klass = attr_type
+    else
+      name = attr_type.name.split("::").last # TOO EXPENSIVE?
+
+      klass = const_get(name) if const_defined?(name)
+      raise AttributorException.new("Could not find class with name #{name}") unless klass
+      raise AttributorException.new("Could not find attribute type for: #{name} [klass: #{klass.name}]")  unless  klass < Attributor::Type
+    end
+
+    if klass.respond_to?(:construct)
+      return klass.construct(constructor_block, options)
+    end
+
+    raise AttributorException.new("Type: #{attr_type} does not support anonymous generation") if constructor_block
+
+    klass
+  end
+
+  def self.humanize_context( context )
+    raise "NIL CONTEXT PASSED TO HUMANZE!!" unless context
+    raise "INVALID CONTEXT!!! (got: #{context.inspect})" unless context.is_a? Enumerable
+    begin
+      return context.join('.')
+    rescue Exception => e
+      raise "Error creating context string: #{e.message}"
+    end
+  end
+
+  def self.errorize_value( value )
+    inspection =value.inspect
+    inspection = inspection[0..500]+ "...[truncated]" if inspection.size>500
+    inspection
+  end
+
+  MODULE_PREFIX       = "Attributor\:\:".freeze
+  MODULE_PREFIX_REGEX = Regexp.new(MODULE_PREFIX)
+
+  require_relative 'attributor/types/container'
+  require_relative 'attributor/types/object'
+  require_relative 'attributor/types/integer'
+  require_relative 'attributor/types/string'
+  require_relative 'attributor/types/model'
+  require_relative 'attributor/types/struct'
+  require_relative 'attributor/types/boolean'
+  require_relative 'attributor/types/date_time'
+  require_relative 'attributor/types/float'
+  require_relative 'attributor/types/collection'
+  require_relative 'attributor/types/hash'
+
+
+  require_relative 'attributor/types/csv'
+  require_relative 'attributor/types/ids'
+
+  # TODO: move these to 'optional types' or 'extra types'... location
+  require_relative 'attributor/types/tempfile'
+  require_relative 'attributor/types/file_upload'
+
+
+end

data/lib/attributor/attribute.rb

@@ -0,0 +1,271 @@
+# TODO: profile keys for attributes, test as frozen strings
+
+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?
+  class Attribute
+
+    attr_reader :type, :options
+
+    # @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
+      if @type.respond_to?(:options)
+        @options = @type.options.merge(@options)
+      end
+
+      check_options!
+    end
+
+    def ==(attribute)
+      raise ArgumentError, "can not compare Attribute with #{attribute.class.name}" unless attribute.kind_of?(Attribute)
+
+      self.type == attribute.type &&
+        self.options == attribute.options
+    end
+
+
+    def parse(value, context=Attributor::DEFAULT_ROOT_CONTEXT)
+      object = self.load(value,context)
+
+      errors = self.validate(object,context)
+      [ object, errors ]
+    end
+
+
+    def load(value, context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
+      value = type.load(value,context,**options) unless value.nil?
+
+      # just in case type.load(value) returned nil, even though value is not nil.
+      if value.nil?
+        value = self.options[:default] if self.options[:default]
+      end
+
+      value
+    rescue AttributorException, NameError
+      raise
+    rescue => e
+      raise Attributor::LoadError, "Error loading attribute #{Attributor.humanize_context(context)} of type #{type.name} from value #{Attributor.errorize_value(value)}\n#{e.message}"
+    end
+
+    def dump(value, **opts)
+      type.dump(value, opts)
+    end
+
+
+    def validate_type(value, context)
+      # delegate check to type subclass if it exists
+      unless self.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: #{self.type.name})"
+        return [msg]
+      end
+      []
+    end
+
+
+    TOP_LEVEL_OPTIONS = [ :description, :values, :default, :example, :required, :required_if ]
+    INTERNAL_OPTIONS = [:dsl_compiler] # Options we don't want to expose when describing attributes
+    def describe(shallow=true)
+      description = { } 
+      # Clone the common options
+      TOP_LEVEL_OPTIONS.each do |option_name|
+        description[option_name] = self.options[option_name] if self.options.has_key? option_name
+      end
+
+      # Make sure this option definition is not mistaken for the real generated example
+      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|
+        description[:options][opt_name] = self.options[opt_name]
+      end
+      # Change the reference option to the actual class name.
+      if ( reference = self.options[:reference] )
+        description[:options][:reference] = reference.name
+      end
+
+      description[:type] = self.type.describe(shallow)
+      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")
+        Random.srand(seed)
+      end
+
+      if self.options.has_key? :example
+        val = self.options[:example] 
+        case val
+        when ::String
+          # FIXME: spec this properly to use self.type.native_type
+          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
+          raise AttributorException, "unknown example attribute type, got: #{val}"
+        end
+      else
+        if (option_values = self.options[:values])
+          option_values.pick
+        else
+          if type.respond_to?(:attributes)
+            self.type.example(context, values)
+          else
+            self.type.example(context, options: self.options)
+          end
+        end
+      end
+    end
+
+
+    def attributes
+      if (@type_has_attributes ||= type.respond_to?(:attributes))
+        type.attributes
+      else
+        nil
+      end
+    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 self.validate_missing_value(context)
+      end
+
+      # TODO: support validation for other types of conditional dependencies based on values of other attributes
+
+      errors = self.validate_type(object,context)
+
+      # End validation if we don't even have the proper type to begin with
+      return errors if errors.any?
+
+      if self.options[:values] && !self.options[:values].include?(object)
+        errors << "Attribute #{Attributor.humanize_context(context)}: #{Attributor.errorize_value(object)} is not within the allowed values=#{self.options[:values].inspect} "
+      end
+
+      errors + self.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 self.options[:required]
+
+      # Missing attribute was not required if :required_if (and :required)
+      # option was NOT set
+      requirement = self.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
+      else
+        # should never get here if the option validation worked...
+        raise AttributorException.new("unknown type of dependency: #{requirement.inspect} for #{Attributor.humanize_context(context)}")
+      end
+      
+      # chop off the last part
+      requirement_context = context[0..-2]
+      requirement_context_string = requirement_context.join(Attributor::SEPARATOR)
+
+      # 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)}) "
+        end
+
+        if predicate
+          message << "matches #{predicate.inspect}."
+        else
+          message << "is present."
+        end
+
+        [message]
+      else
+        []
+      end
+    end
+
+
+    def check_options!
+      self.options.each do |option_name, option_value|
+        if self.check_option!(option_name, option_value) == :unknown
+          if self.type.check_option!(option_name, option_value) == :unknown
+            raise AttributorException.new("unsupported option: #{option_name} with value: #{option_value.inspect} for attribute: #{self.inspect}")
+          end
+        end
+      end
+
+      true
+    end
+
+
+    # TODO: override in type subclass
+    def check_option!(name, definition)
+      case name
+      when :values
+        raise AttributorException.new("Allowed set of values requires an array. Got (#{definition})") unless definition.is_a? ::Array
+      when :default
+        raise AttributorException.new("Default value doesn't have the correct attribute type. Got (#{definition.inspect})") unless self.type.valid_type?(definition) || definition.kind_of?(Proc)
+      when :description
+        raise AttributorException.new("Description value must be a string. Got (#{definition})") unless definition.is_a? ::String
+      when :required
+        raise AttributorException.new("Required must be a boolean") unless !!definition == definition # Boolean check
+        raise AttributorException.new("Required cannot be enabled in combination with :default") if definition == true && options.has_key?(:default)
+      when :required_if
+        raise AttributorException.new("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.new("Required_if cannot be specified together with :required") if self.options[:required]
+      when :example
+        unless definition.is_a?(::Regexp) || definition.is_a?(::String) || definition.is_a?(::Array) || definition.is_a?(::Proc) || definition.nil? || self.type.valid_type?(definition) 
+          raise AttributorException.new("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)")
+        end
+      else
+        return :unknown # unknown option
+      end
+
+      :ok # passes
+    end
+
+  end
+end