dm-validations 1.1.0 → 1.2.0.rc1

data/lib/dm-validations/validators/generic_validator.rb

@@ -1,12 +1,11 @@
 # -*- coding: utf-8 -*-
 module DataMapper
   module Validations
-
     # All validators extend this base class. Validators must:
     #
-    # * Implement the initialize method to capture its parameters, also calling
-    #   super to have this parent class capture the optional, general :if and
-    #   :unless parameters.
+    # * Implement the initialize method to capture its parameters, also
+    #   calling super to have this parent class capture the optional,
+    #   general :if and :unless parameters.
     # * Implement the call method, returning true or false. The call method
     #   provides the validation logic.
     #
@@ -17,16 +16,23 @@ module DataMapper
       attr_accessor :if_clause, :unless_clause
       attr_reader   :field_name, :options, :humanized_field_name
 
-      # Construct a validator. Capture the :if and :unless clauses when present.
+      # Construct a validator. Capture the :if and :unless clauses when
+      # present.
+      #
+      # @param [String, Symbol] field
+      #   The property specified for validation.
+      #
+      # @option [Symbol, Proc] :if
+      #   The name of a method or a Proc to call to determine if the
+      #   validation should occur.
       #
-      # @param field<String, Symbol> The property specified for validation
+      # @option [Symbol, Proc] :unless
+      #   The name of a method or a Proc to call to determine if the
+      #   validation should not occur.
       #
-      # @option :if<Symbol, Proc>   The name of a method or a Proc to call to
-      #                     determine if the validation should occur.
-      # @option :unless<Symbol, Proc> The name of a method or a Proc to call to
-      #                         determine if the validation should not occur
-      # All additional key/value pairs are passed through to the validator
-      # that is sub-classing this GenericValidator
+      # @note
+      #   All additional key/value pairs are passed through to the validator
+      #   that is sub-classing this GenericValidator
       #
       def initialize(field_name, options = {})
         @field_name           = field_name
@@ -36,26 +42,34 @@ module DataMapper
         @humanized_field_name = DataMapper::Inflector.humanize(@field_name)
       end
 
-      # Add an error message to a target resource. If the error corresponds to a
-      # specific field of the resource, add it to that field, otherwise add it
-      # as a :general message.
+      # Add an error message to a target resource. If the error corresponds
+      # to a specific field of the resource, add it to that field,
+      # otherwise add it as a :general message.
       #
-      # @param <Object> target the resource that has the error
-      # @param <String> message the message to add
-      # @param <Symbol> field_name the name of the field that caused the error
+      # @param [Object] target
+      #   The resource that has the error.
       #
-      # TODO - should the field_name for a general message be :default???
+      # @param [String] message
+      #   The message to add.
+      #
+      # @param [Symbol] field_name
+      #   The name of the field that caused the error.
       #
       def add_error(target, message, field_name = :general)
+        # TODO: should the field_name for a general message be :default???
         target.errors.add(field_name, message)
       end
 
-      # Call the validator. "call" is used so the operation is BoundMethod and
-      # Block compatible. This must be implemented in all concrete classes.
+      # Call the validator. "call" is used so the operation is BoundMethod
+      # and Block compatible. This must be implemented in all concrete
+      # classes.
+      #
+      # @param [Object] target
+      #   The resource that the validator must be called against.
+      #
+      # @return [Boolean]
+      #   true if valid, otherwise false.
       #
-      # @param <Object> target  the resource that the validator must be called
-      #                         against
-      # @return <Boolean> true if valid, otherwise false
       def call(target)
         raise NotImplementedError, "#{self.class}#call must be implemented"
       end
@@ -64,26 +78,37 @@ module DataMapper
       # target by evaluating the :if and :unless clauses
       # optionally passed while specifying any validator.
       #
-      # @param <Object> target the resource that we check against
-      # @return <Boolean> true if should be run, otherwise false
+      # @param [Object] target
+      #   The resource that we check against.
+      #
+      # @return [Boolean]
+      #   true if should be run, otherwise false.
+      #
+      # @api private
       def execute?(target)
         if unless_clause = self.unless_clause
-          return !target.__send__(unless_clause) if unless_clause.kind_of?(Symbol)
-          return !unless_clause.call(target)     if unless_clause.respond_to?(:call)
+          !evaluate_conditional_clause(target, unless_clause)
+        elsif if_clause = self.if_clause
+          evaluate_conditional_clause(target, if_clause)
+        else
+          true
         end
