semantic_attributes 1.0.2

data/lib/predicates/whitelisted.rb

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

data/lib/predicates.rb

@@ -0,0 +1,3 @@
+# A namespace for predicates.
+module Predicates
+end

data/lib/semantic_attributes/attribute.rb

@@ -0,0 +1,46 @@
+# a field with its assocatied predicates
+class SemanticAttributes::Attribute
+  attr_reader :field
+  def initialize(field)
+    @field = field.to_sym
+    @set = []
+  end
+
+  # whether this attribute has the given predicate
+  # accepts the 'short name' of a predicate (e.g. "phone_number" instead of Predicates::PhoneNumber)
+  def has?(predicate)
+    predicate = class_of predicate
+    @set.any? {|item| item.is_a? predicate}
+  end
+
+  # retrieves a predicate by name from the attribute
+  # accepts the 'short name' of a predicate (e.g. "phone_number" instead of Predicates::PhoneNumber)
+  def get(predicate)
+    predicate = class_of predicate
+    @set.find {|item| item.is_a? predicate}
+  end
+
+  # adds a predicate to the attribute, with options
+  # accepts the 'short name' of a predicate (e.g. "phone_number" instead of Predicates::PhoneNumber)
+  def add(predicate, options = {})
+    predicate = class_of predicate
+    @set << predicate.new(self.field, options)
+  end
+
+  # The list of predicates, without any shortcuts
+  def predicates
+    @set
+  end
+
+  protected
+
+  # fully-qualified-name of a predicate
+  def fqn(short_name)
+    "Predicates::#{short_name.to_s.camelize}"
+  end
+
+  # the actual predicate class for the given name
+  def class_of(short_name)
+    fqn(short_name).constantize
+  end
+end

data/lib/semantic_attributes/attribute_formats.rb

@@ -0,0 +1,67 @@
+module SemanticAttributes #:nodoc:
+  class MissingAttribute < NameError
+    def initialize(attr)
+      super("#{attr} is not defined. You may have a typo or need to run migrations.")
+    end
+  end
+
+  module AttributeFormats
+    def self.included(base)
+      base.extend ClassMethods
+    end
+    
+    def respond_to?(method_name, *args)
+      if md = method_name.to_s.match(/_for_human$/) and semantic_attributes.include?(md.pre_match)
+        true
+      else
+        super
+      end
+    end
+    
+    protected
+    
+    def method_missing(method_name, *args, &block)
+      if md = method_name.to_s.match(/_for_human$/) and semantic_attributes.include?(md.pre_match)
+        self.class.humanize(md.pre_match, self.send(md.pre_match))
+      else
+        begin
+          super
+        rescue
+          raise $!, $!.to_s, caller
+        end
+      end
+    end
+
+    module ClassMethods
+      # converts the object into human format according to the predicates for the attribute.
+      # the object may really be anything: string, integer, date, etc.
+      def humanize(attr, obj)
+        self.semantic_attributes[attr].predicates.inject(obj) { |val, predicate| val = predicate.to_human(val) }
+      end
+
+      # converts the object into machine format according to the predicates for the attribute.
+      # the object should be a simple object like a string, array, or hash. but really, it depends on the the predicates.
+      def normalize(attr, obj)
+        self.semantic_attributes[attr].predicates.inject(obj) { |val, predicate| val = predicate.normalize(val) }
+      end
+      
+      protected
+
+      def define_normalization_method_for(attr)
+        self.define_attribute_methods if self.respond_to? :attribute_methods_generated? and !self.attribute_methods_generated?
+        
+        writer = "#{attr}_with_normalization="
+        old_writer = "#{attr}_without_normalization=".to_sym
+        unless method_defined? writer
+          define_method writer do |val|
+            send(old_writer, self.class.normalize(attr, val))
+          end
+          alias_method_chain "#{attr}=", :normalization
+        end
+      rescue NameError
+        raise SemanticAttributes::MissingAttribute.new(attr)
+      end
+
+    end
+  end
+end

data/lib/semantic_attributes/locale/en.yml

