semantic_attributes 1.0.2

data/lib/predicates/email.rb

@@ -0,0 +1,42 @@
+# Describes a regular expression pattern for email addresses, based on RFC2822 and RFC3696.
+# Adapted from Alex Dunae's validates_email_format_of plugin v1.2.2, available under MIT License at http://code.dunae.ca/validates_email_format_of.html
+#
+# ==Options
+# * :with_mx_record [boolean, default false] - whether to verify the email's domain using a dns lookup for an mx record. This requires the Unix `dig` command. In Debian this is part of the dnsutils package. NOTE: RFC2821 states that when no MX records are listed, an A record may be used instead. This means that a missing MX record may not mean an invalid email address! Use at your own risk.
+#
+# == Example
+#   field_is_an_email :with_mx_record => true
+class Predicates::Email < Predicates::Base
+  attr_accessor :with_mx_record
+
+  def validate(value, record)
+    # local part max is 64 chars, domain part max is 255 chars
+    domain, local = value.reverse.split('@', 2)
+
+    valid = value.match(EmailAddressPattern)
+    valid &&= !(value.match /\.\./)
+    valid &&= (domain.length <= 255)
+    valid &&= (local.length <= 64)
+
+    if valid and self.with_mx_record
+      mx_record = `dig #{value.split('@').last} mx +noall +short`
+      valid &&= (!mx_record.empty?)
+    end
+
+    valid
+  end
+
+  def error_message
+    @error_message || :email
+  end
+
+  EmailAddressPattern = begin
+    local_part_special_chars = Regexp.escape('!#$%&\'*-/=?+-^_`{|}~')
+    local_part_unquoted = '(([[:alnum:]' + local_part_special_chars + ']+[\.\+]+))*[[:alnum:]' + local_part_special_chars + '+]+'
+    local_part_quoted = '\"(([[:alnum:]' + local_part_special_chars + '\.\+]*|(\\\\[\x00-\xFF]))*)\"'
+    Regexp.new(
+      '^((' + local_part_unquoted + ')|(' + local_part_quoted + ')+)@(((\w+\-+)|(\w+\.))*\w{1,63}\.[a-z]{2,6}$)',
+      Regexp::EXTENDED | Regexp::IGNORECASE, "n"
+    )
+  end
+end

data/lib/predicates/enumerated.rb

@@ -0,0 +1,23 @@
+# A basic pattern where the values are enumerated.
+#
+# ==Options
+# * :options - a complete collection of values that the attribute may contain
+#
+# ==Example
+#   field_is_enumerated :options => ['allowed_value_one', 'allowed_value_two']
+class Predicates::Enumerated < Predicates::Base
+  attr_accessor :options
+
+  def initialize(attr, options = {})
+    options[:or_empty] ||= false
+    super(attr, options)
+  end
+
+  def error_message
+    @error_message || :inclusion
+  end
+
+  def validate(value, record)
+    self.options.include? value
+  end
+end

data/lib/predicates/hex_color.rb

@@ -0,0 +1,24 @@
+# Defines a field as a hex color. These are hexadecimal strings from 3 to 6 characters long. All hex colors will be saved in the database with a preceding pound sign (e.g. #123456). Also, #123456 is actually a pretty cool color. You should try it.
+class Predicates::HexColor < Predicates::Pattern
+  # a fixed regexp
+  def like
+    @like ||= /\A#[0-9a-fA-F]{6}\Z/
+  end
+
+  def error_message
+    @error_message ||= :hex
+  end
+
+  def normalize(value)
+    return value if value.blank?
+
+    # ensure leading pound sign
+    value = "##{value}" unless value[0].chr == '#'
+    # expand from three characters to six characters
+    if value =~ /\A#[0-9a-fA-F]{3}\Z/
+      value = "##{value[1].chr * 2}#{value[2].chr * 2}#{value[3].chr * 2}"
+    end
+
+    value
+  end
+end

data/lib/predicates/length.rb

