gist.rdoc

Describing¶ ↑

Format:

#{attribute_name}_#{verb}_#{required}?_#{predicate}(options = {})

Example:

class Post < ActiveRecord::Base
  belongs_to :author

  title_is_required
  author_is_a_required_association
  body_has_length :below => 256
end

Predicates¶ ↑

aliased¶ ↑

Use when the attribute may only contain certain values, but those values have human labels.

Example:

class User < ActiveRecord::Base
  classification_is_aliased :options => {
    1 => "user",
    2 => "admin",
    3 => "superadmin"
  }
end

association¶ ↑

Use when an association has a minimum or maximum number of records, or when you need to require that it exists. Note that it’s ok for two records to require each other – there won’t be any infinitely recursive validation problems.

Example:

class User < ActiveRecord::Base
  has_many :quotes

  quotes_is_an_association :max => 3
end

class Quote < ActiveRecord::Base
  belongs_to :user

  user_is_a_required_association
end

blacklisted¶ ↑

Use when you need to make sure some value is NOT saved. Maybe you’ve reserved some for yourself?

By default this is not case sensitive. Which means that by default this assumes you only have strings. If you need to blacklist other data types, set :case_sensitive => false.

Example:

class User < ActiveRecord::Base
  username_is_blacklisted :restricted => %w(admin superadmin god user anonymous)
end

domain¶ ↑

Use when you need to capture a domain name, without protocol or path information.

Example:

class Account < ActiveRecord::Base
  cname_is_domain
end

email¶ ↑

Use when you want to eliminate malformed email addresses. This will not ensure deliverability – that requires a field test.

Example:

class User < ActiveRecord::Base
  email_address_is_email
end

enumerated aka whitelisted¶ ↑

Use when you want to limit the values a field may have. Useful for constraining polymorphic associations! Note that because of how required-ness is handled, if a field is empty this predicate will not be evaluated.

Note that this predicate implies required-ness.

Example:

class Favorite < ActiveRecord::Base
  belongs_to :favoritable, :polymorphic => true

  # only allow favoriting of a User or Project
  favoritable_type_is_enumerated :options => %w(User Project)
end

hex_color¶ ↑

Use when you need to capture hex colors. Useful for theming! All colors will be stored in the database with a leading pound sign, expanded to the full six character size (e.g. “a1e” becomes “#aa11ee”).

Example:

class Account < ActiveRecord::Base
  background_is_hex_color
end

length aka size¶ ↑

Use when you need to set an upper or lower boundary on the length of a field. Note that this also works on arrays and hashes.

Example:

class User < ActiveRecord::Base
  username_has_length :range => 3..20
  # the following are identical:
  password_has_length :above => 3
  password_has_length :above => 4, :exactly => true
end

number¶ ↑

Use when you have a numeric field that needs to be constrained on the number line.

Example:

class Auction < ActiveRecord::Base
  buyout_is_number :integer => true
  bid_increment_is_number :at_least => 5
  quantity_is_number :range => 1..10
end

pattern¶ ↑

Use when you need to define a regular expression pattern for a field. Actually, DON’T USE THIS. Instead, extend it and create a new predicate!

phone_number¶ ↑

Use when you want to validate phone numbers against a formal numbering plan. Currently only supports NANP (North American Numbering Plan), which uses the +1 prefix. This predicate is smart enough to exclude the bogus 555-01xx numbers.

If you use Semantic Attributes in an international application before I do, please help by contributing back to this predicate.

Example:

class User < ActiveRecord::Base
  mobile_is_a_phone_number
end

required¶ ↑

Use when you simple need a field to be required. Note that if the field has any other semantics, you should add required-ness to those!

Example:

class User < ActiveRecord::Base
  password_is_required
end

same_as¶ ↑

Use when you need some attribute to be the same as another attribute, aka this-is-how-you-do-password-confirmation.

Example:

class User < ActiveRecord::Base
  password_confirmation_is_same_as :method => :password
end

time¶ ↑

Use when you have a time field that needs to be constrained on the timeline. You may set your constraint either absolutely (e.g. after Jan 1, 2005) or relatively (e.g. no older than 5 minutes from now).

Example:

class Project < ActiveRecord::Base
  # this deadline must be after Jan 1, 2005
  deadline_is_time :after => Time.parse("2005-01-01 00:00:00")
end

class Project < ActiveRecord::Base
  # this deadline must be no older than 5 days and no further in the future than 1 week, as of the time of validation.
  deadline_is_time :distance => (-5.days)..(1.week)
end

unique¶ ↑

Use when you need an attribute to be unique, possibly in the scope of some other attributes. By default this is not case sensitive.

Example:

class User < ActiveRecord::Base
  email_is_unique :scope => [:account_id]
end

url¶ ↑

Use when you have url. Please, use it! URLs can be complex. You may constrain your url to a list of domains, schemes, or ports. You may allow or disallow ip addresses.

Example:

class User < ActiveRecord::Base
  homepage_is_url :domain => %w(com net biz info edu)
  backup_is_url :schemes => %w(https), :ports => [443], :implied_scheme => 'https'
end

usa_state¶ ↑

Use when you have a USA state (or territory). Stores all states using USPS abbreviation.

Example:

class Address < ActiveRecord::Base
  state_is_a_usa_state :with_territories => true
end

usa_zip_code¶ ↑

Use when you have a USA postal code, possibly with the extended +4 syntax.

Example:

class Address < ActiveRecord::Base
  # :extended may be any of :allowed, :required, or false (default)
  postal_code_is_a_usa_zip_code :extended => :allowed
end