virtus 1.0.0.beta8 → 1.0.0.rc1

data/Changelog.md

@@ -1,3 +1,30 @@
+# v1.0.0 [to-be-released]
+
+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)
+* [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..master](https://github.com/solnic/virtus/compare/v0.5.4...master)
+
 # v0.5.4 2012-12-20
 
 * [feature] Allow *any* enumerable to be a collection attribute (aptinio)
@@ -12,7 +39,7 @@
 * [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)
-* [interal] Switched to rspec 2 and mutant for mutation testing (mbj)
+* [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)
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2012 Piotr Solnica
+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

data/README.md

@@ -69,46 +69,36 @@ user.age  # => 21
 ### Cherry-picking extensions
 
 ``` ruby
-# include just the attribute DSL
+# include attribute DSL + constructor + mass-assignment
 class User
-  include Virtus::Model::Core
+  include Virtus.model
 
   attribute :name, String
 end
 
-user = User.new
-user.name = 'Piotr'
+user = User.new(:name => 'Piotr')
+user.attributes = { :name => 'John' }
+user.attributes
+# => {:name => 'John'}
 
 # include attribute DSL + constructor
 class User
-  include Virtus::Model::Core
-  include Virtus::Model::Constructor
+  include Virtus.model(:mass_assignment => false)
 
   attribute :name, String
 end
 
 User.new(:name => 'Piotr')
 
-# include attribute DSL + constructor + mass-assignment
+# include just the attribute DSL
 class User
-  include Virtus::Model::Core
-  include Virtus::Model::Constructor
-  include Virtus::Model::MassAssignment
+  include Virtus.model(:constructor => false, :mass_assignment => false)
 
   attribute :name, String
 end
 
-user = User.new(:name => 'Piotr')
-user.attributes = { :name => 'John' }
-user.attributes
-# => {:name => 'John'}
-
-# starting from virtus 1.0.0 preferred way to do this is to use module builder
-MyModel = Virtus.model(:constructor => false, :mass_assignment => false)
-
-class User
-  include MyModel
-end
+user = User.new
+user.name = 'Piotr'
 ```
 
 ### Using Virtus with Modules
@@ -525,7 +515,7 @@ 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 
+to use lazy-finalization of attributes and finalize virtus manually after all
 types have been already loaded:
 
 ``` ruby

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
-threshold: 13
-total_score: 321
+threshold: 24
+total_score: 439

data/config/flog.yml

@@ -1,2 +1,2 @@
 ---
-threshold: 21.4
+threshold: 33

data/config/mutant.yml

@@ -3,12 +3,13 @@ name: virtus
 namespace:
   - 'Virtus::Attribute'
   - 'Virtus::AttributeSet'
+  - 'Virtus::Builder'
   - 'Virtus::ClassInclusions'
   - 'Virtus::ClassMethods'
   - 'Virtus::Configuration'
   - 'Virtus::ConstMissingExtensions'
   - 'Virtus::Extensions'
   - 'Virtus::InstanceMethods'
-  - 'Virtus::ModuleBuilder'
+  - 'Virtus::Model'
   - 'Virtus::ModuleExtensions'
   - 'Virtus::ValueObject'

data/config/reek.yml

@@ -1,7 +1,6 @@
 ---
 Attribute:
-  enabled: true
-  exclude: []
+  enabled: false
 BooleanParameter:
   enabled: true
   exclude: []
@@ -10,23 +9,39 @@ ClassVariable:
   exclude: []
 ControlParameter:
   enabled: true
-  exclude: []
+  exclude:
+    - 'Virtus::InstanceMethods::Constructor#initialize'
 DataClump:
   enabled: true
-  exclude: []
   max_copies: 2
   min_clump_size: 2
+  exclude:
+    - 'Virtus::AttributeSet'
 DuplicateMethodCall:
   enabled: false
 FeatureEnvy:
   enabled: true
-  exclude: []
+  exclude:
+    - 'Virtus::Attribute::Boolean#value_coerced?'
+    - 'Virtus::AttributeSet#get'
+    - 'Virtus::AttributeSet#set'
+    - 'Virtus::AttributeSet#skip_default?'
+    - 'Virtus::Builder#add_extended_hook'
+    - 'Virtus::Builder#add_included_hook'
+    - 'Virtus::InstanceMethods#assert_valid_name'
+    - 'Virtus::TypeLookup#determine_type_from_primitive'
 IrresponsibleModule:
   enabled: true
   exclude: []
 LongParameterList:
   enabled: true
-  exclude: []
+  exclude:
+    - 'Virtus::AttributeSet#define_reader_method'
+    - 'Virtus::AttributeSet#define_writer_method'
+    - 'Virtus::Extensions::Methods#attribute'
+    - 'Virtus::ModuleExtensions#attribute'
+    - 'Virtus::ModuleExtensions#self.setup'
+    - 'Virtus::ValueObject::ClassMethods#attribute'
   max_params: 2
 LongYieldList:
   enabled: true
@@ -36,34 +51,65 @@ NestedIterators:
   enabled: true
   max_allowed_nesting: 1
   ignore_iterators: []
-  exclude: []
+  exclude:
+    - 'Virtus::Builder#add_extended_hook'
+    - 'Virtus::Builder#add_included_hook'
+    - 'Virtus::ModuleBuilder#add_included_hook'
+    - 'Virtus::Equalizer#define_cmp_method'
+    - 'Virtus::Equalizer#define_hash_method'
+    - 'Virtus::Equalizer#define_inspect_method'
 NilCheck:
   enabled: true
-  exclude: []
+  exclude:
+    - 'Virtus::Attribute::EmbeddedValue::FromOpenStruct#call'
+    - 'Virtus::Attribute::EmbeddedValue::FromStruct#call'
+    - 'Virtus::Attribute::Strict#coerce'
+    - 'Virtus::Options#options'
+    - 'Virtus::TypeLookup#determine_type_from_primitive'
 RepeatedConditional:
   enabled: true
-  exclude: []
   max_ifs: 1
+  exclude:
+    - 'Virtus::AttributeSet'
+    - 'Virtus::Builder'
 TooManyInstanceVariables:
   enabled: true
-  exclude: []
   max_instance_variables: 3
+  exclude:
+    - 'Virtus::Attribute'
+    - 'Virtus::Attribute::Builder'
+    - 'Virtus::Configuration'
 TooManyMethods:
   enabled: true
-  exclude: []
-  max_methods: 10
+  max_methods: 6
+  exclude:
+    - 'Virtus::Equalizer'
+    - 'Virtus::Builder'
+    - 'Virtus::Attribute'
+    - 'Virtus::AttributeSet'
 TooManyStatements:
   enabled: true
-  exclude: []
   max_statements: 4
+  exclude:
+    - 'Virtus#self.included'
+    - 'Virtus::Attribute::Builder#self.determine_type'
+    - 'Virtus::Attribute::Collection#self.infer'
+    - 'Virtus::Attribute::Hash#self.infer'
+    - 'Virtus::Builder#add_extended_hook'
+    - 'Virtus::Builder#add_included_hook'
+    - 'Virtus::ModuleBuilder#add_included_hook'
+    - 'Virtus::ClassInclusions#self.included'
+    - 'Virtus::ClassMethods#self.extended'
+    - 'Virtus::Extensions#self.extended'
+    - 'Virtus::ModuleExtensions#included'
+    - 'Virtus::TypeLookup#determine_type_from_primitive'
+    - 'Virtus::ValueObject#self.included'
 UncommunicativeMethodName:
   enabled: true
-  exclude: []
   reject:
   - !ruby/regexp /^[a-z]$/
   - !ruby/regexp /[0-9]$/
   - !ruby/regexp /[A-Z]/
-  accept: []
 UncommunicativeModuleName:
   enabled: true
   exclude: []
@@ -78,7 +124,7 @@ UncommunicativeParameterName:
   - !ruby/regexp /^.$/
   - !ruby/regexp /[0-9]$/
   - !ruby/regexp /[A-Z]/
-  accept: []
+  accept: ['_']
 UncommunicativeVariableName:
   enabled: true
   exclude: []
@@ -92,5 +138,9 @@ UnusedParameters:
   exclude: []
 UtilityFunction:
   enabled: true
-  exclude: []
   max_helper_calls: 0
+  exclude:
+    - 'Virtus::Attribute::Boolean#value_coerced?'
+    - 'Virtus::AttributeSet#set_default'
+    - 'Virtus::AttributeSet#skip_default?'
+    - 'Virtus::Extensions::Methods#merge_options'

data/lib/virtus.rb

@@ -25,6 +25,8 @@ module Virtus
   #
   # @return [undefined]
   #
+  # @deprecated
+  #
   # @api private
   def self.included(object)
     super
@@ -44,6 +46,8 @@ module Virtus
   #
   # @return [undefined]
   #
+  # @deprecated
+  #
   # @api private
   def self.extended(object)
     Virtus.warn("extending with Virtus module is deprecated. Use 'extend(Virtus.model)' instead #{caller.first}")
@@ -124,21 +128,53 @@ module Virtus
   #
   # @api public
   def self.model(options = {}, &block)
-    ModelExtensionBuilder.call(options, &block)
+    ModelBuilder.call(options, &block)
   end
 
   # Builds a module for...modules
   #
+  # @example
+  #
+  #   module Common
+  #     include Virtus.module
+  #
+  #     attribute :name, String
+  #     attribute :age,  Integer
+  #   end
+  #
+  #   class User
+  #     include Common
+  #   end
+  #
+  #   class Admin
+  #     include Common
+  #   end
+  #
+  # @return [Module]
+  #
   # @api public
   def self.module(options = {}, &block)
-    ModuleExtensionBuilder.call(options, &block)
+    ModuleBuilder.call(options, &block)
   end
 
   # Builds a module for value object models
   #
+  # @example
+  #
+  #   class GeoLocation
+  #     include Virtus.value_object
+  #
+  #     values do
+  #       attribute :lat, Float
+  #       attribute :lng, Float
+  #     end
+  #   end
+  #
+  # @return [Module]
+  #
   # @api public
   def self.value_object(options = {}, &block)
-    ValueObjectExtensionBuilder.call(options, &block)
+    ValueObjectBuilder.call(options, &block)
   end
 
   # Global configuration instance
@@ -150,9 +186,28 @@ module Virtus
     @configuration ||= Configuration.new
   end
 
+  # Finalize pending attributes
+  #
+  # @example
+  #   class User
+  #     include Virtus.model(:finalize => false)
+  #
+  #     attribute :address, 'Address'
+  #   end
+  #
+  #   class Address
+  #     include Virtus.model(:finalize => false)
+  #
+  #     attribute :user, 'User'
+  #   end
+  #
+  #   Virtus.finalize # this will resolve constant names
+  #
+  # @return [Array] array of finalized models
+  #
   # @api public
   def self.finalize
-    ExtensionBuilder.pending.each do |klass|
+    Builder.pending.each do |klass|
       klass.attribute_set.finalize
     end
   end
@@ -180,7 +235,8 @@ require 'virtus/class_inclusions'
 require 'virtus/module_extensions'
 
 require 'virtus/configuration'
-require 'virtus/module_builder'
+require 'virtus/builder'
+require 'virtus/builder/hook_context'
 
 require 'virtus/class_methods'
 require 'virtus/instance_methods'

data/lib/virtus/attribute.rb

@@ -1,5 +1,20 @@
 module Virtus
 
+  # Attribute objects handle coercion and provide interface to hook into an
+  # attribute set instance that's included into a class or object
+  #
+  # @example
+  #
+  #   # non-strict mode
+  #   attr = Virtus::Attribute.build(Integer)
+  #   attr.coerce('1')
+  #   # => 1
+  #
+  #   # strict mode
+  #   attr = Virtus::Attribute.build(Integer, :strict => true)
+  #   attr.coerce('not really coercible')
+  #   # => Virtus::CoercionError: Failed to coerce "fsafa" into Integer
+  #
   class Attribute
     extend DescendantsTracker, Options, TypeLookup
 
@@ -24,22 +39,28 @@ module Virtus
       self
     end
 
-    attr_reader :type, :primitive, :options, :default_value, :coercer
+    # Return type of this attribute
+    #
+    # @return [Axiom::Types::Type]
+    #
+    # @api public
+    attr_reader :type
+
+    # @api private
+    attr_reader :primitive, :options, :default_value, :coercer
 
     # Builds an attribute instance
     #
-    # @param [Symbol] name
-    #   the name of an attribute
-    #
-    # @param [Class] type
-    #   optional type class of an attribute
+    # @param [Class,Array,Hash,String,Symbol] type
+    #   this can be an explicit class or an object from which virtus can infer
+    #   the type
     #
     # @param [#to_hash] options
     #   optional extra options hash
     #
     # @return [Attribute]
     #
-    # @api private
+    # @api public
     def self.build(type, options = {})
       Builder.call(type, options)
     end
@@ -52,13 +73,6 @@ module Virtus
       )
     end
 
-    # @api private
-    def self.new(*args)
-      attribute = super
-      yield(attribute)
-      attribute
-    end
-
     # @api private
     def self.build_type(definition)
       Axiom::Types.infer(definition.primitive)
@@ -69,16 +83,6 @@ module Virtus
       # noop
     end
 
-    # Initializes an attribute instance
-    #
-    # @param [#to_sym] name
-    #   the name of an attribute
-    #
-    # @param [#to_hash] options
-    #   hash of extra options which overrides defaults set on an attribute class
-    #
-    # @return [undefined]
-    #
     # @api private
     def initialize(type, options)
       @type          = type
@@ -88,16 +92,37 @@ module Virtus
       @coercer       = options.fetch(:coercer)
     end
 
+    # Coerce the input into the expected type
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String)
+    #   attr.coerce(:one) # => 'one'
+    #
+    # @param [Object] input
+    #
     # @api public
-    def coerce(value)
-      coercer.call(value)
+    def coerce(input)
+      coercer.call(input)
     end
 
+    # Return a new attribute with the new name
+    #
+    # @param [Symbol] name
+    #
+    # @return [Attribute]
+    #
     # @api public
     def rename(name)
       self.class.build(type, options.merge(:name => name))
     end
 
+    # Return if the given value was coerced
+    #
+    # @param [Object] value
+    #
+    # @return [Boolean]
+    #
     # @api public
     def value_coerced?(value)
       coercer.success?(primitive, value)
@@ -105,6 +130,14 @@ module Virtus
 
     # Return if the attribute is coercible
     #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :coerce => true)
+    #   attr.coercible? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :coerce => false)
+    #   attr.coercible? # => false
+    #
     # @return [Boolean]
     #
     # @api public
@@ -112,21 +145,69 @@ module Virtus
       kind_of?(Coercible)
     end
 
+    # Return if the attribute has lazy default value evaluation
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :lazy => true)
+    #   attr.lazy? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :lazy => false)
+    #   attr.lazy? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def lazy?
       kind_of?(LazyDefault)
     end
 
+    # Return if the attribute is in the strict coercion mode
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :strict => true)
+    #   attr.strict? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :strict => false)
+    #   attr.strict? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def strict?
       kind_of?(Strict)
     end
 
+    # Return if the attribute is accepts nil values as valid coercion output
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :required => true)
+    #   attr.required? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :required => false)
+    #   attr.required? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def required?
       options[:required]
     end
 
+    # Return if the attribute was already finalized
+    #
+    # @example
+    #
+    #   attr = Virtus::Attribute.build(String, :finalize => true)
+    #   attr.finalized? # => true
+    #
+    #   attr = Virtus::Attribute.build(String, :finalize => false)
+    #   attr.finalized? # => false
+    #
+    # @return [Boolean]
+    #
     # @api public
     def finalized?
       frozen?