@@ -0,0 +1,71 @@
+# Lets you declare a min/max/exact length for something. This works for arrays and strings both.
+#
+# ==Options
+# * :above [integer] - when the attribute has a minimum
+# * :below [integer] - when the attribute has a maximum
+# * :range [range] - when the attribute has a minimum and a maximum
+# * :exactly [integer] - when the attribute must be exactly some length
+#
+# ==Examples
+#   field_has_length :exactly => 3
+#   field_has_length :above => 5
+#   field_has_length :range => 4..8
+class Predicates::Length < Predicates::Base
+  # when the length has just a min
+  attr_accessor :above
+
+  # when the length has just a max
+  attr_accessor :below
+
+  # when the length has both a max and a min
+  attr_accessor :range
+
+  # when the length must be exact
+  attr_accessor :exactly
+
+  def error_message
+    @error_message || range_description
+  end
+  
+  def error_binds
+    self.range ?
+      {:min => self.range.first, :max => self.range.last} :
+      {:min => self.above, :max => self.below, :count => self.exactly}
+  end
+
+  def validate(value, record)
+    l = tokenize(value).length
+    if self.exactly
+      l == self.exactly
+    elsif self.range
+      self.range.include? l
+    elsif self.above
+      l > self.above
+    elsif self.below
+      l < self.below
+    else
+      true
+    end
+  end
+  
+  def normalize(v)
+    (v and v.is_a? String) ? v.gsub("\r\n", "\n") : v
+  end
+
+  protected
+  
+  def tokenize(value)
+    case value
+      when Array, Hash then value
+      else              value.to_s.mb_chars
+    end
+  end
+  
+  def range_description
+    return :inexact_length if self.exactly
+    return :wrong_length if self.range
+    return :too_short if self.above
+    return :too_long if self.below
+    raise 'undetermined range'
+  end
+end

data/lib/predicates/number.rb

@@ -0,0 +1,104 @@
+# Describes an attribute as a number. You may specify boundaries for the number (min, max, or both), and also specify whether it must be an integer.
+#
+# ==Options
+# * :integer [boolean, default: false] - if the number is an integer (or float/decimal)
+# * :above [integer, float] - when the number has a minimum
+# * :below [integer, float] - when the number has a maximum
+# * :range [range] - when the number has a minimum and a maximum
+# * :inclusive [boolean, default: false] - if your maximum or minimum is also an allowed value. Does not work with :range.
+# * :at_least [integer, float] - an easy way to say :above and :inclusive
+# * :no_more_than [integer, float] - an easy way to say :below and :inclusive
+#
+# ==Examples
+#   field_is_a_number :integer => true
+#   field_is_a_number :range => 1..5, :integer => true
+#   field_is_a_number :above => 4.5
+#   field_is_a_number :below => 4.5, :inclusive => true
+class Predicates::Number < Predicates::Base
+  # whether to require an integer value
+  attr_accessor :integer
+
+  # when the number has a minimum value, but no maximum
+  attr_accessor :above
+
+  # when the number has a maximum value, but no minimum
+  attr_accessor :below
+
+  # when the number has both a maximum and a minimum value
+  attr_accessor :range
+
+  # meant to be used with :above and :below, when you want the endpoint to be inclusive.
+  # with the :range option you can just specify inclusion using the standard Ruby range syntax.
+  attr_accessor :inclusive
+  
+  def at_least=(val)
+    self.above = val
+    self.inclusive = true
+  end
+  
+  def no_more_than=(val)
+    self.below = val
+    self.inclusive = true
+  end
+
+  def error_message
+    @error_message || range_description
+  end
+  
+  def error_binds
+    self.range ?
+      {:min => self.range.first, :max => self.range.last} :
+      {:min => self.above, :max => self.below}
+  end
+
+  def validate(value, record)
+    # check data type
+    valid = if self.integer
+        # if it must be an integer, do a regexp check for digits only
+        value.to_s.match(/\A[+-]?[0-9]+\Z/) unless value.is_a? Hash or value.is_a? Array
+      else
+        # if it can also be a float or decimal, then try a conversion
+        begin
+          Kernel.Float(value)
+          true
+        rescue ArgumentError, TypeError
+          false
+        end
+      end
+
+    # if it's the right data type, then also check boundaries
+    valid &&= if self.range
+        self.range.include? value
+      elsif self.above
+        operator = self.inclusive ? :>= : :>
+        value.send operator, self.above
+      elsif self.below
+        operator = self.inclusive ? :<= : :<
+        value.send operator, self.below
+      else
+        true
+      end
+
+    valid
+  end
+
+  protected
+
+  def range_description
+    # if it has two endpoints
+    if self.range
+      return :between
+    end
+    # if it only has one inclusive endpoint
+    if inclusive
+      return :greater_than_or_equal_to if self.above
+      return :less_than_or_equal_to if self.below
+    # if it only has one exclusive endpoint
+    else
+      return :greater_than if self.above
+      return :less_than if self.below
+    end
+    # if it has no endpoints
+    :not_a_number
+  end
+end

