hanami-validations 0.0.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cf76bc3940612ffdc8aa64e07941219547ca0c32
-  data.tar.gz: 04ad62428f8e83fa41ec449f84bd38ade15d0345
+  metadata.gz: adeb97811a77f27c28ac940395e0fab28c0670c0
+  data.tar.gz: d6bc2be331bde334ff930692e1b66458b08f04c5
 SHA512:
-  metadata.gz: 17a5e5c9f565fd7101ed62a12883d2ecb8c8467d5a0c2da0f081030ea3b0066a1f6119d38b17b97fb24b944058264ae1ee06c4e23ae48cf33305fb51403146e6
-  data.tar.gz: 4863bd75a0ce12a0e4ef59ede8d24959917b6d20b469d29cf6ac5ebdcadccd4c4c1e2dee68dd59d0418c398509d9d9711493848dd73f19b2dc06d3937702f5da
+  metadata.gz: 5fb1f27b1db7511d4b2cbb926acba8650596615c171901d27c2dcc5c5c5d6ed55ff0edb41c47d267441b98c07780ec90eb900ebc3d4240c78e55f05f07762eeb
+  data.tar.gz: 517a5991fae90f9c8b83fe0dbf96ad9e86ff93ac0898c9b8fc296da16547a78d9fbb7d8341772fc9e32bdc4454f507cf59a382e9c386202b0c5485fa4c15468e

data/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Hanami::Validations
+Validations mixin for Ruby objects
+
+## v0.5.0 - 2016-01-22
+### Changed
+- [Luca Guidi] Renamed the project
+
+## v0.4.0 - 2016-01-12
+## Changed
+- [Hélio Costa e Silva & Luca Guidi] Ignore blank values for format and size validation
+
+### Fixed
+- [Pascal Betz] Ensure acceptance validation to reject blank strings
+
+## v0.3.3 - 2015-09-30
+### Added
+- [Luca Guidi] Official support for JRuby 9k+
+
+## v0.3.2 - 2015-05-22
+### Added
+- [deepj] Introduced `Lotus::Validations#invalid?`
+
+## v0.3.1 - 2015-05-15
+### Fixed
+- [Luca Guidi] Fixed Hash serialization for nested validations. It always return nested `::Hash` structure.
+- [Alfonso Uceda Pompa & Dmitry Tymchuk] Fixed Hash serialization when `Lotus::Entity` is included in the same class.
+
+## v0.3.0 - 2015-03-23
+
+## v0.2.4 - 2015-01-30
+### Added
+- [Steve Hodgkiss] Introduced `Lotus::Validations::Error#attribute_name`
+- [Steve Hodgkiss] Nested validations
+
+### Changed
+- [Steve Hodgkiss] `Lotus::Validations::Error#name` returns the complete attribute name (Eg. `first_name` or `address.street`)
+
+## v0.2.3 - 2015-01-12
+### Added
+- [Luca Guidi] Compatibility with Lotus::Entity
+
+### Fixed
+- [Luca Guidi] Ensure `.validates` usage to not raise `ArgumentError` when `:type` option is passed
+- [Luca Guidi] Ensure to assign attributes when only `.validates` is used
+
+## v0.2.2 - 2015-01-08
+### Added
+- [Steve Hodgkiss] Introduced `Validations.validates`. It defines validations, for already existing attributes.
+
+## v0.2.1 - 2014-12-23
+### Added
+- [Luca Guidi] Introduced `Validations::Errors#to_h` and `to_a`
+- [Luca Guidi] Introduced `Validations::Errors#any?`
+- [Luca Guidi] Official support for Ruby 2.2
+
+### Fixed
+- [Satoshi Amemiya] Made `Validations#valid?` idempotent
+
+## v0.2.0 - 2014-11-23
+### Added
+- [Luca Guidi] Skip attribute whitelisting when a validator does not define any attribute
+- [Luca Guidi] Official support for Rubinius 2.3+
+- [Luca Guidi] Implemented `#each` in order to allow bulk operations on attributes
+- [Luca Guidi] Implemented `#to_h` to make validations usable by other libraries
+- [Luca Guidi] Made `#initialize` to accept Hashes with strings as keys, but only for declared attributes
+- [Luca Guidi] Lazy coercions, from now on `valid?` is not required to obtain a coerced value from a single attribute
+- [Rik Tonnard] Made validators reusable by allowing infinite inclusion
+
+## v0.1.0 - 2014-10-23
+### Added
+- [Luca Guidi] Made `#initialize` to accept any object that implements `#to_h`
+- [Luca Guidi] Custom coercions for user defined classes
+- [Luca Guidi] Raise an exception at the load time when a validation is not recognized
+- [Luca Guidi] Allow validators inheritance
+- [Luca Guidi] Confirmation validation
+- [Luca Guidi] Exclusion validation
+- [Luca Guidi] Size validation
+- [Luca Guidi] Acceptance validation
+- [Jeremy Stephens] Inclusion validation
+- [Luca Guidi] Format validation
+- [Luca Guidi] Presence validation
+- [Luca Guidi] Coercions
+- [Luca Guidi] Basic module inclusion
+- [Luca Guidi] Official support for JRuby 1.7+ (with 2.0 mode)
+- [Luca Guidi] Official support for MRI 2.0+
+
+### Fixed
+- [Jeremy Stephens] Ensure to not fail validations when coerce falsey values
+- [Luca Guidi] Ensure `Lotus::Validations#valid?` to be idempotent

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright © 2014-2016 Luca Guidi
+
+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

