ardm-validations 1.2.0

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

@@ -0,0 +1,184 @@
+# -*- 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 call method, returning true or false. The call method
+    #   provides the validation logic.
+    #
+    # @author Guy van den Berg
+    # @since  0.9
+    class GenericValidator
+
+      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.
+      #
+      # @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.
+      #
+      # @option [Symbol, Proc] :unless
+      #   The name of a method or a Proc to call to determine if the
+      #   validation should not occur.
+      #
+      # @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
+        @options              = DataMapper::Ext::Hash.except(options, :if, :unless)
+        @if_clause            = options[:if]
+        @unless_clause        = options[:unless]
+        @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.
+      #
+      # @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.
+      #
+      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.
+      #
+      # @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
+
+      # Determines if this validator should be run against the
+      # 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.
+      #
+      # @api private
+      def execute?(target)
+        if unless_clause = self.unless_clause
+          !evaluate_conditional_clause(target, unless_clause)
+        elsif if_clause = self.if_clause
+          evaluate_conditional_clause(target, if_clause)
+        else
+          true
+        end
+      end
+
+      # @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
+      end
+
+      # Set the default value for allow_nil and allow_blank
+      #
+      # @param [Boolean] default value
+      #
+      # @api private
+      def set_optional_by_default(default = true)
+        [ :allow_nil, :allow_blank ].each do |key|
+          @options[key] = true unless options.key?(key)
+        end
+      end
+
+      # Test the value to see if it is blank or nil, and if it is allowed.
+      # Note that allowing blank without explicitly denying nil allows nil
+      # values, since nil.blank? is true.
+      #
+      # @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))
+        elsif DataMapper::Ext.blank?(value)
+          @options[:allow_blank]
+        end
+      end
+
+      # Returns true if validators are equal
+      #
+      # Note that this intentionally do
+      # validate options equality
+      #
+      # even though it is hard to imagine a situation
+      # when multiple validations will be used
+      # on the same field with the same conditions
+      # but different options,
+      # it happens to be the case every once in a while
+      # with inferred validations for strings/text and
+      # explicitly given validations with different option
+      # (usually as Range vs. max limit for inferred validation)
+      #
+      # @api semipublic
+      def ==(other)
+        self.class == other.class &&
+        self.field_name == other.field_name &&
+        self.if_clause == other.if_clause &&
+        self.unless_clause == other.unless_clause &&
+        self.options == other.options
+      end
+
+      def inspect
+        "<##{self.class.name} @field_name='#{@field_name}' @if_clause=#{@if_clause.inspect} @unless_clause=#{@unless_clause.inspect} @options=#{@options.inspect}>"
+      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