data/lib/predicates/pattern.rb

@@ -0,0 +1,22 @@
+# Provides a generic pattern predicate, which is extended and used by other pattern-based validations.
+#
+# WARNING: If you define a pattern, you probably want to use \A and \Z instead of ^ and $. The latter anchors are per-line, which means that multi-line strings can sneak stuff past your regular expression. For example:
+#
+#   @predicate.like = /^hello world$/
+#   assert @predicate.validate("malicious\nhello world\ntext", nil), 'must match only one line'
+#   @predicate.like = /\Ahello world\Z/
+#   assert !@predicate.validate("malicious\nhello world\ntext", nil), 'must match entire string'
+#
+# ==Options
+# * :like - a regular expression matching pattern
+#
+# == Example
+#   field_has_a_pattern :like => /\Aim in ur [a-z]+, [a-z]+ ur [a-z]+\Z/
+class Predicates::Pattern < Predicates::Base
+  attr_accessor :like
+
+  def validate(value, record)
+    value = value.to_s if [Symbol, Fixnum].include?(value.class)
+    value.match(self.like)
+  end
+end

data/lib/predicates/phone_number.rb

@@ -0,0 +1,62 @@
+# Defines a field as a phone number. Currently it assumes the phone number fits the North American Numbering Plan. Future support of other plans will be implemented by calling code, e.g. +44 (UK) or +33 (FR). These will act as triggers for localized phone number validation.
+#
+# ==Options
+# * implied_country_code [integer, default: 1 (North America)]
+#
+# ==Example
+#   field_is_a_phone_number
+class Predicates::PhoneNumber < Predicates::Base
+  attr_accessor :implied_country_code
+
+  def initialize(attr, options = {})
+    options[:implied_country_code] ||= 1
+    super(attr, options)
+  end
+
+  def error_message
+    @error_message ||= :phone
+  end
+
+  def validate(value, record)
+    case value
+      when Patterns::NANP
+      match = $~
+      valid = !match.nil?
+      valid &&= (match[2] != '555' or match[3][0..1] != '01') # 555-01xx are reserved (http://en.wikipedia.org/wiki/555_telephone_number)
+
+      else
+      valid = false
+    end
+
+    valid
+  end
+
+  # check country code, then format differently for each country
+  def to_human(value)
+    case value
+      when Patterns::NANP
+      m = $~
+      "(#{m[1]}) #{m[2]}-#{m[3]}"
+
+      else
+      value
+    end
+  end
+
+  # strip out all non-numeric characters except a leading +
+  def normalize(value)
+    return value if value.blank?
+
+    value = "+#{value}" if value.to_s[0..0] == '1' # north american bias
+    value = "+#{implied_country_code}#{value}" unless value.to_s[0..0] == '+'
+
+    leading_plus = (value[0..0] == '+')
+    value.gsub!(/[^0-9]/, '')
+    value = "+#{value}" if leading_plus
+    value
+  end
+
+  class Patterns
+    NANP = /\A\+1([2-9][0-8][0-9])([2-9][0-9]{2})([0-9]{4})\Z/
+  end
+end

data/lib/predicates/required.rb

