lotus-validations 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 20cf3a7591af700ba75a0ec7926f218e0ae37068
-  data.tar.gz: 921f528200e6f2154174f74cbf6eac5db99c9070
+  metadata.gz: 88761697180386ed3a562170900b63ceb0618b03
+  data.tar.gz: e98d3b024612251600f74e104a3f6f43eb9bf33e
 SHA512:
-  metadata.gz: 5fba96946b8509289218ecbd5b2007996173c37d08f119ebfb03ebdb0d1a51b1db049f7df4a8a0f461acda02ef8e1e2269975495e26ea6a20fc218af05c66e74
-  data.tar.gz: 5263041936a6ca9decaca87cc81a373fa58e69b7c0bd3d3989171f2b40cfd0568e89fbe9c7587a338a3cc91edfa90e90e445e095be0c2a7ab2ecfa4f8ac1d922
+  metadata.gz: 76fac7ccbbafca4210be4ab570a3e5ae708378a08478aae7836a4dfd2e0ddf70c33a99bdaef93e544bbcd3d78917a65ce5f5868ea17e17788e75a1203471d7cb
+  data.tar.gz: 7185e7295684adaf616fa8abb450f11126adc2cc4ea8ed7d1769c27ebfad9a975b76e2727096832ff49e7cfa94a1d7c536293b612e823daaf90659e109502d46

data/README.md

@@ -1,6 +1,28 @@
 # Lotus::Validations
 
