formeze 1.9.1 → 2.0.0

data/README.md

@@ -1,5 +1,8 @@
-Formeze: A little library for handling form data/input
-======================================================
+formeze
+=======
+
+
+A little library for handling form data/input.
 
 
 Motivation
@@ -207,14 +210,93 @@ Custom scrub methods can be defined by adding a symbol/proc entry to the
 `Formeze.scrub_methods` hash.
 
 
+Custom validation
+-----------------
+
+You may need additional validation logic beyond what the field options
+described above provide, such as validating the format of a field without
+using a regular expression, validating that two fields are equal etc.
+This can be accomplished using the `validates` class method. Pass the
+name of the field to be validated, and a block/proc that encapsulates
+the validation logic. For example:
+
+```ruby
+class ExampleForm < Formeze::Form
+  field :email
+
+  validates :email, &EmailAddress.method(:valid?)
+end
+```
+
+If the block/proc takes no arguments then it will be evaluated in the
+scope of the form instance, which gives you access to the values of other
+fields (and methods defined on the form). For example:
+
+```ruby
+class ExampleForm < Formeze::Form
+  field :password
+  field :password_confirmation
+
+  validates :password_confirmation do
+    password_confirmation == password
+  end
+end
+```
+
+Specify the `when` option with a proc to peform the validation conditionally.
+Similar to the `defined_if` and `defined_unless` field options, the proc is
+evaluated in the scope of the form instance. For example:
+
+```ruby
+class ExampleForm < Formeze::Form
+  field :business_name, :defined_if => :business_account?
+  field :vat_number, :defined_if => :business_account?
+
+  validates :vat_number, :when => :business_account? do
+    # ...
+  end
+
+  def initialize(account)
+    @account = account
+  end
+
+  def business_account?
+    @account.business?
+  end
+end
+```
+
+Specify the `error` option with a symbol to control which error the validation
+generates. The I18n integration described below can be used to specify the
+error message used, both for errors that are explicitly specified using this
+option, and the default "invalid" error. For example:
+
+```ruby
+class ExampleForm < Formeze::Form
+  field :email
+  field :password
+  field :password_confirmation
+
+  validates :email, &EmailAddress.method(:valid?)
+
+  validates :password_confirmation, :error => :does_not_match do
+    password_confirmation == password
+  end
+end
+```
+
+The error for the email validation would use the `formeze.errors.invalid`
+I18n key, defaulting to "is invalid". The error message for the password
+confirmation validation would use the `formeze.errors.does_not_match` key.
+
+
 Rails usage
 -----------
 
 This is the basic pattern for using a formeze form in a Rails controller:
 
 ```ruby
-form = SomeForm.new
-form.parse(request.raw_post)
+form = SomeForm.parse(request.raw_post)
 
 if form.valid?
   # do something with form data
@@ -234,8 +316,7 @@ Using formeze with sinatra is similar, the only difference is that there is
 no raw_post method on the request object so the body has to be read directly:
 
 ```ruby
-form = SomeForm.new
-form.parse(request.body.read)
+form = SomeForm.parse(request.body.read)
 
 if form.valid?
   # do something with form data

data/Rakefile.rb

@@ -4,4 +4,5 @@ task :default => :spec
 
 Rake::TestTask.new(:spec) do |t|
   t.test_files = FileList['spec/*_spec.rb']
+  t.warning = true
 end

data/formeze.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = 'formeze'
-  s.version = '1.9.1'
+  s.version = '2.0.0'
   s.platform = Gem::Platform::RUBY
   s.authors = ['Tim Craft']
   s.email = ['mail@timcraft.com']

data/lib/formeze.rb

@@ -16,32 +16,36 @@ module Formeze
 
     def initialize(name, options = {})
       @name, @options = name, options
+
+      if options.has_key?(:word_limit)
+        Kernel.warn '[formeze] :word_limit option is deprecated, please use custom validation instead'
+      end
     end
 
     def validate(value, form)
       value = Formeze.scrub(value, @options[:scrub])
 
       if value !~ /\S/
-        yield error(:required, 'is required') if required?
+        form.add_error(self, error(:required, 'is required')) if required?
 
         form.send(:"#{name}=", blank_value? ? blank_value : value)
       else
-        yield error(:not_multiline, 'cannot contain newlines') if !multiline? && value.lines.count > 1
+        form.add_error(self, error(:not_multiline, 'cannot contain newlines')) if !multiline? && value.lines.count > 1
 
-        yield error(:too_long, 'is too long') if too_long?(value)
+        form.add_error(self, error(:too_long, 'is too long')) if too_long?(value)
 
-        yield error(:too_short, 'is too short') if too_short?(value)
+        form.add_error(self, error(:too_short, 'is too short')) if too_short?(value)
 
