durran-validatable 1.7.5

data/README.rdoc

@@ -0,0 +1,118 @@
+= Validatable
+
+Validatable is a library for adding validations.
+
+by Jay[http://jayfields.blogspot.com] Fields[http://jayfields.blogspot.com]
+
+== Download and Installation
+
+You can download Validatable from here[http://rubyforge.org/projects/validatable] or install it with the following command.
+
+ $ gem install validatable
+
+== License
+ 	
+You may use, copy and redistribute this library under the same terms as Ruby itself (see http://www.ruby-lang.org/en/LICENSE.txt).
+
+== Examples
+
+Validation of an entire hierarchy of objects with errors aggregated at the root object.
+
+	class Person
+	  include Validatable
+	  validates_presence_of :name
+	  attr_accessor :name
+	end
+
+	class PersonPresenter
+	  include Validatable
+	  include_validations_for :person
+	  attr_accessor :person
+  
+	  def initialize(person)
+	    @person = person
+	  end
+	end
+
+	presenter = PersonPresenter.new(Person.new)
+	presenter.valid? #=> false
+	presenter.errors.on(:name) #=> "can't be blank"
+
+Validations that turn off after X times of failed attempts.
+
+	class Person
+	  include Validatable
+	  validates_presence_of :name, :times => 1
+	  attr_accessor :name
+	end
+
+	person = Person.new
+	person.valid? #=> false
+	person.valid? #=> true
+
+Validations can be given levels. If a validation fails on a level the validations for subsequent levels will not be executed.
+
+	class Person
+	  include Validatable
+	  validates_presence_of :name, :level => 1, :message => "name message"
+	  validates_presence_of :address, :level => 2
+	  attr_accessor :name, :address
+	end
+
+	person = Person.new
+	person.valid? #=> false
+	person.errors.on(:name) #=> "name message"
+	person.errors.on(:address) #=> nil
+
+Validations can also be given groups. Groups can be used to validate an object when it can be valid in various states.  For example a mortgage application may be valid for saving (saving a partial application), but that same mortgage application would not be valid for underwriting. In our example a application can be saved as long as a Social Security Number is present; however, an application can not be underwritten unless the name attribute contains a value.
+
+  class MortgageApplication
+    include Validatable
+    validates_presence_of :ssn, :groups => [:saving, :underwriting]
+    validates_presence_of :name, :groups => :underwriting
+    attr_accessor :name, :ssn
+  end
+  
+  application = MortgageApplication.new
+  application.ssn = 377990118
+  application.valid_for_saving? #=> true
+  application.valid_for_underwriting? #=> false
+  
+As you can see, you can use an array if the validation needs to be part of various groups.  However, if the validation only applies to one group you can simply use a symbol for the group name.
+
+Similar to Rails, Validatable also supports conditional validation.
+
+	class Person
+	  include Validatable
+	  attr_accessor :name
+	  validates_format_of :name, :with => /.+/, :if => Proc.new { !name.nil? }
+	end
+	Person.new.valid? #=> true
+		
+Validatable also exposes an after_validate hook method.
+
+	class Person
+	  include Validatable
+	  validates_presence_of :name
+	  attr_accessor :name
+	end
+	
+	class ValidatesPresenceOf
+	  after_validate do |result, instance, attribute|
+			instance.errors.add("#{attribute} can't be blank") unless result
+		end
+	end
+
+	person = Person.new
+	person.valid? #=> false
+	person.errors.on(:name) #=> "name can't be blank"
+	
+The after_validate hook yields the result of the validation being run, 
+the instance the validation was run on, and the attribute that was validated
+
+In the above example the attribute "name" is appended to the message.
+
+See the tests for more examples
+
+== Contributors
+Rick Bradley, Anonymous Z, Jason Miller, Ali Aghareza, Xavier Shay, Dan Manges, Karthik Krishnan and Venkat, Clint Bishop, Chris Didyk, Yi Wen

data/Rakefile

@@ -0,0 +1,55 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "durran-validatable"
+    gem.summary = %Q{Validatable is a library for adding validations.}
+    gem.email = "durran@gmail.com"
+    gem.homepage = "http://github.com/durran/validatable"
+    gem.authors = ['Jay Fields', 'John Nunemaker', 'Durran Jordan']
+    gem.files = FileList['lib/**/*.rb', '[A-Z]*', 'test/**/*'].to_a
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "validatable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 7
+:patch: 5
+:major: 1

data/lib/child_validation.rb

@@ -0,0 +1,15 @@
+module Validatable
+  class ChildValidation #:nodoc:
+    attr_accessor :attribute, :map, :should_validate_proc
+    
+    def initialize(attribute, map, should_validate_proc)
+      @attribute = attribute
+      @map = map
+      @should_validate_proc = should_validate_proc
+    end
+    
+    def should_validate?(instance)
+      instance.instance_eval &should_validate_proc
+    end
+  end
+end

data/lib/errors.rb

@@ -0,0 +1,90 @@
+module Validatable
+  class Errors
+    extend Forwardable
+    include Enumerable
+
+    def_delegators :errors, :clear, :each, :each_pair, :empty?, :length, :size
+
+    # Returns true if the specified +attribute+ has errors associated with it.
+    #
+    #   class Company < ActiveRecord::Base
+    #     validates_presence_of :name, :address, :email
+    #     validates_length_of :name, :in => 5..30
+    #   end
+    #
+    #   company = Company.create(:address => '123 First St.')
+    #   company.errors.invalid?(:name)      # => true
+    #   company.errors.invalid?(:address)   # => false
+    def invalid?(attribute)
+      !@errors[attribute.to_sym].nil?
+    end
+
+    # call-seq: on(attribute)
+    # 
+    # * Returns nil, if no errors are associated with the specified +attribute+.
+    # * Returns the error message, if one error is associated with the specified +attribute+.
+    # * Returns an array of error messages, if more than one error is associated with the specified +attribute+.
+    def on(attribute)
+      return nil if errors[attribute.to_sym].nil?
+      errors[attribute.to_sym].size == 1 ? errors[attribute.to_sym].first : errors[attribute.to_sym]
+    end
+    
+    alias [] on
+
+    def add(attribute, message) #:nodoc:
+      errors[attribute.to_sym] = [] if errors[attribute.to_sym].nil?
+      errors[attribute.to_sym] << message
+    end
+
+    def merge!(errors) #:nodoc:
+      errors.each_pair{|k, v| add(k,v)}
+      self
+    end
+
+    # call-seq: replace(attribute)
+    # 
+    # * Replaces the errors value for the given +attribute+
+    def replace(attribute, value)
+      errors[attribute.to_sym] = value
+    end
+
+    # call-seq: raw(attribute)
+    # 
+    # * Returns an array of error messages associated with the specified +attribute+.
+    def raw(attribute)
+      errors[attribute.to_sym]
+    end
+    
+    def errors #:nodoc:
+      @errors ||= {}
+    end
+
+    def count #:nodoc:
+      errors.values.flatten.size
+    end
+
+    # call-seq: full_messages -> an_array_of_messages
+    # 
+    # Returns an array containing the full list of error messages.
+    def full_messages
+      full_messages = []
+
+      errors.each_key do |attribute|
+        errors[attribute].each do |msg|
+          next if msg.nil?
+
+          if attribute.to_s == "base"
+            full_messages << msg
+          else
+            full_messages << humanize(attribute.to_s) + " " + msg
+          end
+        end
+      end
+      full_messages
+    end
+    
+    def humanize(lower_case_and_underscored_word) #:nodoc:
+      lower_case_and_underscored_word.to_s.gsub(/_id$/, "").gsub(/_/, " ").capitalize
+    end
+  end
+end

data/lib/included_validation.rb

@@ -0,0 +1,9 @@
+module Validatable
+  class IncludedValidation #:nodoc:
+    attr_accessor :attribute
+    
+    def initialize(attribute)
+      @attribute = attribute
+    end
+  end
+end

data/lib/macros.rb

@@ -0,0 +1,306 @@
+module Validatable
+  module Macros
+    # call-seq: validates_each(*args)
+    # 
+    # Validates that the logic evaluates to true
+    # 
+    #   class Address
+    #     include Validatable
+    #     validates_each :zip_code, :logic => lambda { errors.add(:zip_code, "is not valid") if ZipCodeService.allows(zip_code) }
+    #   end
+    #
+    # The logic option is required.
+    #
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * level - The level at which the validation should occur
+    #     * logic - A block that executes to perform the validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    def validates_each(*args)
+      add_validations(args, ValidatesEach)
+    end
+    
+    # call-seq: validates_format_of(*args)
+    # 
+    # Validates whether the value of the specified attribute is of the 
+    # correct form by matching it against the regular expression provided.
+    # 
+    #   class Person
+    #     include Validatable    
+    #     validates_format_of :first_name, :with => /[ A-Za-z]/
+    #   end
+    # 
+    # A regular expression must be provided or else an exception will be raised.
+    # 
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * with - The regular expression used to validate the format
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_format_of(*args)
+      add_validations(args, ValidatesFormatOf)
+    end
+    
+    # call-seq: validates_length_of(*args)
+    # 
+    # Validates that the specified attribute matches the length restrictions supplied.
+    # 
+    #   class Person
+    #     include Validatable
+    #     validates_length_of :first_name, :maximum=>30
+    #     validates_length_of :last_name, :minimum=>30
+    #   end
+    # 
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * minimum - The minimum size of the attribute
+    #     * maximum - The maximum size of the attribute
+    #     * is - The size the attribute must be
+    #     * within - A range that the size of the attribute must fall within
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_length_of(*args)
+      add_validations(args, ValidatesLengthOf)
+    end
+
+    # call-seq: validates_numericality_of(*args)
+    # 
+    # Validates that the specified attribute is numeric.
+    # 
+    #   class Person
+    #     include Validatable
+    #     validates_numericality_of :age
+    #   end
+    # 
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    #     * only_integer - Whether the attribute must be an integer (default is false)
+    def validates_numericality_of(*args)
+      add_validations(args, ValidatesNumericalityOf)
+    end
+
+    # call-seq: validates_acceptance_of(*args)
+    #
+    # Encapsulates the pattern of wanting to validate the acceptance of a terms of service check box (or similar agreement). Example:
+    # 
+    #   class Person
+    #     include Validatable
+    #     validates_acceptance_of :terms_of_service
+    #     validates_acceptance_of :eula, :message => "must be abided"
+    #   end
+    #
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_acceptance_of(*args)
+      add_validations(args, ValidatesAcceptanceOf)
+    end
+
+    # call-seq: validates_confirmation_of(*args)
+    #
+    # Encapsulates the pattern of wanting to validate a password or email address field with a confirmation. Example:
+    # 
+    #   Class:
+    #     class PersonPresenter
+    #       include Validatable
+    #       validates_confirmation_of :user_name, :password
+    #       validates_confirmation_of :email_address, :message => "should match confirmation"
+    #     end
+    # 
+    #   View:
+    #     <%= password_field "person", "password" %>
+    #     <%= password_field "person", "password_confirmation" %>
+    #
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * case_sensitive - Whether or not to apply case-sensitivity on the comparison.  Defaults to true.
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_confirmation_of(*args)
+      add_validations(args, ValidatesConfirmationOf)
+    end
+  
+    # call-seq: validates_presence_of(*args)
+    # 
+    # Validates that the specified attributes are not nil or an empty string
+    # 
+    #   class Person
+    #     include Validatable
+    #     validates_presence_of :first_name
+    #   end
+    #
+    # The first_name attribute must be in the object and it cannot be nil or empty.
+    #
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_presence_of(*args)
+      add_validations(args, ValidatesPresenceOf)
+    end
+    
+    # call-seq: validates_true_for(*args)
+    # 
+    # Validates that the logic evaluates to true
+    # 
+    #   class Person
+    #     include Validatable
+    #     validates_true_for :first_name, :logic => lambda { first_name == 'Jamie' }
+    #   end
+    #
+    # The logic option is required.
+    #
+    # Configuration options:
+    # 
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    #     * logic - A block that executes to perform the validation
+    def validates_true_for(*args)
+      add_validations(args, ValidatesTrueFor)
+    end
+
+    # call-seq: validates_associated(*args)
+    #
+    # Checks the validity of an associated object or objects and adds a single
+    # error if validation fails.
+    #
+    #   class Person
+    #     include Validatable
+    #     attr_accessor :addresses
+    #     validates_associated :addresses
+    #   end
+    #
+    # Configuration options:
+    #
+    #     * after_validate - A block that executes following the run of a validation
+    #     * message - The message to add to the errors collection when the validation fails
+    #     * times - The number of times the validation applies
+    #     * level - The level at which the validation should occur
+    #     * if - A block that when executed must return true of the validation will not occur
+    #     * group - The group that this validation belongs to.  A validation can belong to multiple groups
+    def validates_associated(*args)
+      add_validations(args, ValidatesAssociated)
+    end
+
+    # call-seq: include_validations_from(attribute)
+    # 
+    # Includes all the validations that are defined on the attribute.
+    #   class Person
+    #     include Validatable
+    #     validates_presence_of :name
+    #   end
+    # 
+    #   class PersonPresenter
+    #     include Validatable
+    #     include_validataions_from :person
+    #     attr_accessor :person
+    #     def name
+    #       person.name
+    #     end
+    #
+    #     def initialize(person)
+    #       @person = person
+    #     end
+    #   end
+    #   
+    #   presenter = PersonPresenter.new(Person.new)
+    #   presenter.valid? #=> false
+    #   presenter.errors.on(:name) #=> "can't be blank"
+    #
+    # The name attribute whose validations should be added.
+    def include_validations_from(attribute_to_validate, options = {})
+      validations_to_include << IncludedValidation.new(attribute_to_validate)
+    end
+
+    # call-seq: include_errors_from(attribute_to_validate, options = {})
+    # 
+    # Validates the specified attributes.
+    #   class Person
+    #     include Validatable
+    #     validates_presence_of :name
+    #     attr_accessor :name
+    #   end
+    # 
+    #   class PersonPresenter
+    #     include Validatable
+    #     include_errors_from :person, :map => { :name => :namen }, :if => lambda { not person.nil? }
+    #     attr_accessor :person
+    #     
+    #     def initialize(person)
+    #       @person = person
+    #     end
+    #   end
+    #   
+    #   presenter = PersonPresenter.new(Person.new)
+    #   presenter.valid? #=> false
+    #   presenter.errors.on(:namen) #=> "can't be blank"
+    #
+    # The person attribute will be validated.  
+    # If person is invalid the errors will be added to the PersonPresenter errors collection.
+    #
+    # Configuration options:
+    # 
+    #     * map - A hash that maps attributes of the child to attributes of the parent.
+    #     * if - A block that when executed must return true of the validation will not occur.
+    def include_errors_from(attribute_to_validate, options = {})
+      children_to_validate << ChildValidation.new(attribute_to_validate, options[:map] || {}, options[:if] || lambda { true })
+    end
+    
+    def include_validations_for(attribute_to_validate, options = {}) #:nodoc:
+      puts "include_validations_for is deprecated; use include_errors_from instead"
+      children_to_validate << ChildValidation.new(attribute_to_validate, options[:map] || {}, options[:if] || lambda { true })
+    end
+    
+    # call-seq: before_validation(&block)
+    # 
+    # Is called before valid? or valid_for_*?
+    # 
+    #   class Person
+    #     include Validatable
+    #     before_validation do
+    #       self.name = "default name"
+    #     end
+    # 
+    #     attr_accessor :name
+    #   end
+    # 
+    def before_validation(&block)
+      before_validations << block
+    end
+  end
+end