virtus2 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 931b9a71f0f9c09c2b861371f2ad57a7553f005b0ddb5920674dd8c2d2df12a6
+  data.tar.gz: 754af0ece66410668ceb1ea23c7a5aca49a9d7edf8c8fd4587e168c57369ff45
+SHA512:
+  metadata.gz: bf30cb66aa3fb3c507d9cc7dac83749b3f30dfb51d701cd1797015e847573123042779bfa7ace1b666b28b8fe8f7f99503a533ed73f21e5a8006c6b0ed119ed1
+  data.tar.gz: 366a2a1989ffeaad24342f2c687835b4b48735cd7cd83916f2a8dfe6a8201c9397b931f03a2c64229c3dc00859607f5e421e597e15b93250ba737f3eedc0d021

data/.gitignore

@@ -0,0 +1,39 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## Rubinius
+*.rbc
+.rbx
+
+## PROJECT::GENERAL
+*.gem
+coverage
+profiling
+turbulence
+rdoc
+pkg
+tmp
+doc
+log
+.yardoc
+measurements
+
+## BUNDLER
+.bundle
+Gemfile.lock
+bin/
+
+## PROJECT::SPECIFIC
+.idea

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/.yardopts

@@ -0,0 +1 @@
+- README.md History.md LICENSE

data/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Current project status
+
+Virtus recently hit it's 1.0 release (2013-10-16). The focus now is on bug-fixes and maintenance while [@solnic][solnic] is away from the project. An experimental branch will be kept up-to date where proposed features and API changes can be made. Please direct your questions and issues to [@elskwid][elskwid], the maintainer.
+
+# Contributing to Virtus
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with Rakefile or version
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+Author: [@solnic][solnic]
+Maintainer: [@elskwid][elskwid]
+
+[solnic]: https://github.com/solnic
+[elskwid]: https://github.com/elskwid

data/Changelog.md

