aequitas 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm use @aequitas --create

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in aequitas.gemspec
+gemspec
+
+gem 'dm-core', '~>1.3.0.beta', git: 'https://github.com/datamapper/dm-core'

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2007 Guy van den Berg
+Copyright (c) 2011 DataMapper development team
+
+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.rdoc

@@ -0,0 +1,125 @@
+This module provides validations for any Ruby class.
+
+== Specifying Validations
+
+There are two primary ways to implement validations
+
+1) Placing validation methods with properties as params in your class
+
+  require 'aequitas'
+
+  class ProgrammingLanguage
+    include Aequitas
+
+    attr_accessor :name
+
+    validates_presence_of :name
+  end
+
+2) (TODO) Using inferred validations on Virtus attributes, please see Aequitas::Inferred.
+Note that not all validations that are provided via validation methods,
+are also available as autovalidation options. If they are available,
+they're functionally equivalent though.
+
+  class ProgrammingLanguage
+    include Virtus
+    include Aequitas
+
+    attribute :name, String, :required => true
+  end
+
+See Aequitas::Macros to learn about the complete collection of validation rules available.
+
+== Validating
+
+Aequitas validations may be manually evaluated against a resource using the
+`#valid?` method, which will return true if the resource is valid,
+and false if it is invalid.
+
+== Working with Validation Errors
+
+If an instance fails one or more validation rules, Aequitas::Violation instances
+will populate the Aequitas::ViolationSet object that is available through
+the #errors method.
+
+For example:
+
+  my_account = Account.new(:name => "Jose")
+  if my_account.valid?
+    # my_account is valid and has been saved
+  else
+    my_account.errors.each do |e|
+      puts e
+    end
+  end
+
+See Aequitas::ViolationSet for all you can do with the #errors method.
+
+== Contextual Validation
+
+Aequitas also provide a means of grouping your validations into
+contexts. This enables you to run different sets of validations when you
+need it. For example, an instance may require separate validation rules
+depending on its state: publishing, exporting, importing and so on.
+
+Again, using our example for pure Ruby class validations:
+
+  class ProgrammingLanguage
+    include Virtus
+    include Aequitas
+
+    attribute :name, String
+
+    def ensure_allows_manual_memory_management
+      # ...
+    end
+
+    def ensure_allows_optional_parentheses
+      # ...
+    end
+
+    validates_presence_of :name
+    validates_with_method :ensure_allows_optional_parentheses,     :when => [:implementing_a_dsl]
+    validates_with_method :ensure_allows_manual_memory_management, :when => [:doing_system_programming]
+  end
+
+ProgrammingLanguage instance now use #valid? method with one of two context symbols:
+
+  @ruby.valid?(:implementing_a_dsl)       # => true
+  @ruby.valid?(:doing_system_programming) # => false
+
+  @c.valid?(:implementing_a_dsl)       # => false
+  @c.valid?(:doing_system_programming) # => true
+
+Each context causes different set of validations to be triggered. If you don't
+specify a context using :when, :on or :group options (they are all aliases and do
+the same thing), default context name is :default. When you do model.valid? (without
+specifying context explicitly), again, :default context is used. One validation
+can be used in two, three or five contexts if you like:
+
+  class Book
+    include Virtus
+    include Aequitas
+
+    attribute :id,           Serial
+    attribute :name,         String
+
+    attribute :agreed_title, String
+    attribute :finished_toc, Boolean
+
+    # used in all contexts, including default
+    validates_presence_of :name,         :when => [:default, :sending_to_print]
+    validates_presence_of :agreed_title, :when => [:sending_to_print]
+
+    validates_with_block :toc, :when => [:sending_to_print] do
+      if self.finished_toc
+        [true]
+      else
+        [false, "TOC must be finalized before you send a book to print"]
+      end
+    end
+  end
+
+In the example above, name is validated for presence in both :default context and
+:sending_to_print context, while TOC related block validation and title presence validation
+only take place in :sending_to_print context.

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  gem 'jeweler', '~> 1.6.4'
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name        = 'aequitas'
+    gem.summary     = 'Library for performing validations on Ruby objects'
+    gem.description = gem.summary
+    gem.email       = 'emmanuel.gomez@gmail.com'
+    gem.homepage    = 'http://github.com/emmanuel/%s' % gem.name
+    gem.authors     = [ 'Emmanuel Gomez' ]
+    gem.has_rdoc    = 'yard'
+
+    gem.rubyforge_project = 'datamapper'
+  end
+
+  Jeweler::GemcutterTasks.new
+
+  FileList['tasks/**/*.rake'].each { |task| import task }
+rescue LoadError
+  puts 'Jeweler (or a dependency) not available. Install it with: gem install jeweler -v 1.6.4'
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/aequitas.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "aequitas/version"
+
+Gem::Specification.new do |s|
+  s.name        = "aequitas"
+  s.version     = Aequitas::VERSION
+  s.authors     = ["Emmanuel Gomez"]
+  s.email       = ["emmanuel.gomez@gmail.com"]
+  s.homepage    = "https://github.com/emmanuel/aequitas"
+  s.summary     = %q{Library for performing validations on Ruby objects.}
+  s.description = %q{Library for validating Ruby objects with rich metadata support.}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency("minitest", ["~> 2.8"])
+end