-        yield error(:no_match, 'is invalid') if no_match?(value)
+        form.add_error(self, error(:no_match, 'is invalid')) if no_match?(value)
 
-        yield error(:bad_value, 'is invalid') if values? && !values.include?(value)
+        form.add_error(self, error(:bad_value, 'is invalid')) if values? && !values.include?(value)
 
         form.send(:"#{name}=", value)
       end
     end
 
-    def error(i18n_key, default)
-      translate(i18n_key, :scope => [:formeze, :errors], :default => default)
+    def error(key, default)
+      Formeze.translate(key, :scope => [:formeze, :errors], :default => default)
     end
 
     def key
@@ -53,7 +57,7 @@ module Formeze
     end
 
     def label
-      @options.fetch(:label) { translate(name, :scope => [:formeze, :labels], :default => Label.new(name)) }
+      @options.fetch(:label) { Formeze.translate(name, :scope => [:formeze, :labels], :default => Label.new(name)) }
     end
 
     def required?
@@ -77,15 +81,7 @@ module Formeze
     end
 
     def too_many_characters?(value)
-      if @options.has_key?(:maxlength)
-        value.chars.count > @options.fetch(:maxlength)
-      elsif @options.has_key?(:char_limit)
-        Kernel.warn '[formeze] :char_limit option is deprecated, please use :maxlength instead'
-
-        value.chars.count > @options.fetch(:char_limit)
-      else
-        value.chars.count > 64
-      end
+      value.chars.count > @options.fetch(:maxlength) { 64 }
     end
 
     def too_many_words?(value)
@@ -127,12 +123,60 @@ module Formeze
     def defined_unless
       @options.fetch(:defined_unless)
     end
+  end
 
-    def translate(key, options)
-      if defined?(I18n)
-        I18n.translate(key, options)
-      else
-        options.fetch(:default)
+  class FieldSet
+    include Enumerable
+
+    def initialize
+      @fields, @index = [], {}
+    end
+
+    def each(&block)
+      @fields.each(&block)
+    end
+
+    def <<(field)
+      @fields << field
+
+      @index[field.name] = field
+    end
+
+    def [](field_name)
+      @index.fetch(field_name)
+    end
+  end
+
+  class Validation
+    def initialize(field, options, &block)
+      @field, @options, @block = field, options, block
+    end
+
+    def error_key
+      @options.fetch(:error) { :invalid }
+    end
+
+    def error_message
+      Formeze.translate(error_key, :scope => [:formeze, :errors], :default => 'is invalid')
+    end
+
+    def validates?(form)
+      @options.has_key?(:when) ? form.instance_eval(&@options[:when]) : true
+    end
+
+    def value?(form)
+      form.send(@field.name) =~ /\S/
+    end
+
+    def validate(form)
+      if validates?(form) && value?(form)
+        return_value = if @block.arity == 1
+          @block.call(form.send(@field.name))
+        else
+          form.instance_eval(&@block)
+        end
+
+        form.add_error(@field, error_message) unless return_value
       end
     end
   end
@@ -164,7 +208,7 @@ module Formeze
     include ArrayAttrAccessor
 
     def fields
-      @fields ||= []
+      @fields ||= FieldSet.new
     end
 
     def field(*args)
@@ -179,20 +223,12 @@ module Formeze
       end
     end
 
-    def checks
-      @checks ||= []
+    def validations
+      @validations ||= []
     end
 
-    def check(&block)
-      checks << block
-    end
-
-    def errors
-      @errors ||= []
-    end
-
-    def error(message)
-      errors << message
+    def validates(field_name, options = {}, &block)
+      validations << Validation.new(fields[field_name], options, &block)
     end
 
     def parse(encoded_form_data)
@@ -236,23 +272,33 @@ module Formeze
         end
 
         values.each do |value|
-          field.validate(value, self) do |error|
-            error!("#{field.label} #{error}", field.name)
-          end
+          field.validate(value, self)
         end
       end
 
       if defined?(Rails)
-        %w(utf8 authenticity_token).each { |field_key| form_data.delete(field_key) }
+        %w(utf8 authenticity_token).each do |key|
+          form_data.delete(key)
+        end
       end
 
-      raise KeyError unless form_data.empty?
+      unless form_data.empty?
+        raise KeyError, "unexpected form keys: #{form_data.keys.sort.join(', ')}"
+      end
 
-      self.class.checks.zip(self.class.errors) do |check, message|
-        instance_eval(&check) ? next : error!(message)
+      self.class.validations.each do |validation|
+        validation.validate(self)
       end
     end
 
+    def add_error(field, message)
+      error = ValidationError.new("#{field.label} #{message}")
+
+      errors << error
+
+      field_errors[field.name] << error
+    end
+
     def valid?
       errors.empty?
     end
@@ -273,13 +319,15 @@ module Formeze
       field_errors[field_name]
     end
 
