attributor 2.1.0

data/lib/attributor/attribute_resolver.rb

@@ -0,0 +1,116 @@
+require 'ostruct'
+
+module Attributor
+
+
+  class AttributeResolver
+    ROOT_PREFIX = '$'.freeze
+
+    class Data < ::Hash
+      include Hashie::Extensions::MethodReader
+    end
+
+    attr_reader :data
+
+    def initialize
+      @data = Data.new
+    end
+
+
+    # TODO: support collection queries
+    def query!(key_path, path_prefix=ROOT_PREFIX)
+      # If the incoming key_path is not an absolute path, append the given prefix
+      # NOTE: Need to index key_path by range here because Ruby 1.8 returns a
+      # FixNum for the ASCII code, not the actual character, when indexing by a number.
+      unless key_path[0..0] == ROOT_PREFIX
+        # TODO: prepend path_prefix to path_prefix if it did not include it? hm.
+        key_path = path_prefix + SEPARATOR + key_path
+      end
+
+      # Discard the initial element, which should always be ROOT_PREFIX at this point
+      _root, *path = key_path.split(SEPARATOR)
+
+      # Follow the hierarchy path to the requested node and return it
+      # Example path => ["instance", "ssh_key", "name"]
+      # Example @data => {"instance" => { "ssh_key" => { "name" => "foobar" } }}
+      result = path.inject(@data) do |hash, key|
+        return nil if hash.nil?
+        hash.send key
+      end
+      result
+    end
+
+
+    # Query for a certain key in the attribute hierarchy
+    #
+    # @param [String] key_path The name of the key to query and its path
+    # @param [String] path_prefix
+    #
+    # @return [String] The value of the specified attribute/key
+    #
+    def query(key_path,path_prefix=ROOT_PREFIX)
+      query!(key_path,path_prefix)
+    rescue NoMethodError => e
+      nil
+    end
+
+    def register(key_path, value)
+      if key_path.split(SEPARATOR).size > 1
+        raise AttributorException.new("can only register top-level attributes. got: #{key_path}")
+      end
+
+      @data[key_path] = value
+    end
+
+
+    # Checks that the the condition is met. This means the attribute identified
+    # by path_prefix and key_path satisfies the optional predicate, which when
+    # nil simply checks for existence.
+    #
+    # @param path_prefix [String]
+    # @param key_path [String]
+    # @param predicate [String|Regexp|Proc|NilClass]
+    #
+    # @returns [Boolean] True if :required_if condition is met, false otherwise
+    #
+    # @raise [AttributorException] When an unsupported predicate is passed
+    #
+    def check(path_prefix, key_path, predicate=nil)
+      value = self.query(key_path, path_prefix)
+
+      # we have a value, any value, which is good enough given no predicate
+      if !value.nil? && predicate.nil?
+        return true
+      end
+
+      case predicate
+      when ::String, ::Regexp, ::Integer, ::Float, ::DateTime, true, false
+        return predicate === value
+      when ::Proc
+        # Cannot use === here as above due to different behavior in Ruby 1.8
+        return predicate.call(value)
+      when nil
+        return !value.nil?
+      else
+        raise AttributorException.new("predicate not supported: #{predicate.inspect}")
+      end
+
+    end
+
+    # TODO: kill this when we also kill Taylor's IdentityMap.current
+    def self.current=(resolver)
+      Thread.current[:_attributor_attribute_resolver] = resolver
+    end
+
+
+    def self.current
+      if resolver = Thread.current[:_attributor_attribute_resolver]
+        return resolver
+      else
+        raise AttributorException, "No AttributeResolver set."
+      end
+    end
+
+  end
+
+end

data/lib/attributor/dsl_compiler.rb