data/lib/aequitas.rb

@@ -0,0 +1,80 @@
+# -*- encoding: utf-8 -*-
+
+require 'aequitas/version'
+
+require 'aequitas/class_methods'
+require 'aequitas/violation_set'
+
+module Aequitas
+
+  def self.included(base)
+    super
+    base.extend ClassMethods
+  end
+
+  # Check if a resource is valid in a given context
+  #
+  # @api public
+  def valid?(context_name = default_validation_context)
+    validate(context_name).errors.empty?
+  end
+
+  # Command a resource to populate its ViolationSet with any violations of
+  # its validation Rules in +context_name+
+  #
+  # @api public
+  def validate(context_name = default_validation_context)
+    # TODO: errors.replace(validation_violations(context_name))
+    errors.clear
+    validation_violations(context_name).each { |v| errors.add(v) }
+
+    self
+  end
+
+  # Get a list of violations for the receiver *without* mutating it
+  # 
+  # @api private
+  def validation_violations(context_name = default_validation_context)
+    validation_rules.validate(self, context_name)
+  end
+
+  # @return [ViolationSet]
+  #   the collection of current validation errors for this resource
+  #
+  # @api public
+  def errors
+    @errors ||= ViolationSet.new(self)
+  end
+
+  # The default validation context for this Resource.
+  # This Resource's default context can be overridden by implementing
+  # #default_validation_context
+  # 
+  # @return [Symbol]
+  #   the current validation context from the context stack
+  #   (if valid for this model), or :default
+  # 
+  # @api public
+  def default_validation_context
+    validation_rules.current_context
+  end
+
+  # @api private
+  def validation_rules
+    self.class.validation_rules
+  end
+
+  # Retrieve the value of the given property name for the purpose of validation.
+  # Default implementation is to send the attribute name arg to the receiver
+  # and use the resulting value as the attribute value for validation
+  # 
+  # @param [Symbol] attribute_name
+  #   the name of the attribute for which to retrieve
+  #   the attribute value for validation.
+  # 
+  # @api public
+  def validation_attribute_value(attribute_name)
+    __send__(attribute_name) if respond_to?(attribute_name, true)
+  end
+
+end # module Aequitas

data/lib/aequitas/class_methods.rb

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+
+require 'aequitas/contextual_rule_set'
+require 'aequitas/macros'
+
+module Aequitas
+  module ClassMethods
+    include Macros
+
+    # Return the ContextualRuleSet for this model
+    #
+    # @api public
+    def validation_rules
+      @validation_rules ||= ContextualRuleSet.new
+    end
+
+  private
+
+    # @api private
+    def inherited(base)
+      super
+      base.validation_rules.concat(validation_rules)
+    end
+
+  end # module ClassMethods
+end # module Aequitas

