semantic_attributes 1.0.2

data/.gitignore

@@ -0,0 +1,2 @@
+rdoc
+test/test.log

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,99 @@
+PATH
+  remote: .
+  specs:
+    semantic_attributes (1.0.1)
+      rails (~> 3.2.2)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    actionmailer (3.2.2)
+      actionpack (= 3.2.2)
+      mail (~> 2.4.0)
+    actionpack (3.2.2)
+      activemodel (= 3.2.2)
+      activesupport (= 3.2.2)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.1)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.1)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
+    activemodel (3.2.2)
+      activesupport (= 3.2.2)
+      builder (~> 3.0.0)
+    activerecord (3.2.2)
+      activemodel (= 3.2.2)
+      activesupport (= 3.2.2)
+      arel (~> 3.0.2)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.2)
+      activemodel (= 3.2.2)
+      activesupport (= 3.2.2)
+    activesupport (3.2.2)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.0)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    journey (1.0.3)
+    json (1.6.6)
+    mail (2.4.4)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    metaclass (0.0.1)
+    mime-types (1.18)
+    mocha (0.10.5)
+      metaclass (~> 0.0.1)
+    multi_json (1.2.0)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.2.2)
+      actionmailer (= 3.2.2)
+      actionpack (= 3.2.2)
+      activerecord (= 3.2.2)
+      activeresource (= 3.2.2)
+      activesupport (= 3.2.2)
+      bundler (~> 1.0)
+      railties (= 3.2.2)
+    railties (3.2.2)
+      actionpack (= 3.2.2)
+      activesupport (= 3.2.2)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.8.7)
+    rdoc (3.12)
+      json (~> 1.4)
+    sprockets (2.1.2)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.5)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.32)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (>= 1.0.0)
+  mocha (>= 0.10.5)
+  rake (= 0.8.7)
+  semantic_attributes!
+  sqlite3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007-2012 Lance Ivy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,54 @@
+SemanticAttributes
+==================
+-by Lance Ivy, 2007
+
+http://github.com/cainlevy/semantic-attributes
+
+http://code.google.com/p/semanticattributes/
+
+==Summary
+
+A validation library that allows introspection (User.name_is_required?) and supports database normalization (aka "form input cleaning").
+
+==Philosophy
+
+The method-chained validation routine built into ActiveRecord must die! It's time for an object-oriented approach to attribute validations. The Semantic Attributes plugin provides this approach by letting you attach predicates to your attributes with a tasty DSL. These predicates package up some really sweet behavior, where validations are really only the beginning. I've also discovered that it can be really useful to use these predicates to convert between human and machine formats: for example, with the phone number predicate you can let your users enter phone numbers with whatever formatting they want, always save the values to the database as numeric strings, and then present the values back to the user with standard formatting.
+
+I've also found other nifty uses for object-oriented predicates that package up validation. For example, it becomes easy to run a quick validation check on a field with a sample value and report true/false. This is exactly what the <tt>expected_error_for(:field, value)</tt> method does, and it lets you build a validation routine that listens to form data as it's being typed and report problems without duplicating your validation code client-side. In a similar vein, the <tt>_valid?</tt> attribute suffix lets you do single-attribute validation on a record anytime you want.
+
+==Example
+
+  class User < ActiveRecord::Base
+    email_is_an_email
+    home_page_is_a_url :domains => ['com', 'net', 'org'], :allow_ip_address => false
+    mobile_is_a_phone_number
+  end
+
+Now imagine a sample script/console session:
+
+  >> User.name_is_required?
+  => true
+  >> User.mobile_is_required?
+  => false
+
+Ok, we have a DSL for introspection. What if we want to retrieve configuration details?
+
+  >> User.semantic_attributes[:home_page].get(:url).domains
+  => ['com', 'net', 'org']
+
+Let's create a user and play around with some instance methods:
+
+  >> user = User.new
+  >> user.mobile = '222 333.4444'
+  >> user.mobile_valid?
+  => true
+  >> user.mobile
+  => '+12223334444'
+  >> user.mobile_for_human
+  => '(222) 333-4444'
+
+==See Also
+* gist.rdoc
+* Predicates
+* ActiveRecord::Predicates::ClassMethods (see #method_missing)
+* ActiveRecord::AttributeFormats

data/Rakefile

@@ -0,0 +1,37 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+require 'rake/testtask'
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the SemanticAttributes plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/unit/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the SemanticAttributes plugin.'
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SemanticAttributes'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('gist.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+

data/gist.rdoc

@@ -0,0 +1,208 @@
+==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
+

data/lib/active_record/validation_recursion_control.rb

@@ -0,0 +1,33 @@
+module ActiveRecord #:nodoc:
+module ValidationRecursionControl #:nodoc:
+  def self.included(base)
+    base.class_eval do
+      alias_method_chain :valid?, :recursion_control
+    end
+  end
+
+  # It's easy to break out of circular validation dependencies. All we need to do
+  # is suppose that if a record's validity depends in some way on itself, then we
+  # can assume that circular condition is satisfied. That assumption will change
+  # nothing about the actual validity of the record.
+  def valid_with_recursion_control?(*args, &block)
+    assumed_valid? or with_recursion_control do valid_without_recursion_control?(*args, &block) end
+  end
+
+  private
+
+  mattr_accessor :recursion_stack
+  @@recursion_stack = []
+
+  def assumed_valid?
+    recursion_stack.include? self
+  end
+
+  def with_recursion_control(&block)
+    recursion_stack << self
+    result = yield
+    recursion_stack.delete(self)
+    result
+  end
+end
+end

data/lib/core_ext/class.rb

@@ -0,0 +1,14 @@
+class Class #:nodoc:
+  def alias_accessor(new, old)
+    alias_reader(new, old)
+    alias_writer(new, old)
+  end
+  
+  def alias_reader(new, old)
+    alias_method new, old
+  end
+  
+  def alias_writer(new, old)
+    alias_method "#{new}=", "#{old}="
+  end
+end

data/lib/predicates/aliased.rb

@@ -0,0 +1,22 @@
+# A special case of enumeration where the values are actually aliased for humans.
+# Create this like a normal enumeration, but make :options a Hash of {value => alias}
+#
+# ==Example
+#   field_is_aliased :options => {'a' => 'Alpha', 'b' => 'Beta'}
+class Predicates::Aliased < Predicates::Enumerated
+  def to_human(v)
+    options[v]
+  end
+
+  def validate(value, record)
+    self.options.has_value? value
+  end
+
+  def normalize(v)
+    if RUBY_VERSION < "1.9"
+      options.index(v)
+    else
+      options.key(v)
+    end
+  end
+end

data/lib/predicates/association.rb

@@ -0,0 +1,43 @@
+# Marks an attribute as being an association. Has options for controlling how many associated objects there can be.
+#
+# You can require associations by name.
+#
+# Example:
+#   class Comment < ActiveRecord::Base
+#     has_one :owner
+#     owner_is_association :or_empty => true
+#   end
+class Predicates::Association < Predicates::Base
+  # if there's a minimum to the number of associated records
+  attr_accessor :min
+
+  # if there's a maximum to the number of associated records
+  attr_accessor :max
+
+  def error_message
+    @error_message || :required
+  end
+
+  def validate(value, record)
+    # we treat singular and plural the same
+    associated = [value].flatten
+
+    # we need to check the validity of new records in order to calculate how many
+    # will save properly. this lets us validate against the min/max parameters.
+    invalid_new_records = associated.select{|r| r.new_record? and not r.valid?}
+    valid_new_records = associated - invalid_new_records
+
+    valid = true
+
+    # then validate against min/max
+    quantity = valid_new_records.length
+    valid &&= (!min or quantity >= min)
+    valid &&= (!max or quantity <= max)
+
+    # if we can't allow empty associations, then we need to do an extra check: if these
+    # records are new and invalid then they might not persist.
+    valid &&= (allow_empty? or quantity > 0)
+
+    valid
+  end
+end

data/lib/predicates/base.rb

@@ -0,0 +1,93 @@
+module Predicates
+  # The base class for all predicates. Defines the interface and standard settings.
+  #
+  # All predicates that inherit from Base get the following options:
+  #
+  #   :error_message   Feedback for the user if the validation fails. Remember that Rails will prefix the attribute name.
+  #   :validate_if     Restricts when the validation can happen. If it returns false, validation will not happen. May be a proc (with the record object as the argument) or a symbol that names a method on the record to call.
+  #   :validate_on     When to do the validation, during :update, :create, or both (default).
+  #   :or_empty        Whether to allow empty/nil values during validation (default: true)
+  class Base
+    ##
+    ## Standard Configuration Options
+    ##
+
+    # the error string when validation fails
+    def error_message
+      @error_message || :invalid
+    end
+    attr_writer :error_message
+    alias_accessor :message, :error_message
+
+    # available interpolation variables for the error message (see I18n.translate)
+    def error_binds
+      {}
+    end
+    
+    # a message that won't be pre-interpolated by semantic-attributes, so that it
+    # can work with ActiveRecord::Error#generate_full_message's translation lookup
+    attr_accessor :full_message
+    
+    def error
+      if full_message
+        full_message
+      elsif error_message.is_a?(Symbol)
+        I18n.t(error_message, error_binds.merge(:scope => 'semantic-attributes.errors.messages'))
+      else
+        error_message
+      end
+    end
+
+    # a condition to restrict when validation should occur. if it returns false, the validation will not happen.
+    # if the value is a proc, then the proc will be called and the record object passed as the argument
+    # if the value is a symbol, then a method by that name will be called on the record
+    attr_accessor :validate_if
+    alias_accessor :if, :validate_if
+
+    # defines when to do the validation - during :update or :create (default is both, signified by absence of specification)
+    # options: :update, :create, and :both
+    attr_reader :validate_on
+    def validate_on=(val)
+      raise ArgumentError('unknown value for :validate_on parameter') unless [:update, :create, :both].include? val
+      @validate_on = val
+    end
+    alias_accessor :on, :validate_on
+
+    # whether to allow empty (and nil) values during validation (default: true)
+    attr_writer :or_empty
+    def allow_empty?
+      @or_empty ? true : false
+    end
+
+    ##
+    ## Internal
+    ##
+
+    # the initialization method provides quick support for assigning options using existing methods
+    def initialize(attribute_name, options = {})
+      @attribute = attribute_name
+      @validate_on = :both
+      @or_empty = true
+      options.each_pair do |k, v|
+        self.send("#{k}=", v)
+      end
+    end
+
+    # define this in the concrete class to provide a validation routine for your predicate
+    def validate(value, record)
+      raise NotImplementedError
+    end
+    
+    # define this in the concrete class to provide a method for normalizing human inputs.
+    # this gives you the ability to be very forgiving of formatting variations in form data.
+    def normalize(value)
+      value
+    end
+
+    # define this in the concrete class to provide a method for converting from a storage format to a human readable format
+    # this is good for presenting your clean, logical data in a way that people like to read.
+    def to_human(value)
+      value
+    end
+  end
+end

data/lib/predicates/blacklisted.rb

@@ -0,0 +1,23 @@
+# Blacklisted is the inverse of Enumerated. This is how you can say that a field may _not_ be certain values.
+#
+# ==Example
+#   field_is_blacklisted :not => ['disallowed_value_one', 'disallowed_value_two']
+class Predicates::Blacklisted < Predicates::Base
+  # whether the comparison is case-sensitive
+  attr_accessor :case_sensitive
+
+  # the blacklist
+  attr_accessor :restricted
+
+  def error_message
+    @error_message || :exclusion
+  end
+
+  def validate(val, record)
+    if self.case_sensitive
+      !self.restricted.include? val
+    else
+      !self.restricted.any? {|r| r.to_s.downcase == val.to_s.downcase }
+    end
+  end
+end

data/lib/predicates/domain.rb

@@ -0,0 +1,31 @@
+require 'uri'
+
+# Defines a field as a simple domain (not URL).
+class Predicates::Domain < Predicates::Base
+  def error_message
+    @error_message || :domain
+  end
+
+  def validate(value, record)
+    url = URI.parse(with_protocol(value))
+    valid = (url.host == value)
+    valid &&= (value.match /\..+\Z/) # to catch "http://example" or similar
+    valid &&= (!value.match /^([0-9]{1,3}\.){3}[0-9]{1,3}$/) # to catch ip addresses
+
+    valid
+  rescue URI::InvalidURIError
+    false
+  end
+
+  def normalize(v)
+    URI.parse(with_protocol(v)).host || v
+  rescue URI::InvalidURIError
+    v
+  end
+
+  protected
+
+  def with_protocol(value)
+    !value or value.include?("://") ? value : "http://#{value}"
+  end
+end