@@ -0,0 +1,106 @@
+#Container of options and structure definition
+module Attributor
+
+  # RULES FOR ATTRIBUTES
+  #   The type of an attribute is:
+  #     the specified type
+  #     inferred from a reference type.
+  #       it should always end up being an anonymous type, otherwise the Model class will explode
+  #     Struct if a block is given
+
+  #   The reference option for an attribute is passed if a block is given
+
+  class DSLCompiler
+
+    attr_accessor :options, :target
+
+    def initialize(target, **options)
+      @target = target
+      @options = options
+    end
+
+    def parse(*blocks)
+      blocks.push(Proc.new) if block_given?
+      blocks.each { |block| self.instance_eval(&block) }
+      self
+    end
+
+    def attributes
+      if target.respond_to?(:attributes)
+        target.attributes
+      else
+        target.keys
+      end
+    end
+
+    def attribute(name, attr_type=nil, **opts, &block)
+      raise AttributorException, "Attribute names must be symbols, got: #{name.inspect}" unless name.kind_of? ::Symbol
+      target.attributes[name] = define(name, attr_type, **opts, &block)
+    end
+
+    def key(name, attr_type=nil, **opts, &block)
+      unless name.kind_of?(options.fetch(:key_type, Attributor::Object).native_type)
+        raise "Invalid key: #{name.inspect}, must be instance of #{options[:key_type].native_type.name}"
+      end
+      target.keys[name] = define(name, attr_type, **opts, &block)
+    end
+
+    # Creates an Attributor:Attribute with given definition.
+    #
+    # @overload define(name, type, opts, &block)
+    #   With an explicit type.
+    #   @param [symbol] name describe name param
+    #   @param [Attributor::Type] type describe type param
+    #   @param [Hash] opts describe opts param
+    #   @param [Block] block describe block param
+    #   @example
+    #     attribute :email, String, example: /[:email:]/
+    # @overload define(name, opts, &block)
+    #   Assume a type of Attributor::Struct
+    #   @param [symbol] name describe name param
+    #   @param [Hash] opts describe opts param
+    #   @param [Block] block describe block param
+    #   @example
+    #     attribute :address do
+    #       attribute :number, String
+    #       attribute :street, String
+    #       attribute :city, String
+    #       attribute :state, String
+    #     end
+    # @api semiprivate
+    def define(name, attr_type=nil, **opts, &block)
+      if (existing_attribute = attributes[name])
+        if existing_attribute.attributes
+          existing_attribute.type.attributes(&block)
+          return existing_attribute
+        end
+      end
+
+      if (reference = self.options[:reference])
+        inherited_attribute = reference.attributes[name]
+      else
+        inherited_attribute = nil
+      end
+
+      if attr_type.nil?
+        if inherited_attribute
+          attr_type = inherited_attribute.type
+          # Only inherit opts if no explicit attr_type was given.
+          opts = inherited_attribute.options.merge(opts)
+        elsif block_given?
+          attr_type = Attributor::Struct
+        else
+          raise AttributorException, "type for attribute with name: #{name} could not be determined"
+        end
+      end
+
+      if block_given? && inherited_attribute
+        opts[:reference] = inherited_attribute.type
+      end
+
+      Attributor::Attribute.new(attr_type, opts, &block)
+    end
+
+
+  end
+end

data/lib/attributor/exceptions.rb

@@ -0,0 +1,38 @@
+module Attributor
+  class AttributorException < ::StandardError
+  end
+
+  class LoadError < AttributorException
+  end
+  
+  class IncompatibleTypeError < LoadError
+    
+    def initialize(type:, value_type: , context: )
+      super "Type #{type} cannot load values of type #{value_type} while loading #{Attributor.humanize_context(context)}."
+    end
+  end
+
+  class CoercionError < LoadError
+    def initialize( context: , from: , to:, value: nil)
+      msg = "Error coercing from #{from} to #{to} while loading #{Attributor.humanize_context(context)}."
+      msg += " Received value #{Attributor.errorize_value(value)}" if value
+      super msg
+    end
+  end
+  
+  class DeserializationError < LoadError
+    def initialize( context: , from:, encoding: , value: nil)
+      msg = "Error deserializing a #{from} using #{encoding} while loading #{Attributor.humanize_context(context)}."
+      msg += " Received value #{Attributor.errorize_value(value)}" if value
+      super msg
+    end  
+  end
+  
+  class DumpError < AttributorException
+    def initialize( context: , name: , type: , original_exception: )
+      msg = "Error while dumping attribute #{name} of type #{type} for context #{Attributor.humanize_context(context)} ."
+      msg << " Reason: #{original_exception}"
+      super msg
+    end
+  end
+end

