sbf-dm-validations 1.3.0.beta

data/README.rdoc

@@ -0,0 +1,122 @@
+This is a DataMapper plugin that provides validations for DataMapper model classes.
+
+== Setup
+DataMapper validation capabilities are automatically available for DataMapper resources when you require dm-validations' in your application. There is no need to manually include anything, every DataMapper::Resource will be able to handle validations once this gem got required.
+
+== Specifying Model Validations
+
+There are two primary ways to implement validations for your models
+
+1) Placing validation methods with properties as params in your class
+
+  require 'dm-core'
+  require 'dm-validations'
+
+  class ProgrammingLanguage
+    include DataMapper::Resource
+    property :name, String
+    validates_presence_of :name
+  end
+
+2) Using auto-validations, please see DataMapper::Validation::AutoValidations. 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 DataMapper::Resource
+    property :name, String, :required => true
+  end
+
+See data_mapper/validation/macros.rb for to learn about the complete collection of validation rules available.
+
+== Validating
+
+DataMapper validations, when included, alter the default save/create/update process for a model.  Unless you specify a context the resource must be valid in the :default context before saving.
+
+You may manually validate 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 your validators find errors in your model, they will populate the DataMapper::Validation::ViolationSet object that is available through each of your models via calls to your model's errors method.
+
+For example:
+
+  my_account = Account.new(:name => "Jose")
+  if my_account.save
+    # my_account is valid and has been saved
+  else
+    my_account.errors.each do |e|
+      puts e
+    end
+  end
+
+See DataMapper::Validation::ViolationSet for all you can do with your model's
+errors method.
+
+== Contextual Validation
+
+DataMapper Validation also provide a means of grouping your validations into
+contexts. This enables you to run different sets of validations when you
+need it. For instance, the same model may not only behave differently
+when initially saved or saved on update, but also require special validation sets
+for publishing, exporting, importing and so on.
+
+Again, using our example for pure Ruby class validations:
+
+  class ProgrammingLanguage
+
+    include DataMapper::Resource
+
+    property :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 ::DataMapper::Resource
+
+    property :id,           Serial
+    property :name,         String
+
+    property :agreed_title, String
+    property :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,4 @@
+require 'rubygems'
+require 'rake'
+
+FileList['tasks/**/*.rake'].each { |task| import task }

data/dm-validations.gemspec

