module AWS::Record::Validations
Validation methods to be used with subclasses of AWS::Record::Model.
# General Usage
All standard validation methods follow the same basic usage. Call the validation method followed by one more attribute names and then an optional hash of modifiers.
class Book < AWS::Record::Model # ... validates_presence_of :title, :author validates_length_of :summary, :max => 500, :allow_nil => true, :allow_blank => true end
# Conditional Validations
Sometimes you only want to validate an attribute under certain conditions. To make this simple, all validation methods accept the following 3 options:
-
`:on`
-
`:if`
-
`:unless`
You may mix and match all 3 of the above options.
### Validate on :create or :update
By default validations are run on create and update, but you can specify them to run for only create (initial save) or updates.
validates_presence_of :created_at, :on => :create validates_presence_of :updated_at, :on => :update
### Validate :if or :unless
Sometimes you have more complex requirements to determine if/when a validation should run. `:if` and `:unless`: both accept either a method name or proc.
class Person # ... validates_presence_of :job_title, :if => :employee? validates_presence_of :nickname, :if => lambda {|person| person.is_family? or person.is_friend? } end
# Validating Virtual (Non-persisted) Attributes
All of the validators can be used with configured attributes, but they can also be used with any attribute that has a setter and a getter.
Class Book < AWS::Record::Model attr_accessor :title validates_presence_of :title end
Public Class Methods
# File lib/aws/record/validations.rb, line 88 def self.extended base base.send(:define_method, :run_validations) do errors.clear! self.class.send(:validators).each do |validator| validator.validate(self) end end base.send(:private, :run_validations) end
Public Instance Methods
Registers a validation method.
validate :ensure_age_is_greater_than_shoe_size def ensure_age_is_greater_than_shoe_size unless age > shoe_size errors.add(:age, 'should be greater than your shoe size') end end
You can also pass a list of method names that should be called during validation.
validate :some_complex_validation, :some_other_validation
As with most other validation methods you can also pass a hash of options that affect when the named validation methods get called.
validate :my_custom_validation, :unless => :new_record?
@overload validate(*method_names, options = {})
@param [Array<Symbol>] method_names A list of methods to call during validation. @param [Hash] options @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 138 def validate *args validators << MethodValidator.new(self, *args) end
This validation method is primariliy intended for ensuring a form checkbox (like an EULA agreement or terms of service acknowledgement) is checked.
class User < AWS::Record::Model boolean_attr :terms_of_service validates_acceptance_of :terms_of_service end
### Virtual Attributes
If you choose to validate the acceptance of a non-existant attribute then a setter and a getter will be added automtically for you.
class User < AWS::Record::Model validates_acceptance_of :terms_of_service end user = User.new user.respond_to?(:terms_of_service) #=> true user.respond_to?(:terms_of_service=) #=> true
### Accepted Values
The default behavior for `validates_acceptance_of` is to add an error when the value is '1' or `true`. Also note, this validation method defaults `:allow_nil` to true.
-
`nil` implies the field was omitted from the form and therefore should not be validated
class User < AWS::Record::Model validates_acceptance_of :terms_of_service end u = User.new u.terms_of_service #=> nil u.valid? #=> true
-
'1' is the default value for most checkbox form helpers, and # therefore indicates an accepted value.
-
`true` is how boolean attributes typecast '1'. This is helpful when you have your checkbox post its value to a `:boolean_attr`.
### Multi-Valued Attributes
This validator works only with single-valued attributes. If you need to validate that all of the values in a set are true, then use {#validates_inclusion_of}.
@note Most validators default :allow_nil to false, this one defaults to true @note This validator should not be used with multi-valued attributes
@overload #validates_acceptance_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [mixed] :accpet Specify an additional accepted value. validates_acceptance_of :agree, :accept => 'yes' @option options [String] :message A custom error message. The default `:message` is "must be accepted". @option options [Boolean] :allow_nil (true) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (true) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 222 def validates_acceptance_of *args validators << AcceptanceValidator.new(self, *args) end
Intended primarily for validating a form field was entered correctly by requiring it twice:
Model: class User < AWS::Record::Model validates_confirmation_of :password, :if => :password_changed? end View: <%= password_field "user", "password" %> <%= password_field "user", "password_confirmation" %>
### Confirmation Value Accessors
If your model does not have accessors for the confirmation value then they will be automatically added. In the example above the user class would have an `attr_accessor` for `:password_confirmation`.
### Conditional Validation
Mostly commonly you only need to validate confirmation of an attribute when it has changed. It is therefore suggested to pass an `:if` condition reflecting this:
validates_confirmation_of :password, :if => :password_changed?
### Multi-Valued Attributes
This validator works only with single-valued attributes. It should not be used on attributes that have array or set values.
@note This validation method does not accept the `:allow_nil` or the `:allow_blank` options.
@overload #validates_confirmation_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [String] :message A custom error message. The default `:message` is "doesn't match confirmation". @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 279 def validates_confirmation_of *args validators << ConfirmationValidator.new(self, *args) end
Validates the number of values for a given attribute.
### Length vs Count
`validates_count_of` validates the number of attribute values, whereas +validates_length_of: validates the length of each attribute value instead.
If you need to ensure each attribute value is a given length see {#validates_length_of} instead.
### Examples
You can validate there are a certain number of values:
validates_count_of :parents, :exactly => 2
You can also specify a range:
validates_count_of :tags, :within => (2..10)
You can also specify min and max value seperately:
validates_count_of :tags, :minimum => 2, :maximum => 10
### `nil` Values
If you are validating an array or set that contains `nil` values, the `nil` values are counted normally as 1 each.
If you are validating a non-enuemrable attribute that only contains a single nil or other scalar value, then nil is counted as 0.
### Singular Attributes
This validator is intended to for validating attributes that have an array or set of values. If used on an attribute that returns a scalar value (like `nil` or a string), the count will always be 0 (for `nil`) or 1 (for everything else).
It is therefore recomended to use `:validates_presence_of` in place of `:validates_count_of` when working with single-valued attributes.
@overload #validates_count_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [Integer] :exactly The exact number of values the attribute should have. If this validation option fails the error message specified by `:wrong_number` will be added. @option options [Range] :within An range of number of values to accept. If the attribute has a number of values outside this range then the `:too_many` or `:too_few` error message will be added. @option options [Integer] :minimum The minimum number of values the attribute should have. If it has fewer, the `:too_few` error message will be added. @option options [Integer] :maximum The maximum number of values the attribute should have. If it has more, the `:too_many` error message will be added. @option options [String] :too_many An error message added when the attribute has too many values. Defaults to <code>"has too many values (maximum is %{maximum})"</code> @option options [String] :too_few An error message added when the attribute has too few values. Defaults to <code>"has too few values (minimum is %{minimum})"</code> @option options [String] :wrong_number An error message added when the number of attribute values does not match the `:exactly` option. Defaults to <code>"has the wrong number of values (should have exactly %{exactly}"</code> @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 365 def validates_count_of *args validators << CountValidator.new(self, *args) end
Adds a block validator that is called during record validation.
class ExampleClass < AWS::Record::Model string_attr :name validates_each(:name) do |record, attribute_name, value| if value == 'John Doe' record.errors.add(attr_name, 'may not be an alias') end end end
@overload #validates_each(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 402 def validates_each *attributes, &block unless block_given? raise ArgumentError, 'missing required block for validates_each' end validators << BlockValidator.new(self, *attributes, &block) end
Validates that the attribute value is not included in the given enumerable.
validates_exlusion_of :username, :in => %w(admin administrator)
### Multi-Valued Attributes
You may use this with multi-valued attributes the same way you use it with single-valued attributes:
class Product < AWS::Record::Model string_attr :tags, :set => true validates_exlusion_of :tags, :in => four_letter_words end
@overload #validates_exclusion_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [required, Enumerable] :in An enumerable object to ensure the value is not in. @option options [String] :message A custom error message. The default `:message` is "is reserved". @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 447 def validates_exclusion_of *args validators << ExclusionValidator.new(self, *args) end
Validates the attribute's value matches the given regular exression.
validates_format_of :year, :with => /^\d{4}$/
You can also perform a not-match using `:without` instead of `:with`.
validates_format_of :username, :without => /\d/
### Multi-Valued Attributes
You may use this with multi-valued attributes the same way you use it with single-valued attributes:
class Product < AWS::Record::Model string_attr :tags, :set => true validates_format_of :tags, :with => /^\w{2,10}$/ end
@overload #validates_format_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [Regexp] :with If the value matches the given regex, an error will not be added. @option options [Regexp] :without If the value matches the given regex, an error will be added. must match, or an error is added. @option options [String] :message A custom error message. The default `:message` is "is reserved". @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 495 def validates_format_of *args validators << FormatValidator.new(self, *args) end
Validates that the attribute value is included in the given enumerable object.
class MultipleChoiceAnswer < AWS::Record::Model validates_inclusion_of :letter, :in => %w(a b c d e) end
### Multi-Valued Attributes
You may use this with multi-valued attributes the same way you use it with single-valued attributes.
@overload #validates_inclusion_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [required, Enumerable] :in An enumerable object to check for the value in. @option options [String] :message A custom error message. The default `:message` is "is not included in the list". @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 534 def validates_inclusion_of *attributes validators << InclusionValidator.new(self, *attributes) end
Validates the attribute values are of a specified length.
validates_lenth_of :username, :within => 3..25
### Length vs Count
`validates_length_of` validates the length of individual attribute values, whereas +validates_count_of: validates the number of attribute values.
If you need to ensure there are certain number of values see {#validates_count_of} instead.
@overload #validates_length_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [Enumerable] :within An enumerable object to ensure the length of the value falls within. @option options [Integer] :exactly The exact length a value must be. If this validation fails the error message specified by `:wrong_length` will be added. @option options [Range] :within An enumerable object which must include the length of the attribute, or an error will be added. If the attribute has a length outside the range then the `:too_long` or `:too_short` error message will be added. @option options [Integer] :minimum The minimum length an attribute value should be. If it is shorter, the `:too_short` error message will be added. @option options [Integer] :maximum The maximum length an attribute value should be. If it is longer, the `:too_long` error message will be added. @option options [String] :too_long An error message added when the attribute value is too long. Defaults to <code>"is too long (maximum is %{maximum} characters)"</code> @option options [String] :too_short An error message added when the attribute value is too short. Defaults to <code>"is too short (minimum is %{minimum} characters)"</code> @option options [String] :wrong_length An error message added when the attribute has the incorrect length (as specified by `:exactly`). Defaults to <code>"is the wrong length (should be %{exactly} characters"</code> @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 597 def validates_length_of *args validators << LengthValidator.new(self, *args) end
Validates the attribute has a numeric value.
validates_numericality_of :age, :only_integer => true
### Multi-Valued Attributes
You can validate multi-valued attributes using this the same way you validate single-valued attributes. Each value will be validated individually.
@overload #validates_numericality_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [Boolean] :only_integer (false) Adds an error when valiating and the value is numeric, but it not a whole number. @option options [Integer] :equal_to When set the value must equal the given value exactly. May not be used with the greater/less options. @option options [Numeric] :greater_than Ensures the attribute is greater than the given number. @option options [Integer] :greater_than_or_equal_to Ensures the attribute is greater than or equal to the given number. @option options [Numeric] :less_than Ensures the attribute is less than the given value. @option options [Integer] :less_than_or_equal_to Ensures the value is less than or equal to the given number. @option options [Numeric] :even If true, the value may only be an even integer. This forces the `:only_integer` to `true`. @option options [Numeric] :odd If true, the value may only be an odd integer. This forces the `:only_integer` to `true`. @option options [String] :message A custom error message. The default `:message` is "is not a number". @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 649 def validates_numericality_of *args validators << NumericalityValidator.new(self, *args) end
Validates the named attributes are not blank. For validation purposes, blank values include:
-
`nil`
-
empty string
-
anything that responds to empty? with true
-
anything that responds to blank? with true
@overload #validates_presence_of(*attributes, options = {}, &block)
@param attributes A list of attribute names to validate. @param [Hash] options @option options [String] :message A custom error message. The default `:message` is "may not be blank". @option options [Symbol] :on (:save) When this validation is run. Valid values include: * `:save` * `:create` * `:update` @option options [Boolean] :allow_nil (false) Skip validation if the attribute value is `nil`. @option options [Boolean] :allow_blank (false) Skip validation if the attribute value is `blank`. @option options [Symbol,String,Proc] :if Specifies a method or proc to call. The validation will only be run if the return value is of the method/proc is true (e.g. `:if => :name_changed?` or `:if => lambda{|book| book.in_stock? }`). @option options [Symbol,String,Proc] :unless Specifies a method or proc to call. The validation will *not* be run if the return value is of the method/proc is false.
# File lib/aws/record/validations.rb, line 682 def validates_presence_of *args validators << PresenceValidator.new(self, *args) end
Private Instance Methods
@api private
# File lib/aws/record/validations.rb, line 688 def validators @validators ||= [] end