sbf-dm-validations 1.3.0.beta

data/lib/data_mapper/validation/inferred.rb

@@ -0,0 +1,264 @@
+module DataMapper
+  # for options_with_message
+  # TODO: rename :auto_validation => :infer_validation
+  Property.accept_options :auto_validation, :validates, :set, :format, :message, :messages
+
+  module Validation
+    module Inferred
+
+      # @api private
+      def property(*)
+        property = super
+
+        if property.options.fetch(:auto_validation, true) && !disabled_auto_validations?
+          rule_definitions = Validation::Inferred.rules_for_property(property)
+          rule_definitions.each do |rule_class, attribute_name, options|
+            validation_rules.add(rule_class, [attribute_name], options)
+          end
+        end
+
+        # FIXME: explicit return needed for YARD to parse this properly
+        return property
+      end
+
+      # attr_accessor :infer_validations
+
+      # TODO: replace the @disabled_auto_validations reader methods with
+      #   a positive statement instead of negative (instead of skip/disable, etc)
+      #   eg., @infer_validations, #infer_validations?
+      #
+      # Checks whether auto validations are currently
+      # disabled (see +disable_auto_validations+ method
+      # that takes a block)
+      #
+      # @return [TrueClass, FalseClass]
+      #   true if auto validation is currently disabled
+      #
+      # @api public
+      # def infer_validations?
+      #   defined?(@infer_validations) ? @infer_validations : true
+      # end
+
+      # TODO: why are there 3 entry points to this ivar?
+      # #disable_auto_validations, #disabled_auto_validations?, #auto_validations_disabled?
+      attr_reader :disable_auto_validations
+
+      # Checks whether auto validations are currently
+      # disabled (see +disable_auto_validations+ method
+      # that takes a block)
+      #
+      # @return [TrueClass, FalseClass]
+      #   true if auto validation is currently disabled
+      #
+      # @api semipublic
+      def disabled_auto_validations?
+        @disable_auto_validations || false
+      end
+
+      # TODO: deprecate all but one of these 3 variants
+      alias_method :auto_validations_disabled?, :disabled_auto_validations?
+
+      # Disable generation of validations for the duration of the given block
+      #
+      # @api public
+      def without_auto_validations
+        previous, @disable_auto_validations = @disable_auto_validations, true
+        yield
+      ensure
+        @disable_auto_validations = previous
+        self
+      end
+
+      # Infer validations for a given property. This will only occur
+      # if the option :auto_validation is either true or left undefined.
+      #
+      #   Triggers that generate validator creation
+      #
+      #   :required => true
+      #       Setting the option :required to true causes a Rule::Presence
+      #       to be created for the property
+      #
+      #   :length => 20
+      #       Setting the option :length causes a Rule::Length to be created
+      #       for the property.
+      #       If the value is a Integer the Rule will have :maximum => value.
+      #       If the value is a Range the Rule will have :within => value.
+      #
+      #   :format => :predefined / lambda / Proc
+      #       Setting the :format option causes a Rule::Format to be created
+      #       for the property
+      #
+      #   :set => ["foo", "bar", "baz"]
+      #       Setting the :set option causes a Rule::Within to be created
+      #       for the property
+      #
+      #   Integer type
+      #       Using a Integer type causes a Rule::Numericalness to be created
+      #       for the property.  The Rule's :integer_only option is set to true
+      #
+      #   BigDecimal or Float type
+      #       Using a Integer type causes a Rule::Numericalness to be created
+      #       for the property.  The Rule's :integer_only option will be set
+      #       to false, and precision/scale will be set to match the Property
+      #
+      #
+      #   Messages
+      #
+      #   :messages => {..}
+      #       Setting :messages hash replaces standard error messages
+      #       with custom ones. For instance:
+      #       :messages => {:presence => "Field is required",
+      #                     :format => "Field has invalid format"}
+      #       Hash keys are: :presence, :format, :length, :is_unique,
+      #                      :is_number, :is_primitive
+      #
+      #   :message => "Some message"
+      #       It is just shortcut if only one validation option is set
+      #
+      # @api private
+      def self.rules_for_property(property)
+        rule_definitions = []
+
+        # all inferred rules should not be skipped when the value is nil
+        #   (aside from Rule::Presence/Rule::Absence)
+        opts = { :allow_nil => true }
+
+        if property.options.key?(:validates)
+          opts[:context] = property.options[:validates]
+        end
+
+        rule_definitions << infer_presence(  property, opts.dup)
+        rule_definitions << infer_length(    property, opts.dup)
+        rule_definitions << infer_format(    property, opts.dup)
+        rule_definitions << infer_uniqueness(property, opts.dup)
+        rule_definitions << infer_within(    property, opts.dup)
+        rule_definitions << infer_type(      property, opts.dup)
+
+        rule_definitions.compact
+      end
+
+    private
+
+      # @api private
+      def self.infer_presence(property, options)
+        return if property.allow_blank? || property.serial?
+
+        validation_options = options_with_message(options, property, :presence)
+
+        [Rule::Presence, property.name, validation_options]
+      end
+
+      # @api private
+      def self.infer_length(property, options)
+        # TODO: return unless property.primitive <= String (?)
+        return unless (property.kind_of?(Property::String) ||
+                       property.kind_of?(Property::Text))
+        length = property.options.fetch(:length, Property::String.length)
+
+
+        if length.is_a?(Range)
+          if length.last == Infinity
+            raise ArgumentError, "Infinity is not a valid upper bound for a length range"
+          end
+          options[:within]  = length
+        else
+          options[:maximum] = length
+        end
+
+        validation_options = options_with_message(options, property, :length)
+
+        [Rule::Length, property.name, validation_options]
+      end
+
+      # @api private
+      def self.infer_format(property, options)
+        return unless property.options.key?(:format)
+
+        options[:with] = property.options[:format]
+
+        validation_options = options_with_message(options, property, :format)
+
+        [Rule::Format, property.name, validation_options]
+      end
+
+      # @api private
+      def self.infer_uniqueness(property, options)
+        return unless property.options.key?(:unique)
+
+        case value = property.options[:unique]
+          when Array, Symbol
+            # TODO: fix this to behave like :unique_index
+            options[:scope] = Array(value)
+
+            validation_options = options_with_message(options, property, :is_unique)
+            [Rule::Uniqueness, property.name, validation_options]
+          when TrueClass
+            validation_options = options_with_message(options, property, :is_unique)
+            [Rule::Uniqueness, property.name, validation_options]
+        end
+      end
+
+      # @api private
+      def self.infer_within(property, options)
+        return unless property.options.key?(:set)
+
+        options[:set] = property.options[:set]
+
+        validation_options = options_with_message(options, property, :within)
+        [Rule::Within, property.name, validation_options]
+      end
+
+      # @api private
+      def self.infer_type(property, options)
+        return if property.respond_to?(:custom?) && property.custom?
+
+        if property.kind_of?(Property::Numeric)
+          options[:gte] = property.min if property.min
+          options[:lte] = property.max if property.max
+        end
+
+        if Integer == property.load_as
+          options[:integer_only] = true
+
+          validation_options = options_with_message(options, property, :is_number)
+          [Rule::Numericalness, property.name, validation_options]
+        elsif (BigDecimal == property.load_as ||
+               Float == property.load_as)
+          options[:precision] = property.precision
+          options[:scale]     = property.scale
+
+          validation_options = options_with_message(options, property, :is_number)
+          [Rule::Numericalness, property.name, validation_options]
+        else
+          # We only need this in the case we don't already
+          # have a numeric validator, because otherwise
+          # it will cause duplicate validation errors
+          validation_options = options_with_message(options, property, :is_primitive)
+          [Rule::PrimitiveType, property.name, validation_options]
+        end
+      end
+
+      # TODO: eliminate this;
+      #   mutating one arg based on a non-obvious interaction of the other two...
+      #   well, it makes my skin crawl.
+      #
+      # @api private
+      def self.options_with_message(base_options, property, validator_name)
+        options = base_options.clone
+        opts    = property.options
+
+        if opts.key?(:messages)
+          options[:message] = opts[:messages][validator_name]
+        elsif opts.key?(:message)
+          options[:message] = opts[:message]
+        end
+
+        options
+      end
+
+    end # module Inferred
+  end # module Validation
+
+  Model.append_extensions Validation::Inferred
+
+end # module DataMapper