@@ -0,0 +1,20 @@
+require File.expand_path('../lib/data_mapper/validation/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors = ['Guy van den Berg', 'Emmanuel Gomez']
+  gem.email = ['emmanuel.gomez@gmail.com']
+  gem.summary = 'Library for performing validations on DataMapper resources and plain Ruby objects'
+  gem.description = 'This is a DataMapper plugin that provides validations for DataMapper model classes.'
+  gem.homepage = 'https://datamapper.org'
+  gem.license = 'Nonstandard'
+
+  gem.files = `git ls-files`.split("\n")
+  gem.extra_rdoc_files = %w(LICENSE README.rdoc)
+
+  gem.name = 'sbf-dm-validations'
+  gem.require_paths = ['lib']
+  gem.version = DataMapper::Validation::VERSION
+  gem.required_ruby_version = '>= 2.7.8'
+
+  gem.add_runtime_dependency('sbf-dm-core', '~> 1.3.0.beta')
+end

data/lib/data_mapper/core.rb

@@ -0,0 +1 @@
+require 'dm-core'

data/lib/data_mapper/support/assertions.rb

@@ -0,0 +1 @@
+require 'dm-core/support/assertions'

data/lib/data_mapper/support/equalizer.rb

@@ -0,0 +1 @@
+require 'dm-core/support/equalizer'

data/lib/data_mapper/support/ordered_set.rb

@@ -0,0 +1,2 @@
+# temporary shim until I restructure dm-core
+require "dm-core/support/ordered_set"

data/lib/data_mapper/validation/backward.rb

@@ -0,0 +1,205 @@
+module DataMapper
+  module Validation
+
+    # Alias for validate(:default)
+    #
+    # @api public
+    def valid_for_default?
+      # warn "#{self.class}#valid_for_default? is deprecated and will be removed in a future version (#{caller[0]})"
+      valid?(:default)
+    end
+
+    module ClassMethods
+      extend Deprecate
+
+      # deprecate :validators, :validation_rules
+
+      # This is a widely used API, wait a little before issuing warnings
+      def validators
+        validation_rules
+      end
+
+    end
+
+    class ViolationSet
+      extend Deprecate
+
+      deprecate :clear!, :clear
+      deprecate :errors, :violations
+
+      def self.default_error_messages=(error_messages)
+        MessageTransformer::Default.error_messages = error_messages
+      end
+
+      def self.default_error_message(violation_type, attribute_name, *violation_data)
+        MessageTransformer::Default.error_message(violation_type, attribute_name, *violation_data)
+      end
+    end
+
+    class ContextualRuleSet
+      extend Deprecate
+
+      deprecate :contexts,  :rule_sets
+      deprecate :clear!,    :clear
+
+      def execute(context_name, resource)
+        # warn "#{self.class}#execute is deprecated. Use #{self.class}#validate instead."
+        context(context_name).execute(resource)
+      end
+
+      # Given a new context create an instance method of
+      # valid_for_<context>? which simply calls validate(context)
+      # if it does not already exist
+      #
+      # @api private
+      def self.create_context_instance_methods(model, context)
+        name = "valid_for_#{context}?"
+        present = model.respond_to?(:resource_method_defined) ? model.resource_method_defined?(name) : model.instance_methods.include?(name)
+        unless present
+          model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            def #{name}                   # def valid_for_signup?
+              # warn "\#{self.class}##{name} is deprecated. Use #valid?(context_name) instead (\#{caller[0]})"
+              valid?(:#{context})         #   valid?(:signup)
+            end                           # end
+          RUBY
+        end
+      end
+
+    end
+
+    class Rule
+      extend Deprecate
+
+      deprecate :field_name, :attribute_name
+
+      def humanized_field_name
+        # warn "#{self.class}#humanized_field_name is deprecated and will be removed in a future version (#{caller[0]})"
+        DataMapper::Inflector.humanize(attribute_name)
+      end
+
+      # Call the validator. "call" is used so the operation is BoundMethod
+      # and Block compatible. This must be implemented in all concrete
+      # classes.
+      #
+      # @param [Object] resource
+      #   The resource that the validator must be called against.
+      #
+      # @return [Boolean]
+      #   true if valid, otherwise false.
+      #
+      def call(resource)
+        # warn "#{self.class}#call is deprecated and will be removed in a future version (#{caller[0]})"
+        return true if valid?(resource)
+
+        error_message = self.custom_message ||
+          MessageTransformer::Default.error_message(
+            violation_type(resource),
+            attribute_name,
+            *violation_values(resource))
+
+        add_error(resource, error_message, attribute_name)
+
+        false
+      end
+
+      class Block
+        def call(resource)
+          # warn "#{self.class}#call is deprecated and will be removed in a future version (#{caller[0]})"
+          result, error_message = resource.instance_eval(&self.block)
+          add_error(resource, error_message, attribute_name) unless result
+          result
+        end
+      end
+
+      class Method
+        def call(resource)
+          # warn "#{self.class}#call is deprecated and will be removed in a future version (#{caller[0]})"
+          result, error_message = resource.__send__(method)
+          add_error(resource, error_message, attribute_name) unless result
+          result
+        end
+      end
+
+    end
+
+    class RuleSet
+      extend Deprecate
+
+      # This is present to provide a backwards-compatible codepath to
+      # ContextualRuleSet#execute
+      def execute(resource)
+        rules = rules_for_resource(resource)
+        rules.map { |rule| rule.call(resource) }.all?
+      end
+    end
+
+    class Violation
+      # TODO: Extract the correct custom message for a Rule's context
+      #   (in ContextualRuleSet#add). That change will break this interface.
+      def [](context_name)
+        # warn "Accessing custom messages by context name will be removed in a future version (#{caller[0]})"
+        @custom_message[context_name]
+      end
+    end
+
+    module Macros
+      extend Deprecate
+
+      deprecate :validates_absent,        :validates_absence_of
+      deprecate :validates_format,        :validates_format_of
+      deprecate :validates_present,       :validates_presence_of
+      deprecate :validates_length,        :validates_length_of
+      deprecate :validates_is_accepted,   :validates_acceptance_of
+      deprecate :validates_is_confirmed,  :validates_confirmation_of
+      deprecate :validates_is_number,     :validates_numericality_of
+      deprecate :validates_is_primitive,  :validates_primitive_type_of
+      deprecate :validates_is_unique,     :validates_uniqueness_of
+
+      def validates_numericality_of(*attribute_names)
+        # warn "'Numericality' is not a word in the English language, please use validates_numericalness_of (#{caller[0]})"
+        options = attribute_names.last.kind_of?(Hash) ? attribute_names.pop : {}
+        validation_rules.add(Rule::Numericalness, attribute_names, options)
+      end
+    end
+
+    module Inferred
+      extend Deprecate
+
+      # TODO: why are there 3 entry points to this ivar?
+      # #disable_auto_validations, #disabled_auto_validations?, #auto_validations_disabled?
+      # def disable_auto_validations
+      #   !infer_validations?
+      # end
+
+      # Checks whether auto validations are currently
+      # disabled (see +disable_auto_validations+ method
+      # that takes a block)
+      #
+      # @return [TrueClass, FalseClass]
+      #   true if auto validation is currently disabled
+      #
+      # @api semipublic
+      # def disabled_auto_validations?
+      #   !infer_validations?
+      # end
+
+      # deprecate :auto_validations_disabled?,  :infer_validations?
+      # deprecate :without_auto_validations,    :without_inferred_validations
+
+    end # module Inferred
+
+    AutoValidations      = Inferred
+    ValidationErrors     = ViolationSet
+    ContextualValidators = ContextualRuleSet
+
+  end # module Validation
+
+  # Previously used similarly to Violation (I believe)
+  class ValidationError < StandardError; end
+
+  # Previous top-level namespace (1.0-1.1)
+  Validations = Validation
+  # Very old constant name (0.9?)
+  Validate    = Validation
+
+end # module DataMapper

data/lib/data_mapper/validation/context.rb

@@ -0,0 +1,57 @@
+# -*- encoding: utf-8 -*-
+
+module DataMapper
+  module Validation
+
+    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 Validation
+end # module DataMapper

data/lib/data_mapper/validation/contextual_rule_set.rb

@@ -0,0 +1,210 @@
+# -*- encoding: utf-8 -*-
+
+require 'forwardable'
+require 'data_mapper/validation/exceptions'
+require 'data_mapper/validation/context'
+require 'data_mapper/validation/rule_set'
+
+module DataMapper
+  module Validation
+
+    class ContextualRuleSet
+      extend Forwardable
+      include Enumerable
+
+      # 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
+
+      # Whether to optimize the execution of validators for this model's resources
+      #
+      # @api public
+      attr_reader :optimize
+
+      def_delegators :rule_sets, :each, :empty?
+
+      # Clear all named context rule sets
+      #
+      # @api public
+      def_delegators :rule_sets, :clear
+
+      def initialize(model = nil)
+        @model     = model
+        @rule_sets = Hash.new { |h, context_name| h[context_name] = RuleSet.new }
+      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[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 [DataMapper::Validation::Rule] rule_class
+      #    Rule class, example: DataMapper::Validation::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
+      #   the context in which the new rule should be run
+      # @option [Boolean] :allow_nil
+      #   whether or not the new rule should allow nil values
+      # @option [Boolean] :message
+      #   the error message the new rule will provide on validation failure
+      #
+      # @return [ContextualRuleSet]
+      #   This method is a command, thus returns the receiver
+      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| context(context).concat(rules) }
+        end
+
+        # TODO: remove this shortcut, then eliminate the @model ivar entirely
+        context_names.each do |context|
+          ContextualRuleSet.create_context_instance_methods(@model, context) if @model
+        end
+
+        self
+      end
+
+      # Assimilate all rules contained in +other+ into the receiver
+      #
+      # @param [ContextualRuleSet] other
+      #   the ContextualRuleSet whose rules are to be assimilated
+      #
+      # @return [ContextualRuleSet]
+      #   +self+, the receiver
+      def concat(other)
+        other.rule_sets.each do |context_name, rule_set|
+          context(context_name).concat(rule_set)
+        end
+        self
+      end
+
+      def optimize=(new_value)
+        @optimize = new_value
+        rule_sets.each { |rule_set| rule_set.optimize = self.optimize }
+        new_value
+      end
+
+      # Returns the current validation context on the stack if valid for this model,
+      # nil if no RuleSets are defined for the model (and no context names are on
+      # the validation stack), or :default if the current context is invalid for
+      # this model or no contexts have been defined for this model 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: simplify the semantics of #current_context, #validate
+      def current_context
+        context = Validation::Context.current
+        valid_context?(context) ? context : :default
+      end
+
+      # Test if the context is valid for the model
+      #
+      # @param [Symbol] context
+      #   the context to test
+      #
+      # @return [Boolean]
+      #   true if the context is valid for the model
+      #
+      # @api private
+      def valid_context?(context_name)
+        !context_name.nil? &&
+          (rule_sets.empty? || rule_sets.include?(context_name))
+      end
+
+      # Assert that the given context is valid for this model
+      #
+      # @param [Symbol] context
+      #   the context to test
+      #
+      # @raise [InvalidContextError]
+      #   raised if the context is not valid for this model
+      #
+      # @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_names = [
+          options.delete(:context),
+          options.delete(:group),
+          options.delete(:when),
+          options.delete(:on)
+        ].compact.first
+
+        Array(context_names || :default)
+      end
+
+    end # class ContextualRuleSet
+
+  end # module Validation
+end # module DataMapper

data/lib/data_mapper/validation/exceptions.rb

@@ -0,0 +1,7 @@
+module DataMapper
+  module Validation
+
+    class InvalidContextError < StandardError; end
+
+  end
+end