@@ -0,0 +1,31 @@
+# based on ActiveRecord's locale/en.yml file
+en:
+  semantic-attributes:
+    errors:
+      messages:
+        us_zip_code: 'must be a US zip code.'
+        required: 'is required.'
+        exclusion: "is not an allowed option."
+        inclusion: "is not an allowed option."
+        domain: "must be a simple domain."
+        email: 'must be an email address.'
+        hex: "must be a hex color."
+        invalid: "is invalid."
+        phone: "must be a phone number."
+        time: "must be a point in time."
+        taken: "has already been taken."
+        url: 'must be a valid URL.'
+        same_as: "must match."
+        us_state_or_territory: "must be a US state or territory."
+        us_state: "must be a US state."
+        inexact_length: "must be %{count} characters long"
+        wrong_length: "must be %{min} to %{max} characters long"
+        too_short: "must be more than %{min} characters long"
+        too_long: "must be less than %{max} characters long"
+        not_a_number: "must be a number."
+        between: "must be a number from %{min} to %{max}."
+        greater_than_or_equal_to: "must be a number at least %{min}."
+        less_than_or_equal_to: "must be a number no more than %{max}."
+        greater_than: "must be a number greater than %{min}."
+        less_than: "must be a number less than %{max}."
+        

data/lib/semantic_attributes/predicates.rb

@@ -0,0 +1,170 @@
+# active record tie-ins
+module SemanticAttributes
+  module Predicates
+    def self.included(base)
+      base.class_eval do
+        extend ClassMethods
+        base.semantic_attributes = SemanticAttributes::Set.new
+        attribute_method_suffix '_valid?'
+        validate :validate_predicates
+      end
+    end
+
+    def semantic_attributes
+      self.class.semantic_attributes
+    end
+
+    # the validation hook that checks all predicates
+    def validate_predicates
+      semantic_attributes.each do |attribute|
+        applicable_predicates = attribute.predicates.select{|p| validate_predicate?(p)}
+
+        next if applicable_predicates.empty?
+
+        # skip validations on associations that aren't already loaded
+        # note: it's not worth skipping a has_one, since there's no way to distinguish
+        # between loaded and absent without a query.
+        if reflection = self.class.reflect_on_association(attribute.field.to_sym)
+          if reflection.collection?
+            next unless self.association(attribute.field).loaded?
+          elsif reflection.macro == :belongs_to and self[reflection.foreign_key]
+            next unless self.association(attribute.field).loaded?
+          end
+        end
+
+        value = self.send(attribute.field)
+        applicable_predicates.each do |predicate|
+          if value.blank?
+            # it's empty, so add an error or not but either way move along
+            self.errors.add(attribute.field, predicate.error) unless predicate.allow_empty?
+            next
+          end
+
+          unless predicate.validate(value, self)
+            self.errors.add(attribute.field, predicate.error)
+          end
+        end
+      end
+    end
+
+    protected
+    # Returns true if this attribute would pass validation during the next save.
+    # Intended to be called via attribute suffix, like:
+    #   User#login_valid?
+    def attribute_valid?(attr)
+      semantic_attributes[attr.to_sym].predicates.all? do |p|
+        !validate_predicate?(p) or (self.send(attr).blank? and p.allow_empty?) or p.validate(self.send(attr), self)
+      end
+    end
+
+    # Returns true if the given predicate (for a specific attribute) should be validated.
+    def validate_predicate?(predicate)
+      case predicate.validate_if
+        when Symbol
+        return false unless send(predicate.validate_if)
+
+        when Proc
+        return false unless predicate.validate_if.call(self)
+      end
+
+      case predicate.validate_on
+        when :create
+        return false unless new_record?
+
+        when :update
+        return false if new_record?
+      end
+
+      true
+    end
+
+    module ClassMethods
+      def semantic_attributes
+        @semantic_attributes ||= SemanticAttributes::Set.new
+      end
+
+      def semantic_attributes=(val)
+        @semantic_attributes = val || SemanticAttributes::Set.new
+      end
+ 
+      def inherited(klass)
+        klass.semantic_attributes = self.semantic_attributes.dup
+        super
+      end
+
+      # Provides sugary syntax for adding and querying predicates
+      #
+      # The syntax supports the following forms:
+      #   #{attribute}_is_#{predicate}(options = {})
+      #   #{attribute}_is_a_#{predicate}(options = {})
+      #   #{attribute}_is_an_#{predicate}(options = {})
+      #   #{attribute}_has_#{predicate}(options = {})
+      #   #{attribute}_has_a_#{predicate}(options = {})
+      #   #{attribute}_has_an_#{predicate}(options = {})
+      #
+      # You may also add required-ness into the declaration:
+      #   #{attribute}_is_a_required_#{predicate}(options = {})
+      #
+      # If you want to assign a predicate to multiple fields, you may replace the attribute component with the word 'fields', and pass a field list as the first argument, like this:
+      #   fields_are_#{predicate}(fields = [], options = {})
+      #
+      # Each form may also have a question mark at the end, to query whether the attribute has the predicate.
+      #
+      # In order to avoid clashing with other method_missing setups, this syntax is checked *last*, after all other method_missing metaprogramming attempts have failed.
+      def method_missing(name, *args)
+        begin
+          super
+        rescue NameError
+          if /^(.*)_(is|has|are)_(an?_)?(required_)?([^?]*)(\?)?$/.match(name.to_s)
+            options = args.last.is_a?(Hash) ? args.pop : {}
+            options[:or_empty] = false if !$4.nil?
+            fields = ($1 == 'fields') ? args.map(&:to_s) : [$1]
+
+            predicate = $5
+            if $6 == '?'
+              self.semantic_attributes[fields.first].has? predicate
+            else
+              args = [predicate]
+              args << options if options
+              fields.each do |field|
+                # TODO: create a less sugary method that may be used programmatically and takes care of defining the normalization method properly
+                define_normalization_method_for field
+                self.semantic_attributes[field].add *args
+              end
+            end
+          else
+            raise
+          end
+        end
+      end
+
+      # Provides a way to pre-validate a single value out of context of
+      # an entire record. This is helpful for validating parts of a form
+      # before it has been submitted.
+      #
+      # For values that are (in)valid only in context, such as the common
+      # :password_confirmation (which is only valid with a matching :password),
+      # additional values may be specified.
+      #
+      # WARNING: I still have not figured out what to do about differences in
+      # validation for new/existing records.
+      #
+      # Returns first error message if value is expected invalid.
+      #
+      # Example:
+      #   User.expected_error_for(:username, "bob")
+      #   => "has already been taken."
+      #   User.expected_error_for(:username, "bob2392")
+      #   => nil
+      #   User.expected_error_for(:password_confirmation, "mismatched", :password => "opensesame")
+      #   => "must be the same as password."
+      def expected_error_for(attribute, value, extra_values = {})
+        @record = self.new(extra_values)
+        semantic_attributes[attribute.to_sym].predicates.each do |predicate|
+          return predicate.error_message unless predicate.validate(value, @record)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/semantic_attributes/set.rb