-TODO: Write a gem description
+Validations mixins for objects
+
+## Status
+
+[![Gem Version](http://img.shields.io/gem/v/lotus-validations.svg)](https://badge.fury.io/rb/lotus-validations)
+[![Build Status](http://img.shields.io/travis/lotus/validations/master.svg)](https://travis-ci.org/lotus/validations?branch=master)
+[![Coverage](http://img.shields.io/coveralls/lotus/validations/master.svg)](https://coveralls.io/r/lotus/validations)
+[![Code Climate](http://img.shields.io/codeclimate/github/lotus/validations.svg)](https://codeclimate.com/github/lotus/validations)
+[![Dependencies](http://img.shields.io/gemnasium/lotus/validations.svg)](https://gemnasium.com/lotus/validations)
+[![Inline Docs](http://inch-ci.org/github/lotus/validations.svg)](http://inch-ci.org/github/lotus/validations)
+
+## Contact
+
+* Home page: http://lotusrb.org
+* Mailing List: http://lotusrb.org/mailing-list
+* API Doc: http://rdoc.info/gems/lotus-validations
+* Bugs/Issues: https://github.com/lotus/validations/issues
+* Support: http://stackoverflow.com/questions/tagged/lotus-ruby
+* Chat: https://gitter.im/lotus/chat
+
+## Rubies
+
+__Lotus::Validations__ supports Ruby (MRI) 2+ and JRuby 1.7 (with 2.0 mode).
 
 ## Installation
 
@@ -20,12 +42,353 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+`Lotus::Validations` is a set of lightweight validations for Ruby objects.
+
+### Attributes
+
+The framework allows you to define attributes for each object.
+
+It defines an initializer, whose attributes can be passed as a hash.
+All unknown values are ignored, which is useful for whitelisting attributes.
+
+```ruby
+require 'lotus/validations'
+
+class Person
+  include Lotus::Validations
+
+  attribute :name
+end
+
+person = Person.new(name: 'Luca', age: 32)
+person.name # => "Luca"
+person.age  # => raises NoMethodError because `:age` wasn't defined as attribute.
+```
+
+### Coercions
+
+If a Ruby class is passed to the `:type` option, the given value is coerced, accordingly.
+
+#### Standard coercions
+
+```ruby
+require 'lotus/validations'
+
+class Person
+  include Lotus::Validations
+
+  attribute :fav_number, type: Integer
+end
+
+person = Person.new(fav_number: '23')
+person.valid?
+
+person.fav_number # => 23
+```
+
+Allowed types are:
+
+  * `Array`
+  * `BigDecimal`
+  * `Boolean`
+  * `Date`
+  * `DateTime`
+  * `Float`
+  * `Hash`
+  * `Integer`
+  * `Pathname`
+  * `Set`
+  * `String`
+  * `Symbol`
+  * `Time`
+
+#### Custom coercions
+
+If a user defined class is specified, it can be freely used for coercion purposes.
+The only limitation is that the constructor should have **arity of 1**.
+
+```ruby
+require 'lotus/validations'
+
+class FavNumber
+  def initialize(number)
+    @number = number
+  end
+end
+
+class BirthDate
+end
+
+class Person
+  include Lotus::Validations
+
+  attribute :fav_number, type: FavNumber
+  attribute :date,       type: BirthDate
+end
+
+person = Person.new(fav_number: '23', date: 'Oct 23, 2014')
+person.valid?
+
+person.fav_number # => 23
+person.date       # => this raises an error, because BirthDate#initialize doesn't accept any arg
+```
+
+### Validations
+
+Each attribute definition can receive a set of options to define one or more
+validations.
+
+**Validations are triggered when you invoke `#valid?`.**
+
+#### Acceptance
+
+An attribute is valid if it's value satisfies [Ruby's _truthiness_](http://ruby.about.com/od/control/a/Boolean-Expressions.htm).
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :terms_of_service, acceptance: true
+end
+
+signup = Signup.new(terms_of_service: '1')
+signup.valid? # => true
+
+signup = Signup.new(terms_of_service: '')
+signup.valid? # => false
+```
+
+#### Confirmation
+
+An attribute is valid if it's value and the value of a corresponding attribute
+is valid.
+
+By convention, if you have a `password` attribute, the validation looks for `password_validation`.
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :password, confirmation: true
+end
+
+signup = Signup.new(password: 'secret', password_confirmation: 'secret')
+signup.valid? # => true
+
+signup = Signup.new(password: 'secret', password_confirmation: 'x')
+signup.valid? # => false
+```
+
+#### Exclusion
+
+An attribute is valid, if the value isn't excluded from the value described by
+the validator.
+
+The validator value can be anything that responds to `#include?`.
+In Ruby, this includes most of the core objects: `String`, `Enumerable` (`Array`, `Hash`,
+`Range`, `Set`).
+
+See also [Inclusion](#inclusion).
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :music, exclusion: ['pop']
+end
+
+signup = Signup.new(music: 'rock')
+signup.valid? # => true
+
+signup = Signup.new(music: 'pop')
+signup.valid? # => false
+```
+
+#### Format
+
+An attribute is valid if it matches the given Regular Expression.
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :name, format: /\A[a-zA-Z]+\z/
+end
+
+signup = Signup.new(name: 'Luca')
+signup.valid? # => true
+
+signup = Signup.new(name: '23')
+signup.valid? # => false
+```
+
+#### Inclusion
+
+An attribute is valid, if the value provided is included in the validator's
+value.
+
+The validator value can be anything that responds to `#include?`.
+In Ruby, this includes most of the core objects: like `String`, `Enumerable` (`Array`, `Hash`,
+`Range`, `Set`).
+
+See also [Exclusion](#exclusion).
+
+```ruby
+require 'prime'
+require 'lotus/validations'
+
+class PrimeNumbers
+  def initialize(limit)
+    @numbers = Prime.each(limit).to_a
+  end
+
+  def include?(number)
+    @numbers.include?(number)
+  end
+end
+
+class Signup
+  include Lotus::Validations
+
+  attribute :age,        inclusion: 18..99
+  attribute :fav_number, inclusion: PrimeNumbers.new(100)
+end
+
+signup = Signup.new(age: 32)
+signup.valid? # => true
+
+signup = Signup.new(age: 17)
+signup.valid? # => false
+
+signup = Signup.new(fav_number: 23)
+signup.valid? # => true
+
+signup = Signup.new(fav_number: 8)
+signup.valid? # => false
+```
+
+#### Presence
+
+An attribute is valid if present.
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :name, presence: true
+end
+
+signup = Signup.new(name: 'Luca')
+signup.valid? # => true
+
+signup = Signup.new(name: '')
+signup.valid? # => false
+
+signup = Signup.new(name: nil)
+signup.valid? # => false
+```
+
+#### Size
+
+An attribute is valid if it's `#size` falls within the described value.
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  MEGABYTE = 1024 ** 2
+  include Lotus::Validations
+
+  attribute :ssn,      size: 11    # exact match
+  attribute :password, size: 8..64 # range
+  attribute :avatar,   size  1..(5 * MEGABYTE)
+end
+
+signup = Signup.new(password: 'a-very-long-password')
+signup.valid? # => true
+
+signup = Signup.new(password: 'short')
+signup.valid? # => false
+```
+
+**Note that in the example above you are able to validate the weight of the file,
+because Ruby's `File` and `Tempfile` both respond to `#size`.**
+
+#### Uniqueness
+
+Uniqueness validations aren't implemented because this library doesn't deal with persistence.
+The other reason is that this isn't an effective way to ensure uniqueness of a value in a database.
+
+Please read more at: [The Perils of Uniqueness Validations](http://robots.thoughtbot.com/the-perils-of-uniqueness-validations).
+
+### Complete example
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :first_name, presence: true
+  attribute :last_name,  presence: true
+  attribute :email,      presence: true, format: /\A(.*)@(.*)\.(.*)\z/
+  attribute :password,   presence: true, confirmation: true, size: 8..64
+end
+```
+
+### Errors
+
+When you invoke `#valid?`, validations errors are available at `#errors`.
+It's a set of errors grouped by attribute. Each error contains the name of the
+invalid attribute, the failed validation, the expected value and the current one.
+
+```ruby
+require 'lotus/validations'
+
+class Signup
+  include Lotus::Validations
+
+  attribute :email, presence: true, format: /\A(.*)@(.*)\.(.*)\z/
+  attribute :age, size: 18..99
+end
+
+signup = Signup.new(email: 'user@example.org')
+signup.valid? # => true
+
+signup = Signup.new(email: '', age: 17)
+signup.valid? # => false
+
+signup.errors
+  # => #<Lotus::Validations::Errors:0x007fe00ced9b78
+  # @errors={
+  #   :email=>[
+  #     #<Lotus::Validations::Error:0x007fe00cee3290 @attribute=:email, @validation=:presence, @expected=true, @actual="">,
+  #     #<Lotus::Validations::Error:0x007fe00cee31f0 @attribute=:email, @validation=:format, @expected=/\A(.*)@(.*)\.(.*)\z/, @actual="">
+  #   ],
+  #   :age=>[
+  #     #<Lotus::Validations::Error:0x007fe00cee30d8 @attribute=:age, @validation=:size, @expected=18..99, @actual=17>
+  #   ]
+  # }>
+```
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/lotus-validations/fork )
+1. Fork it ( https://github.com/lotus/lotus-validations/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
+
+## Copyright
+
+Copyright 2014 Luca Guidi – Released under MIT License

data/lib/lotus-validations.rb

@@ -0,0 +1 @@
+require 'lotus/validations'

data/lib/lotus/validations.rb

@@ -1,7 +1,398 @@
-require "lotus/validations/version"
+require 'lotus/validations/version'
+require 'lotus/validations/errors'
+require 'lotus/validations/attribute_validator'
 
 module Lotus
+  # Lotus::Validations is a set of lightweight validations for Ruby objects.
+  #
+  # @since 0.1.0
   module Validations
-    # Your code goes here...
+
+    # Override Ruby's hook for modules.
+    #
+    # @param base [Class] the target action
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @see http://www.ruby-doc.org/core/Module.html#method-i-included
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Validations DSL
+    #
+    # @since 0.1.0
+    module ClassMethods
+      # Define an attribute
+      #
+      # @param name [#to_sym] the name of the attribute
+      # @param options [Hash] optional set of validations
+      # @option options [Class] :type the Ruby type used to coerce the value
+      # @option options [TrueClass,FalseClass] :acceptance requires Ruby
+      #   thruthiness of the value
+      # @option options [TrueClass,FalseClass] :confirmation requires the value
+      #   to be confirmed twice
+      # @option options [#include?] :exclusion requires the value NOT be
+      #   included in the given collection
+      # @option options [Regexp] :format requires value to match the given
+      #   Regexp
+      # @option options [#include?] :inclusion requires the value BE included in
+      #   the given collection
+      # @option options [TrueClass,FalseClass] :presence requires the value be
+      #   included in the given collection
+      # @option options [Numeric,Range] :size requires value's to be equal or
+      #   included by the given validator
+      #
+      # @raise [ArgumentError] if an unknown or mispelled validation is given
+      #
+      # @example Attributes
+      #   require 'lotus/validations'
+      #
+      #   class Person
+      #     include Lotus::Validations
+      #
+      #     attribute :name
+      #   end
+      #
+      #   person = Person.new(name: 'Luca', age: 32)
+      #   person.name # => "Luca"
+      #   person.age  # => raises NoMethodError because `:age` wasn't defined as attribute.
+      #
+      # @example Standard coercions
+      #   require 'lotus/validations'
+      #
+      #   class Person
+      #     include Lotus::Validations
+      #
+      #     attribute :fav_number, type: Integer
+      #   end
+      #
+      #   person = Person.new(fav_number: '23')
+      #   person.valid?
+      #
+      #   person.fav_number # => 23
+      #
+      # @example Custom coercions
+      #   require 'lotus/validations'
+      #
+      #   class FavNumber
+      #     def initialize(number)
+      #       @number = number
+      #     end
+      #   end
+      #
+      #   class BirthDate
+      #   end
+      #
+      #   class Person
+      #     include Lotus::Validations
+      #
+      #     attribute :fav_number, type: FavNumber
+      #     attribute :date,       type: BirthDate
+      #   end
+      #
+      #   person = Person.new(fav_number: '23', date: 'Oct 23, 2014')
+      #   person.valid?
+      #
+      #   person.fav_number # => 23
+      #   person.date       # => this raises an error, because BirthDate#initialize doesn't accept any arg
+      #
+      # @example Acceptance
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :terms_of_service, acceptance: true
+      #   end
+      #
+      #   signup = Signup.new(terms_of_service: '1')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(terms_of_service: '')
+      #   signup.valid? # => false
+      #
+      # @example Confirmation
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :password, confirmation: true
+      #   end
+      #
+      #   signup = Signup.new(password: 'secret', password_confirmation: 'secret')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(password: 'secret', password_confirmation: 'x')
+      #   signup.valid? # => false
+      #
+      # @example Exclusion
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :music, exclusion: ['pop']
+      #   end
+      #
+      #   signup = Signup.new(music: 'rock')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(music: 'pop')
+      #   signup.valid? # => false
+      #
+      # @example Format
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :name, format: /\A[a-zA-Z]+\z/
+      #   end
+      #
+      #   signup = Signup.new(name: 'Luca')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(name: '23')
+      #   signup.valid? # => false
+      #
+      # @example Inclusion
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :age, inclusion: 18..99
+      #   end
+      #
+      #   signup = Signup.new(age: 32)
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(age: 17)
+      #   signup.valid? # => false
+      #
+      # @example Presence
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     include Lotus::Validations
+      #
+      #     attribute :name, presence: true
+      #   end
+      #
+      #   signup = Signup.new(name: 'Luca')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(name: nil)
+      #   signup.valid? # => false
+      #
+      # @example Size
+      #   require 'lotus/validations'
+      #
+      #   class Signup
+      #     MEGABYTE = 1024 ** 2
+      #     include Lotus::Validations
+      #
+      #     attribute :ssn,      size: 11    # exact match
+      #     attribute :password, size: 8..64 # range
+      #     attribute :avatar,   size  1..(5 * MEGABYTE)
+      #   end
+      #
+      #   signup = Signup.new(password: 'a-very-long-password')
+      #   signup.valid? # => true
+      #
+      #   signup = Signup.new(password: 'short')
+      #   signup.valid? # => false
+      def attribute(name, options = {})
+        attributes[name.to_sym] = validate_options!(name, options)
+
+        class_eval %{
+          def #{ name }
+            @attributes[:#{ name }]
+          end
+        }
+      end
+
+      private
+      # Set of user defined attributes
+      #
+      # @return [Hash]
+      #
+      # @since 0.1.0
+      # @api private
+      def attributes
+        @attributes ||= Hash.new
+      end
+
+      # Checks at the loading time if the user defined validations are recognized
+      #
+      # @param name [Symbol] the attribute name
+      # @param options [Hash] the set of validations associated with the given attribute
+      #
+      # @raise [ArgumentError] if at least one of the validations are not
+      #   recognized
+      #
+      # @since 0.1.0
+      # @api private
+      def validate_options!(name, options)
+        if (unknown = (options.keys - validations)) && unknown.any?
+          raise ArgumentError.new(%(Unknown validation(s): #{ unknown.join ', ' } for "#{ name }" attribute))
+        end
+
+        options
+      end
+
+      # Names of the implemented validations
+      #
+      # @return [Array]
+      #
+      # @since 0.1.0
+      # @api private
+      def validations
+        [:presence, :acceptance, :format, :inclusion, :exclusion, :confirmation, :size, :type]
+      end
+    end
+
+    # Validation errors
+    #
+    # @return [Lotus::Validations::Errors] the set of validation errors
+    #
+    # @since 0.1.0
+    #
+    # @see Lotus::Validations::Errors
+    #
+    # @example Valid attributes
+    #   require 'lotus/validations'
+    #
+    #   class Signup
+    #     include Lotus::Validations
+    #
+    #     attribute :email, presence: true, format: /\A(.*)@(.*)\.(.*)\z/
+    #   end
+    #
+    #   signup = Signup.new(email: 'user@example.org')
+    #   signup.valid? # => true
+    #
+    #   signup.errors
+    #     # => #<Lotus::Validations::Errors:0x007fd594ba9228 @errors={}>
+    #
+    # @example Invalid attributes
+    #   require 'lotus/validations'
+    #
+    #   class Signup
+    #     include Lotus::Validations
+    #
+    #     attribute :email, presence: true, format: /\A(.*)@(.*)\.(.*)\z/
+    #     attribute :age, size: 18..99
+    #   end
+    #
+    #   signup = Signup.new(email: '', age: 17)
+    #   signup.valid? # => false
+    #
+    #   signup.errors
+    #     # => #<Lotus::Validations::Errors:0x007fe00ced9b78
+    #     # @errors={
+    #     #   :email=>[
+    #     #     #<Lotus::Validations::Error:0x007fe00cee3290 @attribute=:email, @validation=:presence, @expected=true, @actual="">,
+    #     #     #<Lotus::Validations::Error:0x007fe00cee31f0 @attribute=:email, @validation=:format, @expected=/\A(.*)@(.*)\.(.*)\z/, @actual="">
+    #     #   ],
+    #     #   :age=>[
+    #     #     #<Lotus::Validations::Error:0x007fe00cee30d8 @attribute=:age, @validation=:size, @expected=18..99, @actual=17>
+    #     #   ]
+    #     # }>
+    attr_reader :errors
+
+    # Create a new instance with the given attributes
+    #
+    # @param attributes [#to_h] an Hash like object which contains the
+    #   attributes
+    #
+    # @since 0.1.0
+    #
+    # @example Initialize with Hash
+    #   require 'lotus/validations'
+    #
+    #   class Signup
+    #     include Lotus::Validations
+    #
+    #     attribute :name
+    #   end
+    #
+    #   signup = Signup.new(name: 'Luca')
+    #
+    # @example Initialize with Hash like
+    #   require 'lotus/validations'
+    #
+    #   class Params
+    #     def initialize(attributes)
+    #       @attributes = Hash[*attributes]
+    #     end
+    #
+    #     def to_h
+    #       @attributes.to_h
+    #     end
+    #   end
+    #
+    #   class Signup
+    #     include Lotus::Validations
+    #
+    #     attribute :name
+    #   end
+    #
+    #   params = Params.new([:name, 'Luca'])
+    #   signup = Signup.new(params)
+    #
+    #   signup.name # => "Luca"
+    def initialize(attributes)
+      @attributes = attributes.to_h
+      @errors     = Errors.new
+    end
+
+    # Checks if the current data satisfies the defined validations
+    #
+    # @return [TrueClass,FalseClass] the result of the validations
+    #
+    # @since 0.1.0
+    def valid?
+      @errors.clear
+
+      _attributes.each do |name, options|
+        AttributeValidator.new(self, name, options).validate!
+      end
+
+      @errors.empty?
+    end
+
+    protected
+    # Returns the attributes passed at the initialize time
+    #
+    # @return [Hash] attributes
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @example
+    #   require 'lotus/validations'
+    #
+    #   class Signup
+    #     include Lotus::Validations
+    #
+    #     attribute :email
+    #   end
+    #
+    #   signup = Signup.new(email: 'user@example.org')
+    #   signup.attributes # => {:email=>"user@example.org"}
+    attr_reader :attributes
+
+    private
+    # @since 0.1.0
+    # @api private
+    #
+    # @see Lotus::Validations::ClassMethods#attributes
+    def _attributes
+      self.class.__send__(:attributes)
+    end
   end
 end