Add tests and documentation for allow_blank. Closes #10651 [blj]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8733 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

activerecord/lib/active_record/validations.rb

@@ -684,6 +684,8 @@ module ActiveRecord
       #
       # Configuration options:
       # * <tt>message</tt> - A custom error message (default is: "is invalid")
+      # * <tt>allow_nil</tt> - If set to true, skips this validation if the attribute is null (default is: false)
+      # * <tt>allow_blank</tt> - If set to true, skips this validation if the attribute is blank (default is: false)
       # * <tt>with</tt> - The regular expression used to validate the format with (note: must be supplied!)
       # * <tt>on</tt> Specifies when this validation is active (default is :save, other options :create, :update)
       # * <tt>if</tt> - Specifies a method, proc or string to call to determine if the validation should

activerecord/test/cases/validations_test.rb

@@ -489,6 +489,14 @@ class ValidationsTest < ActiveRecord::TestCase
     assert_raise(ArgumentError) { Topic.validates_format_of(:title, :content) }
   end
 
+  def test_validate_format_with_allow_blank
+    Topic.validates_format_of(:title, :with => /^Validation\smacros \w+!$/, :allow_blank=>true)
+    assert !Topic.create("title" => "Shouldn't be valid").valid?
+    assert Topic.create("title" => "").valid?
+    assert Topic.create("title" => nil).valid?
+    assert Topic.create("title" => "Validation macros rule!").valid?
+  end
+
   # testing ticket #3142
   def test_validate_format_numeric
     Topic.validates_format_of(:title, :content, :with => /^[1-9][0-9]*$/, :message => "is bad data")