@@ -0,0 +1,249 @@
+module DataMapper
+  module Validations
+    class LengthValidator < GenericValidator
+
+      # Initialize a length validator
+      #
+      # @param [Symbol] field_name
+      #   the name of the field to validate
+      #
+      # @param [Hash] options
+      #   the validator options
+      #
+      # @api semipublic
+      def initialize(field_name, options)
+        super
+
+        @equal = options[:is]      || options[:equals]
+        @range = options[:within]  || options[:in]
+        @min   = options[:minimum] || options[:min]
+        @max   = options[:maximum] || options[:max]
+
+        if @min && @max
+          @range ||= @min..@max
+        end
+      end
+
+      # Test the resource field for validity
+      #
+      # @example when the resource field is valid
+      #   validator.call(valid_resource)  # => true
+      #
+      # @example when the resource field is not valid
+      #   validator.call(invalid_resource)  # => false
+      #
+      #
+      # @param [Resource] target
+      #   the Resource to test
+      #
+      # @return [Boolean]
+      #   true if the field is valid, false if not
+      #
+      # @api semipublic
+      def call(target)
+        value = target.validation_property_value(field_name)
+        return true if optional?(value)
+
+        return true unless error_message = error_message_for(value)
+
+        add_error(target, error_message, field_name)
+        false
+      end
+
+      private
+
+      # Return the error messages for the value if it is invalid
+      #
+      # @param [#to_s] value
+      #   the value to test
+      #
+      # @return [String, nil]
+      #   the error message if invalid, nil if not
+      #
+      # @api private
+      def error_message_for(value)
+        if error_message = send(validation_method, value_length(value.to_s))
+          @options.fetch(:message, error_message)
+        end
+      end
+
+      # Return the method to validate the value with
+      #
+      # @return [Symbol]
+      #   the validation method
+      #
+      # @api private
+      def validation_method
+        @validation_method ||=
+          if    @equal then :validate_equals
+          elsif @range then :validate_range
+          elsif @min   then :validate_min
+          elsif @max   then :validate_max
+          end
+      end
+
+      # Return the length in characters
+      #
+      # @param [#to_str] value
+      #   the string to get the number of characters for
+      #
+      # @return [Integer]
+      #   the number of characters in the string
+      #
+      # @api private
+      def value_length(value)
+        value.to_str.length
+      end
+
+      if RUBY_VERSION < '1.9'
+        def value_length(value)
+          value.to_str.scan(/./u).size
+        end
+      end
+
+      # Validate the value length is equal to the expected length
+      #
+      # @param [Integer] length
+      #   the value length
+      #
+      # @return [String, nil]
+      #   the error message if invalid, nil if not
+      #
+      # @api private
+      def validate_equals(length)
+        return if length == @equal
+
+        ValidationErrors.default_error_message(
+          :wrong_length,
+          humanized_field_name,
+          @equal
+        )
+      end
+
+      # Validate the value length is within expected range
+      #
+      # @param [Integer] length
+      #   the value length
+      #
+      # @return [String, nil]
+      #   the error message if invalid, nil if not
+      #
+      # @api private
+      def validate_range(length)
+        return if @range.include?(length)
+
+        ValidationErrors.default_error_message(
+          :length_between,
+          humanized_field_name,
+          @range.min,
+          @range.max
+        )
+      end
+
+      # Validate the minimum expected value length
+      #
+      # @param [Integer] length
+      #   the value length
+      #
+      # @return [String, nil]
+      #   the error message if invalid, nil if not
+      #
+      # @api private
+      def validate_min(length)
+        return if length >= @min
+
+        ValidationErrors.default_error_message(
+          :too_short,
+          humanized_field_name,
+          @min
+        )
+      end
+
+      # Validate the maximum expected value length
+      #
+      # @param [Integer] length
+      #   the value length
+      #
+      # @return [String, nil]
+      #   the error message if invalid, nil if not
+      #
+      # @api private
+      def validate_max(length)
+        return if length <= @max
+
+        ValidationErrors.default_error_message(
+          :too_long,
+          humanized_field_name,
+          @max
+        )
+      end
+
+    end # class LengthValidator
+
+    module ValidatesLength
+      extend Deprecate
+
+      # Validates that the length of the attribute is equal to, less than,
+      # greater than or within a certain range (depending upon the options
+      # you specify).
+      #
+      # @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
+      #     include DataMapper::Resource
+      #
+      #     property high, Integer
+      #     property low, Integer
+      #     property just_right, Integer
+      #
+      #     validates_length_of :high, :min => 100000000000
+      #     validates_length_of :low, :equals => 0
+      #     validates_length_of :just_right, :within => 1..10
+      #
+      #     # a call to valid? will return false unless:
+      #     # high is greater than or equal to 100000000000
+      #     # low is equal to 0
+      #     # just_right is between 1 and 10 (inclusive of both 1 and 10)
+      #
+      def validates_length_of(*fields)
+        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

@@ -0,0 +1,64 @@
+module DataMapper
+  module Validations
+    # @author Guy van den Berg
+    # @since  0.9
+    class MethodValidator < GenericValidator
+
+      def initialize(field_name, options={})
+        super
+        @options[:method] = @field_name unless @options.key?(:method)
+      end
+
+      def call(target)
+        result, message = target.__send__(@options[:method])
+        add_error(target, message, field_name) unless result
+        result
+      end
+
+      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.
+      #
+      # 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.
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #  class Page
+      #    include DataMapper::Resource
+      #
+      #    property :zip_code, String
+      #
+      #    validates_with_method :zip_code,
+      #                          :method => :in_the_right_location?
+      #
+      #    def in_the_right_location?
+      #      if @zip_code == "94301"
+      #        return true
+      #      else
+      #        return [false, "You're in the wrong zip code"]
+      #      end
+      #    end
+      #
+      #    # A call to valid? will return false and
+      #    # populate the object's errors with "You're in the
+      #    # wrong zip code" unless zip_code == "94301"
+      #  end
+      def validates_with_method(*fields)
+        validators.add(MethodValidator, *fields)
+      end
+    end # module ValidatesWithMethod
+  end # module Validations
+end # module DataMapper