Added find_or_initialize_by_X which works like find_or_create_by_X but doesn't save the newly instantiated record

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

activerecord/CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Added find_or_initialize_by_X which works like find_or_create_by_X but doesn't save the newly instantiated record. [Sam Stephenson]
+
 * Row locking. Provide a locking clause with the :lock finder option or true for the default "FOR UPDATE". Use the #lock! method to obtain a row lock on a single record (reloads the record with :lock => true). [Shugo Maeda]
     # Obtain an exclusive lock on person 1 so we can safely increment visits.
     Person.transaction do

activerecord/lib/active_record/base.rb

@@ -179,6 +179,12 @@ module ActiveRecord #:nodoc:
   #   # Now the 'Summer' tag does exist
   #   Tag.find_or_create_by_name("Summer") # equal to Tag.find_by_name("Summer")
   #
+  # Use the <tt>find_or_initialize_by_</tt> finder if you want to return a new record without saving it first. Example:
+  #
+  #   # No 'Winter' tag exists
+  #   winter = Tag.find_or_initialize_by_name("Winter")
+  #   winter.new_record? # true
+  #
   # == Saving arrays, hashes, and other non-mappable objects in text columns
   #
   # Active Record can serialize any object in text columns using YAML. To do so, you must specify this with a call to the class method +serialize+.
@@ -1159,13 +1165,14 @@ module ActiveRecord #:nodoc:
               else
                 send(deprecated_finder, conditions, *arguments[attribute_names.length..-1]) # deprecated API
             end
-          elsif match = /find_or_create_by_([_a-zA-Z]\w*)/.match(method_id.to_s)
+          elsif match = /find_or_(initialize|create)_by_([_a-zA-Z]\w*)/.match(method_id.to_s)
+            instantiator = determine_instantiator(match)
             attribute_names = extract_attribute_names_from_match(match)
             super unless all_attributes_exists?(attribute_names)
 
             options = { :conditions => construct_conditions_from_arguments(attribute_names, arguments) }
             set_readonly_option!(options)
-            find_initial(options) || create(construct_attributes_from_arguments(attribute_names, arguments))
+            find_initial(options) || send(instantiator, construct_attributes_from_arguments(attribute_names, arguments))
           else
             super
           end
@@ -1179,6 +1186,10 @@ module ActiveRecord #:nodoc:
           match.captures.first == 'all_by' ? :find_all : :find_first
         end
 
+        def determine_instantiator(match)
+          match.captures.first == 'initialize' ? :new : :create
+        end
+
         def extract_attribute_names_from_match(match)
           match.captures.last.split('_and_')
         end

activerecord/test/finder_test.rb

@@ -336,6 +336,7 @@ class FinderTest < Test::Unit::TestCase
     sig38 = Company.find_or_create_by_name("38signals")
     assert_equal number_of_companies + 1, Company.count
     assert_equal sig38, Company.find_or_create_by_name("38signals")
+    assert !sig38.new_record?
   end
 
   def test_find_or_create_from_two_attributes
@@ -343,6 +344,20 @@ class FinderTest < Test::Unit::TestCase
     another = Topic.find_or_create_by_title_and_author_name("Another topic","John")
     assert_equal number_of_topics + 1, Topic.count
     assert_equal another, Topic.find_or_create_by_title_and_author_name("Another topic", "John")
+    assert !another.new_record?
+  end
+  
+  def test_find_or_initialize_from_one_attribute
+    sig38 = Company.find_or_initialize_by_name("38signals")
+    assert_equal "38signals", sig38.name
+    assert sig38.new_record?
+  end
+  
+  def test_find_or_initialize_from_two_attributes
+    another = Topic.find_or_initialize_by_title_and_author_name("Another topic","John")
+    assert_equal "Another topic", another.title
+    assert_equal "John", another.author_name
+    assert another.new_record?
   end
 
   def test_find_with_bad_sql