auto_build 0.0.2 → 0.0.3

data/README.md

@@ -1,44 +1,104 @@
 AutoBuild
 =========
 
-Automatically initialize associations in your Rails models
+Automatically initialize associations in your Rails models.
 
 What
 ----
-AutoBuild gives your models the option to automatically initialize (build)
-associations. This is useful to skip the `build_association` calls in your controllers when working
-with nested fields (`fields_for`).
-
-Right now it only supports `has_one` associations.
+AutoBuild gives your models the option to automatically initialize (build) their
+associations. This is useful to skip the `build_association` or `record.association.build` calls in
+your models, controllers or views when working with nested fields.
 
 Installation
 ----
 Add `auto_build` to your Gemfile:
 
-    gem "autobuild"
+    gem "auto_build"
 
 And run `bundle install`.
 
 Usage
 ----
+
+### has_one associations
+
 Just call the `auto_build` method in your models:
 
      class User
        has_one :address
+       has_one :phone
+
        auto_build :address
      end
 
 With this in place, `address` will always be initialized, so you don't have to manually call
-`build_address` anywhere.
+`build_address` anywhere. If the `User` already has an `address` assigned this won't overwrite it.
+
+You can also do:
+
+    auto_build :address, :phone,
+
+To initialize several fields. One `after_initialize` callback will be created per association.
+
+### has_many associations
+
+You can automatically initialize a `has_many` association in the same way you initialized a `has_one`
+association:
+
+    class User
+      has_many :friends
+      auto_build :friends
+    end
+
+    # User.new.friends.count == 1
+
+The behavior will be the same, it will create a new `Friend` if none exists yet. If there's at least
+one `Friend` in the collection then nothing will be created.
+
+If you want to always append a new empty object at the end of the collection, you can pass the
+`:append => true` option:
+
+    class User
+      has_many :friends
+      auto_build :friends, :append => true
+    end
+
+    # count = some_user.friends.count
+    # user = User.find(some_user.id)
+    # user.friends.count == count + 1
+
+This will always create a new `Friend` instance regardless of the value of `friends`. It
+won't overwrite any existing values.
+
+Finally, if you want to always bulk-add a number of records, you can pass the `:count` option with
+the number of records you want to add:
+
+    class User
+      has_many :friends
+      auto_build :friends, :count => 5
+    end
+
+    # count = some_user.friends.count
+    # user = User.find(some_user.id)
+    # user.friends.count == count + 5
+
+This will always add 5 **extra** objects at the end of the collection. It won't overwrite any
+existing values.
+
+Notes
+----
+* The option `:append => true` is equivalent to `:count => 5`.
+* You **cannot** pass the `:append` and `:count` options to the same association.
+* None of the operations will overwrite existing objects.
+
 
-How
+How it works
 ----
-`auto_build` works by adding an `after_initialize` hook to your model that build the association if
-its current value is nil. It **will not** override existing values.
+`auto_build` works by adding an `after_initialize` callback **per association** to your model.
 
 Etc.
 ----
