planter 0.0.2 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe6195656eb33a7e774e6f5fb37e6f1dbcf6d7be33230c97605f291201d04de0
-  data.tar.gz: 68e04cc88dde75734fd06b69e0fd783f8f1849cb9d7f6e73fd33c18814cb1c61
+  metadata.gz: 61c2952a2b44b89c48245554cd6be4b19598891aa958b3f2f0dd3e3d2548a079
+  data.tar.gz: 91e099c652ce4bfb0bf87320f9efa3d1e0e0826ae031e17e967563beb8561f19
 SHA512:
-  metadata.gz: dbcea200bc37aa0d691cc001a918bcafea73a6c37754f83dea3f56867c4cb0773f474d276477c71081c03a5cc83d592b5ff511e745005e3bb17919436943b33a
-  data.tar.gz: 26f4beb0e5613aedbb6308bcad145a5cd39c20f328fbfa6fb7db0f6bb588128c6c031c014ef00a61d519f246e89eea9e14b05d4126a990fca7235349a9615c9f
+  metadata.gz: d70a187f4064ab1081a5a4b3df180f4ced5436601151029fca74b985cc0658e0422b56f338693b08a885a5dfc7d241357ef86144373825d8553117c3e7f6f30e
+  data.tar.gz: 923979e971e3cbc573a9eaffbc39481d8fc8a4930894de1ea8d8f4ef79c3f6d7bbaba0ab111d0099ee67298b336373a0836802126c5d5bba4c237eb41ab0c5d8

data/README.md

@@ -1,18 +1,23 @@
 # Planter
