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:

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

extended(base) click to toggle source
# 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

validate(*args) click to toggle source

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
validates_acceptance_of(*args) click to toggle source

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
validates_confirmation_of(*args) click to toggle source

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_count_of(*args) click to toggle source

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
validates_each(*attributes, &block) click to toggle source

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_exclusion_of(*args) click to toggle source

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_format_of(*args) click to toggle source

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_inclusion_of(*attributes) click to toggle source

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_length_of(*args) click to toggle source

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_numericality_of(*args) click to toggle source

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_presence_of(*args) click to toggle source

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

validators() click to toggle source

@api private

# File lib/aws/record/validations.rb, line 688
def validators
  @validators ||= []
end