virtus2 2.0.1

data/lib/virtus/support/equalizer.rb

@@ -0,0 +1,128 @@
+module Virtus
+
+  # Define equality, equivalence and inspection methods
+  class Equalizer < Module
+
+    # Initialize an Equalizer with the given keys
+    #
+    # Will use the keys with which it is initialized to define #cmp?,
+    # #hash, and #inspect
+    #
+    # @param [String] name
+    #
+    # @param [Array<Symbol>] keys
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def initialize(name, keys = [])
+      @name = name.dup.freeze
+      @keys = keys.dup
+      define_methods
+      include_comparison_methods
+    end
+
+    # Append a key and compile the equality methods
+    #
+    # @return [Equalizer] self
+    #
+    # @api private
+    def <<(key)
+      @keys << key
+      self
+    end
+
+  private
+
+    # Define the equalizer methods based on #keys
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_methods
+      define_cmp_method
+      define_hash_method
+      define_inspect_method
+    end
+
+    # Define an #cmp? method based on the instance's values identified by #keys
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_cmp_method
+      keys = @keys
+      define_method(:cmp?) do |comparator, other|
+        keys.all? { |key| send(key).send(comparator, other.send(key)) }
+      end
+    end
+
+    # Define a #hash method based on the instance's values identified by #keys
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_hash_method
+      keys = @keys
+      define_method(:hash) do
+        keys.map { |key| send(key) }.push(self.class).hash
+      end
+    end
+
+    # Define an inspect method that reports the values of the instance's keys
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_inspect_method
+      name, keys = @name, @keys
+      define_method(:inspect) do
+        "#<#{name}#{keys.map { |key| " #{key}=#{send(key).inspect}" }.join}>"
+      end
+    end
+
+    # Include the #eql? and #== methods
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def include_comparison_methods
+      module_eval { include Methods }
+    end
+
+    # The comparison methods
+    module Methods
+
+      # Compare the object with other object for equality
+      #
+      # @example
+      #   object.eql?(other)  # => true or false
+      #
+      # @param [Object] other
+      #   the other object to compare with
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def eql?(other)
+        instance_of?(other.class) && cmp?(__method__, other)
+      end
+
+      # Compare the object with other object for equivalency
+      #
+      # @example
+      #   object == other  # => true or false
+      #
+      # @param [Object] other
+      #   the other object to compare with
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def ==(other)
+        other.kind_of?(self.class) && cmp?(__method__, other)
+      end
+
+    end # module Methods
+  end # class Equalizer
+end # module Virtus

data/lib/virtus/support/options.rb

@@ -0,0 +1,113 @@
+module Virtus
+
+  # A module that adds class and instance level options
+  module Options
+
+    # Returns default options hash for a given attribute class
+    #
+    # @example
+    #   Virtus::Attribute::String.options
+    #   # => {:primitive => String}
+    #
+    # @return [Hash]
+    #   a hash of default option values
+    #
+    # @api public
+    def options
+      accepted_options.each_with_object({}) do |option_name, options|
+        option_value         = send(option_name)
+        options[option_name] = option_value unless option_value.nil?
+      end
+    end
+
+    # Returns an array of valid options
+    #
+    # @example
+    #   Virtus::Attribute::String.accepted_options
+    #   # => [:primitive, :accessor, :reader, :writer]
+    #
+    # @return [Array]
+    #   the array of valid option names
+    #
+    # @api public
+    def accepted_options
+      @accepted_options ||= []
+    end
+
+    # Defines which options are valid for a given attribute class
+    #
+    # @example
+    #   class MyAttribute < Virtus::Attribute
+    #     accept_options :foo, :bar
+    #   end
+    #
+    # @return [self]
+    #
+    # @api public
+    def accept_options(*new_options)
+      add_accepted_options(new_options)
+      new_options.each { |option| define_option_method(option) }
+      descendants.each { |descendant| descendant.add_accepted_options(new_options) }
+      self
+    end
+
+  protected
+
+    # Adds a reader/writer method for the give option name
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_option_method(option)
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def self.#{option}(value = Undefined)           # def self.primitive(value = Undefined)
+          @#{option} = nil unless defined?(@#{option})  #   @primitive = nil unless defined?(@primitive)
+          return @#{option} if value.equal?(Undefined)  #   return @primitive if value.equal?(Undefined)
+          @#{option} = value                            #   @primitive = value
+          self                                          #   self
+        end                                             # end
+      RUBY
+    end
+
+    # Sets default options
+    #
+    # @param [#each] new_options
+    #   options to be set
+    #
+    # @return [self]
+    #
+    # @api private
+    def set_options(new_options)
+      new_options.each { |pair| send(*pair) }
+      self
+    end
+
+    # Adds new options that an attribute class can accept
+    #
+    # @param [#to_ary] new_options
+    #   new options to be added
+    #
+    # @return [self]
+    #
+    # @api private
+    def add_accepted_options(new_options)
+      accepted_options.concat(new_options)
+      self
+    end
+
+  private
+
+    # Adds descendant to descendants array and inherits default options
+    #
+    # @param [Class] descendant
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def inherited(descendant)
+      super
+      descendant.add_accepted_options(accepted_options).set_options(options)
+    end
+
+  end # module Options
+end # module Virtus