+[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fevanthegrayt%2Fplanter%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/evanthegrayt/planter/goto?ref=master)
+[![Gem Version](https://badge.fury.io/rb/planter.svg)](https://badge.fury.io/rb/planter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 > Pre-release version! Anything is subject to change in the near future!
 
 Seeds for Rails applications can get complicated fast, and Rails doesn't provide
 much for assisting with this process. This plugin seeks to rectify that by
-providing easy ways to seed specific tables by hooking into the existing `rails
-db:seed` task.
+providing easy ways to seed specific tables.
 
 Features include:
 
 - Seed tables from CSV files, an array of hashes, or custom methods.
-- Seed specific tables with `rails db:seed TABLES=users,addresses`.
+- Call specific seeders with `rails planter:seed SEEDERS=users,addresses`.
 - Control the number of records being created.
 - Seed associations.
 
+You can view the documentation [here](https://evanthegrayt.github.io/planter/).
+
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -35,30 +40,69 @@ $ gem install planter
 ## Usage
 Let's assume you'd like to seed your `users` table.
 
-To get started, simply add the following to your `db/seeds.rb` file. Note that
-the `config.tables` should be an array of the tables to seed. They should be in
-the correct order to successfully seed the tables when considering associations.
+To get started, run `rails generate planter:initializer`, which will create
+`config/initializers/planter.rb` with the following contents.
 
 ```ruby
 require 'planter'
 
 Planter.configure do |config|
-  config.tables = %i[ users ]
+  ##
+  # The list of seeders. These files are stored in the
+  # config.seeders_directory, which can be changed below. When a new
+  # seeder is generated, it will be appended to the bottom of this
+  # list. If the order is incorrect, you'll need to adjust the it.
+  # Just be sure to keep the ending bracket on its own line, or the
+  # generator won't know where to put new elements.
+  config.seeders = %i[
+  ]
+
+  ##
+  # The directory where the seeder files are kept.
+  # config.seeders_directory = 'db/seeds'
+
+  ##
+  # The directory where CSVs are kept.
+  # config.csv_files_directory = 'db/seed_files'
 end
+```
+
+By default, a `planter:seed` task is provided for seeding your application. This
+allows you to use `db:seed` for other purposes. If you want Planter to hook
+into the existing `db:seed` task, simply add the following to `db/seeds.rb`.
 
+```ruby
 Planter.seed
 ```
 
-Then, create a directory called `db/seeds`, and create a file called
-`db/seeds/users_seeder.rb`. In that file, create the following class. Note the
-name of the seeder is the name of the table, plus `Seeder`, and it inherits from
-`Planter::Seeder`.
+To create a users seeder, run `rails generate planter:seeder users`. Usually,
+seeders seed a specific table, so it's recommended to name your seeders after
+the table. If you don't, you'll need to manually specify a few things. More on
+that later. This will create a file named `db/seeds/users_seeder.rb` (the
+directory will be created if it doesn't exist) with the following contents.
 
 ```ruby
 class UsersSeeder < Planter::Seeder
+  # TODO: Choose a seeding_method. For example:
+  # seeding_method :csv
+
+  # For now, we overload the seed method so no exception will be raised.
+  def seed
+  end
 end
 ```
 
+This also adds `users` to the `config.seeders` array in our initializer. A few
+things to note.
+
+- The seeder will always be appended at the end of the array. If this is not the
+correct order, you'll need to adjust the array manually.
+- When adjusting the array, always keep the closing bracket on its own line, or
+the generator won't know where to put the new seeders.
+
+If you want to generate a seeder for every table currently in your database, run
+`rails generate planter:seeder ALL`.
+
 You then need to choose a seeding method, of which there are currently three.
 
 ### Seeding from CSV
@@ -66,7 +110,7 @@ To seed from CSV, you simply need to add the following to your seeder class.
 
 ```ruby
 class UsersSeeder < Planter::Seeder
-  seeding_method :standard_csv
+  seeding_method :csv
 end
 ```
 
@@ -80,16 +124,28 @@ test1@example.com,test1
 test2@example.com,test2
 ```
 
-If the CSV files are not located in the project, you can specify a `:csv_file`
-option. Note that the value must be a full path.
+If the CSV file is named differently than the seeder, you can specify the
+`:csv_name` option. Note that the value should not include the file extension.
 
 ```ruby
 class UsersSeeder < Planter::Seeder
-  seeding_method :standard_csv, csv_file: '/home/me/users.csv'
+  seeding_method :csv, csv_name: :people
 end
 ```
 
-Running `rails db:seed` will now seed your `users` table.
+`ERB` can be used in the CSV files if you name it with `.erb` at the end of the
+file name. For example, `users.csv.erb`. Note that lines starting with `<%` and
+ending with `%>` will not be considered rows, so you can use `ERB` rows to set
+values. For example:
+
+```csv.erb
+email,login_attempts
+<% count = 1 %>
+test2@example.com,<%= count += 1 %>
+test2@example.com,<%= count += 1 %>
+```
+
+Running `rails planter:seed` will now seed your `users` table.
 
 ## Seeding from a data array
 If you need dynamic seeds, you can add something similar to the following to
@@ -97,7 +153,7 @@ your seeder class. In this example, we'll use
 [faker](https://github.com/faker-ruby/faker).
 
 ```ruby
-require 'faker' # You should really just require this in `db/seeds.rb`.
+require 'faker' # You could just require this in `db/seeds.rb`.
 
 class UsersSeeder < Planter::Seeder
   seeding_method :data_array, number_of_records: 10
@@ -117,7 +173,7 @@ ten elements to create ten records. It's also worth noting that setting an
 instance variable called `@data` from an `initialize` method would also work, as
 the `Planter::Seeder` parent class automatically provides `attr_reader :data`.
 
-Running `rails db:seed` should now seed your `users` table.
+Running `rails planter:seed` should now seed your `users` table.
 
 You can also seed children records for every existing record of a parent model.
 For example, to seed an address for every user, you'd need to create an
@@ -142,10 +198,8 @@ end
 
 Note that specifying `number_of_records` in this instance will create that many
 records *for each record of the parent model*. You can also specify the
-association if it's different from the table name, using the `assocation:`
-option. Currently, associations are assumed to be as `has_many`, so the
-association is plural by default. Any help with making this more heuristically
-complete would be welcome.
+association if it's different from the table name, using the `:assocation`
+option.
 
 ### Custom seeds
 To write your own custom seeds, just overload the `seed` method and do whatever
@@ -154,7 +208,7 @@ you need to do.
 ```ruby
 class UsersSeeder < Planter::Seeder
   USERS = {
-    'test1@example.com' => { username: 'John Smith' }
+    'test1@example.com' => { username: 'John Smith' },
     'test2@example.com' => { username: 'Jane Smith' }
   }
 
@@ -164,26 +218,6 @@ class UsersSeeder < Planter::Seeder
 end
 ```
 
-## Customization
-You can change the directories of both the seeder files and the csv files. In
-your `configure` block in `db/seeds.rb`, you can add the following. Note that,
-in both instances, the path should be relative to `Rails.root`.
-
-```ruby
-require 'planter'
-
-Planter.configure do |config|
-  config.seeders_directory = 'db/seeder_classes'
-  config.csv_files_directory = 'db/csvs'
-  config.tables = %i[
-    users
-    addresses
-  ]
-end
-
-Planter.seed
-```
-
 ## License
 The gem is available as open source under the terms of the [MIT
 License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -11,7 +11,7 @@ end
 
 RDoc::Task.new do |rdoc|
   rdoc.main = 'README.md'
-  rdoc.rdoc_dir = 'doc'
+  rdoc.rdoc_dir = 'docs'
   rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
 end
 

data/lib/generators/planter/initializer_generator.rb

@@ -0,0 +1,33 @@
+module Planter
+  module Generators
+    class InitializerGenerator < Rails::Generators::Base
+      desc 'Genrates an initializer for Planter at config/initializers/planter.rb'
+
+      def create_initializer_file
+        create_file 'config/initializers/planter.rb', <<~EOF
+          require 'planter'
+
+          Planter.configure do |config|
+            ##
+            # The list of seeders. These files are stored in the
+            # config.seeders_directory, which can be changed below. When a new
+            # seeder is generated, it will be appended to the bottom of this
+            # list. If the order is incorrect, you'll need to adjust the it.
+            # Just be sure to keep the ending bracket on its own line, or the
+            # generator won't know where to put new elements.
+            config.seeders = %i[
+            ]
+
+            ##
+            # The directory where the seeder files are kept.
+            # config.seeders_directory = 'db/seeds'
+
+            ##
+            # The directory where CSVs are kept.
+            # config.csv_files_directory = 'db/seed_files'
+          end
+        EOF
+      end
+    end
+  end
+end

data/lib/generators/planter/seeder_generator.rb

@@ -0,0 +1,40 @@
+module Planter
+  module Generators
+    class SeederGenerator < Rails::Generators::Base
+      argument :seeder, required: true
+
+      desc "This generator creates a seeder file at #{::Planter.config.seeders_directory}"
+
+      def generate_seeders
+        seeder == 'ALL' ? tables.each { |t| generate(t) } : generate(seeder)
+      end
+
+      private
+
+      def generate(seeder)
+        empty_directory ::Planter.config.seeders_directory
+
+        create_file "#{::Planter.config.seeders_directory}/#{seeder}_seeder.rb", <<~EOF
+          class #{seeder.camelize}Seeder < Planter::Seeder
+            # TODO: Choose a seeding_method. For example:
+            # seeding_method :csv
+
+            # For now, we overload the seed method so no exception will be raised.
+            def seed
+            end
+          end
+        EOF
+
+        inject_into_file 'config/initializers/planter.rb',
+          "    #{seeder}\n",
+          before: /^\s*\]\s*$/
+      end
+
+      def tables
+        @tables ||= ActiveRecord::Base.connection.tables.reject do |table|
+          %w[ar_internal_metadata schema_migrations].include?(table)
+        end
+      end
+    end
+  end
+end

data/lib/planter.rb

@@ -1,74 +1,28 @@
 # frozen_string_literal: true
 
 require 'csv'
+require 'erb'
 require 'planter/version'
 require 'planter/railtie'
 require 'planter/config'
 require 'planter/seeder'
 
 ##
-# Class that seeders should inherit from. Seeder files should be in +db/seeds+,
-# and named +TABLE_seeder.rb+, where +TABLE+ is the name of the table being
-# seeded (I.E. +users_seeder.rb+). The seeder's class name should be the same
-# as the file name, but camelized. So, +UsersSeeder+. The directory where the
-# seeder files are located can be changed via an initializer.
+# The main module for the plugin. It nicely wraps the +Planter::Config+ class
+# so that you can customize the plugin via an initializer or in the
+# +db/seeds.rb+ file. This is how you'll specify your list of seeders to use,
+# along with customizing the +seeders_directory+ and +csv_files_directory+.
 #
-# The most basic way to seed is to have a CSV file with the same name as the
-# table in +db/seed_files/+. So, +users.csv+. This CSV should have the table's
-# column names as header. To seed using this method, your class should look
-# like the following. Note that +:csv_file+ is not required; it defaults to the
-# table name with a +csv+ file extension. The directory where the seed files
-# are kept can be changed via an initializer.
-#   # db/seeds/users_seeder.rb
-#   require 'planter'
-#   class UsersSeeder < Planter::Seeder
-#     seeding_method :standard_csv, csv_file: '/home/me/users.csv'
+#   Planter.configure do |config|
+#     config.seeders = %i[users]
+#     config.seeders_directory = 'db/seeds'
+#     config.csv_files_directory = 'db/seed_files'
 #   end
 #
-# Another way to seed is to create records from a data array. To do this, your
-# class must implement a +data+ attribute or method, which is an array of
-# hashes. Note that this class already provides the +attr_reader+ for this
-# attribute, so the most you have to do it create instance variables in your
-# constructor. If if you want your data to be different for each new record
-# (via Faker, +Array#sample+, etc.), you'll probably want to supply a method
-# called data that returns an array of new data each time.
-#   require 'planter'
-#   class UsersSeeder < Planter::Seeder
-#     seeding_method :data_array
-#     def data
-#       [{foo: 'bar', baz: 'bar'}]
-#     end
-#   end
-#
-# In both of the above methods, you can specify +parent_model+ and
-# +association+. If specified, records will be created via that parent model's
-# association. If +association+ is not provided, it will be assumed to be the
-# model name, pluralized and snake-cased (implying a +has_many+ relationship).
-# For example, if we're seeding the users table, and the model is +User+, the
-# association will default to +users+.
-#   require 'planter'
-#   class UsersSeeder < Planter::Seeder
-#     seeding_method :data_array, parent_model: 'Person', association: :users
-#     def data
-#       [{foo: 'bar', baz: 'bar'}]
-#     end
-#   end
+# To then seed your application, simply call the +seed+ method from your
+# +db/seeds.rb+ file (or wherever you need to call it from).
 #
-# You can also set +number_of_records+ to determine how many times each record
-# in the +data+ array will get created. The default is 1. Note that if this
-# attribute is set alongside +parent_model+ and +association+,
-# +number_of_records+ will be how many records will be created for each record
-# in the parent table.
-#   require 'planter'
-#   class UsersSeeder < Planter::Seeder
-#     seeding_method :data_array, number_of_records: 5
-#     def data
-#       [{foo: 'bar', baz: 'bar'}]
-#     end
-#   end
-#
-# If you need to seed a different way, put your own custom +seed+ method in
-# your seeder class and do whatever needs to be done.
+#   Planter.seed
 module Planter
   ##
   # The seeder configuration.
@@ -89,34 +43,36 @@ module Planter
   ##
   # Quick way of configuring the directories via an initializer.
   #
-  # @return [self]
+  # @return [Planter::Config]
   #
   # @example
-  #   Planter.configure do |app_seeder|
-  #     app_seeder.tables = %i[users]
-  #     app_seeder.seeders_directory = 'db/seeds'
-  #     app_seeder.csv_files_directory = 'db/seed_files'
+  #   require 'planter'
+  #   Planter.configure do |config|
+  #     config.seeders = %i[users]
+  #     config.seeders_directory = 'db/seeds'
+  #     config.csv_files_directory = 'db/seed_files'
   #   end
   def self.configure
     config.tap { |c| yield c }
   end
 
   ##
-  # This is the method to call from your +db/seeds.rb+. It seeds the tables
-  # listed in +Planter.config.tables+. To seed specific tables at
-  # runtime, you can set the +TABLES+ environmental variable to a
-  # comma-separated list of tables.
+  # This is the method to call from your +db/seeds.rb+. It callse the seeders
+  # listed in +Planter.config.seeders+. To call specific seeders at runtime,
+  # you can set the +SEEDERS+ environmental variable to a comma-separated list
+  # of seeders, like +rails db:seed SEEDERS=users,accounts+.
   #
   # @example
-  #   rails db:seed TABLES=users,accounts
+  #   # db/seeds.rb, assuming your +configure+ block is in an initializer.
+  #   Planter.seed
   def self.seed
-    tables = ENV['TABLES']&.split(',') || config.tables&.map(&:to_s)
-    raise RuntimeError, 'No tables specified; nothing to do' unless tables&.any?
+    seeders = ENV['SEEDERS']&.split(',') || config.seeders&.map(&:to_s)
+    raise RuntimeError, 'No seeders specified' unless seeders&.any?
 
-    tables.each do |table|
-      require Rails.root.join(config.seeders_directory, "#{table}_seeder.rb").to_s
-      puts "Seeding #{table}" unless config.quiet
-      "#{table.camelize}Seeder".constantize.new.seed
+    seeders.each do |s|
+      require Rails.root.join(config.seeders_directory, "#{s}_seeder.rb").to_s
+      puts "Seeding #{s}" unless config.quiet
+      "#{s.camelize}Seeder".constantize.new.seed
     end
   end
 end

data/lib/planter/config.rb

@@ -5,7 +5,7 @@ module Planter
   # Configure the application seeder.
   #
   # @example
-  #   Planter.configure { |seeder| seeder.tables = %i[users] }
+  #   Planter.configure { |seeder| seeder.seeders = %i[users] }
   class Config
     ##
     # Tell the application where the seeder classes are kept. Must be a path
@@ -26,13 +26,13 @@ module Planter
     attr_accessor :csv_files_directory
 
     ##
-    # Tell the application what tables to seed. Elements should be in the correct
-    # order, and can be strings or symbols.
+    # Tell the application what seeders exist. Elements should be in the correct
+    # order to seed the tables successfully, and can be strings or symbols.
     #
-    # @param [Array] tables
+    # @param [Array] seeders
     #
     # @return [Array]
-    attr_accessor :tables
+    attr_accessor :seeders
 
     ##
     # When true, don't print output when seeding.

data/lib/planter/railtie.rb

@@ -2,5 +2,13 @@
 
 module Planter
   class Railtie < ::Rails::Railtie # :nodoc:
+    rake_tasks do
+      load File.join(
+        File.expand_path(File.dirname(__FILE__)),
+        '..',
+        'tasks',
+        'planter_tasks.rake'
+      )
+    end
   end
 end

data/lib/planter/seeder.rb

@@ -2,21 +2,101 @@
 
 module Planter
   ##
-  # The class your seeder files should inherit from.
+  # Class that seeders should inherit from. Seeder files should be in
+  # +db/seeds+, and named +TABLE_seeder.rb+, where +TABLE+ is the name of the
+  # table being seeded (I.E. +users_seeder.rb+). If your seeder is named
+  # differently than the table, you'll need to specify the table with the
+  # +model+ option. The seeder's class name should be the same as the file
+  # name, but camelized. So, +UsersSeeder+. The directory where the seeder
+  # files are located can be changed via an initializer.
+  #
+  # The most basic way to seed is to have a CSV file with the same name as the
+  # table in +db/seed_files/+. So, +users.csv+. This CSV should have the
+  # table's column names as header. To seed using this method, your class
+  # should look like the following. Note that +:csv_name+ and +:model+ are only
+  # required if your seeder or csv are named differently than the table being
+  # seeded. The directory where the seed files are kept can be changed via an
+  # initializer.
+  #   # db/seeds/users_seeder.rb
+  #   require 'planter'
+  #   class UsersSeeder < Planter::Seeder
+  #     seeding_method :csv, csv_name: :users, model: 'User'
+  #   end
+  #
+  # Another way to seed is to create records from a data array. To do this,
+  # your class must implement a +data+ attribute or method, which is an array
+  # of hashes. Note that this class already provides the +attr_reader+ for this
+  # attribute, so the most you have to do it create instance variables in your
+  # constructor. If if you want your data to be different for each new record
+  # (via Faker, +Array#sample+, etc.), you'll probably want to supply a method
+  # called data that returns an array of new data each time.
+  #   require 'planter'
+  #   class UsersSeeder < Planter::Seeder
+  #     seeding_method :data_array
+  #     def data
+  #       [{foo: 'bar', baz: 'bar'}]
+  #     end
+  #   end
+  #
+  # In both of the above methods, you can specify +parent_model+ and
+  # +association+. If specified, records will be created via that parent
+  # model's association. If +association+ is not provided, it will be assumed
+  # to be the model name, pluralized and snake-cased (implying a +has_many+
+  # relationship).  For example, if we're seeding the users table, and the
+  # model is +User+, the association will default to +users+.
+  #   require 'planter'
+  #   class UsersSeeder < Planter::Seeder
+  #     seeding_method :data_array, parent_model: 'Person', association: :users
+  #     def data
+  #       [{foo: 'bar', baz: 'bar'}]
+  #     end
+  #   end
+  #
+  # You can also set +number_of_records+ to determine how many times each
+  # record in the +data+ array will get created. The default is 1. Note that if
+  # this attribute is set alongside +parent_model+ and +association+,
+  # +number_of_records+ will be how many records will be created for each
+  # record in the parent table.
+  #   require 'planter'
+  #   class UsersSeeder < Planter::Seeder
+  #     seeding_method :data_array, number_of_records: 5
+  #     def data
+  #       [{foo: 'bar', baz: 'bar'}]
+  #     end
+  #   end
+  #
+  # By default, all fields are used to look up the record. If it already
+  # exists, it is not re-created. If you have specific fields that a record
+  # should be looked-up by, you can pass the +unique_columns+ option. This will
+  # attempt to look up the record by those fields only, and if one doesn't
+  # exist, one will be created with the rest of the attributes. An example of
+  # when this would be useful is with Devise; you can't pass +password+ in the
+  # create method, so specifying +unique_columns+ on everything except
+  # +password+ allows it to be passed as an attribute to the +first_or_create+
+  # call.
+  #   require 'planter'
+  #   class UsersSeeder < Planter::Seeder
+  #     seeding_method :data_array, unique_columns: %i[username email]
+  #     def data
+  #       [{username: 'foo', email: 'bar', password: 'Example'}]
+  #     end
+  #   end
+  #
+  # If you need to seed a different way, put your own custom +seed+ method in
+  # your seeder class and do whatever needs to be done.
   class Seeder
     ##
     # The allowed seeding methods.
     #
     # @return [Array]
-    SEEDING_METHODS = %i[standard_csv data_array].freeze
+    SEEDING_METHODS = %i[csv data_array].freeze
 
     ##
     # Array of hashes used to create records. Your class must set this
-    # attribute when using +data_hash+ seeding method, although it's probably
+    # attribute when using +data_array+ seeding method, although it's probably
     # more likely that you'll want to define a method that returns a new set of
-    # data each time (via +Faker+, +Array#sample+, etc.). When using
-    # +standard_csv+, +data+ will be set to the data within the csv. You can
-    # override this.
+    # data each time (via +Faker+, +Array#sample+, etc.). When using +csv+,
+    # +data+ will be set to the data within the csv. You can override this.
     #
     # @return [Array]
     attr_reader :data
@@ -28,40 +108,58 @@ module Planter
     #
     # @param [Symbol] seeding_method
     #
-    # @param [Hash] options
+    # @kwarg [Integer] number_of_records
+    #
+    # @kwarg [String] model
+    #
+    # @kwarg [String] parent_model
+    #
+    # @kwarg [Symbol, String] association
+    #
+    # @kwarg [Symbol, String] csv_name
+    #
+    # @kwarg [Symbol, String] unique_columns
     #
     # @example
     #   require 'planter'
     #   class UsersSeeder < Planter::Seeder
-    #     seeding_method :data_array,
+    #     seeding_method :csv,
+    #       number_of_records: 2,
     #       model: 'User'
     #       parent_model: 'Person',
     #       association: :users,
-    #       number_of_records: 2
+    #       csv_name: :awesome_users,
+    #       unique_columns %i[username email]
     #   end
-    def self.seeding_method(method, **options)
+    def self.seeding_method(
+      method,
+      number_of_records: 1,
+      model: to_s.delete_suffix('Seeder').singularize,
+      parent_model: nil,
+      association: nil,
+      csv_name: nil,
+      unique_columns: nil
+    )
       if !SEEDING_METHODS.include?(method.intern)
         raise ArgumentError, "Method must be one of #{SEEDING_METHODS.join(', ')}"
-      elsif options[:association] && !options[:parent_model]
+      elsif association && !parent_model
         raise ArgumentError, "Must specify :parent_model with :association"
       end
 
       @seeding_method = method
-      @number_of_records = options.fetch(:number_of_records, 1)
-      @model = options.fetch(:model, to_s.delete_suffix('Seeder').singularize)
-      @parent_model = options[:parent_model]
-      @association = @parent_model && options.fetch(:association) do
-        determine_association(options)
-      end
-      return unless @seeding_method == :standard_csv
-
-      @csv_file = options.fetch(:csv_file, Rails.root.join(
-        Planter.config.csv_files_directory,
-        "#{to_s.delete_suffix('Seeder').underscore}.csv"
-      ).to_s)
+      @number_of_records = number_of_records
+      @model = model
+      @parent_model = parent_model
+      @association = @parent_model && (association || determine_association)
+      @csv_file = determine_csv_filename(csv_name) if @seeding_method == :csv
+      @unique_columns =
+        case unique_columns
+        when String, Symbol then [unique_columns.intern]
+        when Array then unique_columns.map(&:intern)
+        end
     end
 
-    def self.determine_association(options) # :nodoc:
+    def self.determine_association # :nodoc:
       associations =
         @parent_model.constantize.reflect_on_all_associations.map(&:name)
       table = to_s.delete_suffix('Seeder').underscore.split('/').last
@@ -70,10 +168,23 @@ module Planter
         return t if associations.include?(t)
       end
 
-      raise ArgumentError, 'Could not determine association name'
+      raise ArgumentError, "Couldn't determine association name"
     end
     private_class_method :determine_association
 
+    def self.determine_csv_filename(csv_name) # :nodoc:
+      file = (
+        csv_name || "#{to_s.delete_suffix('Seeder').underscore}"
+      ).to_s + '.csv'
+      [file, "#{file}.erb"].each do |f|
+        fname = Rails.root.join(Planter.config.csv_files_directory, f).to_s
+        return fname if ::File.file?(fname)
+      end
+
+      raise ArgumentError, "Couldn't find csv for #{@model}"
+    end
+    private_class_method :determine_csv_filename
+
     ##
     # The default seed method. To use this method, your class must provide a
     # valid +seeding_method+, and not implement its own +seed+ method.
@@ -140,14 +251,23 @@ module Planter
       @csv_file ||= self.class.instance_variable_get('@csv_file')
     end
 
+    ##
+    # When creating a record, the fields that will be used to look up the
+    # record. If it already exists, a new one will not be created.
+    #
+    # @return [Array]
+    def unique_columns
+      @unique_columns ||= self.class.instance_variable_get('@unique_columns')
+    end
+
     ##
     # Creates records from the +data+ attribute.
     def create_records
       data.each do |rec|
         number_of_records.times do
-          model.constantize.where(
-            rec.transform_values { |value| value == 'NULL' ? nil : value }
-          ).first_or_create!
+          rec.transform_values { |value| value == 'NULL' ? nil : value }
+          unique, attrs = split_record(rec)
+          model.constantize.where(unique).first_or_create!(attrs)
         end
       end
     end
@@ -165,31 +285,47 @@ module Planter
 
     private
 
-    def create_method
+    def create_method # :nodoc:
       parent_model.constantize.reflect_on_association(
         association
       ).macro.to_s.include?('many') ? :create_has_many : :create_has_one
     end
 
-    def create_has_many(assoc_rec, association, rec)
-      assoc_rec.public_send(association).where(rec).first_or_create!
+    def create_has_many(assoc_rec, association, rec) # :nodoc:
+      unique, attrs = split_record(rec)
+      assoc_rec.public_send(association).where(unique).first_or_create!(attrs)
     end
 
-    def create_has_one(assoc_rec, association, rec)
-      assoc_rec.public_send("create_#{association}", rec)
+    def create_has_one(assoc_rec, association, rec) # :nodoc:
+      if assoc_rec.public_send(association)
+        assoc_rec.public_send(association).update_attributes(rec)
+      else
+        assoc_rec.public_send("create_#{association}", rec)
+      end
     end
 
     def validate_attributes # :nodoc:
       case seeding_method.intern
-      when :standard_csv
-        raise "#{csv_file} does not exist" unless ::File.file?(csv_file)
+      when :csv
+        contents = ::File.read(csv_file)
+        if csv_file.end_with?('.erb')
+          contents = ERB.new(contents, trim_mode: '<>').result(binding)
+        end
 
-        @data ||= ::CSV.table(csv_file).map(&:to_hash)
+        @data ||= ::CSV.parse(
+          contents, headers: true, header_converters: :symbol
+        ).map(&:to_hash)
       when :data_array
         raise "Must define '@data'" if public_send(:data).nil?
       else
         raise("Must set 'seeding_method'")
       end
     end
+
+    def split_record(rec) # :nodoc:
+      return [rec, {}] unless unique_columns
+      u = unique_columns.each_with_object({}) { |c, h| h[c] = rec.delete(c) }
+      [u, rec]
+    end
   end
 end

data/lib/planter/version.rb

@@ -1,7 +1,54 @@
 # frozen_string_literal: true
 
 module Planter
+  ##
+  # Module that contains all gem version information. Follows semantic
+  # versioning. Read: https://semver.org/
+  module Version
+    ##
+    # Major version.
+    #
+    # @return [Integer]
+    MAJOR = 0
+
+    ##
+    # Minor version.
+    #
+    # @return [Integer]
+    MINOR = 0
+
+    ##
+    # Patch version.
+    #
+    # @return [Integer]
+    PATCH = 9
+
+    ##
+    # Version as +[MAJOR, MINOR, PATCH]+
+    #
+    # @return [Array]
+    def self.to_a
+      [MAJOR, MINOR, PATCH]
+    end
+
+    ##
+    # Version as +MAJOR.MINOR.PATCH+
+    #
+    # @return [String]
+    def self.to_s
+      to_a.join('.')
+    end
+
+    ##
+    # Version as +{major: MAJOR, minor: MINOR, patch: PATCH}+
+    #
+    # @return [Hash]
+    def self.to_h
+      Hash[%i[major minor patch].zip(to_a)]
+    end
+  end
+
   ##
   # Gem version, semantic.
-  VERSION = '0.0.2'.freeze
+  VERSION = Version.to_s.freeze
 end

data/lib/tasks/planter_tasks.rake

@@ -1,4 +1,13 @@
-# desc "Explaining what the task does"
-# task :planter do
-#   # Task goes here
-# end
+require 'planter'
+
+namespace :planter do
+  desc 'Seed application. Use this to keep planter separate from db:seed'
+  task seed: :environment do
+    Planter.configure do |config|
+      # NOTE: the seed method already looks for ENV['SEEDERS']
+      ENV['SEEDERS_DIRECTORY'] && config.seeders_directory = ENV['SEEDERS_DIRECTORY']
+      ENV['CSV_FILES_DIRECTORY'] && config.csv_files_directory = ENV['CSV_FILES_DIRECTORY']
+    end
+    Planter.seed
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.9
 platform: ruby
 authors:
 - Evan Gray
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-05-23 00:00:00.000000000 Z
+date: 2021-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,6 +41,8 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/generators/planter/initializer_generator.rb
+- lib/generators/planter/seeder_generator.rb
 - lib/planter.rb
 - lib/planter/config.rb
 - lib/planter/railtie.rb
@@ -54,7 +56,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/evanthegrayt/planter
   source_code_uri: https://github.com/evanthegrayt/planter
-post_install_message: 
+  documentation_uri: https://evanthegrayt.github.io/planter/
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -69,8 +72,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: Framework for seeding rails applications.
 test_files: []