data/lib/attributor/extensions/randexp.rb

@@ -0,0 +1,10 @@
+require 'date'
+
+
+class Randgen
+  DATE_TIME_EPOCH = ::DateTime.new(2015, 1, 1, 0, 0, 0)
+
+  def self.date
+    return DATE_TIME_EPOCH - rand(800)
+  end
+end

data/lib/attributor/type.rb

@@ -0,0 +1,117 @@
+# 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...)
+  # TODO: should this be a mixin since it is an abstract class?
+  module Type
+
+    def self.included( klass )
+      klass.extend(ClassMethods)
+    end
+
+
+    module ClassMethods
+      
+      # Generic decoding and coercion of the attribute.
+      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 
+        end
+
+        value
+      end
+
+      # Generic encoding of the attribute
+      def dump(value,**opts)
+        value
+      end
+
+      # TODO: refactor this to take just the options instead of the full attribute?
+      # TODO: delegate to subclass
+      def validate(value,context=Attributor::DEFAULT_ROOT_CONTEXT,attribute)
+        errors = []
+        attribute.options.each do |option, opt_definition|
+          case option
+          when :max
+            errors << "#{Attributor.humanize_context(context)} value (#{value}) is larger than the allowed max (#{opt_definition.inspect})" unless value <= opt_definition
+          when :min
+            errors << "#{Attributor.humanize_context(context)} value (#{value}) is smaller than the allowed min (#{opt_definition.inspect})" unless value >= opt_definition
+          when :regexp
+            errors << "#{Attributor.humanize_context(context)} value (#{value}) does not match regexp (#{opt_definition.inspect})"  unless value =~ opt_definition
+          end
+        end
+        errors
+      end
+
+      # Default, overridable valid_type? function
+      def valid_type?(value)
+        return value.is_a?(native_type) if respond_to?(:native_type)
+
+        raise AttributorException.new("#{self} must implement #valid_type? or #native_type")
+      end
+
+      # Default, overridable example function
+      def example(context=nil, options:{})
+        raise AttributorException.new("#{self} must implement #example")
+        # return options[:example] if options.has_key? :example
+        # return options[:default] if options.has_key? :default
+        # if options.has_key? :values
+        #   vals = options[:values]
+        #   return vals[rand(vals.size)]
+        # end
+        # return  nil
+      end
+
+
+      # HELPER FUNCTIONS
+
+
+      def check_option!(name, definition)
+        case name
+        when :min
+          raise AttributorException.new("Value for option :min does not implement '<='. Got: (#{definition.inspect})") unless definition.respond_to?(:<=)
+        when :max
+          raise AttributorException.new("Value for option :max does not implement '>='. Got(#{definition.inspect})") unless definition.respond_to?(:>=)
+        when :regexp
+          # could go for a respoind_to? :=~ here, but that seems overly... cute... and not useful.
+          raise AttributorException.new("Value for option :regexp is not a Regexp object. Got (#{definition.inspect})") unless definition.is_a? ::Regexp
+        else
+          return :unknown
+        end
+
+        return :ok
+      end
+
+
+      def generate_subcontext(context, subname)
+        context + [subname] 
+      end
+
+      def dsl_compiler
+        DSLCompiler
+      end
+
+      # By default, non complex types will not have a DSL subdefinition this handles such case
+      def compile_dsl( options, block )
+        raise AttributorException.new("Basic structures cannot take extra block definitions") if block
+        # Simply create a DSL compiler to store the options, and not to parse any DSL
+        sub_definition=dsl_compiler.new( options )
+        return sub_definition
+      end
+
+      # Default describe for simple types...only their name (stripping the base attributor module)
+      def describe(root=false)
+        type_name = self.ancestors.find { |k| k.name && !k.name.empty? }.name
+        { :name => type_name.gsub( Attributor::MODULE_PREFIX_REGEX, '' ) }        
+      end
+      
+    end
+  end
+end

data/lib/attributor/types/boolean.rb