data/lib/virtus/support/type_lookup.rb

@@ -0,0 +1,109 @@
+module Virtus
+
+  # A module that adds type lookup to a class
+  module TypeLookup
+
+    TYPE_FORMAT = /\A[A-Z]\w*\z/.freeze
+
+    # Set cache ivar on the model
+    #
+    # @param [Class] model
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def self.extended(model)
+      model.instance_variable_set('@type_lookup_cache', {})
+    end
+
+    # Returns a descendant based on a name or class
+    #
+    # @example
+    #   MyClass.determine_type('String')  # => MyClass::String
+    #
+    # @param [Class, #to_s] class_or_name
+    #   name of a class or a class itself
+    #
+    # @return [Class]
+    #   a descendant
+    #
+    # @return [nil]
+    #   nil if the type cannot be determined by the class_or_name
+    #
+    # @api public
+    def determine_type(class_or_name)
+      @type_lookup_cache[class_or_name] ||= determine_type_and_cache(class_or_name)
+    end
+
+    # Return the default primitive supported
+    #
+    # @return [Class]
+    #
+    # @api private
+    def primitive
+      raise NotImplementedError, "#{self}.primitive must be implemented"
+    end
+
+  private
+
+    # @api private
+    def determine_type_and_cache(class_or_name)
+      case class_or_name
+      when singleton_class
+        determine_type_from_descendant(class_or_name)
+      when Class
+        determine_type_from_primitive(class_or_name)
+      else
+        determine_type_from_string(class_or_name.to_s)
+      end
+    end
+
+    # Return the class given a descendant
+    #
+    # @param [Class] descendant
+    #
+    # @return [Class]
+    #
+    # @api private
+    def determine_type_from_descendant(descendant)
+      descendant if descendant < self
+    end
+
+    # Return the class given a primitive
+    #
+    # @param [Class] primitive
+    #
+    # @return [Class]
+    #
+    # @return [nil]
+    #   nil if the type cannot be determined by the primitive
+    #
+    # @api private
+    def determine_type_from_primitive(primitive)
+      type = nil
+      descendants.select(&:primitive).reverse_each do |descendant|
+        descendant_primitive = descendant.primitive
+        next unless primitive <= descendant_primitive
+        type = descendant if type.nil? or type.primitive > descendant_primitive
+      end
+      type
+    end
+
+    # Return the class given a string
+    #
+    # @param [String] string
+    #
+    # @return [Class]
+    #
+    # @return [nil]
+    #   nil if the type cannot be determined by the string
+    #
+    # @api private
+    def determine_type_from_string(string)
+      if string =~ TYPE_FORMAT and const_defined?(string, *EXTRA_CONST_ARGS)
+        const_get(string, *EXTRA_CONST_ARGS)
+      end
+    end
+
+  end # module TypeLookup
+end # module Virtus

data/lib/virtus/value_object.rb