data/lib/aequitas/context.rb

@@ -0,0 +1,53 @@
+# -*- encoding: utf-8 -*-
+
+module Aequitas
+  module Context
+    # Module with validation context functionality.
+    #
+    # Contexts are implemented using a thread-local array-based stack.
+
+
+    # Execute a block of code within a specific validation context
+    # 
+    # @param [Symbol] context
+    #   the context to execute the block of code within
+    # 
+    # @api semipublic
+    def self.in_context(context)
+      stack << context
+      return_value = yield
+    ensure
+      stack.pop
+      return_value
+    end
+
+    # Get the current validation context or nil (if no context is on the stack).
+    # 
+    # @return [Symbol, NilClass]
+    #   The current validation context (for the current thread),
+    #   or nil if no current context is on the stack
+    def self.current
+      stack.last
+    end
+
+    # Are there any contexts on the stack?
+    # 
+    # @return [Boolean]
+    #   true/false whether there are any contexts on the context stack
+    # 
+    # @api semipublic
+    def self.any?(&block)
+      stack.any?(&block)
+    end
+
+    # The (thread-local) validation context stack
+    # This allows object graphs to be saved within potentially nested contexts
+    # without having to pass the validation context throughout
+    # 
+    # @api private
+    def self.stack
+      Thread.current[:dm_validations_context_stack] ||= []
+    end
+
+  end # module Context
+end # module Aequitas

data/lib/aequitas/contextual_rule_set.rb

