mixture 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2be9a2d68accc0bae55d6a86edac6d0d0d0fd034
-  data.tar.gz: 28db784d61898c2f4bfc5ed546f5644724ea627f
+  metadata.gz: 3e1746012422c7e9f856706e2820d0423f404784
+  data.tar.gz: 0591ce1acb37f9805c37b06298bf7f4c10c4f3f7
 SHA512:
-  metadata.gz: 88764ff3ef98d101f7acc87221cb715a9544a47bc330dc679a07bf9ec0696c1eb8bd1d792ccb7f9e602418289d40416195cd26b62b06011ac4cd0370bc46a3c3
-  data.tar.gz: 9fcfa02187da824b8d21eb726526230f178f5c48ec9eb2f638d3214bd08a29d22f5aeb740a7be9278ab4ffc780c1161ae4b1eb8a76d6afd0c1a8ab1da0602e18
+  metadata.gz: 6a2b4634e7d03ef8ed5e8c4730895e497bd1c98307f87f012f27ab4d4a1d401912076c39b366194d52cdeaf1f9beb2dcf673c57729b6f8f679a0656bb39280f1
+  data.tar.gz: a15206cb105329873a6890deeb46d8aa797385835315568a427c3e98272a8d3862f3af158777a9afbe077c546621b3af42b89ac7427a1a2e5bc073558407669e

data/.gitignore

@@ -8,3 +8,4 @@
 /spec/reports/
 /tmp/
 /spec/examples.txt
+/.rbenv-gemsets

data/.travis.yml

@@ -4,3 +4,6 @@ rvm:
   - 2.1.0
   - 1.9.3
   - rbx
+script:
+  - bundle exec rubocop --format clang
+  - bundle exec rspec spec

data/Gemfile.lock

@@ -1,11 +1,14 @@
 PATH
   remote: .
   specs:
-    mixture (0.1.0)
+    mixture (0.2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    ast (2.0.0)
+    astrolabe (1.3.0)
+      parser (>= 2.2.0.pre.3, < 3.0)
     coderay (1.1.0)
     coveralls (0.8.2)
       json (~> 1.8)
@@ -23,10 +26,14 @@ GEM
     method_source (0.8.2)
     mime-types (2.6.1)
     netrc (0.10.3)
+    parser (2.2.2.6)
+      ast (>= 1.1, < 3.0)
+    powerpack (0.1.1)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
+    rainbow (2.0.0)
     rake (10.4.2)
     rest-client (1.8.0)
       http-cookie (>= 1.0.2, < 2.0)
@@ -45,6 +52,13 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.3.0)
     rspec-support (3.3.0)
+    rubocop (0.32.1)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.2.5, < 3.0)
+      powerpack (~> 0.1)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.7.5)
     simplecov (0.10.0)
       docile (~> 1.1.0)
       json (~> 1.8)
@@ -69,6 +83,7 @@ DEPENDENCIES
   pry
   rake
   rspec
+  rubocop
 
 BUNDLED WITH
    1.10.5

data/README.md

@@ -1,5 +1,7 @@
 # Mixture
 