-    def to_hash
+    def to_h
       self.class.fields.inject({}) do |hash, field|
         hash[field.name] = send(field.name)
         hash
       end
     end
 
+    alias_method :to_hash, :to_h
+
     private
 
     def field_defined?(field)
@@ -295,14 +343,6 @@ module Formeze
     def field_errors
       @field_errors ||= Hash.new { |h, k| h[k] = [] }
     end
-
-    def error!(message, field_name = nil)
-      error = ValidationError.new(message)
-
-      errors << error
-
-      field_errors[field_name] << error unless field_name.nil?
-    end
   end
 
   def self.scrub_methods
@@ -321,6 +361,10 @@ module Formeze
     end
   end
 
+  def self.translate(key, options)
+    defined?(I18n) ? I18n.translate(key, options) : options.fetch(:default)
+  end
+
   def self.setup(form)
     form.send :include, InstanceMethods
 

data/spec/formeze_spec.rb

@@ -38,8 +38,10 @@ describe 'FormWithField' do
       proc { @form.parse('title=foo&title=bar') }.must_raise(Formeze::ValueError)
     end
 
-    it 'raises an exception when there is an unexpected key' do
-      proc { @form.parse('title=Untitled&foo=bar') }.must_raise(Formeze::KeyError)
+    it 'raises an exception when the data contains unexpected keys' do
+      exception = proc { @form.parse('title=Untitled&foo=bar&baz=') }.must_raise(Formeze::KeyError)
+
+      exception.message.must_equal('unexpected form keys: baz, foo')
     end
   end
 
@@ -105,6 +107,12 @@ describe 'FormWithField after parsing valid input' do
     end
   end
 
+  describe 'to_h method' do
+    it 'returns a hash containing the field name and its value' do
+      @form.to_h.must_equal({:title => 'Untitled'})
+    end
+  end
+
   describe 'to_hash method' do
     it 'returns a hash containing the field name and its value' do
       @form.to_hash.must_equal({:title => 'Untitled'})
@@ -227,23 +235,6 @@ describe 'FormWithFieldThatCanHaveMultipleLines after parsing input containing n
   end
 end
 
-class FormWithCharacterLimitedField < Formeze::Form
-  field :title, :char_limit => 16
-end
-
-describe 'FormWithCharacterLimitedField after parsing input with too many characters' do
-  before do
-    @form = FormWithCharacterLimitedField.new
-    @form.parse('title=This+Title+Will+Be+Too+Long')
-  end
-
-  describe 'valid query method' do
-    it 'returns false' do
-      @form.valid?.must_equal(false)
-    end
-  end
-end
-
 class FormWithMaxLengthField < Formeze::Form
   field :title, :maxlength => 16
 end
@@ -509,16 +500,55 @@ describe 'FormWithHaltingCondition after parsing input with same_address set and
   end
 end
 
-class FormWithCustomValidation < Formeze::Form
+class FormWithOptionalKey < Formeze::Form
+  field :accept_terms, :values => %w(true), :key_required => false
+end
+
+describe 'FormWithOptionalKey after parsing input without the key' do
+  before do
+    @form = FormWithOptionalKey.new
+    @form.parse('')
+  end
+
+  describe 'valid query method' do
+    it 'returns true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+class FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues < Formeze::Form
+  field :size, :required => false, :values => %w(S M L XL)
+end
+
+describe 'FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues after parsing blank input' do
+  before do
+    @form = FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues.new
+    @form.parse('size=')
+  end
+
+  describe 'valid query method' do
+    it 'returns true' do
+      @form.valid?.must_equal(true)
+    end
+  end
+end
+
+module EmailAddress
+  def self.valid?(address)
+    address.include?('@')
+  end
+end
+
+class FormWithCustomEmailValidation < Formeze::Form
   field :email
 
-  check { email.include?(?@) }
-  error 'Email is invalid'
+  validates :email, &EmailAddress.method(:valid?)
 end
 
-describe 'FormWithCustomValidation after parsing invalid input' do
+describe 'FormWithCustomEmailValidation after parsing invalid input' do
   before do
-    @form = FormWithCustomValidation.new
+    @form = FormWithCustomEmailValidation.new
     @form.parse('email=alice')
   end
 
@@ -527,33 +557,85 @@ describe 'FormWithCustomValidation after parsing invalid input' do
       @form.valid?.must_equal(false)
     end
   end
+
+  describe 'errors method' do
+    it 'includes a generic error message for the named field' do
+      @form.errors.map(&:to_s).must_include('Email is invalid')
+    end
+  end
+
+  describe 'errors_on query method' do
+    it 'returns true when given the field name' do
+      @form.errors_on?(:email).must_equal(true)
+    end
+  end
 end
 