@@ -0,0 +1,40 @@
+# a set of SemanticAttributes::Attribute objects, which themselves contain Predicates
+class SemanticAttributes::Set
+  include Enumerable
+
+  def initialize
+    @set = []
+  end
+
+  def add(semantic_attribute)
+    unless semantic_attribute.is_a? SemanticAttributes::Attribute
+      raise ArgumentError, 'Must pass a SemanticAttributes::Attribute object'
+    end
+    @set << semantic_attribute
+  end
+
+  # method for field lookups. creates the field if it doesn't exist.
+  def [](field)
+    field = field.to_sym
+    semantic_attribute = @set.find {|i| i.field == field}
+    self.add(semantic_attribute = SemanticAttributes::Attribute.new(field)) unless semantic_attribute
+    semantic_attribute
+  end
+
+  # method for field lookups which does *not* create the field if it doesn't exist
+  def include?(field)
+    field = field.to_sym
+    @set.find {|i| i.field == field} ? true : false
+  end
+
+  def each
+    @set.each do |i|
+      yield i
+    end
+  end
+
+  private
+  def initialize_copy(from)
+    @set = from.instance_variable_get('@set').clone
+  end
+end

data/lib/semantic_attributes/version.rb

@@ -0,0 +1,3 @@
+module SemanticAttributes
+  VERSION = "1.0.2"
+end

data/lib/semantic_attributes.rb