data/lib/data_mapper/validation/macros.rb

@@ -0,0 +1,449 @@
+# -*- encoding: utf-8 -*-
+
+require 'data_mapper/validation/rule'
+
+require 'data_mapper/validation/rule/absence'
+require 'data_mapper/validation/rule/acceptance'
+require 'data_mapper/validation/rule/block'
+require 'data_mapper/validation/rule/confirmation'
+require 'data_mapper/validation/rule/format'
+require 'data_mapper/validation/rule/length'
+require 'data_mapper/validation/rule/method'
+require 'data_mapper/validation/rule/numericalness'
+require 'data_mapper/validation/rule/presence'
+require 'data_mapper/validation/rule/primitive_type'
+require 'data_mapper/validation/rule/uniqueness'
+require 'data_mapper/validation/rule/within'
+
+module DataMapper
+  module Validation
+    module Macros
+      def self.extract_options(arguments)
+        arguments.last.kind_of?(Hash) ? arguments.pop : {}
+      end
+
+      # Validates that the specified attribute is "blank" via the
+      # attribute's #blank? method.
+      #
+      # @note
+      #   dm-core's support lib adds the #blank? method to many classes,
+      # @see lib/dm-core/support/blank.rb (dm-core) for more information.
+      #
+      # @example [Usage]
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :unwanted_attribute, String
+      #     property :another_unwanted, String
+      #     property :yet_again, String
+      #
+      #     validates_absence_of :unwanted_attribute
+      #     validates_absence_of :another_unwanted, :yet_again
+      #
+      #     # a call to #validate will return false unless
+      #     # all three attributes are blank
+      #   end
+      #
+      def validates_absence_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Absence, attribute_names, options)
+      end
+
+      # Validates that the attributes's value is in the set of accepted
+      # values.
+      #
+      # @option [Boolean] :allow_nil (true)
+      #   true if nil is allowed, false if not allowed.
+      #
+      # @option [Array] :accept (["1", 1, "true", true, "t"])
+      #   A list of accepted values.
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :license_agreement_accepted, String
+      #     property :terms_accepted, String
+      #     validates_acceptance_of :license_agreement, :accept => "1"
+      #     validates_acceptance_of :terms_accepted, :allow_nil => false
+      #
+      #     # a call to valid? will return false unless:
+      #     # license_agreement is nil or "1"
+      #     # and
+      #     # terms_accepted is one of ["1", 1, "true", true, "t"]
+      #
+      def validates_acceptance_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Acceptance, attribute_names, options)
+      end
+
+      # Validate using the given block. The block given needs to return:
+      # [result::<Boolean>, Error Message::<String>]
+      #
+      # @example [Usage]
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :zip_code, String
+      #
+      #     validates_with_block do
+      #       if @zip_code == "94301"
+      #         true
+      #       else
+      #         [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"
+      #
+      #     # You can also specify field:
+      #
+      #     validates_with_block :zip_code do
+      #       if @zip_code == "94301"
+      #         true
+      #       else
+      #         [false, "You're in the wrong zip code"]
+      #       end
+      #     end
+      #
+      #     # it will add returned error message to :zip_code field
+      #
+      def validates_with_block(*attribute_names, &block)
+        unless block_given?
+          raise ArgumentError, 'You need to pass a block to validates_with_block'
+        end
+
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Block, attribute_names, options, &block)
+      end
+
+      # Validates that the given attribute is confirmed by another
+      # attribute. A common use case scenario is when you require a user to
+      # confirm their password, for which you use both password and
+      # password_confirmation attributes.
+      #
+      # @option [Boolean] :allow_nil (true)
+      #   true or false.
+      #
+      # @option [Boolean] :allow_blank (true)
+      #   true or false.
+      #
+      # @option [Symbol] :confirm (firstattr_confirmation)
+      #   The attribute that you want to validate against.
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :password, String
+      #     property :email, String
+      #     attr_accessor :password_confirmation
+      #     attr_accessor :email_repeated
+      #
+      #     validates_confirmation_of :password
+      #     validates_confirmation_of :email, :confirm => :email_repeated
+      #
+      #     # a call to valid? will return false unless:
+      #     # password == password_confirmation
+      #     # and
+      #     # email == email_repeated
+      #
+      def validates_confirmation_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Confirmation, attribute_names, options)
+      end
+
+      # Validates that the attribute is in the specified format. You may
+      # use the :as (or :with, it's an alias) option to specify the
+      # pre-defined format that you want to validate against. You may also
+      # specify your own format via a Proc or Regexp passed to the the :as
+      # or :with options.
+      #
+      # @option [Boolean] :allow_nil (true)
+      #   true or false.
+      #
+      # @option [Boolean] :allow_blank (true)
+      #   true or false.
+      #
+      # @option [Format, Proc, Regexp] :as
+      #   The pre-defined format, Proc or Regexp to validate against.
+      #
+      # @option [Format, Proc, Regexp] :with
+      #   An alias for :as.
+      #
+      #   :email_address (format is specified in DataMapper::Validation::Format::Email - note that unicode emails will *not* be matched under MRI1.8.7)
+      #   :url (format is specified in DataMapper::Validation::Format::Url)
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :email, String
+      #     property :zip_code, String
+      #
+      #     validates_format_of :email, :as => :email_address
+      #     validates_format_of :zip_code, :with => /^\d{5}$/
+      #
+      #     # a call to valid? will return false unless:
+      #     # email is formatted like an email address
+      #     # and
+      #     # zip_code is a string of 5 digits
+      #
+      def validates_format_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Format, attribute_names, options)
+      end
+
+      # 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(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Length, attribute_names, options)
+      end
+
+      # 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 attribute_names 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(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Method, attribute_names, options)
+      end
+
+      # Validate whether a field is numeric.
+      #
+      # @option [Boolean] :allow_nil
+      #   true if number can be nil, false if not.
+      #
+      # @option [Boolean] :allow_blank
+      #   true if number can be blank, false if not.
+      #
+      # @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).
+      #
+      # @option [Numeric] :precision
+      #   Required precision of a value.
+      #
+      # @option [Numeric] :scale
+      #   Required scale of a value.
+      #
+      # @option [Numeric] :gte
+      #   'Greater than or equal to' requirement.
+      #
+      # @option [Numeric] :lte
+      #   'Less than or equal to' requirement.
+      #
+      # @option [Numeric] :lt
+      #   'Less than' requirement.
+      #
+      # @option [Numeric] :gt
+      #   'Greater than' requirement.
+      #
+      # @option [Numeric] :eq
+      #   'Equal' requirement.
+      #
+      # @option [Numeric] :ne
+      #   'Not equal' requirement.
+      #
+      # @option [Boolean] :integer_only
+      #   Use to restrict allowed values to integers.
+      #
+      def validates_numericalness_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Numericalness, attribute_names, options)
+      end
+
+      # Validates that the specified attribute is present.
+      #
+      # For most property types "being present" is the same as being "not
+      # blank" as determined by the attribute's #blank? method. However, in
+      # the case of Boolean, "being present" means not nil; i.e. true or
+      # false.
+      #
+      # @note
+      #   dm-core's support lib adds the blank? method to many classes,
+      #
+      # @see lib/dm-core/support/blank.rb (dm-core) for more information.
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Page
+      #     include DataMapper::Resource
+      #
+      #     property :required_attribute, String
+      #     property :another_required, String
+      #     property :yet_again, String
+      #
+      #     validates_presence_of :required_attribute
+      #     validates_presence_of :another_required, :yet_again
+      #
+      #     # a call to valid? will return false unless
+      #     # all three attributes are !blank?
+      #   end
+      def validates_presence_of(*attribute_names)
+        options = attribute_names.last.kind_of?(Hash) ? attribute_names.pop : {}
+        validation_rules.add(Rule::Presence, attribute_names, options)
+      end
+
+      # Validates that the specified attribute is of the correct primitive
+      # type.
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Person
+      #     include DataMapper::Resource
+      #
+      #     property :birth_date, Date
+      #
+      #     validates_primitive_type_of :birth_date
+      #
+      #     # a call to valid? will return false unless
+      #     # the birth_date is something that can be properly
+      #     # casted into a Date object.
+      #   end
+      def validates_primitive_type_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::PrimitiveType, attribute_names, options)
+      end
+
+      # Validate the uniqueness of a field
+      #
+      # TODO: YARDoc for this method
+      def validates_uniqueness_of(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Uniqueness, attribute_names, options)
+      end
+
+      # Validates that the value of a field is within a range/set.
+      #
+      # This validation is defined by passing a field along with a :set
+      # parameter. The :set can be a Range or any object which responds
+      # to the #include? method (an array, for example).
+      #
+      # @example Usage
+      #   require 'dm-validations'
+      #
+      #   class Review
+      #     include DataMapper::Resource
+      #
+      #     STATES = ['new', 'in_progress', 'published', 'archived']
+      #
+      #     property :title, String
+      #     property :body, String
+      #     property :review_state, String
+      #     property :rating, Integer
+      #
+      #     validates_within :review_state, :set => STATES
+      #     validates_within :rating,       :set => 1..5
+      #
+      #     # a call to valid? will return false unless
+      #     # the two properties conform to their sets
+      #   end
+      def validates_within(*attribute_names)
+        options = Macros.extract_options(attribute_names)
+        validation_rules.add(Rule::Within, attribute_names, options)
+      end
+
+    end # module Macros
+  end # module Validation
+end # module DataMapper