Module AWS::Record::Validations
In: lib/aws/record/validations.rb

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

Methods

Public Class methods

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

[Validate]