+[![Build Status](https://travis-ci.org/medcat/mixture.svg?branch=master)](https://travis-ci.org/medcat/mixture) [![Coverage Status](https://coveralls.io/repos/medcat/mixture/badge.svg?branch=master&service=github)](https://coveralls.io/github/medcat/mixture?branch=master) [![Gem Version](https://badge.fury.io/rb/mixture.svg)](http://badge.fury.io/rb/mixture)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -12,22 +14,106 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+## Usage
 
-    $ gem install mixture
+It's simple, really.
 
-## Usage
+```ruby
+module MyLibrary
+  class MyClass
+    include Mixture::Model
+  end
+end
+```
+
+This provides a few simple things.  First off, it provides the
+`.attribute` class method.  The attribute class method allows you to
+define an attribute on your class.  Attributes use the instance
+variables just like `attr_reader`/`attr_writer` do - but it also
+allows coercion on assignment, as well.  Defining an attribute is as
+simple as `attribute :name`.  This provides the `:name` and `:name=`
+methods on the instance.
+
+You also get access to the `#attributes=`, `#attributes`, and
+`#attribute` instance methods.  The first group assigns attributes,
+running it through any update callbacks defined.  The second retrieves
+the attributes on the instance, even if they weren't assigned.  The
+last provides easy get/set functionality.
+
+If you want to take advantage of the coercion abilities, just add a
+`:type` key to the options for the attribute:
+
+```ruby
+module MyLibrary
+  class MyClass
+    include Mixture::Model
+
+    attribute :name, type: String
+  end
+end
+```
 
-TODO: Write usage instructions here
+This will automagically cause `name` to be coerced to a string on
+assignment.
 
-## Development
+For validation, use the `.validate` class method:
 
-To install this gem onto your local machine, run
-`bundle exec rake install`. To release a new version, update the
-version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the
-version, push git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+```ruby
+module MyLibrary
+  class MyClass
+    include Mixture::Model
+    attribute :name, type: String
+    validate :name, format: /^.{3,20}$/
+  end
+end
+```
+
+Some validators are available by default:
+
+- `:exclusion` - Validates that the value for the attribute is not
+  within a given set of values.
+- `:inclusion` - Validates that the value for the attribute _is_
+  within a given set of values.
+- `:length` - Validates that the value for the attribute is within a
+  certain length.
+- `:match` - Validates that the value for the attribute matches a
+  regular expression.  This is also known as `:format`.
+- `:presence` - Validates that the value is not nil and isn't empty
+  (by checking for `#empty?`).
+
+Adding a validator is simple:
+
+```ruby
+module MyLibrary
+  class MyValidator < Mixture::Validate::Base
+    # This registers it with Mixture, so it can be used within a
+    # `validate` call.
+    register_as :my_validator
+
+    def validate(record, attribute, value)
+      # this sets instance variables mapping the above arguments.
+      super
+      my_super_awesome_validation
+    end
+  end
+end
+```
+
+Adding a coercer is also simple:
+
+```ruby
+module MyLibrary
+  module Coerce
+    class MyObject < Mixture::Coerce::Base
+      type Mixture::Type[MyLibrary::MyObject]
+
+      coerce_to(Mixture::Type::Array) do |value|
+        value.to_a
+      end
+    end
+  end
+end
+```
 
 ## Contributing
 

data/lib/mixture/attribute.rb

@@ -3,27 +3,62 @@
 module Mixture
   # An attribute for a mixture object.
   class Attribute
+    # The name of the attribute.
+    #
+    # @return [Symbol]
     attr_reader :name
+
+    # The options for the attribute.  This is mainly used for coercion
+    # and validation.
+    #
+    # @return [Hash]
     attr_reader :options
 
+    # Initialize the attribute.
+    #
+    # @param name [Symbol] The name of the attribute.
+    # @param list [AttributeList] The attribute list this attribute is
+    #   a part of.
+    # @param options [Hash] The optiosn for the attribute.
     def initialize(name, list, options = {})
       @name = name
       @list = list
       @options = options
     end
 
+    # Update the attribute with the given value.  It runs the value
+    # through the callbacks, and returns a new value given by the
+    # callbacks.
+    #
+    # @param value [Object] The new value.
+    # @return [Object] The new new value.
     def update(value)
       @list.callbacks[:update].inject(value) { |a, e| e.call(self, a) }
     end
 
+    # The instance variable for this attribute.
+    #
+    # @example
+    #   attribute.ivar # => :@name
+    # @return [Symbol]
     def ivar
       @_ivar ||= :"@#{@name}"
     end
 
+    # The getter method for this attribute.
+    #
+    # @example
+    #   attribute.getter # => :name
+    # @return [Symbol]
     def getter
       @name
     end
 
+    # The setter method for this attribute.
+    #
+    # @example
+    #   attribute.setter # :name=
+    # @return [Symbol]
     def setter
       @_setter ||= :"#{@name}="
     end

data/lib/mixture/attribute_list.rb

@@ -3,7 +3,8 @@
 require "forwardable"
 
 module Mixture
-  # A list of attributes.
+  # A list of attributes.  This is used instead of a hash in order to
+  # add in the {#options} and {#callbacks}.
   class AttributeList
     extend Forwardable
     # If it looks like a duck...
@@ -13,15 +14,30 @@ module Mixture
     # Then it must be a duck.
     delegate [:fetch, :[], :[]=, :key?, :each, :<=>] => :@list
 
+    # Returns a set of options used for the attributes.  This isn't
+    # used at the moment.
+    #
+    # @return [Hash{Symbol => Object}]
     attr_reader :options
+
+    # Returns a set of callbacks.  This is used for coercion, but may
+    # be used for other things.
+    #
+    # @return [Hash{Symbol => Array<Proc>}]
     attr_reader :callbacks
 
+    # Initializes the attribute list.
     def initialize
       @list = {}
       @options = {}
       @callbacks = Hash.new { |h, k| h[k] = [] }
     end
 
+    # Creates a new attribute with the given name and options.
+    #
+    # @param name [Symbol] The name of the attribute.
+    # @param options [Hash] The options for the attribute.
+    # @return [Attribute]
     def create(name, options = {})
       @list[name] = Attribute.new(name, self, options)
     end

data/lib/mixture/coerce/base.rb

@@ -8,15 +8,15 @@ module Mixture
     # type, and the instance handles the "to".
     class Base
       include Singleton
-      # @!method type
+
+      # @overload type()
       #   Returns the type this instance corresponds to.
       #
       #   @return [Mixture::Type]
-      #
-      # @!method type(value)
+      # @overload type(value)
       #   Sets the type this instance corresponds to.
       #
-      #   @param [Mixture::Type]
+      #   @param value [Mixture::Type]
       #   @return [void]
       def self.type(value = Undefined)
         if value == Undefined
@@ -26,10 +26,40 @@ module Mixture
         end
       end
 
+      # The coercions that this class has.  It's a map of the type
+      # to the method that performs that coercion.
+      #
+      # @return [Hash{Mixture::Type => Symbol}]
       def self.coercions
         @_coercions ||= {}
       end
 
+      # This is a DSL for the class itself.  It essentially defines a
+      # method to perform the coercion of the given type.
+      #
+      # @overload coerce_to(to) { }
+      #   This is a DSL for the class itself.  It essentially defines
+      #   a method to perform the coercion of the given type.
+      #
+      #   @param to [Mixture::Type] The type to coerce to.
+      #   @yield [value] The block is called with the value to coerce
+      #     when coercion needs to happen.  Note that the block is not
+      #     used as the body of the method - the method returns the
+      #     block.
+      #   @yieldparam value [Object] The object to coerce.
+      #   @yieldreturn [Object] The coerced value.
+      #   @return [void]
+      #
+      # @overload coerce_to(to, value)
+      #   This is a DSL for the class itself.  It essentially defines
+      #   a method to perform the coercion of the given type.
+      #
+      #   @param to [Mixture::Type] The type to coerce to.
+      #   @param value [Proc] The block that is called with the value
+      #     for coercion.  This block is returned by the defined
+      #     coercion method.
+      #   @return [void]
+      #
       def self.coerce_to(to, value = Undefined, &block)
         fail ArgumentError, "Expected Mixture::Type, got #{to.class}" unless
           to.is_a?(Mixture::Type)
@@ -47,10 +77,17 @@ module Mixture
         define_method(to.method_name) { body }
       end
 
+      # (see #to)
       def self.to(type)
         instance.to(type)
       end
 
+      # Returns a block to perform the coercion to the given type.
+      # If it cannot find a coercion, it raises {CoercionError}.
+      #
+      # @param type [Mixture::Type] The type to coerce to.
+      # @raise [CoercionError] If it could not find the coercion.
+      # @return [Proc{(Object) => Object}]
       def to(type)
         method_name = self.class.coercions.fetch(type) do
           fail CoercionError,

data/lib/mixture/coerce/object.rb

@@ -6,6 +6,10 @@ module Mixture
     class Object < Base
       type Type::Object
 
+      # Tries a set of methods on the object, before failing with a
+      # coercion error.
+      #
+      # @return [Proc{(Symbol) => Proc{(Object) => Object}}]
       TryMethods = proc do |*methods|
         proc do |value|
           method = methods.find { |m| value.respond_to?(m) }

data/lib/mixture/coerce.rb

@@ -18,7 +18,7 @@ require "mixture/coerce/time"
 module Mixture
   # Handles coercion of objects.
   module Coerce
-    # Registers a coercion with the module.  This uses the {COERCERS}
+    # Registers a coercion with the module.  This uses the {.coercers}
     # constant.
     #
     # @param coercion [Mixture::Coerce::Base] The coercer to register.

data/lib/mixture/errors.rb

@@ -9,6 +9,7 @@ module Mixture
   class CoercionError < BasicError
   end
 
+  # Occurs when a validation fails.
   class ValidationError < BasicError
   end
 end

data/lib/mixture/extensions/attributable.rb

@@ -6,6 +6,13 @@ module Mixture
     module Attributable
       # The class methods for attribution.
       module ClassMethods
+        # Defines an attribute.  Defines the getter and the setter for
+        # for the attribute, the getter and setter alias to the
+        # {#attribute}.
+        #
+        # @param name [Symbol] The name of the attribute.
+        # @param options [Hash] The options for the attribute.
+        # @return [Attribute] The new attribute.
         def attribute(name, options = {})
           name = name.to_s.intern
           attr = attributes.create(name, options)
@@ -14,6 +21,10 @@ module Mixture
           attr
         end
 
+        # The attribute list.  Acts as a hash for the attributes.
+        #
+        # @see AttributeList
+        # @return [AttributeList]
         def attributes
           @_attributes ||= AttributeList.new
         end
@@ -21,21 +32,54 @@ module Mixture
 
       # The instance methods for attribution.
       module InstanceMethods
-        # Sets the attributes on the instance.
+        # Sets the attributes on the instance.  It iterates through
+        # the given hash and uses {#attribute} to set the key, value
+        # pair.
+        #
+        # @param attrs [Hash] The attributes to set.
+        # @return [void]
         def attributes=(attrs)
           attrs.each { |key, value| attribute(key, value) }
         end
 
+        # The attributes defined on this instance.  It returns a
+        # hash containing the key-value pairs for each attribute.
+        #
+        # @return [Hash{Symbol => Object}]
         def attributes
           Hash[self.class.attributes.map do |name, attr|
             [name, instance_variable_get(attr.ivar)]
           end]
         end
 
+        # Called when an unknown attribute is accessed using
+        # {#attribute}.  By default, it just raises an `ArgumentError`.
+        #
+        # @param attr [Symbol] The attribute.
+        # @raise [ArgumentError]
         def unknown_attribute(attr)
           fail ArgumentError, "Unknown attribute #{attr} passed"
         end
 
+        # @overload attribute(key)
+        #   Accesses an attribute by the given key name.  If the
+        #   attribute could not be found, it calls
+        #   {#unknown_attribute}.  It uses the instance variable value
+        #   of the attribute as the value of the attribute (e.g. it
+        #   uses `@name` for the `name` attribute).
+        #
+        #   @param key [Symbol] The name of the attribute.
+        #   @return [Object] The value of the attribute.
+        # @overload attribute(key, value)
+        #   Sets an attribute value by the given key name.  If the
+        #   attribute could not be found, it calls
+        #   {#unknown_attribute}.  It calls any of the update
+        #   callbacks via {Attribute#update}, and sets the instance
+        #   variable for the attribute.
+        #
+        #   @param key [Symbol] The name of the attribute.
+        #   @param value [Object] The new value of the attribute.
+        #   @return [void]
         def attribute(key, value = Undefined)
           attr = self.class.attributes.fetch(key) do
             return unknown_attribute(key)

data/lib/mixture/extensions/coercable.rb

@@ -4,6 +4,14 @@ module Mixture
   module Extensions
     # Extends the attribute definition to allow coercion.
     module Coercable
+      # Performs the coercion for the attribute and the value.
+      # It is used in a `:update` callback.
+      #
+      # @param attribute [Attribute] The attribute
+      # @param value [Object] The new value.
+      # @return [Object] The new new value.
+      # @raise [CoercionError] If an error occurs while a coercion is
+      #   running.
       def self.coerce_attribute(attribute, value)
         return value unless attribute.options[:type]
         attr_type = Type.infer(attribute.options[:type])

data/lib/mixture/extensions/hashable.rb

@@ -10,25 +10,82 @@ module Mixture
       include Enumerable
       include Comparable
 
-      delegate [:each, :<=>] => :attributes
+      # The methods that are mapped directly to the {#to_hash} method.
+      #
+      # @return [Array<Symbol>]
+      MAPPED_METHODS = %w(
+        each <=> keys values each_key each_value has_value? value?
+        size length empty? each_pair
+      ).map(&:intern)
 
+      delegate MAPPED_METHODS => :attributes
+
+      # Alias for {Attributable::InstanceMethods#attribute}.
+      #
+      # @param (see Attributable::InstanceMethods#attribute)
+      # @return (see Attributable::InstanceMethods#attribute)
       def [](key)
         attribute(key.to_s.intern)
       end
 
+      # Alias for {Attributable::InstanceMethods#attribute}.
+      #
+      # @param (see Attributable::InstanceMethods#attribute)
+      # @return (see Attributable::InstanceMethods#attribute)
       def []=(key, value)
         attribute(key.to_s.intern, value)
       end
+      alias_method :store, :[]=
+
+      # (see Attributable::InstanceMethods#attributes)
+      def to_hash
+        attributes
+      end
+      alias_method :to_h, :to_hash
 
+      # Checks for an attribute with the given name.
+      #
+      # @param key [Symbol] The name of the attribute to check.
+      # @return [Boolean]
       def key?(key)
         self.class.attributes.key?(key.to_s.intern)
       end
+      alias_method :has_key?, :key?
 
-      def fetch(key, default = Unknown)
+      # @overload fetch(key)
+      #   Performs a fetch.  This acts just like Hash's `fetch`.
+      #
+      #   @param key [Symbol] The key to check for an attribute.
+      #   @raise [KeyError] If the key isn't present.
+      #   @return [Object] The attribute's value.
+      # @overload fetch(key, default)
+      #   Performs a fetch.  This acts just like Hash's fetch.  If
+      #   the attribute doesn't exist, the default argument value is
+      #   used as a value instead.
+      #
+      #   @param key [Symbol] The key to check for an attribute.
+      #   @param default [Object] The value to use instead of an
+      #     error.
+      #   @return [Object] The attribute's value, or the default value
+      #     instead.
+      # @overload fetch(key) { }
+      #   Performs a fetch.  This acts just like Hash's fetch.  If
+      #   the attribute doesn't exist, the value of the block is used
+      #   as a value instead.
+      #
+      #   @param key [Symbol] The key to check for an attribute.
+      #   @yield [key] The block is called if an attribute does not
+      #     exist.
+      #   @yieldparam key [Symbol] The key of the non-existant
+      #     attribute.
+      #   @yieldreturn [Object] Return value of the method.
+      #   @return [Object] The attribute's value, or the block's
+      #     value instead.
+      def fetch(key, default = Undefined)
         case
         when key?(key.to_s.intern) then attribute(key.to_s.intern)
         when block_given?          then yield(key.to_s.intern)
-        when default != Unknown    then default
+        when default != Undefined  then default
         else fail KeyError, "Undefined attribute #{key.to_s.intern}"
         end
       end

data/lib/mixture/extensions/validatable.rb

@@ -10,6 +10,13 @@ module Mixture
         # Creates a new validation for the given attribute.  The
         # attribute _must_ be defined before this call, otherwise it
         # _will_ error.
+        #
+        # @param name [Symbol] The name of the attribute to validate.
+        # @param options [Hash] The options for validation.  This is
+        #   normally a key-value pair, where the key is the name of
+        #   the validator, and the value is the options to pass to
+        #   the validator.
+        # @return [void]
         def validate(name, options = {})
           attributes.fetch(name).options[:validate] = options
         end
@@ -17,7 +24,10 @@ module Mixture
 
       # The instance methods.
       module InstanceMethods
-        # Validates the attributes on the record.
+        # Validates the attributes on the record.  This will fill up
+        # {#errors} with errors, if there are any.
+        #
+        # @return [Boolean]
         def valid?
           @errors = Hash.new { |h, k| h[k] = [] }
           self.class.attributes.each do |name, attribute|
@@ -27,10 +37,18 @@ module Mixture
           !@errors.values.any?(&:any?)
         end
 
+        # Opposite of valid.
+        #
+        # @see #valid?
+        # @return [Boolean]
         def invalid?
           !valid?
         end
 
+        # Returns a hash, mapping attributes to the errors that they
+        # have.
+        #
+        # @return [Hash{Attribute => Array<ValidationError>}]
         def errors
           @errors ||= Hash.new { |h, k| h[k] = [] }
         end

data/lib/mixture/extensions.rb

@@ -5,14 +5,29 @@ module Mixture
   # extensions, so that extensions can be referend by a name instead
   # of the constant.
   module Extensions
+    # Registers an extension with the module.  This maps a name to
+    # an extension.  Extensions may be registered multiple times,
+    # with different names.
+    #
+    # @param name [Symbol] The name of the extension to register.
+    # @param extension [Module] The module to register.
     def self.register(name, extension)
       extensions[name.to_s.downcase.intern] = extension
     end
 
+    # Loads an extension with the given name.  If it cannot find the
+    # matching extension, it raises a `KeyError`.
+    #
+    # @param name [Symbol] The name of the extension.
+    # @return [Module] The corresponding extension.
+    # @raise [KeyError]
     def self.[](name)
       extensions.fetch(name)
     end
 
+    # The extensions that are registered with this module.
+    #
+    # @return [Hash{Symbol => Module}]
     def self.extensions
       @_extensions ||= {}
     end

data/lib/mixture/model.rb

@@ -6,8 +6,29 @@ module Mixture
   # @example
   #   class MyClass
   #     include Mixture::Model
-  #     mixture_modules :attributable, :hashable
+  #     mixture_modules :attribute, :hash
   #   end
   module Model
+    # The class methods for the module.
+    module ClassMethods
+      # Used to include certain extensions.
+      #
+      # @see Extensions.[]
+      # @param mods [Symbol] The mod name to include.
+      # @return [void]
+      def mixture_modules(*mods)
+        mods.each do |mod|
+          include Extensions[mod]
+        end
+      end
+    end
+
+    # A method used internally by ruby.
+    #
+    # @api private
+    def self.included(base)
+      base.extend ClassMethods
+      base.mixture_modules(:attribute, :coerce, :validate)
+    end
   end
 end

data/lib/mixture/type.rb

@@ -8,14 +8,31 @@ module Mixture
   class Type
     extend Forwardable
     @instances = {}
+    # A class to represent the Boolean type (i.e. true, false), since
+    # ruby doesn't have a Boolean class.
+    #
+    # @return [Class]
     BooleanClass = Class.new
-    InstanceClass = Class.new
 
+    # Ancestors that two classes might have in common with each other.
+    #
+    # @return [Array<Module, Class>]
+    COMMON_ANCESTORS = BooleanClass.ancestors - [BooleanClass]
+
+    # The builtin types of Ruby.  These are initialized as types
+    # before anything else happens.
+    #
+    # @return [Array<Symbol>]
     BUILTIN_TYPES = %w(
       Object Array Hash Integer Rational Float Set String Symbol
       Time Date DateTime
     ).map(&:intern).freeze
 
+    # The aliases for types.  This overrides any other possible
+    # inferences that this class can make.  For example, `true` and
+    # `false` are automatically mapped to `BooleanClass`.
+    #
+    # @return [Hash{Object, Symbol => Class}]
     TYPE_ALIASES = {
       true => BooleanClass,
       false => BooleanClass,
@@ -44,7 +61,7 @@ module Mixture
     private_class_method :new
 
     # Returns a {Type} from a given class.  It assumes that the type
-    # given is a class, and passes it to {#new} - which will error if
+    # given is a class, and passes it to `#new` - which will error if
     # it isn't.
     #
     # @param type [Class] A type.
@@ -61,12 +78,10 @@ module Mixture
     end
 
     # Determines the best type that represents the given value.  If
-    # the given value is a {Type}, it returns the value.  If the
-    # given value is already defined as a {Type}, it returns the
-    # {Type}.  If the value's class is already defined as a {Type},
-    # it returns the class's {Type}; otherwise, it returns the types
-    # for Class and Object, depending on if the value is a Class or
-    # not, respectively.
+    # the given type is listed in {TYPE_ALIASES}, it uses the alias
+    # value for a lookup.  If the given type is a {Type}, it returns
+    # the type.  If the given type is a `Class`, it uses {.infer_class}.
+    # Otherwise, it uses {.infer_class} on the type's class.
     #
     # @example
     #   Mixture::Type.infer(Integer) # => Mixture::Type::Integer
@@ -75,7 +90,7 @@ module Mixture
     #   Mixture::Type.infer(1) # => Mixture::Type::Integer
     #
     # @example
-    #   Mixture::Type.infer(MyClass) # => Mixture::Type::Instance
+    #   Mixture::Type.infer(MyClass) # => Mixture::Type[MyClass]
     #
     # @example
     #   Mixture::Type.infer(Object.new) # => Mixture::Type::Object
@@ -91,15 +106,28 @@ module Mixture
       end
     end
 
+    # Infer a classes' type.  If the class is a type, it returns the
+    # type.  Otherwise, it checks the most basic ancestors (most basic
+    # ancestors being any ancestors not shared with a new class) for
+    # any classes that have a {Type}; if there are none, it creates a
+    # new type from the class.
+    #
+    # @param klass [Class] The class to infer type from.
+    # @return [Mixture::Type]
     def self.infer_class(klass)
       if klass.is_a?(Type)
         klass
       else
-        basic_ancestors = klass.ancestors - ancestors
+        basic_ancestors = klass.ancestors - COMMON_ANCESTORS
         from(basic_ancestors.find { |a| @instances.key?(a) } || klass)
       end
     end
 
+    # Loads the builtin types.  This includes `Boolean` and `Nil`.
+    #
+    # @see BUILTIN_TYPES
+    # @see BooleanClass
+    # @return [void]
     def self.load
       BUILTIN_TYPES.each do |sym|
         const_set(sym, from(::Object.const_get(sym)))
@@ -107,14 +135,24 @@ module Mixture
 
       @instances[BooleanClass] = new(BooleanClass, name: "Boolean")
       const_set("Boolean", @instances[BooleanClass])
-      @instances[InstanceClass] = new(InstanceClass, name: "Instance")
-      const_set("Instance", @instances[InstanceClass])
       @instances[NilClass] = new(NilClass, name: "Nil")
       const_set("Nil", @instances[NilClass])
     end
 
+    # The name of the type.  If this wasn't provided upon
+    # initialization, it is guessed to be the class's name, which is
+    # normally good enough.
+    #
+    # @return [String]
     attr_reader :name
 
+    # Initialize the type.  The class given _must_ be a class;
+    # otherwise, it will error.  A name can be provided as an option.
+    #
+    # @param type [Class] The type to create.
+    # @param options [Hash{Symbol => Object}] The options.
+    # @option options [String] :name The name to provide the type
+    #   with.  If this is not provided, it uses the class name.
     def initialize(type, options = {})
       fail ArgumentError, "Expected a Class, got #{type.class}" unless
         type.is_a?(Class)
@@ -122,11 +160,19 @@ module Mixture
       @name = options.fetch(:name, @type.name)
     end
 
+    # Creates a string representation of the type.  This normally has
+    # the format `Mixture::Type(Class)`, where `Class` is the class.
+    #
+    # @return [String]
     def to_s
       "#{self.class.name}(#{@name})"
     end
     alias_method :inspect, :to_s
 
+    # Creates a `:to_` method name for the type.
+    #
+    # @example
+    #   Mixture::Type[Array].method_name # => :to_array
     def method_name
       @_method_name ||= begin
         body = name

data/lib/mixture/validate/base.rb

@@ -2,17 +2,47 @@
 
 module Mixture
   module Validate
+    # A base for validations.  All validators should inherit this
+    # class.
+    #
+    # @abstract
     class Base
+      # Registers this validator as the given name.
+      #
+      # @see Validate.register
+      # @param name [Symbol] The name of the validator.
+      # @return [void]
+      def self.register_as(name)
+        Validate.register(name, self)
+      end
+
+      # Initialize the validator.
+      #
+      # @param options [Hash] The options for the validator.
       def initialize(options)
         @options = options
       end
 
+      # Performs the validation.
+      #
+      # @param record [Mixture::Model] The model that has the
+      #   attribute.  At least, it should respond to `#errors`.
+      # @param attribute [Attribute] The attribute to validate.
+      # @param value [Object] The value of the attribute.
+      # @return [void]
+      # @abstract
       def validate(record, attribute, value)
         @record = record
         @attribute = attribute
         @value = value
       end
 
+      private
+
+      # Raises an error with the given a message.
+      #
+      # @param message [String] The message to raise.
+      # @raise [ValidationError]
       def error(message)
         fail ValidationError, message
       end

data/lib/mixture/validate/exclusion.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Mixture
+  module Validate
+    # Checks to make sure that the value isn't in the given set.  This
+    # uses the `#includes?` method on the `@options`.
+    class Exclusion < Base
+      register_as :exclusion
+      # Performs the validation.
+      #
+      # @param (see Base#validate)
+      # @return (see Base#validate)
+      def validate(record, attribute, value)
+        super
+        error("Value is in the given set") if
+          @options[:in].include?(value)
+      end
+    end
+  end
+end

data/lib/mixture/validate/inclusion.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+
+module Mixture
+  module Validate
+    # Checks to make sure that the value is in the given set.  This
+    # uses the `#includes?` method on the `@options`.
+    class Inclusion < Base
+      register_as :inclusion
+      # Performs the validation.
+      #
+      # @param (see Base#validate)
+      # @return (see Base#validate)
+      def validate(record, attribute, value)
+        super
+        error("Value isn't in the given set") unless
+          @options[:in].include?(value)
+      end
+    end
+  end
+end

data/lib/mixture/validate/length.rb

@@ -0,0 +1,109 @@
+# encoding: utf-8
+
+module Mixture
+  module Validate
+    # Validates the length of an attribute.
+    class Length < Base
+      register_as :length
+      # Validates the length of the value.  It first composes an
+      # acceptable range, and then determines if the length is within
+      # that acceptable range.  If either components error, the
+      # validation fails.
+      #
+      # @param (see Base#validate)
+      # @return [void]
+      def validate(record, attribute, value)
+        super
+        error("Length is not acceptable") unless acceptable.cover?(length)
+      end
+
+      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/CyclomaticComplexity
+      # rubocop:disable Metrics/PerceivedComplexity
+
+      # Determines the acceptable range that the length ca nbe in.
+      # This first turns the options into a hash via {#to_hash}, and
+      # then checks the hash.
+      #
+      # @option options [Range] :in If this is provided, it is used
+      #   as the acceptable range.
+      # @option options [Numeric] :is If this is provided, it is used
+      #   as an exact match.
+      # @option options [Numeric] :maximum If this is provided without
+      #   `:minimum`, it is set as the upper limit on the length (i.e.
+      #   it is equivalent to `in: 0..maximum`).  If it is provided
+      #   with `:minimum`, it is the upper limit (i.e. equivalent to
+      #   `in: minimum..maximum`).
+      # @option options [Numeric] :minimum If this is provided without
+      #   `:maximum`, it is set as the lower limit on the length (i.e.
+      #   equivalent to `in: minimum..Float::INFINITY`).  If it is
+      #   provided with `:maximum`, it is the lower limit (i.e.
+      #   equivalent to `in: minimum..maximum`).
+      # @note If it is unable to find any of the options, or unable to
+      #   turn the given value into a hash, it will raise a
+      #   {ValidationError}.  This means validation will fail, even if
+      #   the value may be valid.
+      # @return [Range]
+      # @see #to_hash
+      def acceptable
+        @_acceptable ||= begin
+          options = to_hash(@options)
+
+          if options.key?(:in)         then options[:in]
+          elsif options.key?(:is)      then options[:is]..options[:is]
+          elsif options.key?(:maximum) && options.key?(:minimum)
+            options[:minimum]..options[:maximum]
+          elsif options.key?(:maximum) then 0..options[:maximum]
+          elsif options.key?(:minimum) then options[:minimum]..Float::INFINITY
+          else
+            error("Unable to determine acceptable range")
+          end
+        end
+      end
+
+      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/CyclomaticComplexity
+      # rubocop:enable Metrics/PerceivedComplexity
+
+      # Turns any other recoginizable value into a hash that
+      # {#acceptable} can use.  The mappings go as follows:
+      #
+      # - `Range`: turns into `{ in: value }`.
+      # - `Numeric`: turns into `{ in: value..value }`
+      # - `Array`: turns into `{ in: value[0]..value[1] }`
+      # - `Hash`: turns into itself.
+      #
+      # Any other class/value causes an error.
+      #
+      # @param value [Object] The value to turn into a hash.
+      # @return [Hash]
+      # @raise [ValidationError] If it can't turn into a hash.
+      def to_hash(value)
+        case value
+        when Range   then { in: value }
+        when Numeric then { in: value..value }
+        when Array   then { in: value[0]..value[1] }
+        when Hash    then value
+        else
+          error("Unable to determine acceptable range")
+        end
+      end
+
+      # Attempts to get the value of the length.  It tries the
+      # `#size`, `#length`, and finally, `#count`; if it can't
+      # find any of these, it raises an error.
+      #
+      # @return [Numeric] The length.
+      # @raise [ValidationError] If it cannot determine the length of
+      #   the value.
+      def length
+        case
+        when @value.respond_to?(:size)    then @value.size
+        when @value.respond_to?(:length)  then @value.length
+        when @value.respond_to?(:count)   then @value.count
+        else error("Value isn't countable")
+        end
+      end
+    end
+  end
+end

data/lib/mixture/validate/match.rb

@@ -4,13 +4,29 @@ module Mixture
   module Validate
     # Checks that a value matches.
     class Match < Base
+      register_as :match
+      register_as :format
+      # Performs the validation.
+      #
+      # @param (see Base#validate)
+      # @return (see Base#validate)
+      # @raise [ValidationError] If {#match?} returns false.
       def validate(record, attribute, value)
         super
         error("Value does not match") unless match?
       end
 
+      private
+
+      # Checks if the value matches the given matcher.  It uses the
+      # `=~` operator.  If it fails (i.e. raises an error), it returns
+      # false.
+      #
+      # @return [Boolean]
       def match?
         @value =~ @options
+      rescue StandardError
+        false
       end
     end
   end

data/lib/mixture/validate/presence.rb

@@ -4,11 +4,24 @@ module Mixture
   module Validate
     # Checks that a value is present.
     class Presence < Base
+      register_as :presence
+      # Performs the validation.
+      #
+      # @param (see Base#validate)
+      # @return (see Base#validate)
+      # @raise [ValidationError] If {#empty?} returns true.
       def validate(record, attribute, value)
         super
         error("Value is empty") if empty?
       end
 
+      private
+
+      # Determins if the given value is empty.  If it's not nil,
+      # and it responds to `empty?`, it returns the value of `empty?`;
+      # otherwise, it returns the value of `nil?`.
+      #
+      # @return [Boolean]
       def empty?
         @value.nil? || (@value.respond_to?(:empty?) && @value.empty?)
       end

data/lib/mixture/validate.rb

@@ -1,30 +1,65 @@
 # encoding: utf-8
 
 module Mixture
+  # Handles validation of attributes.  You can register validators
+  # with this module, and they will be used to validate attributes.
+  # Check out {Validate::Base} for the expected interface.
   module Validate
+    # Registers a validator.  This lets Mixture know about the
+    # validators that can occur.
+    #
+    # @param name [Symbol] The name of the validator.  This is used in
+    #   the {Extensions::Validatable::ClassMethods#validate} call as
+    #   a key.
+    # @param validator [Validate::Base] The validator to use.
+    # @return [void]
     def self.register(name, validator)
       validations[name] = validator
     end
 
+    # The validators that are currently registered.  This returns a
+    # key-value hash of validations.
+    #
+    # @return [Hash{Symbol => Validate::Base}]
     def self.validations
       @_validations ||= {}
     end
 
     require "mixture/validate/base"
+    require "mixture/validate/exclusion"
+    require "mixture/validate/inclusion"
+    require "mixture/validate/length"
     require "mixture/validate/match"
     require "mixture/validate/presence"
 
-    register :match, Match
-    register :format, Match
-    register :presence, Presence
-
+    # Performs a validation on the attribute.  It loops through the
+    # validation requirements on the attribute, and runs each
+    # validation with {.validate_with}.
+    #
+    # @param record [Mixture::Model] A class that has included
+    #   {Mixture::Model} or {Mixture::Extensions::Validatable}.
+    # @param attribute [Mixture::Attribute] The attribute to validate.
+    # @param value [Object] The new value of the attribute.
+    # @return [void]
     def self.validate(record, attribute, value)
+      return unless attribute.options[:validate]
       attribute.options[:validate].each do |k, v|
         validator = validations.fetch(k).new(v)
         validate_with(validator, record, attribute, value)
       end
     end
 
+    # Validates a (record, attribute, value) triplet with the given
+    # validator.  It calls `#validate` on the validator with the
+    # three as arguments, and rescues any validation errors thrown
+    # (and places them in `record.errors`).
+    #
+    # @param validator [Validator::Base, #validate]
+    #   The validator to validate with.
+    # @param record [Mixture::Model]
+    # @param attribute [Mixture::Attribute] The attribute to validate.
+    # @param value [Object] The new value.
+    # @return [void]
     def self.validate_with(validator, record, attribute, value)
       validator.validate(record, attribute, value)
 

data/lib/mixture/version.rb

@@ -5,5 +5,5 @@ module Mixture
   # The current version of Mixture.
   #
   # @return [String]
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/mixture.gemspec

@@ -27,4 +27,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "coveralls"
+  spec.add_development_dependency "rubocop"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mixture
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jeremy Rodi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-09 00:00:00.000000000 Z
+date: 2015-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Handle validation, coercion, and attributes.
 email:
 - redjazz96@gmail.com
@@ -125,6 +139,9 @@ files:
 - lib/mixture/type.rb
 - lib/mixture/validate.rb
 - lib/mixture/validate/base.rb
+- lib/mixture/validate/exclusion.rb
+- lib/mixture/validate/inclusion.rb
+- lib/mixture/validate/length.rb
 - lib/mixture/validate/match.rb
 - lib/mixture/validate/presence.rb
 - lib/mixture/version.rb
@@ -149,7 +166,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Handle validation, coercion, and attributes.