@@ -0,0 +1,37 @@
+I18n.load_path << File.dirname(__FILE__) + '/semantic_attributes/locale/en.yml'
+
+module SemanticAttributes; end
+
+require 'core_ext/class'
+require 'active_record/validation_recursion_control'
+require 'predicates'
+require 'predicates/base'
+require 'predicates/enumerated'
+require 'predicates/pattern'
+require 'predicates/aliased'
+require 'predicates/association'
+require 'predicates/blacklisted'
+require 'predicates/domain'
+require 'predicates/email'
+require 'predicates/hex_color'
+require 'predicates/length'
+require 'predicates/number'
+require 'predicates/phone_number'
+require 'predicates/required'
+require 'predicates/same_as'
+require 'predicates/size'
+require 'predicates/time'
+require 'predicates/unique'
+require 'predicates/url'
+require 'predicates/usa_state'
+require 'predicates/usa_zip_code'
+require 'predicates/aliased'
+require 'semantic_attributes/attribute'
+require 'semantic_attributes/attribute_formats'
+require 'semantic_attributes/predicates'
+require 'semantic_attributes/set'
+require 'semantic_attributes/version'
+
+ActiveRecord::Base.send(:include, SemanticAttributes::Predicates)
+ActiveRecord::Base.send(:include, SemanticAttributes::AttributeFormats)
+ActiveRecord::Base.send(:include, ActiveRecord::ValidationRecursionControl)

data/semantic_attributes.gemspec