+      end
 
-        if if_clause = self.if_clause
-          return target.__send__(if_clause) if if_clause.kind_of?(Symbol)
-          return if_clause.call(target)     if if_clause.respond_to?(:call)
+      # @api private
+      def evaluate_conditional_clause(target, clause)
+        if clause.kind_of?(Symbol)
+          target.__send__(clause)
+        elsif clause.respond_to?(:call)
+          clause.call(target)
         end
-
-        true
       end
 
       # Set the default value for allow_nil and allow_blank
       #
       # @param [Boolean] default value
-      # @return <undefined>
+      #
+      # @api private
       def set_optional_by_default(default = true)
         [ :allow_nil, :allow_blank ].each do |key|
           @options[key] = true unless options.key?(key)
@@ -94,11 +119,17 @@ module DataMapper
       # Note that allowing blank without explicitly denying nil allows nil
       # values, since nil.blank? is true.
       #
-      # @param <Object> value to test
-      # @return <Boolean> true if blank/nil is allowed, and the value is blank/nil
+      # @param [Object] value
+      #   The value to test.
+      #
+      # @return [Boolean]
+      #   true if blank/nil is allowed, and the value is blank/nil.
+      #
+      # @api private
       def optional?(value)
         if value.nil?
-          @options[:allow_nil] || (@options[:allow_blank] && !@options.has_key?(:allow_nil))
+          @options[:allow_nil] ||
+            (@options[:allow_blank] && !@options.has_key?(:allow_nil))
         elsif DataMapper::Ext.blank?(value)
           @options[:allow_blank]
         end
@@ -124,7 +155,7 @@ module DataMapper
         self.field_name == other.field_name &&
         self.if_clause == other.if_clause &&
         self.unless_clause == other.unless_clause &&
-        self.instance_variable_get(:@options) == other.instance_variable_get(:@options)
+        self.options == other.options
       end
 
       def inspect
@@ -132,6 +163,22 @@ module DataMapper
       end
 
       alias_method :to_s, :inspect
+
+    private
+
+      # Get the corresponding Resource property, if it exists.
+      #
+      # Note: DataMapper validations can be used on non-DataMapper resources.
+      # In such cases, the return value will be nil.
+      #
+      # @api private
+      def get_resource_property(resource, property_name)
+        model = resource.model if resource.respond_to?(:model)
+        repository = resource.repository               if model
+        properties = model.properties(repository.name) if model
+        properties[property_name]                      if properties
+      end
+
     end # class GenericValidator
   end # module Validations
 end # module DataMapper

data/lib/dm-validations/validators/length_validator.rb

@@ -6,11 +6,10 @@ module DataMapper
       #
       # @param [Symbol] field_name
       #   the name of the field to validate
+      #
       # @param [Hash] options
       #   the validator options
       #
-      # @return [undefined]
-      #
       # @api semipublic
       def initialize(field_name, options)
         super
@@ -48,7 +47,6 @@ module DataMapper
         return true unless error_message = error_message_for(value)
 
         add_error(target, error_message, field_name)
-
         false
       end
 
@@ -114,7 +112,12 @@ module DataMapper
       # @api private
       def validate_equals(length)
         return if length == @equal
-        ValidationErrors.default_error_message(:wrong_length, humanized_field_name, @equal)
+
+        ValidationErrors.default_error_message(
+          :wrong_length,
+          humanized_field_name,
+          @equal
+        )
       end
 
       # Validate the value length is within expected range
@@ -128,7 +131,13 @@ module DataMapper
       # @api private
       def validate_range(length)
         return if @range.include?(length)
-        ValidationErrors.default_error_message(:length_between, humanized_field_name, @range.min, @range.max)
+
+        ValidationErrors.default_error_message(
+          :length_between,
+          humanized_field_name,
+          @range.min,
+          @range.max
+        )
       end
 
       # Validate the minimum expected value length
@@ -142,7 +151,12 @@ module DataMapper
       # @api private
       def validate_min(length)
         return if length >= @min
-        ValidationErrors.default_error_message(:too_short, humanized_field_name, @min)
+
+        ValidationErrors.default_error_message(
+          :too_short,
+          humanized_field_name,
+          @min
+        )
       end
 
       # Validate the maximum expected value length