@@ -1,8 +1,28 @@
 # Hanami::Validations
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/hanami/validations`. To experiment with that code, run `bin/console` for an interactive prompt.
+Validations mixins for objects
 
-TODO: Delete this and the text above, and describe your gem
+## Status
+
+[![Gem Version](http://img.shields.io/gem/v/hanami-validations.svg)](https://badge.fury.io/rb/hanami-validations)
+[![Build Status](http://img.shields.io/travis/hanami/validations/master.svg)](https://travis-ci.org/hanami/validations?branch=master)
+[![Coverage](http://img.shields.io/coveralls/hanami/validations/master.svg)](https://coveralls.io/r/hanami/validations)
+[![Code Climate](http://img.shields.io/codeclimate/github/hanami/validations.svg)](https://codeclimate.com/github/hanami/validations)
+[![Dependencies](http://img.shields.io/gemnasium/hanami/validations.svg)](https://gemnasium.com/hanami/validations)
+[![Inline Docs](http://inch-ci.org/github/hanami/validations.svg)](http://inch-ci.org/github/hanami/validations)
+
+## Contact
+
+* Home page: http://hanamirb.org
+* Mailing List: http://hanamirb.org/mailing-list
+* API Doc: http://rdoc.info/gems/hanami-validations
+* Bugs/Issues: https://github.com/hanami/validations/issues
+* Support: http://stackoverflow.com/questions/tagged/hanami
+* Chat: http://chat.hanamirb.org
+
+## Rubies
+
+__Hanami::Validations__ supports Ruby (MRI) 2+, JRuby 9k+
 
 ## Installation
 
@@ -22,15 +42,547 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+`Hanami::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 'hanami/validations'
+
+class Person
+  include Hanami::Validations
+
+  attribute :name,  presence: true
+  attribute :email, presence: true
+end
+
+person = Person.new(name: 'Luca', email: 'me@example.org', age: 32)
+person.name  # => "Luca"
+person.email # => "me@example.org"
+person.age   # => raises NoMethodError because `:age` wasn't defined as attribute.
+```
+
+#### Blank Values
+
+The framework will treat as valid any blank attributes, __without__ `presence`, for both `format` and `size` predicates.
+
+```ruby
+require 'hanami/validations'
+
+class Person
+  include Hanami::Validations
+
+  attribute :name,    type: String, size: 5..45
+  attribute :email,   type: String, size: 20..80, format: /@/
+  attribute :skills,  type: Array,  size: 1..3
+  attribute :keys,    type: Hash,   size: 1..3
+end
+
+Person.new.valid?                             # < true
+Person.new(name: '').valid?                   # < true
+Person.new(skills: '').valid?                 # < true
+Person.new(skills: ['ruby', 'hanami']).valid?  # < true
+
+Person.new(skills: []).valid?                 # < false
+Person.new(keys: {}).valid?                   # < false
+Person.new(keys: {a: :b}, skills: []).valid?  # < false
+```
+
+If you want to _disable_ this behaviour, please, refer to [presence](https://github.com/hanami/validations#presence).
+
+### Validations
+
+If you prefer Hanami::Validations to **only define validations**, but **not attributes**,
+you can use the following alternative syntax.
+
+```ruby
+require 'hanami/validations'
+
+class Person
+  include Hanami::Validations
+  attr_accessor :name, :email
+
+  # Custom initializer
+  def initialize(attributes = {})
+    @name, @email = attributes.values_at(:name, :email)
+  end
+
+  validates :name,  presence: true
+  validates :email, presence: true
+end
+
+person = Person.new(name: 'Luca', email: 'me@example.org')
+person.name  # => "Luca"
+person.email # => "me@example.org"
+```
+
+This is a bit more verbose, but offers a great level of flexibility for your
+Ruby objects. It also allows to use Hanami::Validations in combination with
+**other frameworks**.
+
+### Coercions
+
+If a Ruby class is passed to the `:type` option, the given value is coerced, accordingly.
+
+#### Standard coercions
+
+```ruby
+require 'hanami/validations'
+
+class Person
+  include Hanami::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 'hanami/validations'
+
+class FavNumber
+  def initialize(number)
+    @number = number
+  end
+end
+
+class BirthDate
+end
+
+class Person
+  include Hanami::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 # => #<FavNumber:0x007ffc644bba00 @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 its value is _truthy_.
+
+```ruby
+require 'hanami/validations'
+
+class Signup
+  include Hanami::Validations
+
+  attribute :terms_of_service, acceptance: true
+end
+
+signup = Signup.new(terms_of_service: '1')
+signup.valid? # => true
+
+signup = Signup.new(terms_of_service: 'true')
+signup.valid? # => true
+
+signup = Signup.new(terms_of_service: '')
+signup.valid? # => false
+
+signup = Signup.new(terms_of_service: '0')
+signup.valid? # => false
+```
+
+#### Confirmation
+
+An attribute is valid if its value and the value of a corresponding attribute
+is valid.
+
+By convention, if you have a `password` attribute, the validation looks for `password_confirmation`.
+
+```ruby
+require 'hanami/validations'
+
+class Signup
+  include Hanami::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 'hanami/validations'
+
+class Signup
+  include Hanami::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 'hanami/validations'
+
+class Signup
+  include Hanami::Validations
+
+  attribute :name, format: /\A[a-zA-Z]+\z/
+end
 
-## Development
+signup = Signup.new(name: 'Luca')
+signup.valid? # => true
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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 'hanami/validations'
+
+class PrimeNumbers
+  def initialize(limit)
+    @numbers = Prime.each(limit).to_a
+  end
+
+  def include?(number)
+    @numbers.include?(number)
+  end
+end
+
+class Signup
+  include Hanami::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 'hanami/validations'
+
+class Signup
+  include Hanami::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 its `#size` falls within the described value.
+
+```ruby
+require 'hanami/validations'
+
+class Signup
+  MEGABYTE = 1024 ** 2
+  include Hanami::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).
+
+### Nested validations
+
+Nested validations are handled with a nested block syntax.
+
+```ruby
+class ShippingDetails
+  include Hanami::Validations
+
+  attribute :full_name, presence: true
+
+  attribute :address do
+    attribute :street,      presence: true
+    attribute :city,        presence: true
+    attribute :country,     presence: true
+    attribute :postal_code, presence: true, format: /.../
+  end
+end
+
+validator = ShippingDetails.new
+validator.valid? # => false
+```
+
+Bulk operations on errors are guaranteed by `#each`.
+This method yields a **flattened collection of errors**.
+
+```ruby
+validator.errors.each do |error|
+  error.name
+    # => on the first iteration it returns "full_name"
+    # => the second time it returns "address.street" and so on..
+end
+```
+
+Errors for a specific attribute can be accessed via `#for`.
+
+```ruby
+error = validator.errors.for('full_name').first
+error.name           # => "full_name"
+error.attribute_name # => "full_name"
+
+error = validator.errors.for('address.street').first
+error.name           # => "address.street"
+error.attribute_name # => "street"
+```
+
+### Composable validations
+
+Validations can be reused via composition:
+
+```ruby
+require 'hanami/validations'
+
+module NameValidations
+  include Hanami::Validations
+
+  attribute :name, presence: true
+end
 
-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).
+module EmailValidations
+  include Hanami::Validations
+
+  attribute :email, presence: true, format: /.../
+end
+
+module PasswordValidations
+  include Hanami::Validations
+
+  # We validate only the presence here
+  attribute :password, presence: true
+end
+
+module CommonValidations
+  include EmailValidations
+  include PasswordValidations
+end
+
+# A valid signup requires:
+#   * name (presence)
+#   * email (presence and format)
+#   * password (presence and confirmation)
+class Signup
+  include NameValidations
+  include CommonValidations
+
+  # We decorate PasswordValidations behavior, by requiring the confirmation too.
+  # This additional validation is active only in this case.
+  attribute :password, confirmation: true
+end
+
+# A valid signin requires:
+#   * email (presence)
+#   * password (presence)
+class Signin
+  include CommonValidations
+end
+
+# A valid "forgot password" requires:
+#   * email (presence)
+class ForgotPassword
+  include EmailValidations
+end
+```
+
+### Complete example
+
+```ruby
+require 'hanami/validations'
+
+class Signup
+  include Hanami::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?`, validation 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 'hanami/validations'
+
+class Signup
+  include Hanami::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
+  # => #<Hanami::Validations::Errors:0x007fe00ced9b78
+  # @errors={
+  #   :email=>[
+  #     #<Hanami::Validations::Error:0x007fe00cee3290 @attribute=:email, @validation=:presence, @expected=true, @actual="">,
+  #     #<Hanami::Validations::Error:0x007fe00cee31f0 @attribute=:email, @validation=:format, @expected=/\A(.*)@(.*)\.(.*)\z/, @actual="">
+  #   ],
+  #   :age=>[
+  #     #<Hanami::Validations::Error:0x007fe00cee30d8 @attribute=:age, @validation=:size, @expected=18..99, @actual=17>
+  #   ]
+  # }>
+```
+
+### Hanami::Entity
+
+Integration with [`Hanami::Entity`](https://github.com/hanami/model) is straight forward.
+
+```ruby
+require 'hanami/model'
+require 'hanami/validations'
+
+class Product
+  include Hanami::Entity
+  include Hanami::Validations
+
+  attribute :name,  type: String,  presence: true
+  attribute :price, type: Integer, presence: true
+end
+
+product = Product.new(name: 'Book', price: '100')
+product.valid? # => true
+
+product.name  # => "Book"
+product.price # => 100
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hanami-validations.
+1. Fork it ( https://github.com/hanami/hanami-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-2016 Luca Guidi – Released under MIT License
 
+This project was formerly known as Lotus (`lotus-validations`).