@@ -0,0 +1,150 @@
+module Virtus
+
+  # Include this Module for Value Object semantics
+  #
+  # The idea is that instances should be immutable and compared based on state
+  #   (rather than identity, as is typically the case)
+  #
+  # @example
+  #   class GeoLocation
+  #     include Virtus::ValueObject
+  #     attribute :latitude,  Float
+  #     attribute :longitude, Float
+  #   end
+  #
+  #   location = GeoLocation.new(:latitude => 10, :longitude => 100)
+  #   same_location = GeoLocation.new(:latitude => 10, :longitude => 100)
+  #   location == same_location       #=> true
+  #   hash = { location => :foo }
+  #   hash[same_location]             #=> :foo
+  module ValueObject
+
+    # Callback to configure including Class as a Value Object
+    #
+    # Including Class will include Virtus and have additional
+    #   value object semantics defined in this module
+    #
+    # @return [Undefined]
+    #
+    # TODO: stacking modules is getting painful
+    #   time for Facets' module_inheritance, ActiveSupport::Concern or the like
+    #
+    # @api private
+    def self.included(base)
+      Virtus.warn "Virtus::ValueObject is deprecated and will be removed in 1.0.0 #{caller.first}"
+
+      base.instance_eval do
+        include Virtus
+        include InstanceMethods
+        extend ClassMethods
+        extend AllowedWriterMethods
+        private :attributes=
+      end
+    end
+
+    private_class_method :included
+
+    module InstanceMethods
+
+      # ValueObjects are immutable and can't be cloned
+      #
+      # They always represent the same value
+      #
+      # @example
+      #
+      #   value_object.clone === value_object # => true
+      #
+      # @return [self]
+      #
+      # @api public
+      def clone
+        self
+      end
+      alias dup clone
+
+      # Create a new ValueObject by combining the passed attribute hash with
+      # the instances attributes.
+      #
+      # @example
+      #
+      #   number = PhoneNumber.new(kind: "mobile", number: "123-456-78-90")
+      #   number.with(number: "987-654-32-10")
+      #   # => #<PhoneNumber kind="mobile" number="987-654-32-10">
+      #
+      # @return [Object]
+      #
+      # @api public
+      def with(attribute_updates)
+        self.class.new(attribute_set.get(self).merge(attribute_updates))
+      end
+
+    end
+
+    module AllowedWriterMethods
+      # The list of writer methods that can be mass-assigned to in #attributes=
+      #
+      # @return [Set]
+      #
+      # @api private
+      def allowed_writer_methods
+        @allowed_writer_methods ||=
+          begin
+            allowed_writer_methods = super
+            allowed_writer_methods += attribute_set.map{|attr| "#{attr.name}="}
+            allowed_writer_methods.to_set.freeze
+          end
+      end
+    end
+
+    module ClassMethods
+
+      # Define an attribute on the receiver
+      #
+      # The Attribute will have private writer methods (eg., immutable instances)
+      #   and be used in equality/equivalence comparisons
+      #
+      # @example
+      #   class GeoLocation
+      #     include Virtus::ValueObject
+      #
+      #     attribute :latitude,  Float
+      #     attribute :longitude, Float
+      #   end
+      #
+      # @see Virtus::ClassMethods.attribute
+      #
+      # @return [self]
+      #
+      # @api public
+      def attribute(name, type, options = {})
+        equalizer << name
+        super name, type, options.merge(:writer => :private)
+      end
+
+      # Define and include a module that provides Value Object semantics
+      #
+      # Included module will have #inspect, #eql?, #== and #hash
+      # methods whose definition is based on the _keys_ argument
+      #
+      # @example
+      #   virtus_class.equalizer
+      #
+      # @return [Equalizer]
+      #   An Equalizer module which defines #inspect, #eql?, #== and #hash
+      #   for instances of this class
+      #
+      # @api public
+      def equalizer
+        @equalizer ||=
+          begin
+            equalizer = Virtus::Equalizer.new(name || inspect)
+            include equalizer
+            equalizer
+          end
+      end
+
+    end # module ClassMethods
+
+  end # module ValueObject
+
+end # module Virtus