@@ -156,7 +170,12 @@ module DataMapper
       # @api private
       def validate_max(length)
         return if length <= @max
-        ValidationErrors.default_error_message(:too_long, humanized_field_name, @max)
+
+        ValidationErrors.default_error_message(
+          :too_long,
+          humanized_field_name,
+          @max
+        )
       end
 
     end # class LengthValidator
@@ -168,22 +187,40 @@ module DataMapper
       # greater than or within a certain range (depending upon the options
       # you specify).
       #
-      # @option :allow_nil<Boolean> true/false (default is true)
-      # @option :allow_blank<Boolean> true/false (default is true)
-      # @option :minimum    ensures that the attribute's length is greater than
-      #   or equal to the supplied value
-      # @option :min        alias for :minimum
-      # @option :maximum    ensures the attribute's length is less than or equal
-      #   to the supplied value
-      # @option :max        alias for :maximum
-      # @option :equals     ensures the attribute's length is equal to the
-      #   supplied value
-      # @option :is         alias for :equals
-      # @option :in<Range>  given a Range, ensures that the attributes length is
-      #   include?'ed in the Range
-      # @option :within<Range>  alias for :in
-      #
-      # @example [Usage]
+      # @option [Boolean] :allow_nil (true)
+      #   true or false.
+      #
+      # @option [Boolean] :allow_blank (true)
+      #   true or false.
+      #
+      # @option [Boolean] :minimum
+      #   Ensures that the attribute's length is greater than or equal to
+      #   the supplied value.
+      #
+      # @option [Boolean] :min
+      #   Alias for :minimum.
+      #
+      # @option [Boolean] :maximum
+      #   Ensures the attribute's length is less than or equal to the
+      #   supplied value.
+      #
+      # @option [Boolean] :max
+      #   Alias for :maximum.
+      #
+      # @option [Boolean] :equals
+      #   Ensures the attribute's length is equal to the supplied value.
+      #
+      # @option [Boolean] :is
+      #   Alias for :equals.
+      #
+      # @option [Range] :in
+      #   Given a Range, ensures that the attributes length is include?'ed
+      #   in the Range.
+      #
+      # @option [Range] :within
+      #   Alias for :in.
+      #
+      # @example Usage
       #   require 'dm-validations'
       #
       #   class Page
@@ -203,12 +240,10 @@ module DataMapper
       #     # just_right is between 1 and 10 (inclusive of both 1 and 10)
       #
       def validates_length_of(*fields)
-        opts = opts_from_validator_args(fields)
-        add_validator_to_context(opts, fields, DataMapper::Validations::LengthValidator)
+        validators.add(LengthValidator, *fields)
       end
 
       deprecate :validates_length, :validates_length_of
-
     end # module ValidatesLength
   end # module Validations
 end # module DataMapper

data/lib/dm-validations/validators/method_validator.rb

@@ -1,8 +1,5 @@
 module DataMapper
   module Validations
-
-    ##
-    #
     # @author Guy van den Berg
     # @since  0.9
     class MethodValidator < GenericValidator
@@ -21,22 +18,22 @@ module DataMapper
       def ==(other)
         @options[:method] == other.instance_variable_get(:@options)[:method] && super
       end
+
     end # class MethodValidator
 
     module ValidatesWithMethod
-
-      ##
-      # Validate using method called on validated object. The method must to return
-      # either true, or a pair of [false, error message string], and is specified
-      # as a symbol passed with :method option.
+      # Validate using method called on validated object. The method must
+      # to return either true, or a pair of [false, error message string],
+      # and is specified as a symbol passed with :method option.
       #
-      # This validator does support multiple fields being specified at a time,
-      # but we encourage you to use it with one property/method at a time.
+      # This validator does support multiple fields being specified at a
+      # time, but we encourage you to use it with one property/method at a
+      # time.
       #
-      # Real world experience shows that method validation is often useful when
-      # attribute needs to be virtual and not a property name.
+      # Real world experience shows that method validation is often useful
+      # when attribute needs to be virtual and not a property name.
       #
-      # @example [Usage]
+      # @example Usage
       #   require 'dm-validations'
       #
       #  class Page
@@ -44,7 +41,8 @@ module DataMapper
       #
       #    property :zip_code, String
       #
-      #    validates_with_method :zip_code, :method => :in_the_right_location?
+      #    validates_with_method :zip_code,
+      #                          :method => :in_the_right_location?
       #
       #    def in_the_right_location?
       #      if @zip_code == "94301"