@@ -0,0 +1,26 @@
+# Represents a plain old boolean type. TBD: can be nil?
+#
+require_relative '../exceptions'
+
+module Attributor
+
+  class Boolean
+    include Type
+
+    def self.valid_type?(value)
+      value == true || value == false
+    end
+
+    def self.example(context=nil, options: {})
+      [true, false].sample
+    end
+
+    def self.load(value,context=Attributor::DEFAULT_ROOT_CONTEXT, **options)
+      raise CoercionError, context: context, from: value.class, to: self, value: value  if value.is_a?(::Float)
+      return false if [ false, 'false', 'FALSE', '0', 0, 'f', 'F' ].include?(value)
+      return true if [ true, 'true', 'TRUE', '1', 1, 't', 'T' ].include?(value)
+      raise CoercionError, context: context, from: value.class, to: self
+    end
+  end
+end
+

data/lib/attributor/types/collection.rb

@@ -0,0 +1,135 @@
+# Represents an unordered collection of attributes
+#
+
+module Attributor
+
+  class Collection
+    include Container
+
+    # @param type [Attributor::Type] optional, defines the type of all collection members
+    # @return anonymous class with specified type of collection members
+    #
+    # @example Collection.of(Integer)
+    #
+    def self.of(type)
+      resolved_type = Attributor.resolve_type(type)
+      unless resolved_type.ancestors.include?(Attributor::Type)
+        raise Attributor::AttributorException.new("Collections can only have members that are Attributor::Types")
+      end
+      Class.new(self) do
+        @member_type = resolved_type
+      end
+    end
+
+    def self.native_type
+      return ::Array
+    end
+
+    def self.member_type
+      @member_type ||= Attributor::Object
+    end
+
+    def self.member_attribute
+      @member_attribute ||= begin
+        self.construct(nil,{})
+        @member_attribute
+      end
+    end
+
+
+    # generates an example Collection
+    # @return An Array of native type objects conforming to the specified member_type
+    def self.example(context=nil, options: {})
+      result = []
+      size = rand(3) + 1
+      context ||= ["Collection-#{result.object_id}"]
+
+      size.times do |i|
+        subcontext = context + ["at(#{i})"]
+        result << self.member_attribute.example(subcontext)
+      end
+
+      result
+    end
+
+
+    # The incoming value should be an array 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?
+        return nil
+      elsif value.is_a?(Enumerable)
+        loaded_value = value
+      elsif value.is_a?(::String)
+        loaded_value = decode_string(value,context)
+      else
+        raise Attributor::IncompatibleTypeError, context: context, value_type: value.class, type: self 
+      end
+
+      return loaded_value.collect { |member| self.member_attribute.load(member,context) }
+    end
+
+
+    def self.decode_string(value,context)
+      decode_json(value,context)
+    end
+
+
+    def self.dump(values, **opts)
+      return nil if values.nil?
+      values.collect { |value| member_attribute.dump(value,opts) }
+    end
+
+    def self.describe(shallow=false)
+      #puts "Collection: #{self.type}"      
+      hash = super(shallow)
+      hash[:options] = {} unless hash[:options]
+      hash[:options][:member_attribute] = self.member_attribute.describe
+      hash
+    end
+
+    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]
+      end
+      
+      # create the member_attribute, passing in our member_type and whatever constructor_block is.
+      # that in turn will call construct on the type if applicable.
+      @member_attribute = Attributor::Attribute.new self.member_type, member_options, &constructor_block
+
+      # overwrite our type with whatever type comes out of the attribute
+      @member_type = @member_attribute.type
+
+      return self
+    end
+
+
+    def self.check_option!(name, definition)
+      # TODO: support more options like :max_size
+      case name
+      when :reference
+      when :member_options
+      else
+        return :unknown
+      end
+
+      :ok
+    end
+
+    # @param values [Array] Array of values to validate
+    def self.validate(values, context=Attributor::DEFAULT_ROOT_CONTEXT, attribute=nil)
+      values.each_with_index.collect do |value, i|
+        subcontext = context + ["at(#{i})"]
+        self.member_attribute.validate(value, subcontext)
+      end.flatten.compact
+    end
+
+    def self.validate_options( value, context, attribute )
+      errors = []
+      errors
+    end
+
+  end
+end