@@ -0,0 +1,221 @@
+# -*- encoding: utf-8 -*-
+
+require 'forwardable'
+require 'aequitas/support/equalizable'
+require 'aequitas/exceptions'
+require 'aequitas/context'
+require 'aequitas/rule_set'
+
+module Aequitas
+  class ContextualRuleSet
+    extend Equalizable
+    extend Forwardable
+    include Enumerable
+
+    equalize_on :rule_sets
+
+    # MessageTransformer to use for transforming Violations on Resources
+    # instantiated from the model to which this ContextualRuleSet is bound
+    # 
+    # @api public
+    # attr_accessor :transformer
+
+    # @api private
+    attr_reader :rule_sets
+
+    def_delegators :rule_sets, :each, :empty?
+
+    # Clear all named context rule sets
+    #
+    # @api public
+    def_delegators :rule_sets, :clear
+
+    def initialize
+      @rule_sets = Hash.new
+      define_context(:default)
+    end
+
+    def define_context(context_name)
+      rule_sets.fetch(context_name) do |context_name|
+        rule_sets[context_name] = RuleSet.new
+      end
+
+      self
+    end
+
+    # Delegate #validate to RuleSet
+    # 
+    # @api public
+    def validate(resource, context_name)
+      context(context_name).validate(resource)
+    end
+
+    # Return the RuleSet for a given context name
+    #
+    # @param [String] name
+    #   Context name for which to return a RuleSet
+    # @return [RuleSet]
+    #   RuleSet for the given context
+    # 
+    # @api public
+    def context(context_name)
+      rule_sets.fetch(context_name)
+    end
+
+    # Retrieve Rules applicable to a given attribute name
+    # 
+    # @param [Symbol] attribute_name
+    #   name of the attribute for which to retrieve applicable Rules
+    # 
+    # @return [Array]
+    #   list of Rules applicable to +attribute_name+
+    def [](attribute_name)
+      context(:default).fetch(attribute_name, [])
+    end
+
+    # Create a new rule of the given class for each name in +attribute_names+
+    # and add the rules to the RuleSet(s) indicated
+    # 
+    # @param [Aequitas::Rule] rule_class
+    #    Rule class, example: Aequitas::Rule::Presence
+    #
+    # @param [Array<Symbol>] attribute_names
+    #    Attribute names given to validation macro, example:
+    #    [:first_name, :last_name] in validates_presence_of :first_name, :last_name
+    # 
+    # @param [Hash] options
+    #    Options supplied to validation macro, example:
+    #    {:context=>:default, :maximum=>50, :allow_nil=>true, :message=>nil}
+    # 
+    # @option [Symbol] :context, :group, :when, :on
+    #   the context in which the new rule should be run
+    # 
+    # @return [self]
+    def add(rule_class, attribute_names, options = {}, &block)
+      context_names = extract_context_names(options)
+
+      attribute_names.each do |attribute_name|
+        rules = rule_class.rules_for(attribute_name, options, &block)
+
+        context_names.each { |context| add_rules_to_context(context, rules) }
+      end
+
+      self
+    end
+
+    # Assimilate all rules contained in +other+ into the receiver
+    # 
+    # @param [ContextualRuleSet] other
+    #   the ContextualRuleSet whose rules are to be assimilated
+    # 
+    # @return [self]
+    def concat(other)
+      other.rule_sets.each do |context_name, rule_set|
+        add_rules_to_context(context_name, rules)
+      end
+
+      self
+    end
+
+    # Define a context and append rules to it
+    # 
+    # @param [Symbol] context_name
+    #   name of the context to define and append rules to
+    # @param [RuleSet, Array] rules
+    #   Rules to append to +context_name+
+    # 
+    # @return [self]
+    def add_rules_to_context(context_name, rules)
+      define_context(context_name)
+      context(context_name).concat(rules)
+
+      self
+    end
+
+    # Returns the current validation context on the stack if valid for this contextual rule set,
+    #   nil if no RuleSets are defined (and no context names are on the validation context stack),
+    #   or :default if the current context is invalid for this rule set or
+    #     if no contexts have been defined for this contextual rule set and
+    #     no context name is on the stack.
+    #
+    # @return [Symbol]
+    #   the current validation context from the stack (if valid for this model),
+    #   nil if no context name is on the stack and no contexts are defined for
+    #   this model, or :default if the context on the stack is invalid for
+    #   this model or no context is on the stack and this model has at least
+    #   one validation context
+    # 
+    # @api private
+    # 
+    # TODO: this logic behind this method is too complicated.
+    #   simplify the semantics of #current_context, #validate
+    def current_context
+      context = Aequitas::Context.current
+      valid_context?(context) ? context : :default
+    end
+
+    # Test if the validation context name is valid for this contextual rule set.
+    #   A validation context name is valid if not nil and either:
+    #     1) no rule sets are defined for this contextual rule set
+    #   OR
+    #     2) there is a rule set defined for the given context name
+    #
+    # @param [Symbol] context
+    #   the context to test
+    #
+    # @return [Boolean]
+    #   true if the context is valid
+    #
+    # @api private
+    def valid_context?(context_name)
+      !context_name.nil? && context_defined?(context_name)
+    end
+
+    def context_defined?(context_name)
+      rule_sets.include?(context_name)
+    end
+
+    # Assert that the given validation context name
+    #   is valid for this contextual rule set
+    #
+    # @param [Symbol] context
+    #   the context to test
+    #
+    # @raise [InvalidContextError]
+    #   raised if the context is not valid for this contextual rule set
+    #
+    # @api private
+    # 
+    # TODO: is this method actually needed?
+    def assert_valid_context(context_name)
+      unless valid_context?(context_name)
+        actual   = context_name.inspect
+        expected = rule_sets.keys.inspect
+        raise InvalidContextError, "#{actual} is an invalid context, known contexts are #{expected}"
+      end
+    end
+
+  private
+
+    # Allow :context to be aliased to :group, :when & :on
+    # 
+    # @param [Hash] options
+    #   the options from which +context_names+ is to be extracted
+    # 
+    # @return [Array(Symbol)]
+    #   the context name(s) from +options+
+    # 
+    # @api private
+    def extract_context_names(options)
+      context_name = [
+        options.delete(:context),
+        options.delete(:group),
+        options.delete(:when),
+        options.delete(:on)
+      ].compact.first
+
+      Array(context_name || :default)
+    end
+
+  end # class ContextualRuleSet
+end # module Aequitas