@@ -0,0 +1,258 @@
+# v2.0.0 2021-06-07
+
+* [changed] min ruby version is now 2.0 (solnic)
+* [changed] inflecto was replaced with dry-inflector (solnic)
+* [changed] equalizer was replaced with the internal virtus/equalizer (solnic)
+* [changed] `Virtus::Attribute#==` was revised (see ef57af319334a1d4f3e0860acbde7c6d6f0eb8ef) (novikserg)
+* [added] New method `Virtus::Atrribute::Collection#value_coerced?`  (dslh)
+* [fixed] Mass assignment bug fix (see #325) (novikserg)
+
+[Compare v1.0.5..v2.0.0](https://github.com/solnic/virtus/compare/v1.0.5...v2.0.0)
+
+# v1.0.5 2015-03-18
+
+* [feature] Support for :nullify_blank option when configuring a virtus module (lucasmazza)
+
+[Compare v1.0.4..v1.0.5](https://github.com/solnic/virtus/compare/v1.0.4...v1.0.5)
+
+# v1.0.4 2015-01-03
+
+* [feature] Support for :required option when configuring a virtus module (solnic)
+
+[Compare v1.0.3..v1.0.4](https://github.com/solnic/virtus/compare/v1.0.3...v1.0.4)
+
+# v1.0.3 2014-07-24
+
+* [improvement] Expose attribute name in the exception when in strict mode (ntl)
+* [improvement] Set #to_h as an alias to #to_hash (fnando)
+* [fixed] Fix handling of nil in collection coercion (edgibbs)
+* [fixed] Fix issues with using multiple virtus modules (trptcolin)
+* [fixed] Fix handling of Range type (hampei)
+* [fixed] Fix strict mode for collection and hash types (solnic)
+
+[Compare v1.0.2..v1.0.3](https://github.com/solnic/virtus/compare/v1.0.2...v1.0.3)
+
+# v1.0.2 2013-12-03
+
+* [improvement] Don’t override already-defined default values when freezing (amarshall)
+* [improvement] Improved performance of `AttributeSet#each` (Antti)
+* updated axiom-types dependency to ~> 0.1 (solnic)
+
+[Compare v1.0.1..v1.0.2](https://github.com/solnic/virtus/compare/v1.0.1...v1.0.2)
+
+# v1.0.1 2013-12-10
+
+* [feature] re-introduce `ValueObject#with`, which was removed in the past (senny)
+* [fixed] strict mode for Boolean type (solnic)
+
+[Compare v1.0.0..v1.0.1](https://github.com/solnic/virtus/compare/v1.0.0...v1.0.1)
+
+# v1.0.0 2013-10-16
+
+This release no longer works with Ruby 1.8.7.
+
+* [BREAKING CHANGE] Integrated with axiom-types, most of the attribute sub-classes are gone (solnic)
+* [feature] Configurable coercion via coercible integration (solnic)
+* [feature] Strict mode for coercions via `:strict` option (solnic)
+* [feature] Lazy-loaded default values via `:lazy` option (solnic)
+* [feature] Finalizing models solving circular-dependency issue (see #81) (solnic)
+* [feature] Ability to cherry-pick which extension should be included (solnic)
+* [feature] Ability to inject a custom coercer object via `:coercer` option (solnic)
+* [feature] Extension module builder with pre-defined configuration for attributes (elskwid & solnic)
+* [feature] `Virtus::Attribute` exposes a public API - you can easily build, rename and clone attribute instances and use their coercion power (solnic)
+* [feature] Ability to reset attributes to their default values (pewniak747)
+* [changed] A meaningful error will be raised if a reserved name is used as an attribute name (solnic)
+* [changed] Default value can be set via private and protected methods now (solnic)
+* [changed] New syntax for value objects (solnic)
+* [changed] Default values are now set in the constructor for non-lazy attributes (solnic)
+* [deprecated] `Virtus::Attribute.coerce` in favor of `Virtus.coerce` or a customized configured module (solnic)
+* [deprecated] `include Virtus` in favor of `include Virtus.model` (for classes) or `Virtus.module` (for modules) (solnic)
+* [deprecated] `include Virtus::ValueObject` in favor of `include Virtus.value_object` (solnic)
+* [deprecated] `Virtus#attributes` in favor of `Virtus#attribute_set` (solnic)
+* [fixed] const missing hook now works correctly in modules too (cored)
+* [fixed] value object with Hash type works correctly (solnic)
+* [fixed] issues with value-object subclasses and `#==` method (solnic)
+
+[Compare v0.5.4..v1.0.0](https://github.com/solnic/virtus/compare/v0.5.4...v1.0.0)
+
+# v0.5.4 2012-12-20
+
+* [feature] Allow *any* enumerable to be a collection attribute (aptinio)
+* [feature] Add Integer.to_datetime and Float.to_datetime coercion (brutuscat)
+* [fixed] Fixed a regression with Hash attribute introduced by key/member coercion (shingara)
+* [fixed] Change leading non-significant digit type coercion to be coerced (maskact)
+
+[Compare v0.5.3..v0.5.4](https://github.com/solnic/virtus/compare/v0.5.3...v0.5.4)
+
+# v0.5.3 2012-12-13
+
+* [feature] Added Hash member type coercion [example](https://github.com/solnic/virtus#hash-attributes-coercion) (greyblake)
+* [fixed] Fixed issues with String=>Integer coercion and e-notation (greyblake)
+* [changed] Replaced internal DescendantsTracker with the extracted gem (solnic)
+* [internal] Switched to rspec 2 and mutant for mutation testing (mbj)
+
+[Compare v0.5.2..v0.5.3](https://github.com/solnic/virtus/compare/v0.5.2...v0.5.3)
+
+# v0.5.2 2012-09-01
+
+* [feature] Object is now the default attribute type (dkubb)
+* [fixed] Fix module inclusion problems (dkubb)
+* [fixed] Evaluate default values when freezing an object (mbj)
+* [fixed] String representation of a big integer is now properly coerced to an integer (greyblake)
+* [changed] AttributeSet is now a module responsible for defining attribute methods (emmanuel)
+
+[Compare v0.5.1..v0.5.2](https://github.com/solnic/virtus/compare/v0.5.1...v0.5.2)
+
+# v0.5.1 2012-06-11
+
+* [fixed] EV properly handle nil as the value (solnic)
+
+[Compare v0.5.0..v0.5.1](https://github.com/solnic/virtus/compare/v0.5.0...v0.5.1)
+
+# v0.5.0 2012-06-08
+
+* [feature] Support for extending objects (solnic)
+* [feature] Support for defining attributes in modules (solnic)
+* [feature] Support for Struct as an EmbeddedValue or ValueObject attribute (solnic)
+* [changed] Allow any input for EmbeddedValue and ValueObject constructors (solnic)
+* [changed] ValueObject instances cannot be duped or cloned (senny)
+
+[Compare v0.4.2..v0.5.0](https://github.com/solnic/virtus/compare/v0.4.2...v0.5.0)
+
+# v0.4.2 2012-05-08
+
+* [updated] Bump backports dep to ~> 2.5.3 (solnic)
+
+[Compare v0.4.1..v0.4.2](https://github.com/solnic/virtus/compare/v0.4.1...v0.4.2)
+
+# v0.4.1 2012-05-06
+
+* [changed] backports gem is now a runtime dependency (solnic)
+* [BREAKING CHANGE] Renamed Virtus::DefaultValue#evaluate => Virtus::DefaultValue#call (solnic)
+* [BREAKING CHANGE] Renamed Virtus::ValueObject::Equalizer to Virtus::Equalizer (dkubb)
+
+[Compare v0.4.0..v0.4.1](https://github.com/solnic/virtus/compare/v0.4.0...v0.4.1)
+
+# v0.4.0 2012-03-22
+
+* [improvement] Add a caching mechanism for type lookups (solnic)
+* [fixed] Fix attributes mass-assignment when nil is passed (fgrehm)
+* [changed] Replace usage of #to_hash with Hash.try_convert (dkubb)
+
+[Compare v0.3.0..v0.4.0](https://github.com/solnic/virtus/compare/v0.3.0...v0.4.0)
+
+# v0.3.0 2012-02-25
+
+* [feature] Support for default values from a symbol (which can be a method name) (solnic)
+* [feature] Support for mass-assignment via custom setters not generated with attribute (fgrehm)
+* [feature] Virtus::Coercion::String.to_constant handles namespaced names (dkubb)
+* [feature] New coercion: Virtus::Coercion::Object.to_array (dkubb)
+* [feature] New coercion: Virtus::Coercion::Object.to_hash (dkubb)
+* [feature] New coercion: Virtus::Coercion::Object.to_string (dkubb)
+* [feature] New coercion: Virtus::Coercion::Object.to_integer (dkubb)
+* [changed] EmbeddedValue relies on @primitive setting rather than @model (mbj)
+* [BREAKING CHANGE] Removed Attribute#writer_visibility in favor of Attribute#public_writer? (solnic)
+* [BREAKING CHANGE] Removed Attribute#reader_visibility in favor of Attribute#public_reader? (solnic)
+* [BREAKING CHANGE] Removed Attribute#instance_variable_name - this is a private ivar (solnic)
+* [BREAKING CHANGE] Removed Equalizer#host_name and Equalizer#keys (solnic)
+
+[Compare v0.2.0..v0.3.0](https://github.com/solnic/virtus/compare/v0.2.0...v0.3.0)
+
+# v0.2.0 2012-02-08
+
+* [feature] Support for Value Objects (emmanuel)
+* [feature] New Symbol attribute (solnic)
+* [feature] Time => Integer coercion (solnic)
+
+[Compare v0.1.0..v0.2.0](https://github.com/solnic/virtus/compare/v0.1.0...v0.2.0)
+
+# v0.1.0 2012-02-05
+
+* [feature] New EmbeddedValue attribute (solnic)
+* [feature] Array and Set attributes support member coercions (emmanuel)
+* [feature] Support for scientific notation handling in string => integer coercion (dkubb)
+* [feature] Handling of string => numeric coercion with a leading + sign (dkubb)
+* [changed] Update Boolean coercion to handle "on", "off", "y", "n", "yes", "no" (dkubb)
+
+[Compare v0.0.10..v0.1.0](https://github.com/solnic/virtus/compare/v0.0.10...v0.1.0)
+
+# v0.0.10 2011-11-21
+
+* [fixed] Default values are now duped on evaluate (rclosner)
+* [fixed] Allow to override attribute mutator methods (senny)
+
+[Compare v0.0.9..v0.0.10](https://github.com/solnic/virtus/compare/v0.0.9...v0.0.10)
+
+# v0.0.9 2011-10-11
+
+* [fixed] Fix in type lookup for anonymous classes (dkubb)
+
+[Compare v0.0.8..v0.0.9](https://github.com/solnic/virtus/compare/v0.0.8...v0.0.9)
+
+# v0.0.8 2011-08-25
+
+* [fixed] Fixed conflict with ActiveModel (RichGuk)
+* [changed] Renamed Coercion::String.to_class => Coercion::String.to_constant (emmanuel)
+
+[Compare v0.0.7..v0.0.8](https://github.com/solnic/virtus/compare/v0.0.7...v0.0.8)
+
+# v0.0.7 2011-07-31
+
+* [BREAKING CHANGE] Attribute.primitive? has been removed (solnic)
+* [fixed] Added missing coercion_method setting to Virtus::Attribute::Object (solnic)
+* [general] Default value logic has been extracted into Attribute::DefaultValue class (solnic)
+* [added] Virtus::Attribute::Class (solnic)
+
+[Compare v0.0.6..v0.0.7](https://github.com/solnic/virtus/compare/v0.0.6...v0.0.7)
+
+# v0.0.6 2011-07-30
+
+* [BREAKING CHANGE] Moved Virtus.determine_type to a shared module Virtus::TypeLookup (dkubb)
+* [BREAKING CHANGE] Attribute#typecast_to_primitive has been replaced by Attribute#coerce (solnic)
+* [BREAKING CHANGE] Attribute#typecast logic was moved to Attribute#set which is now a public method (solnic)
+* [feature] Added support for default values (solnic)
+* [general] Added custom inspect for Attribute classes (solnic)
+* [general] Added backports as a development dependency (dkubb)
+* [changed] Options API has been extracted from Attribute to a support module Virtus::Options (solnic)
+* [changed] Typecast classes have been replaced by a new hierarchy of Coercion classes like Coercion::String, Coercion::Integer etc. (solnic)
+* [changed] Attribute#get, #get!, #set, #set! & #coerce are now part of the public API (solnic)
+
+[Compare v0.0.5..v0.0.6](https://github.com/solnic/virtus/compare/v0.0.5...v0.0.6)
+
+# v0.0.5 2011-07-10
+
+* [bugfix] Fixed DescendantsTracker + ActiveSupport collision (dkubb)
+
+[Compare v0.0.4..v0.0.5](https://github.com/solnic/virtus/compare/v0.0.4...v0.0.5)
+
+# v0.0.4 2011-07-08
+
+* [BREAKING CHANGE] attributes hash has been replaced by a specialized class AttributeSet (dkubb)
+* [BREAKING CHANGE] Virtus::ClassMethods.attribute returns self instead of a created attribute (solnic)
+* [changed] descendants tracking has been extracted into DescendantsTracker module (dkubb)
+* [changed] Instance #primitive? method has been replaced by class utility method Virtus::Attribute.primitive? (solnic)
+* [changed] Virtus::Attribute::String#typecast_to_primitive delegates to Virtus::Typecast::String.call (solnic)
+
+[Compare v0.0.3..v0.0.4](https://github.com/solnic/virtus/compare/v0.0.3...v0.0.4)
+
+# v0.0.3 2011-06-09
+
+* [BREAKING CHANGE] Attribute classes were moved to Virtus::Attribute namespace (solnic)
+* [BREAKING CHANGE] Attribute instance no longer holds the reference to a model (solnic)
+* [BREAKING CHANGE] #typecast no longer receives an instance of a model (override #set which calls #typecast if you need that) (solnic)
+* [changed] Adding reader/writer methods was moved from the attribute constructor to Virtus::ClassMethods.attribute (solnic)
+* [changed] Typecast logic has been moved into separate classes (see Virtus::Typecast) (solnic)
+* [added] Virtus::Attribute::DateTime#typecast supports objects which implement #to_datetime (solnic)
+* [general] Internals have been cleaned up, simplified and properly documented (solnic)
+
+[Compare v0.0.2..v0.0.3](https://github.com/solnic/virtus/compare/v0.0.2...v0.0.3)
+
+# v0.0.2 2011-06-06
+
+* [bugfix] Fixed #typecast in custom attribute classes (solnic)
+
+[Compare v0.0.1..v0.0.2](https://github.com/solnic/virtus/compare/v0.0.1...v0.0.2)
+
+# v0.0.1 2011-06-04
+
+First public release :)

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'dry-inflector'
+gem 'rspec'
+gem 'bogus'
+gem 'simplecov', platform: :ruby
+
+gem "codeclimate-test-reporter", group: :test, require: false

data/Guardfile

@@ -0,0 +1,19 @@
+guard :rspec, spec_paths: 'spec/unit' do
+  #run all specs if configuration is modified
+  watch('Guardfile')           { 'spec' }
+  watch('Gemfile.lock')        { 'spec' }
+  watch('spec/spec_helper.rb') { 'spec' }
+
+  # run all specs if supporting files files are modified
+  watch(%r{\Aspec/(?:lib|support|shared)/.+\.rb\z}) { 'spec' }
+
+  # run unit specs if associated lib code is modified
+  watch(%r{\Alib/(.+)\.rb\z})                                         { |m| Dir["spec/unit/#{m[1]}"]         }
+  watch(%r{\Alib/(.+)/support/(.+)\.rb\z})                            { |m| Dir["spec/unit/#{m[1]}/#{m[2]}"] }
+  watch("lib/#{File.basename(File.expand_path('../', __FILE__))}.rb") { 'spec'                               }
+
+  # run a spec if it is modified
+  watch(%r{\Aspec/(?:unit|integration)/.+_spec\.rb\z})
+
+  notification :tmux, :display_message => true
+end

data/LICENSE

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

data/README.md

@@ -0,0 +1,630 @@
+[gem]: https://rubygems.org/gems/virtus2
+
+NOTES
+------------
+
+Although the original author of this project has moved on to the `dry-` family of gems, which provides much more power and flexibility, we believe that there is still value in the simplicity and elegance of this original library in cases where that power is unnecessary. Hence the republishing of this gem as `virtus2` to continue to improve and update the gem.
+
+The `dry-` gems have a lot of community support and we would recommend looking there before coming back to this gem only if you think the complexity they provide is more than you need.
+
+Virtus
+======
+
+[![Gem Version](https://badge.fury.io/rb/virtus2.svg)][gem]
+
+Virtus allows you to define attributes on classes, modules or class instances with
+optional information about types, reader/writer method visibility and coercion
+behavior. It supports a lot of coercions and advanced mapping of embedded objects
+and collections.
+
+You can use it in many different contexts like:
+
+* Input parameter sanitization and coercion in web applications
+* Mapping JSON to domain objects
+* Encapsulating data-access in Value Objects
+* Domain model prototyping
+
+And probably more.
+
+Installation
+------------
+
+``` terminal
+$ gem install virtus
+```
+
+or in your **Gemfile**
+
+``` ruby
+gem 'virtus'
+```
+
+Examples
+--------
+
+### Using Virtus with Classes
+
+You can create classes extended with Virtus and define attributes:
+
+``` ruby
+class User
+  include Virtus.model
+
+  attribute :name, String
+  attribute :age, Integer
+  attribute :birthday, DateTime
+end
+
+user = User.new(:name => 'Piotr', :age => 31)
+user.attributes # => { :name => "Piotr", :age => 31, :birthday => nil }
+
+user.name # => "Piotr"
+
+user.age = '31' # => 31
+user.age.class # => Fixnum
+
+user.birthday = 'November 18th, 1983' # => #<DateTime: 1983-11-18T00:00:00+00:00 (4891313/2,0/1,2299161)>
+
+# mass-assignment
+user.attributes = { :name => 'Jane', :age => 21 }
+user.name # => "Jane"
+user.age  # => 21
+```
+
+### Cherry-picking extensions
+
+``` ruby
+# include attribute DSL + constructor + mass-assignment
+class User
+  include Virtus.model
+
+  attribute :name, String
+end
+
+user = User.new(:name => 'Piotr')
+user.attributes = { :name => 'John' }
+user.attributes
+# => {:name => 'John'}
+
+# include attribute DSL + constructor
+class User
+  include Virtus.model(:mass_assignment => false)
+
+  attribute :name, String
+end
+
+User.new(:name => 'Piotr')
+
+# include just the attribute DSL
+class User
+  include Virtus.model(:constructor => false, :mass_assignment => false)
+
+  attribute :name, String
+end
+
+user = User.new
+user.name = 'Piotr'
+```
+
+### Using Virtus with Modules
+
+You can create modules extended with Virtus and define attributes for later
+inclusion in your classes:
+
+```ruby
+module Name
+  include Virtus.module
+
+  attribute :name, String
+end
+
+module Age
+  include Virtus.module(:coerce => false)
+
+  attribute :age, Integer
+end
+
+class User
+  include Name, Age
+end
+
+user = User.new(:name => 'John', :age => 30)
+```
+
+### Dynamically Extending Instances
+
+It's also possible to dynamically extend an object with Virtus:
+
+```ruby
+class User
+  # nothing here
+end
+
+user = User.new
+user.extend(Virtus.model)
+user.attribute :name, String
+user.name = 'John'
+user.name # => 'John'
+```
+
+### Default Values
+
+``` ruby
+class Page
+  include Virtus.model
+
+  attribute :title, String
+
+  # default from a singleton value (integer in this case)
+  attribute :views, Integer, :default => 0
+
+  # default from a singleton value (boolean in this case)
+  attribute :published, Boolean, :default => false
+
+  # default from a callable object (proc in this case)
+  attribute :slug, String, :default => lambda { |page, attribute| page.title.downcase.gsub(' ', '-') }
+
+  # default from a method name as symbol
+  attribute :editor_title, String,  :default => :default_editor_title
+
+  def default_editor_title
+    published? ? title : "UNPUBLISHED: #{title}"
+  end
+end
+
+page = Page.new(:title => 'Virtus README')
+page.slug         # => 'virtus-readme'
+page.views        # => 0
+page.published    # => false
+page.editor_title # => "UNPUBLISHED: Virtus README"
+
+page.views = 10
+page.views                    # => 10
+page.reset_attribute(:views)  # => 0
+page.views                    # => 0
+```
+
+### Default values on dynamically extended instances
+
+This requires you to set `:lazy` option because default values are set in the
+constructor if it's set to false (which is the default setting):
+
+``` ruby
+User = Class.new
+user = User.new
+user.extend(Virtus.model)
+user.attribute :name, String, default: 'jane', lazy: true
+user.name # => "jane"
+```
+
+### Embedded Value
+
+``` ruby
+class City
+  include Virtus.model
+
+  attribute :name, String
+end
+
+class Address
+  include Virtus.model
+
+  attribute :street,  String
+  attribute :zipcode, String
+  attribute :city,    City
+end
+
+class User
+  include Virtus.model
+
+  attribute :name,    String
+  attribute :address, Address
+end
+
+user = User.new(:address => {
+  :street => 'Street 1/2', :zipcode => '12345', :city => { :name => 'NYC' } })
+
+user.address.street # => "Street 1/2"
+user.address.city.name # => "NYC"
+```
+
+### Collection Member Coercions
+
+``` ruby
+# Support "primitive" classes
+class Book
+  include Virtus.model
+
+  attribute :page_numbers, Array[Integer]
+end
+
+book = Book.new(:page_numbers => %w[1 2 3])
+book.page_numbers # => [1, 2, 3]
+
+# Support EmbeddedValues, too!
+class Address
+  include Virtus.model
+
+  attribute :address,     String
+  attribute :locality,    String
+  attribute :region,      String
+  attribute :postal_code, String
+end
+
+class PhoneNumber
+  include Virtus.model
+
+  attribute :number, String
+end
+
+class User
+  include Virtus.model
+
+  attribute :phone_numbers, Array[PhoneNumber]
+  attribute :addresses,     Set[Address]
+end
+
+user = User.new(
+  :phone_numbers => [
+    { :number => '212-555-1212' },
+    { :number => '919-444-3265' } ],
+  :addresses => [
+    { :address => '1234 Any St.', :locality => 'Anytown', :region => "DC", :postal_code => "21234" } ])
+
+user.phone_numbers # => [#<PhoneNumber:0x007fdb2d3bef88 @number="212-555-1212">, #<PhoneNumber:0x007fdb2d3beb00 @number="919-444-3265">]
+
+user.addresses # => #<Set: {#<Address:0x007fdb2d3be448 @address="1234 Any St.", @locality="Anytown", @region="DC", @postal_code="21234">}>
+```
+
+### Hash attributes coercion
+
+``` ruby
+class Package
+  include Virtus.model
+
+  attribute :dimensions, Hash[Symbol => Float]
+end
+
+package = Package.new(:dimensions => { 'width' => "2.2", :height => 2, "length" => 4.5 })
+package.dimensions # => { :width => 2.2, :height => 2.0, :length => 4.5 }
+```
+
+### IMPORTANT note about Boolean type
+
+Be aware that some libraries may do a terrible thing and define a global Boolean
+constant which breaks virtus' constant type lookup, if you see issues with the
+boolean type you can workaround it like that:
+
+``` ruby
+class User
+  include Virtus.model
+
+  attribute :admin, Axiom::Types::Boolean
+end
+```
+
+This will be improved in Virtus 2.0.
+
+### IMPORTANT note about member coercions
+
+Virtus performs coercions only when a value is being assigned. If you mutate the value later on using its own
+interfaces then coercion won't be triggered.
+
+Here's an example:
+
+``` ruby
+class Book
+  include Virtus.model
+
+  attribute :title, String
+end
+
+class Library
+  include Virtus.model
+
+  attribute :books, Array[Book]
+end
+
+library = Library.new
+
+# This will coerce Hash to a Book instance
+library.books = [ { :title => 'Introduction to Virtus' } ]
+
+# This WILL NOT COERCE the value because you mutate the books array with Array#<<
+library.books << { :title => 'Another Introduction to Virtus' }
+```
+
+A suggested solution to this problem would be to introduce your own class instead of using Array and implement
+mutation methods that perform coercions. For example:
+
+``` ruby
+class Book
+  include Virtus.model
+
+  attribute :title, String
+end
+
+class BookCollection < Array
+  def <<(book)
+   if book.kind_of?(Hash)
+    super(Book.new(book))
+   else
+     super
+   end
+  end
+end
+
+class Library
+  include Virtus.model
+
+  attribute :books, BookCollection[Book]
+end
+
+library = Library.new
+library.books << { :title => 'Another Introduction to Virtus' }
+```
+
+### Value Objects
+
+``` ruby
+class GeoLocation
+  include Virtus.value_object
+
+  values do
+    attribute :latitude,  Float
+    attribute :longitude, Float
+  end
+end
+
+class Venue
+  include Virtus.value_object
+
+  values do
+    attribute :name,     String
+    attribute :location, GeoLocation
+  end
+end
+
+venue = Venue.new(
+  :name     => 'Pub',
+  :location => { :latitude => 37.160317, :longitude => -98.437500 })
+
+venue.location.latitude # => 37.160317
+venue.location.longitude # => -98.4375
+
+# Supports object's equality
+
+venue_other = Venue.new(
+  :name     => 'Other Pub',
+  :location => { :latitude => 37.160317, :longitude => -98.437500 })
+
+venue.location === venue_other.location # => true
+```
+
+### Custom Coercions
+
+``` ruby
+require 'json'
+
+class Json < Virtus::Attribute
+  def coerce(value)
+    value.is_a?(::Hash) ? value : JSON.parse(value)
+  end
+end
+
+class User
+  include Virtus.model
+
+  attribute :info, Json, default: {}
+end
+
+user = User.new
+user.info = '{"email":"john@domain.com"}' # => {"email"=>"john@domain.com"}
+user.info.class # => Hash
+
+# With a custom attribute encapsulating coercion-specific configuration
+class NoisyString < Virtus::Attribute
+  def coerce(value)
+    value.to_s.upcase
+  end
+end
+
+class User
+  include Virtus.model
+
+  attribute :scream, NoisyString
+end
+
+user = User.new(:scream => 'hello world!')
+user.scream # => "HELLO WORLD!"
+```
+
+### Private Attributes
+
+``` ruby
+class User
+  include Virtus.model
+
+  attribute :unique_id, String, :writer => :private
+
+  def set_unique_id(id)
+    self.unique_id = id
+  end
+end
+
+user = User.new(:unique_id => '1234-1234')
+user.unique_id # => nil
+
+user.unique_id = '1234-1234' # => NoMethodError: private method `unique_id='
+
+user.set_unique_id('1234-1234')
+user.unique_id # => '1234-1234'
+```
+
+### Overriding setters
+
+``` ruby
+class User
+  include Virtus.model
+
+  attribute :name, String
+
+  def name=(new_name)
+    custom_name = nil
+    if new_name == "Godzilla"
+      custom_name = "Can't tell"
+    end
+    super custom_name || new_name
+  end
+end
+
+user = User.new(name: "Frank")
+user.name # => 'Frank'
+
+user = User.new(name: "Godzilla")
+user.name # => 'Can't tell'
+
+```
+
+## Strict Coercion Mode
+
+By default Virtus returns the input value even when it couldn't coerce it to the expected type.
+If you want to catch such cases in a noisy way you can use the strict mode in which
+Virtus raises an exception when it failed to coerce an input value.
+
+``` ruby
+class User
+  include Virtus.model(:strict => true)
+
+  attribute :admin, Boolean
+end
+
+# this will raise an error
+User.new :admin => "can't really say if true or false"
+```
+
+## Nullify Blank Strings Mode
+
+If you want to replace empty Strings with `nil` values (since they can't be
+coerced into the expected type), you can use the `:nullify_blank` option.
+
+``` ruby
+class User
+  include Virtus.model(:nullify_blank => true)
+
+  attribute :birthday, Date
+end
+
+User.new(:birthday => "").birthday # => nil
+```
+
+### Enums
+
+Virtus supports enums out of the box, represented by a list of Symbols:
+
+```ruby
+class FileProcessor
+  include Virtus.model(strict: true)
+  
+  attribute :mode, Enum[:read, :write]
+end
+processor = FileProcessor.new(mode: :execute) # CoercionError!
+processor = FileProcessor.new(mode: :read).mode # :read
+```
+
+## Building modules with custom configuration
+
+You can also build Virtus modules that contain their own configuration.
+
+```ruby
+YupNopeBooleans = Virtus.model { |mod|
+  mod.coerce = true
+  mod.coercer.config.string.boolean_map = { 'nope' => false, 'yup' => true }
+}
+
+class User
+  include YupNopeBooleans
+
+  attribute :name, String
+  attribute :admin, Boolean
+end
+
+# Or just include the module straight away ...
+class User
+  include Virtus.model(:coerce => false)
+
+  attribute :name, String
+  attribute :admin, Boolean
+end
+```
+
+## Attribute Finalization and Circular Dependencies
+
+If a type references another type which happens to not be available yet you need
+to use lazy-finalization of attributes and finalize virtus manually after all
+types have been already loaded:
+
+``` ruby
+# in blog.rb
+class Blog
+  include Virtus.model(:finalize => false)
+
+  attribute :posts, Array['Post']
+end
+
+# in post.rb
+class Post
+  include Virtus.model(:finalize => false)
+
+  attribute :blog, 'Blog'
+end
+
+# after loading both files just do:
+Virtus.finalize
+
+# constants will be resolved:
+Blog.attribute_set[:posts].member_type.primitive # => Post
+Post.attribute_set[:blog].type.primitive # => Blog
+```
+
+## Plugins / Extensions
+
+List of plugins/extensions that add features to Virtus:
+
+* [virtus-localized](https://github.com/XescuGC/virtus-localized): Localize the attributes
+* [virtus-relations](https://github.com/smanolloff/virtus-relations): Add relations to Virtus objects
+
+Ruby version support
+--------------------
+
+Virtus is known to work correctly with the following rubies:
+
+* 1.9.3
+* 2.0.0
+* 2.1.2
+* 2.7.0
+* 3.0.0
+* jruby
+* (probably) rbx
+
+Credits
+-------
+
+* Dan Kubb ([dkubb](https://github.com/dkubb))
+* Chris Corbyn ([d11wtq](https://github.com/d11wtq))
+* Emmanuel Gomez ([emmanuel](https://github.com/emmanuel))
+* Fabio Rehm ([fgrehm](https://github.com/fgrehm))
+* Ryan Closner ([rclosner](https://github.com/rclosner))
+* Markus Schirp ([mbj](https://github.com/mbj))
+* Yves Senn ([senny](https://github.com/senny))
+
+Contributing
+-------------
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with Rakefile or version
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.