-class FormWithOptionalKey < Formeze::Form
-  field :accept_terms, :values => %w(true), :key_required => false
+describe 'FormWithCustomEmailValidation after parsing blank input' do
+  before do
+    @form = FormWithCustomEmailValidation.new
+    @form.parse('email=')
+  end
+
+  describe 'errors method' do
+    it 'will not include the custom validation error message' do
+      @form.errors.map(&:to_s).wont_include('Email is invalid')
+    end
+  end
 end
 
-describe 'FormWithOptionalKey after parsing input without the key' do
+class FormWithCustomPasswordConfirmationCheck < Formeze::Form
+  field :password
+  field :password_confirmation
+
+  validates :password_confirmation, :error => :does_not_match do
+    password_confirmation == password
+  end
+end
+
+describe 'FormWithCustomPasswordConfirmationCheck after parsing invalid input' do
   before do
-    @form = FormWithOptionalKey.new
-    @form.parse('')
+    @form = FormWithCustomPasswordConfirmationCheck.new
+    @form.parse('password=foo&password_confirmation=bar')
   end
 
   describe 'valid query method' do
-    it 'returns true' do
-      @form.valid?.must_equal(true)
+    it 'returns false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+
+  describe 'errors method' do
+    it 'includes a generic error message for the named field' do
+      @form.errors.map(&:to_s).must_include('Password confirmation is invalid')
+    end
+  end
+
+  describe 'errors_on query method' do
+    it 'returns true when given the field name' do
+      @form.errors_on?(:password_confirmation).must_equal(true)
     end
   end
 end
 
-class FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues < Formeze::Form
-  field :size, :required => false, :values => %w(S M L XL)
+class FormWithCustomMinimumSpendValidation < Formeze::Form
+  field :minimum_spend
+
+  field :fixed_discount, :required => false, :blank => nil
+
+  validates :minimum_spend, :when => :fixed_discount? do
+    minimum_spend.to_f > 0
+  end
+
+  def fixed_discount?
+    !fixed_discount.nil?
+  end
 end
 
-describe 'FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues after parsing blank input' do
+describe 'FormWithCustomMinimumSpendValidation after parsing valid input' do
   before do
-    @form = FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues.new
-    @form.parse('size=')
+    @form = FormWithCustomMinimumSpendValidation.new
+    @form.parse('minimum_spend=0.00&fixed_discount=')
   end
 
   describe 'valid query method' do
@@ -561,6 +643,43 @@ describe 'FormWithOptionalFieldThatCanOnlyHaveSpecifiedValues after parsing blan
       @form.valid?.must_equal(true)
     end
   end
+
+  describe 'errors method' do
+    it 'returns an empty array' do
+      @form.errors.must_be_empty
+    end
+  end
+
+  describe 'errors_on query method' do
+    it 'returns false when given the field name' do
+      @form.errors_on?(:minimum_spend).must_equal(false)
+    end
+  end
+end
+
+describe 'FormWithCustomMinimumSpendValidation after parsing invalid input' do
+  before do
+    @form = FormWithCustomMinimumSpendValidation.new
+    @form.parse('minimum_spend=0.00&fixed_discount=10%')
+  end
+
+  describe 'valid query method' do
+    it 'returns false' do
+      @form.valid?.must_equal(false)
+    end
+  end
+
+  describe 'errors method' do
+    it 'includes a generic error message for the named field' do
+      @form.errors.map(&:to_s).must_include('Minimum spend is invalid')
+    end
+  end
+
+  describe 'errors_on query method' do
+    it 'returns true when given the field name' do
+      @form.errors_on?(:minimum_spend).must_equal(true)
+    end
+  end
 end
 
 describe 'FormWithField on Rails' do
@@ -601,6 +720,22 @@ describe 'I18n integration' do
     form.errors.first.to_s.must_equal('Title cannot be blank')
   end
 
+  it 'provides i18n support for overriding the default custom validation error message' do
+    I18n.backend.store_translations :en, {:formeze => {:errors => {:invalid => 'is not valid'}}}
+
+    form = FormWithCustomEmailValidation.new
+    form.parse('email=alice')
+    form.errors.first.to_s.must_equal('Email is not valid')
+  end
+
+  it 'provides i18n support for specifying custom validation error messages' do
+    I18n.backend.store_translations :en, {:formeze => {:errors => {:does_not_match => 'does not match'}}}
+
+    form = FormWithCustomPasswordConfirmationCheck.new
+    form.parse('password=foo&password_confirmation=bar')
+    form.errors.first.to_s.must_equal('Password confirmation does not match')
+  end
+
   it 'provides i18n support for specifying field labels globally' do
     I18n.backend.store_translations :en, {:formeze => {:labels => {:title => 'TITLE'}}}
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: formeze
 version: !ruby/object:Gem::Version
-  version: 1.9.1
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-06 00:00:00.000000000 Z
+date: 2013-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: See description