Module: AWS::Record::Validations

Included in:
Base
Defined in:
lib/aws/record/validations.rb

Overview

Validation methods to be used with subclasses of AWS::Record::Base.

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::Base

  # ...

  validates_presence_of :title, :author

  validates_length_of :summary, 
    :max => 500,
    :allow_nil => 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::Base

  attr_accessor :title

  validates_presence_of :title

end

Instance Method Summary collapse

Instance Method Details

#validates_acceptance_of(*attributes, options = {}, &block) ⇒ Object

Note:

Most validators default :allow_nil to false, this one defualts to true

Note:

This validator should not be used with multi-valued attributes

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::Base
  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::Base
  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::Base
  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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :accpet (mixed) —

    Specify an additional accepted value.

    validates_acceptance_of :agree, :accept => ‘yes’

  • :message (String) —

    A custom error message. The defualt :message is “must be accepted”.

  • :allow_nil (Boolean) — default: true —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



191
192
193
 
# File 'lib/aws/record/validations.rb', line 191

def validates_acceptance_of *args
  validators << AcceptanceValidator.new(self, *args)
end

#validates_confirmation_of(*attributes, options = {}, &block) ⇒ Object

Note:

This validation method does not accept the :allow_nil option.

Intended primarily for validating a form field was entered correctly by requiring it twice:

Model:
  class User < AWS::Record::Base
    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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :message (String) —

    A custom error message. The defualt :message is “doesn’t match confirmation”.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



246
247
248
 
# File 'lib/aws/record/validations.rb', line 246

def validates_confirmation_of *args
  validators << ConfirmationValidator.new(self, *args)
end

#validates_count_of(*attributes, options = {}, &block) ⇒ Object

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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :exactly (Integer) —

    The exact number of values the attribute should have. If this validation option fails the error message specified by :wrong_number will be added.

  • :within (Range) —

    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.

  • :minimum (Integer) —

    The minimum number of values the attribute should have. If it has fewer, the :too_few error message will be added.

  • :maximum (Integer) —

    The maximum number of values the attribute should have. If it has more, the :too_many error message will be added.

  • :too_many (String) —

    An error message added when the attribute has too many values. Defaults to "has too many values (maximum is %{maximum})"

  • :too_few (String) —

    An error message added when the attribute has too few values. Defaults to "has too few values (minimum is %{minimum})"

  • :wrong_number (String) —

    An error message added when the number of attribute values does not match the :exactly option. Defaults to "has the wrong number of values (should have exactly %{exactly}"

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



332
333
334
 
# File 'lib/aws/record/validations.rb', line 332

def validates_count_of *args
  validators << CountValidator.new(self, *args)
end

#validates_each(*attributes, options = {}, &block) ⇒ Object

Adds a block validator that is called during record validation.

class ExampleClass < AWS::Record::Base

  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

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



367
368
369
370
371
372
 
# File 'lib/aws/record/validations.rb', line 367

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(*attributes, options = {}, &block) ⇒ Object

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::Base

  string_attr :tags, :set => true

  validates_exlusion_of :tags, :in => four_letter_words

end

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :in (required, Enumerable) —

    An enumerable object to ensure the value is not in.

  • :message (String) —

    A custom error message. The defualt :message is “is reserved”.

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



413
414
415
 
# File 'lib/aws/record/validations.rb', line 413

def validates_exclusion_of *args
  validators << ExclusionValidator.new(self, *args)
end

#validates_format_of(*attributes, options = {}, &block) ⇒ Object

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::Base

  string_attr :tags, :set => true

  validates_format_of :tags, :with => /^\w{2,10}$/

end

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :with (Regexp) —

    If the value matches the given regex, an error will not be added.

  • :without (Regexp) —

    If the value matches the given regex, an error will be added. must match, or an error is added.

  • :message (String) —

    A custom error message. The defualt :message is “is reserved”.

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



462
463
464
 
# File 'lib/aws/record/validations.rb', line 462

def validates_format_of *args
  validators << FormatValidator.new(self, *args)
end

#validates_inclusion_of(*attributes, options = {}, &block) ⇒ Object

Validates that the attribute value is included in the given enumerable object.

class MultipleChoiceAnswer < AWS::Record::Base
  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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :in (required, Enumerable) —

    An enumerable object to check for the value in.

  • :message (String) —

    A custom error message. The defualt :message is “is not included in the list”.

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



499
500
501
 
# File 'lib/aws/record/validations.rb', line 499

def validates_inclusion_of *attributes
  validators << InclusionValidator.new(self, *attributes)
end

#validates_length_of(*attributes, options = {}, &block) ⇒ Object

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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :within (Enumerable) —

    An enumerable object to ensure the length of the value falls within.

  • :exactly (Integer) —

    The exact length a value must be. If this validation fails the error message specified by :wrong_length will be added.

  • :within (Range) —

    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.

  • :minimum (Integer) —

    The minimum length an attribute value should be. If it is shorter, the :too_short error message will be added.

  • :maximum (Integer) —

    The maximum length an attribute value should be. If it is longer, the :too_long error message will be added.

  • :too_long (String) —

    An error message added when the attribute value is too long. Defaults to "is too long (maximum is %{maximum} characters)"

  • :too_short (String) —

    An error message added when the attribute value is too short. Defaults to "is too short (minimum is %{minimum} characters)"

  • :wrong_length (String) —

    An error message added when the attribute has the incorrect length (as specified by :exactly). Defaults to "is the wrong length (should be %{exactly} characters"

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



560
561
562
 
# File 'lib/aws/record/validations.rb', line 560

def validates_length_of *args
  validators << LengthValidator.new(self, *args)
end

#validates_numericality_of(*attributes, options = {}, &block) ⇒ Object

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.

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :only_integer (Boolean) — default: false —

    Adds an error when valiating and the value is numeric, but it not a whole number.

  • :equal_to (Integer) —

    When set the value must equal the given value exactly. May not be used with the greater/less options.

  • :greater_than (Numeric) —

    Ensures the attribute is greater than the given number.

  • :greater_than_or_equal_to (Integer) —

    Ensures the attribute is greater than or equal to the given number.

  • :less_than (Numeric) —

    Ensures the attribute is less than the given value.

  • :less_than_or_equal_to (Integer) —

    Ensures the value is less than or equal to the given number.

  • :even (Numeric) —

    If true, the value may only be an even integer. This forces the :only_integer to true.

  • :odd (Numeric) —

    If true, the value may only be an odd integer. This forces the :only_integer to true.

  • :message (String) —

    A custom error message. The defualt :message is “is not a number”.

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



610
611
612
 
# File 'lib/aws/record/validations.rb', line 610

def validates_numericality_of *args
  validators << NumericalityValidator.new(self, *args)
end

#validates_presence_of(*attributes, options = {}, &block) ⇒ Object

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

Parameters:

  • attributes —

    A list of attribute names to validate.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :message (String) —

    A custom error message. The defualt :message is “may not be blank”.

  • :on (Symbol) — default: :save —

    When this validation is run. Valid values include:

    • :save:

    • :create:

    • :update:

  • :allow_nil (Boolean) — default: false —

    Skip validation if the attribute value is nil.

  • :if (Symbol, String, Proc) —

    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? }).

  • :unless (Symbol, String, Proc) —

    Specifies a method or proc to call. The validation will not be run if the return value is of the method/proc is false.



641
642
643
 
# File 'lib/aws/record/validations.rb', line 641

def validates_presence_of *args
  validators << PresenceValidator.new(self, *args)
end