-Bugs, feature suggestions, etc. go to the [Issues](https://github.com/febuiles/auto_build/issues)
+To report bugs or suggest new features go to the [Issues](https://github.com/febuiles/auto_build/issues)
 tracker.
 
 This was written by [Federico](http://mheroin.com). You can follow me on Twitter

data/lib/auto_build/association.rb

@@ -0,0 +1,98 @@
+module AutoBuild
+  # Public: Represents an ActiveRecord association. Takes care
+  # of adding the hooks to the models.
+  class Association
+    # Public: Returns the model this association works on.
+    attr_reader :model
+    # Public: Returns the name of the association.
+    attr_reader :association_name
+    # Public: Returns the options that were passed in when created.
+    attr_reader :options
+    # Public: Returns the type (macro) of association (e.g. has_one,
+    # :has_many).
+    attr_reader:type
+
+    # Public: Creates a new Association.
+    #
+    # model - The ActiveRecord model (not the instance!).
+    # association_name - Name of the association you will want to
+    #                    add the callback to.
+    # options - The Hash options used to the number of
+    #           records (default = {}):
+    #           :count  - An Integer that specifies the number of
+    #                     records to create.
+    #           :append - Boolean, defines if you only want one record
+    #                     at the end of the array. False by default.
+    #                     Equivalent to :count => 1.
+    #
+    # `has_one` associations **don't** receive any options.
+    #
+    # For `has_many` associations, if the user doesn't pass any options,
+    # the default will be to add one new record if no other records
+    # exist yet.
+    #
+    # Examples
+    #
+    #   Association.new(User, :photo)
+    #
+    #   Association.new(User, :projects, :append => true)
+    #
+    #   Association.new(User, :projects, :count => 3)
+    #
+    #   Association.new(user, :photo)
+    #   # => Error! You want to pass the class, no the instance
+    #
+    # Raises AutoBuildError if you pass the :count and :append options
+    # at the same time.
+    def initialize(model, association_name, options={})
+      @model = model
+      @association_name = association_name
+      @options = options
+      @type = model.reflect_on_association(association_name).macro
+
+      validate_options
+    end
+
+    # Public: Adds the callback to the objects.
+    #
+    # It will choose the correct hook based on the value of `type`.
+    def add_hook
+      if type == :has_one
+        has_one_hook
+      else
+        has_many_hook
+      end
+    end
+
+    private
+
+    def has_one_hook
+      code = "self.#{association_name} ||= build_#{association_name}"
+
+      model.class_eval do
+        after_initialize do |record|
+          record.instance_eval(code)
+        end
+      end
+    end
+
+    def has_many_hook
+      name = association_name
+      record_options = options
+      code = "self.#{association_name}.build;"
+
+      model.class_eval do
+        after_initialize do |record|
+          count = number_of_records_to_create(name, record_options)
+          record.instance_eval(code * count)
+        end
+      end
+    end
+
+    def validate_options
+      if options[:count] && options[:append]
+        raise AutoBuildError.new("You can't specify :count and :append at the same time")
+      end
+    end
+  end
+end

data/lib/auto_build/builder.rb

@@ -6,35 +6,90 @@ module AutoBuild
     end
 
     module ClassMethods
-      # Public: This method allows you to auto initialize `has_one` associations
+      # Public: This method allows you to auto initialize associations
       # in your models. After calling it you don't need to call
-      # `build_association` in your controllers or views. Useful for models
-      # that accept nested attributes for associations. It **does not** ovewrite
-      # associations with existing values.
+      # `build_association` or `association.build` in your controllers
+      # or views. Useful for models that accept nested attributes for
+      # associations. It **does not** overwrite associations with
+      # existing values.
       #
       # An `after_initialize` hook will be created for each one of
       # the associations.
       #
-      # associations - A symbol or array with the associations you want to build
+      # Signature
+      #
+      #   auto_build(<field>, <field>, <field>)
+      #   auto_build(<field>, <options>)
+      #
+      # field   - A Symbol with the name of the association you want
+      #           initialize
+      # options - A Hash with the options to initialize the
+      #           associations. See AutoBuilder::Association#initialize
+      #           for the options.
       #
       # Examples
       #
       #     class User
       #       has_one :address
-      #       has_one :phone
-      #       auto_build :address, :phone
+      #       has_many :pictures
+      #       has_many :projects
       #     end
       #
-      def auto_build(*associations)
-        associations = [associations] unless associations.kind_of?(Array)
+      #     auto_build :address, :pictures
+      #     # => Builds a record for each association if none is present
+      #
+      #     auto_build :projects, :count => 3
+      #     # => Builds 3 projects each time you initialize a User
+      #
+      #     auto_build :pictures, :append => true
+      #     # => Builds an extra Picture each time you initialize a User
+      def auto_build(*attr_names)
+        options = attr_names.extract_options!
+        names = attr_names
 
-        associations.each do |assoc|
-          after_initialize do |record|
-            record.instance_eval("self.#{assoc} ||= build_#{assoc}")
-          end
+        names.map do |name|
+          Association.new(self, name, options).add_hook
         end
       end
     end
+
+    private
+
+    # Private: Calculates the number of new records to create in a
+    # `has_many` association.
+    #
+    # name    - A Symbol with the name of the association.
+    # options - The Hash options for the number of records to create.
+    #           See AutoBuilder::Association#initialize for more
+    #           details.
+    #
+    # Examples
+    #
+    #   User.projects.size
+    #   # => 1
+    #
+    #   number_of_records_to_create(:projects)
+    #   # => 0
+    #
+    #   number_of_records_to_create(:projects, :append => true)
+    #   # => 1
+    #
+    #   number_of_records_to_create(:projects, :count => 4)
+    #   # => 4 (User.projects.size == 5)
+    #
+    # Returns the number of records to create.
+    def number_of_records_to_create(name, options={})
+      current = self.send(name).size
+      default_count = current == 0 ? 1 : 0
+
+      if options[:append]
+        1
+      elsif options[:count]
+        options[:count]
+      else
+        default_count
+      end
+    end
   end
 end
 ActiveRecord::Base.send :include, AutoBuild::Builder

data/lib/auto_build/version.rb

@@ -1,3 +1,3 @@
 module AutoBuild
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/auto_build.rb

@@ -1,4 +1,9 @@
 require 'auto_build/builder'
+require 'auto_build/association'
+require 'auto_build/has_one_hook'
+require 'auto_build/version'
 
 module AutoBuild
+  class AutoBuildError < StandardError; end
 end
+

data/test/auto_build_test.rb

@@ -26,4 +26,25 @@ class AutoBuildTest < ActiveSupport::TestCase
     assert @user.address
     assert @user.picture
   end
+
+  test "has_many association" do
+    assert @user.projects.first
+  end
+
+  test "has_many with :count" do
+    assert_equal 3, @user.nicknames.length
+  end
+
+  test "has_many with existing values" do
+    @user.save
+    assert_equal 1, User.last.projects.size
+  end
+
+  test "has_many with :count and :append raises error"  do
+    assert_raise AutoBuild::AutoBuildError do
+      @user.class_eval do
+        auto_build :nicknames, :count => 3, :append => true
+      end
+    end
+  end
 end

data/test/dummy/app/models/nickname.rb

@@ -0,0 +1,3 @@
+class Nickname < ActiveRecord::Base
+  belongs_to :user
+end

data/test/dummy/app/models/project.rb

@@ -0,0 +1,2 @@
+class Project < ActiveRecord::Base
+end

data/test/dummy/app/models/user.rb

@@ -3,5 +3,10 @@ class User < ActiveRecord::Base
   has_one :phone
   has_one :picture
 
+  has_many :projects
+  has_many :nicknames
+
   auto_build :address, :picture
+  auto_build :projects
+  auto_build :nicknames, :count => 3
 end

data/test/dummy/db/migrate/20111213003425_create_projects.rb

@@ -0,0 +1,10 @@
+class CreateProjects < ActiveRecord::Migration
+  def change
+    create_table :projects do |t|
+      t.string :title
+      t.integer :user_id
+
+      t.timestamps
+    end
+  end
+end

data/test/dummy/db/migrate/20111213033025_create_nicknames.rb

@@ -0,0 +1,10 @@
+class CreateNicknames < ActiveRecord::Migration
+  def change
+    create_table :nicknames do |t|
+      t.string :nick
+      t.integer :user_id
+
+      t.timestamps
+    end
+  end
+end

data/test/dummy/db/schema.rb

@@ -11,7 +11,7 @@
 #
 # It's strongly recommended to check this file into your version control system.
 
-ActiveRecord::Schema.define(:version => 20111212001258) do
+ActiveRecord::Schema.define(:version => 20111213033025) do
 
   create_table "addresses", :force => true do |t|
     t.string   "street"
@@ -21,6 +21,13 @@ ActiveRecord::Schema.define(:version => 20111212001258) do
     t.datetime "updated_at"
   end
 
+  create_table "nicknames", :force => true do |t|
+    t.string   "nick"
+    t.integer  "user_id"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
   create_table "phones", :force => true do |t|
     t.string   "number"
     t.integer  "user_id"
@@ -35,6 +42,13 @@ ActiveRecord::Schema.define(:version => 20111212001258) do
     t.datetime "updated_at"
   end
 
+  create_table "projects", :force => true do |t|
+    t.string   "title"
+    t.integer  "user_id"
+    t.datetime "created_at"
+    t.datetime "updated_at"
+  end
+
   create_table "users", :force => true do |t|
     t.string   "name"
     t.datetime "created_at"