@@ -0,0 +1,22 @@
+# Marks an attribute as being required. This is really just a shortcut for using the or_empty? setting.
+#
+# Example:
+#   class Comment < ActiveRecord::Base
+#     has_one :owner
+#     subject_is_required
+#     owner_is_required
+#   end
+class Predicates::Required < Predicates::Base
+  # this permanently sets :or_empty to false
+  def allow_empty?
+    false
+  end
+
+  def error_message
+    @error_message || :required
+  end
+
+  def validate(value, record)
+    !value.blank?
+  end
+end

data/lib/predicates/same_as.rb

@@ -0,0 +1,17 @@
+# Requires that one field must be the same as another field. Useful when combined with virtual attributes to describe things like password or email confirmation.
+#
+# ==Options
+#
+# ==Example
+#   field_is_same_as :method => :other_field
+class Predicates::SameAs < Predicates::Base
+  attr_accessor :method
+
+  def error_message
+    @error_message ||= :same_as
+  end
+  
+  def validate(value, record)
+    value == record.send(self.method)
+  end
+end

data/lib/predicates/size.rb

@@ -0,0 +1,2 @@
+# Size is just an alias for Length
+class Predicates::Size < Predicates::Length; end

data/lib/predicates/time.rb

@@ -0,0 +1,43 @@
+# Describes a field as a Time field. Currently this means that it has both a time and a date.
+#
+# ==Options
+# * :before [time] - specifies that the value must predate the given time (as object or string)
+# * :after [time] - specifies that the value must postdate the given time (as object or string)
+# * :distance [range] - specifies a range of seconds that provide an minimum and maximum time value to be calculated from the current time.
+class Predicates::Time < Predicates::Base
+  # specifies a time that must postdate any valid value
+  def before=(val)
+    @before = val.is_a?(Time) ? val : Time.parse(val)
+  end
+  attr_reader :before
+
+  # specifies a time that must predate any valid value
+  def after=(val)
+    @after = val.is_a?(Time) ? val : Time.parse(val)
+  end
+  attr_reader :after
+  
+  # specifies a range of seconds where the lower boundary
+  # is the minimum time value and the upper boundary is the
+  # maximum time value, both interpreted from the current
+  # time.
+  attr_accessor :distance
+
+  def error_message
+    @error_message || :time
+  end
+
+  def validate(value, record)
+    valid = value.is_a? Time
+    valid &&= (value < self.before) if self.before
+    valid &&= (value > self.after) if self.after
+    
+    if self.distance
+      now = Time.zone.now
+      valid &&= (value >= now + self.distance.begin)
+      valid &&= (value <= now + self.distance.end)
+    end
+
+    valid
+  end
+end

data/lib/predicates/unique.rb