@@ -0,0 +1,29 @@
+$:.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "semantic_attributes/version"
+
+Gem::Specification.new do |s|
+  s.name = 'semantic_attributes'
+  s.version = SemanticAttributes::VERSION
+  s.authors = ["Lance Ivy"]
+  s.email = 'lance@kickstarter.com'
+  s.platform = Gem::Platform::RUBY
+  s.homepage = %q{http://github.com/kickstarter/semantic-attributes}
+  s.require_paths = ["lib"]
+  s.summary = 'A validation library for ActiveRecord models.'
+  s.description = 'A validation library for ActiveRecord models that allows ' + 
+    'introspection (User.name_is_required?) and supports database' +
+    ' normalization (aka "form input cleaning").'
+
+#  s.add_dependency "activerecord", ">= 3.0.12"
+  s.add_dependency "rails", "~> 3.2.2"
+
+  s.add_development_dependency "bundler", ">= 1.0.0"
+  s.add_development_dependency "sqlite3"
+  s.add_development_dependency "rake", "0.8.7"
+  s.add_development_dependency "mocha", ">= 0.10.5"
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test/*`.split("\n")
+end

data/test/db/database.yml

@@ -0,0 +1,3 @@
+semantic_attributes_test:
+  adapter: sqlite3
+  database: ':memory:'

data/test/db/models.rb

@@ -0,0 +1,38 @@
+# A set of classes design to offer not only every association, but every pair of associations.
+# For example, there's a has_one paired with a normal belongs_to, and another has_one paired with a polymorphic belongs_to.
+# To use, mix the PluginTestModels module into the TestCase
+module PluginTestModels
+  def self.included(base)
+    base.set_fixture_class({
+      :addresses => PluginTestModels::Address,
+      :users => PluginTestModels::User,
+      :services => PluginTestModels::Service,
+      :subscriptions => PluginTestModels::Subscription,
+      :roles => PluginTestModels::Role
+    })
+  end
+
+  class Address < ActiveRecord::Base
+    belongs_to :addressable, :polymorphic => true
+  end
+
+  class User < ActiveRecord::Base
+    has_and_belongs_to_many :roles
+    has_one :subscription
+    has_one :address, :as => :addressable
+  end
+
+  class Service < ActiveRecord::Base
+    has_many :subscriptions
+    has_many :users, :through => :subscriptions
+  end
+
+  class Subscription < ActiveRecord::Base
+    belongs_to :service
+    belongs_to :user
+  end
+
+  class Role < ActiveRecord::Base
+    has_and_belongs_to_many :users
+  end
+end

data/test/db/schema.rb

@@ -0,0 +1,33 @@
+ActiveRecord::Schema.define(:version => 1) do
+
+  create_table :addresses, :force => true do |t|
+    t.column :name, :string
+    t.column :addressable_id, :integer
+    t.column :addressable_type, :string
+  end
+
+  create_table :users, :force => true do |t|
+    t.column :login, :string
+    t.column :first_name, :string
+    t.column :last_name, :string
+    t.column :cell, :string
+  end
+
+  create_table :roles_users, :force => true, :id => false do |t|
+    t.column :user_id, :integer
+    t.column :role_id, :integer
+  end
+
+  create_table :services, :force => true do |t|
+    t.column :name, :string
+  end
+
+  create_table :subscriptions, :force => true do |t|
+    t.column :service_id, :integer
+    t.column :user_id, :integer
+  end
+
+  create_table :roles, :force => true do |t|
+    t.column :name, :string
+  end
+end

data/test/fixtures/addresses.yml

@@ -0,0 +1,15 @@
+bobs_home:
+  id: 1
+  name: Home
+  addressable_id: 1
+  addressable_type: 'PluginTestModels::User'
+bobs_work:
+  id: 2
+  name: Work
+  addressable_id: 1
+  addressable_type: 'PluginTestModels::User'
+sues_home:
+  id: 3
+  name: Home
+  addressable_id: 2
+  addressable_type: 'PluginTestModels::User'

data/test/fixtures/roles.yml

@@ -0,0 +1,4 @@
+cook:
+  name: Cook
+gardener:
+  name: Gardener

data/test/fixtures/roles_users.yml

@@ -0,0 +1,6 @@
+bob_is_a_cook:
+  role_id: 1
+  user_id: 1
+sue_is_a_gardener:
+  role_id: 2
+  user_id: 2

data/test/fixtures/services.yml

@@ -0,0 +1,6 @@
+free:
+  id: 1
+  name: Free
+premium:
+  id: 2
+  name: Premium

data/test/fixtures/subscriptions.yml

@@ -0,0 +1,16 @@
+bob_is_free:
+  id: 1
+  service_id: 1
+  user_id: 1
+sue_is_premium:
+  id: 2
+  service_id: 2
+  user_id: 2
+george_is_free:
+  id: 3
+  service_id: 1
+  user_id: 3
+michael_is_free:
+  id: 4
+  service_id: 1
+  user_id: 4

data/test/fixtures/users.yml

@@ -0,0 +1,20 @@
+bob:
+  id: 1
+  login: bob
+  first_name: Bobby
+  last_name: Billiards
+sue:
+  id: 2
+  login: sue
+  first_name: Sue
+  last_name: Swagger
+george:
+  id: 3
+  login: george
+  first_name: George
+  last_name: Ginormous
+michael:
+  id: 4
+  login: michael
+  first_name: Michael
+  last_name: Mindful

data/test/test_helper.rb

@@ -0,0 +1,67 @@
+ENV["RAILS_ENV"] = "test"
+
+# load the support libraries
+require 'test/unit'
+require 'rubygems'
+require 'active_record'
+require 'active_record/fixtures'
+require 'active_support/time'
+
+# load the code-to-be-tested
+require 'semantic_attributes'
+
+Time.zone = 'UTC'
+
+# establish the database connection
+ActiveRecord::Base.configurations = YAML::load(IO.read(File.dirname(__FILE__) + '/db/database.yml'))
+ActiveRecord::Base.establish_connection('semantic_attributes_test')
+
+# capture the logging
+ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + "/test.log")
+
+# load the schema ... silently
+ActiveRecord::Migration.verbose = false
+load(File.dirname(__FILE__) + "/db/schema.rb")
+
+# load the ActiveRecord models
+require File.dirname(__FILE__) + '/db/models'
+
+# configure the TestCase settings
+class SemanticAttributes::TestCase < ActiveSupport::TestCase
+  include ActiveRecord::TestFixtures
+  include PluginTestModels
+
+  self.use_transactional_fixtures = true
+  self.use_instantiated_fixtures  = false
+  self.fixture_path = File.dirname(__FILE__) + '/fixtures/'
+
+  fixtures :all
+end
+
+class ActiveRecord::Base
+  # Aids the management of per-test semantics.
+  #
+  # Examples:
+  #
+  # User.stub_semantics_with(:email => :email)
+  # User.stub_semantics_with(:email => [:email, :unique])
+  # User.stub_semantics_with(:email => {:length => {:above => 5}})
+  # User.stub_semantics_with(:email => [:email, {:length => {:above => 5}}])
+  def self.stub_semantics_with(attr_predicates = {})
+    semantics = SemanticAttributes::Set.new
+    attr_predicates.each do |attr, predicates|
+      [predicates].flatten.each do |predicate|
+        case predicate
+          when String, Symbol
+          semantics[attr].add(predicate)
+          when Hash
+          semantics[attr].add(predicate.keys.first, predicate.values.first)
+          else
+          raise '???'
+        end
+      end
+    end
+
+    self.stubs(:semantic_attributes).returns(semantics)
+  end
+end