@@ -59,10 +57,8 @@ module DataMapper
       #    # wrong zip code" unless zip_code == "94301"
       #  end
       def validates_with_method(*fields)
-        opts = opts_from_validator_args(fields)
-        add_validator_to_context(opts, fields, DataMapper::Validations::MethodValidator)
+        validators.add(MethodValidator, *fields)
       end
-
     end # module ValidatesWithMethod
   end # module Validations
 end # module DataMapper

data/lib/dm-validations/validators/numeric_validator.rb

@@ -1,8 +1,5 @@
 module DataMapper
   module Validations
-
-    ##
-    #
     # @author Guy van den Berg
     # @since  0.9
     class NumericalityValidator < GenericValidator
@@ -37,7 +34,8 @@ module DataMapper
 
       def value_as_string(value)
         case value
-          when Float      then value.to_d.to_s('F')  # Avoid Scientific Notation in Float to_s
+          # Avoid Scientific Notation in Float to_s
+          when Float      then value.to_d.to_s('F')
           when BigDecimal then value.to_s('F')
           else value.to_s
         end
@@ -72,7 +70,11 @@ module DataMapper
         comparison = value.send(cmp, expected)
         return if negated ? !comparison : comparison
 
-        errors << ValidationErrors.default_error_message(error_message_name, field_name, expected)
+        errors << ValidationErrors.default_error_message(
+          error_message_name,
+          field_name,
+          expected
+        )
       end
 
       def validate_integer(value, errors)
@@ -124,59 +126,57 @@ module DataMapper
       def validate_ne(value, errors)
         validate_with_comparison(value, :==, options[:ne] || options[:not_equal_to], :not_equal_to, errors, true)
       end
+
     end # class NumericalityValidator
 
     module ValidatesNumericality
       extend Deprecate
 
-      # Validate whether a field is numeric
+      # Validate whether a field is numeric.
       #
-      # Options are:
+      # @option [Boolean] :allow_nil
+      #   true if number can be nil, false if not.
       #
-      # :allow_nil => true | false
-      #   true if number can be nil, false if not
+      # @option [Boolean] :allow_blank
+      #   true if number can be blank, false if not.
       #
-      # :allow_blank => true | false
-      #   true if number can be blank, false if not
-      #
-      # :message => "Error message for %s"
+      # @option [String] :message
       #   Custom error message, also can be a callable object that takes
-      #   an object (for pure Ruby objects) or object and property (for DM resources)
+      #   an object (for pure Ruby objects) or object and property
+      #   (for DM resources).
       #
-      # :precision => 2
-      #   Required precision of a value
+      # @option [Numeric] :precision
+      #   Required precision of a value.
       #
-      # :scale => 2
-      #   Required scale of a value
+      # @option [Numeric] :scale
+      #   Required scale of a value.
       #
-      # :gte => 5.75
-      #   'Greater than or greater' requirement
+      # @option [Numeric] :gte
+      #   'Greater than or equal to' requirement.
       #
-      # :lte => 5.75
-      #   'Less than or greater' requirement
+      # @option [Numeric] :lte
+      #   'Less than or equal to' requirement.
       #
-      # :lt => 5.75
-      #   'Less than' requirement
+      # @option [Numeric] :lt
+      #   'Less than' requirement.
       #
-      # :gt => 5.75
-      #   'Greater than' requirement
+      # @option [Numeric] :gt
+      #   'Greater than' requirement.
       #
-      # :eq => 5.75
-      #   'Equal' requirement
+      # @option [Numeric] :eq
+      #   'Equal' requirement.
       #
-      # :ne => 5.75
-      #   'Not equal' requirement
+      # @option [Numeric] :ne
+      #   'Not equal' requirement.
       #
-      # :integer_only => true
-      #   Use to restrict allowed values to integers
+      # @option [Boolean] :integer_only
+      #   Use to restrict allowed values to integers.
       #
       def validates_numericality_of(*fields)
-        opts = opts_from_validator_args(fields)
-        add_validator_to_context(opts, fields, DataMapper::Validations::NumericalityValidator)
+        validators.add(NumericalityValidator, *fields)
       end
 
       deprecate :validates_is_number, :validates_numericality_of
-
     end # module ValidatesIsNumber
   end # module Validations
 end # module DataMapper