@@ -0,0 +1,71 @@
+# Describes an attribute as being unique, possibly within a certain scope.
+#
+# ==Options
+# * :scope [array] - a list of other fields that define the context for uniqueness. it's like defining a multi-column uniqueness constraint.
+# * :case_sensitive [boolean, default false] - whether case matters for uniqueness.
+#
+# ==Examples
+#   field_is_unique :case_sensitive => true
+#   field_is_unique :scope => [:other_field, :another_other_field]
+class Predicates::Unique < Predicates::Base
+  attr_accessor :case_sensitive
+  attr_accessor :scope
+
+  def initialize(attribute, options = {})
+    defaults = {
+      :scope => [],
+      :case_sensitive => false
+    }
+    super attribute, defaults.merge(options)
+  end
+
+  def error_message
+    @error_message || :taken
+  end
+
+  def validate(value, record)  
+    klass = record.class
+  
+    # merge all the scope fields with this one. they must all be unique together.
+    # no special treatment -- case sensitivity applies to all or none.
+    values = [scope].flatten.collect{ |attr| [attr, record.send(attr)] }
+    values << [@attribute, value]
+
+    sql = values.map do |(attr, attr_value)|
+      comparison_for(attr, attr_value, klass)
+    end
+
+    unless record.new_record?
+      sql << klass.send(:sanitize_sql, ["#{klass.quoted_table_name}.#{klass.primary_key} <> ?", record.id])
+    end
+
+    !klass.where(sql.join(" AND ")).exists?
+  end
+  
+  protected
+  
+  def comparison_for(field, value, klass)
+    quoted_field = "#{klass.quoted_table_name}.#{klass.connection.quote_column_name(field)}"
+
+    if klass.columns_hash[field.to_s].text?
+      if case_sensitive
+        # case sensitive text comparison in any database
+        klass.send(:sanitize_sql, ["#{quoted_field} #{klass.connection.case_sensitive_equality_operator} ?", value])
+      elsif mysql?(klass.connection)
+        # case INsensitive text comparison in mysql - yes this is a database specific optimization. i'm always open to better ways. :)
+        klass.send(:sanitize_sql, ["#{quoted_field} = ?", value])
+      else
+        # case INsensitive text comparison in most databases
+        klass.send(:sanitize_sql, ["LOWER(#{quoted_field}) = ?", value.to_s.downcase])
+      end
+    else
+      # non-text comparison
+      klass.send(:sanitize_sql, {field => value})
+    end
+  end
+  
+  def mysql?(connection)
+    (defined?(ActiveRecord::ConnectionAdapters::MysqlAdapter) and connection.is_a?(ActiveRecord::ConnectionAdapters::MysqlAdapter)) or
+      (defined?(ActiveRecord::ConnectionAdapters::Mysql2Adapter) and connection.is_a?(ActiveRecord::ConnectionAdapters::Mysql2Adapter))
+  end
+end

data/lib/predicates/url.rb

@@ -0,0 +1,62 @@
+require 'uri'
+
+# Defines a field as a URL.
+#
+# ==Options
+#   :domains [array, default nil] - a whitelist of allowed domains (e.g. ['com', 'net', 'org']). set to nil to allow all domains.
+#   :schemes [array, default ['http', 'https']] - a whitelist of allowed schemes. set to nil to allow all schemes.
+#   :ports [array, default nil] - a whitelist of allowed ports. set to nil to allow all ports.
+#   :allow_ip_address [boolean, default true] - whether to allow ip addresses instead to domain names.
+#   :implied_scheme [string, symbol, default 'http'] - what scheme to assume if non is present.
+#
+# ==Examples
+#   # if you need an ftp url
+#   field_is_an_url :schemes => ['ftp']
+#
+#   # if you want to require https
+#   field_is_an_url :schemes => ['https'], :implied_scheme => 'https', :ports => [443]
+class Predicates::Url < Predicates::Base
+  attr_accessor :domains
+  attr_accessor :allow_ip_address
+  attr_accessor :schemes
+  attr_accessor :ports
+  attr_accessor :implied_scheme
+
+  def initialize(attr, options = {})
+    defaults = {
+      :allow_ip_address => true,
+      :schemes => ['http', 'https'],
+      :implied_scheme => 'http'
+    }
+
+    super attr, defaults.merge(options)
+  end
+
+  def error_message
+    @error_message || :url
+  end
+
+  def validate(value, record)
+    url = URI.parse(value)
+    tld = (url.host && url.host.match(/\..+\Z/)) ? url.host.split('.').last : nil
+
+    valid = true
+    valid &&= (!tld.blank?)
+    valid &&= (!self.schemes or self.schemes.include? url.scheme)
+    valid &&= (!self.domains or self.domains.include? tld)
+    valid &&= (!self.ports or self.ports.include? url.port)
+    valid &&= (self.allow_ip_address or not url.host =~ /^([0-9]{1,3}\.){3}[0-9]{1,3}$/)
+
+    valid
+  rescue URI::InvalidURIError, URI::InvalidComponentError
+    false
+  end
+
+  def normalize(v)
+    url = URI.parse(v)
+    url = URI.parse("#{self.implied_scheme}://#{v}") if self.implied_scheme and not (url.scheme and url.host)
+    url.to_s
+  rescue URI::InvalidURIError, URI::InvalidComponentError
+    v
+  end
+end

data/lib/predicates/usa_state.rb

@@ -0,0 +1,87 @@
+# Requires that an attribute be in a list of valid USA states.
+# Machine format is the abbreviation, human format is the whole word.
+# List acquired from: http://www.usps.com/ncsc/lookups/abbr_state.txt
+#
+# ==Options
+# * :with_territories [boolean, default false] - whether to allow territories
+class Predicates::UsaState < Predicates::Aliased
+  # a boolean for whether to allow united states territories. default is false.
+  attr_writer :with_territories
+  def with_territories?
+    @with_territories ? true : false
+  end
+
+  def options
+    @options ||= STATES.merge(with_territories? ? TERRITORIES : {})
+  end
+  undef_method :options=
+
+  def error_message
+    @error_message || with_territories? ? :us_state_or_territory : :us_state
+  end
+
+  TERRITORIES = {
+    'American Samoa' => 'AS',
+    'Federated States of Micronesia' => 'FM',
+    'Guam' => 'GU',
+    'Marshall Islands' => 'MH',
+    'Northern Mariana Islands' => 'MP',
+    'Palau' => 'PW',
+    'Puerto Rico' => 'PR',
+    'Virgin Islands' => 'VI'
+  }
+
+  STATES = {
+    'Alabama' => 'AL',
+    'Alaska' => 'AK',
+    'Arizona' => 'AZ',
+    'Arkansas' => 'AR',
+    'California' => 'CA',
+    'Colorado' => 'CO',
+    'Connecticut' => 'CT',
+    'Delaware' => 'DE',
+    'District of Columbia' => 'DC',
+    'Florida' => 'FL',
+    'Georgia' => 'GA',
+    'Hawaii' => 'HI',
+    'Idaho' => 'ID',
+    'Illinois' => 'IL',
+    'Indiana' => 'IN',
+    'Iowa' => 'IA',
+    'Kansas' => 'KS',
+    'Kentucky' => 'KY',
+    'Louisiana' => 'LA',
+    'Maine' => 'ME',
+    'Maryland' => 'MD',
+    'Massachusetts' => 'MA',
+    'Michigan' => 'MI',
+    'Minnesota' => 'MN',
+    'Mississippi' => 'MS',
+    'Missouri' => 'MO',
+    'Montana' => 'MT',
+    'Nebraska' => 'NE',
+    'Nevaga' => 'NV',
+    'New Hampshire' => 'NH',
+    'New Jersey' => 'NJ',
+    'New Mexico' => 'NM',
+    'New York' => 'NY',
+    'North Carolina' => 'NC',
+    'North Dakota' => 'ND',
+    'Ohio' => 'OH',
+    'Oklahoma' => 'OK',
+    'Oregon' => 'OR',
+    'Pennsylvania' => 'PA',
+    'Rhode Island' => 'RI',
+    'South Carolina' => 'SC',
+    'South Dakota' => 'SD',
+    'Tennessee' => 'TN',
+    'Texas' => 'TX',
+    'Utah' => 'UT',
+    'Vermont' => 'VT',
+    'Virginia' => 'VA',
+    'Washington' => 'WA',
+    'West Virginia' => 'WV',
+    'Wisconsin' => 'WI',
+    'Wyoming' => 'WY'
+  }
+end

data/lib/predicates/usa_zip_code.rb

@@ -0,0 +1,25 @@
+# A United States zip code.
+# Only validates format, does not attempt any verification for *actual* zip codes.
+# Validates via regular expression.
+#
+# ==Options
+# * :extended [:allowed, :required, or false (default)] - whether to allow (or require!) the extended (+4) zip code format
+class Predicates::UsaZipCode < Predicates::Pattern
+  attr_accessor :extended
+
+  def like
+    return @like unless @like.nil?
+    pattern = '[0-9]{5}'
+    if extended
+      pattern += '(-[0-9]{4})'
+      pattern += '?' unless extended == :required
+    end
+
+    @like = /\A#{pattern}\Z/
+  end
+  undef_method :like=
+
+  def error_message
+    @error_message || :us_zip_code
+  end
+end