planter 0.0.14 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65eb2897cfca2aa456d13a8044d6a86ed9b898aced01a3718e4d11f5dc718da1
-  data.tar.gz: 2dec806f05018f1bdf1e81282047dba3f049274cf6397aeaa8db55ff7bf8856c
+  metadata.gz: a542b8919dda44137996b078e0ac3f773fc8b85bed2225193de3f2a36bdfe099
+  data.tar.gz: '058271874209001fd8de03630c2e3f162959621769225bb354060f1ed8848354'
 SHA512:
-  metadata.gz: 752f29be613b3ce52fad80262ec500db79176329ac802c44f582375be3304c2435653fea1698ac1475f7da938250833f6807fa4b98f558806594db331024dc21
-  data.tar.gz: 46c6632d2faed5ab3ee96a4084de5043dd4312048cd1299dbb45910b537e0f5376b087f80e0e97f5ebc041334876cf47f048bbc8df97e6b052489e5c4bccd8d4
+  metadata.gz: c9728b99a23877a7f96f4267b963dd7f4e15f4c385303759476937f7f3f33bd6335ec0e6b89fde733ecfd7f5380386ba86ca26bfbdb9ac70f587b8a05efc8812
+  data.tar.gz: 1af8f9af55ca77f91f2ef7c01b8cb2c1919166be12f8785d779137d68237050b1ab259726da9546dea7dd2184f85431930e9ec8785d269c16ee1ba6add884b92

data/README.md

@@ -21,10 +21,10 @@ You can view the documentation [here](https://evanthegrayt.github.io/planter/).
 ## Installation
 Add the following line to your application's Gemfile. Because this plugin is
 currently a pre-release version, it's recommended to lock it to a specific
-version, as breaking changes may occur, even at the patch level.
+version, as breaking changes may occur, even at the minor level.
 
 ```ruby
-gem 'planter', '0.0.10'
+gem 'planter', '0.1.3'
 ```
 
 And then execute:
@@ -83,6 +83,7 @@ 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
+# db/seeds.rb
 Planter.seed
 ```
 
@@ -144,8 +145,8 @@ class UsersSeeder < Planter::Seeder
 end
 ```
 
-`ERB` can be used in the CSV files if you end the file name with `.csv.erb`.
-For example, `users.csv.erb`.
+`ERB` can be used in the CSV files if you end the file name with `.csv.erb` or
+`.erb.csv`. For example, `users.csv.erb`.
 
 ```
 participant_id,name
@@ -175,6 +176,38 @@ end
 
 For help with `erb_trim_mode`, see the help documentation for `ERB::new`.
 
+Lastly, it's worth mentioning `transformations` under the CSV section, as that's
+usually the pace where they're needed most, but it will work with any method.
+
+If you're seeding with a CSV, and it contains values that need to have code
+executed on them before it's imported into the database, you can define an
+instance variable called `@transformations`, or a method called
+`transformations`, that returns a Hash of field names, and Procs to run on the
+value. For example, if you have an `admin` column, and the CSV contains "true",
+it will come through as a String, but you probably want it to be a Boolean. This
+can be solved with the following.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :csv
+
+  def transformations
+    {
+      admin: ->(value) { value == 'true' },
+      last_name: ->(value, row) { "#{value} #{row[:suffix]}".squish }
+    }
+  end
+end
+```
+
+When defining a Proc/Lambda, you can make it accept 0, 1, or 2 arguments.
+- When `0`, the value is replaced by the result of the Lambda
+- When `1`, the value is passed to the Lambda, and is subsequently replaced by
+  the result of the Lambda
+- When `2`, the value is the first argument, and the entire row, as a Hash, is
+  the second argument. This allows for more complicated transformations that can
+  be dependent on other fields and values in the record.
+
 Running `rails planter:seed` will now seed your `users` table.
 
 ## Seeding from a data array
@@ -207,13 +240,16 @@ 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
-`AddressesSeeder` that uses the `parent_model` option, as seen below.
+`AddressesSeeder` that uses the `parent` option, as seen below. This option
+should be the name of the `belongs_to` association in your model. The primary
+key, foreign key, and model name of the parent will all be determined by
+reflecting on the association.
 
 ```ruby
 require 'faker'
 
 class AddressesSeeder < Planter::Seeder
-  seeding_method :data_array, parent_model: 'User'
+  seeding_method :data_array, parent: :user
 
   def data
     [{
@@ -227,9 +263,7 @@ 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.
+records *for each record of the parent model*.
 
 ### Custom seeds
 To write your own custom seeds, just overload the `seed` method and do whatever

data/lib/planter/seeder.rb

@@ -26,7 +26,7 @@ module Planter
   # 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
+  # attribute, so the most you have to do is 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.
@@ -38,15 +38,17 @@ module Planter
   #     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+.
+  # In both of the above methods, you can specify a +parent+ association, which
+  # is the +belongs_to+ association name in your model, which, when specified,
+  # records will be created for each record in the parent table. For example,
+  # if we're seeding the users table, and the model is +User+, which belongs to
+  # +Person+, then doing the following will create a user record for each
+  # record in the Person table. Note that nothing is automatically done to
+  # prevent any validation errors; you must do this on your own, mostly likely
+  # using +Faker+ or a similar library.
   #   require 'planter'
   #   class UsersSeeder < Planter::Seeder
-  #     seeding_method :data_array, parent_model: 'Person', association: :users
+  #     seeding_method :data_array, parent: :person
   #     def data
   #       [{foo: 'bar', baz: 'bar'}]
   #     end
@@ -54,9 +56,8 @@ module Planter
   #
   # 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.
+  # this attribute is set alongside +parent+, +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
@@ -101,6 +102,35 @@ module Planter
     # @return [Array]
     attr_reader :data
 
+    ##
+    # A hash of user-defined column names and procs to be run on values. This
+    # is most useful for when seeding from csv, and you need to transform, say,
+    # 'true' (String) into true (Boolean). The user may define this as an
+    # instance variable, or define a method that returns the hash.
+    #
+    # When defining a Proc/Lambda, you can make it accept 0, 1, or 2 arguments.
+    # - When 0, the value is replaced by the result of the Lambda.
+    # - When 1, the value is passed to the Lambda, and is subsequently
+    #   replaced by the result of the Lambda.
+    # - When 2, the value is the first argument, and the entire row, as a
+    #   Hash, is the second argument. This allows for more complicated
+    #   transformations that can be dependent on other fields and values in the
+    #   record.
+    #
+    # @return [Hash, nil]
+    #
+    # @example
+    #   class UsersSeeder < Planter::Seeder
+    #     seeding_method :csv
+    #     def transformations
+    #       {
+    #         admin: ->(v) { v == 'true' },
+    #         last_name: ->(value, row) { "#{value} #{row[:suffix]}".squish }
+    #       }
+    #     end
+    #   end
+    attr_reader :transformations
+
     ##
     # What trim mode should ERB use?
     #
@@ -127,7 +157,7 @@ module Planter
     # class must set this attribute via +seeding_method+.
     #
     # @return [String]
-    class_attribute :parent_model
+    class_attribute :parent
 
     ##
     # The number of records to create from each record in the +data+ array. If
@@ -137,18 +167,11 @@ module Planter
     # @return [Integer]
     class_attribute :number_of_records
 
-    ##
-    # When using +parent_model+, the association name. Your class can set this
-    # attribute via +seeding_method+.
-    #
-    # @return [Symbol]
-    class_attribute :association
-
     ##
     # The csv file corresponding to the model.
     #
     # @return [String]
-    class_attribute :csv_file
+    class_attribute :csv_name
 
     ##
     # The seeding method specified.
@@ -157,96 +180,59 @@ module Planter
     class_attribute :seed_method
 
     ##
-    # Access the metaclass so we can define public and private class methods.
-    class << self
-      ##
-      # If your class is going to use the inherited +seed+ method, you must tell
-      # it which +seeding_method+ to use. The argument to this method must be
-      # included in the +SEEDING_METHODS+ array.
-      #
-      # @param [Symbol] seeding_method
-      #
-      # @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
-      #
-      # @kwarg [String] erb_trim_mode
-      #
-      # @example
-      #   require 'planter'
-      #   class UsersSeeder < Planter::Seeder
-      #     seeding_method :csv,
-      #       number_of_records: 2,
-      #       model: 'User'
-      #       parent_model: 'Person',
-      #       association: :users,
-      #       csv_name: :awesome_users,
-      #       unique_columns %i[username email],
-      #       erb_trim_mode: '<>'
-      #   end
-      def seeding_method(
-        method,
-        number_of_records: 1,
-        model: nil,
-        parent_model: nil,
-        association: nil,
-        csv_name: nil,
-        unique_columns: nil,
-        erb_trim_mode: nil
-      )
-        if !SEEDING_METHODS.include?(method.intern)
-          raise ArgumentError, "Method must be: #{SEEDING_METHODS.join(', ')}"
-        elsif association && !parent_model
-          raise ArgumentError, "Must specify :parent_model with :association"
-        end
-
-        self.seed_method = method
-        self.number_of_records = number_of_records
-        self.model = model || to_s.delete_suffix('Seeder').singularize
-        self.parent_model = parent_model
-        self.association = parent_model && (association || determine_association)
-        self.csv_file = determine_csv_filename(csv_name) if self.seed_method == :csv
-        self.erb_trim_mode = erb_trim_mode || Planter.config.erb_trim_mode
-        self.unique_columns =
-          case unique_columns
-          when String, Symbol then [unique_columns.intern]
-          when Array then unique_columns.map(&:intern)
-          end
-      end
-
-      private
-
-      def determine_association # :nodoc:
-        associations =
-          parent_model.constantize.reflect_on_all_associations.map(&:name)
-        table = to_s.delete_suffix('Seeder').underscore.split('/').last
-
-        [table, table.singularize].map(&:intern).each do |t|
-          return t if associations.include?(t)
-        end
-
-        raise ArgumentError, "Couldn't determine association name"
+    # If your class is going to use the inherited +seed+ method, you must tell
+    # it which +seeding_method+ to use. The argument to this method must be
+    # included in the +SEEDING_METHODS+ array.
+    #
+    # @param [Symbol] seed_method
+    #
+    # @kwarg [Integer] number_of_records
+    #
+    # @kwarg [String] model
+    #
+    # @kwarg [Symbol, String] parent
+    #
+    # @kwarg [Symbol, String] csv_name
+    #
+    # @kwarg [Symbol, String] unique_columns
+    #
+    # @kwarg [String] erb_trim_mode
+    #
+    # @example
+    #   require 'planter'
+    #   class UsersSeeder < Planter::Seeder
+    #     seeding_method :csv,
+    #       number_of_records: 2,
+    #       model: 'User'
+    #       parent: :person,
+    #       csv_name: :awesome_users,
+    #       unique_columns %i[username email],
+    #       erb_trim_mode: '<>'
+    #   end
+    def self.seeding_method(
+      seed_method,
+      number_of_records: 1,
+      model: nil,
+      parent: nil,
+      csv_name: nil,
+      unique_columns: nil,
+      erb_trim_mode: nil
+    )
+      unless SEEDING_METHODS.include?(seed_method.intern)
+        raise ArgumentError, "Method must be: #{SEEDING_METHODS.join(', ')}"
       end
 
-      def 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)
+      self.seed_method = seed_method
+      self.number_of_records = number_of_records
+      self.model = model || to_s.delete_suffix('Seeder').singularize
+      self.parent = parent
+      self.csv_name = csv_name || to_s.delete_suffix('Seeder').underscore
+      self.erb_trim_mode = erb_trim_mode || Planter.config.erb_trim_mode
+      self.unique_columns =
+        case unique_columns
+        when String, Symbol then [unique_columns.intern]
+        when Array then unique_columns.map(&:intern)
         end
-
-        raise ArgumentError, "Couldn't find csv for #{model}"
-      end
     end
 
     ##
@@ -254,78 +240,113 @@ module Planter
     # valid +seeding_method+, and not implement its own +seed+ method.
     def seed
       validate_attributes
+      extract_data_from_csv if seed_method == :csv
 
-      parent_model ? create_records_from_parent : create_records
+      parent ? create_records_from_parent : create_records
     end
 
-    protected
+    private
 
     ##
     # Creates records from the +data+ attribute.
     def create_records
-      data.each do |rec|
-        number_of_records.times do
-          rec.transform_values { |value| value == 'NULL' ? nil : value }
-          unique, attrs = split_record(rec)
-          model.constantize.where(unique).first_or_create!(attrs)
-        end
-      end
+      data.each { |record| create_record(record) }
     end
 
     ##
-    # Create records from the +data+ attribute for each record in the
-    # +parent_table+, via the specified +association+.
+    # Create records from the +data+ attribute for each record in the +parent+.
     def create_records_from_parent
-      parent_model.constantize.all.each do |assoc_rec|
-        number_of_records.times do
-          data.each { |rec| send(create_method, assoc_rec, association, rec) }
-        end
+      parent_model.constantize.pluck(primary_key).each do |parent_id|
+        data.each { |record| create_record(record, parent_id: parent_id) }
       end
     end
 
-    private
-
-    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) # :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) # :nodoc:
-      if assoc_rec.public_send(association)
-        assoc_rec.public_send(association).update_attributes(rec)
-      else
-        assoc_rec.public_send("create_#{association}", rec)
+    def create_record(record, parent_id: nil)
+      number_of_records.times do
+        unique, attrs = split_record(apply_transformations(record))
+        model.constantize.where(
+          unique.tap { |u| u[foreign_key] = parent_id if parent_id }
+        ).first_or_create!(attrs)
       end
     end
 
     def validate_attributes # :nodoc:
       case seed_method.intern
       when :csv
-        contents = ::File.read(csv_file)
-        if csv_file.end_with?('.erb')
-          contents = ERB.new(contents, trim_mode: erb_trim_mode).result(binding)
-        end
-
-        @data ||= ::CSV.parse(
-          contents, headers: true, header_converters: :symbol
-        ).map(&:to_hash)
+        raise "Couldn't find csv for #{model}" unless full_csv_name
       when :data_array
-        raise "Must define '@data'" if public_send(:data).nil?
+        raise 'data is not defined in the seeder' if public_send(:data).nil?
       else
-        raise("Must set 'seeding_method'")
+        raise 'seeding_method not defined in the seeder'
+      end
+    end
+
+    def apply_transformations(record)
+      return record if public_send(:transformations).nil?
+
+      Hash[record.map { |field, value| map_record(field, value, record) }]
+    end
+
+    def map_record(field, value, record)
+      [
+        field,
+        transformations.key?(field) ? transform(field, value, record) : value
+      ]
+    end
+
+    def transform(field, value, record)
+      case transformations[field].arity
+      when 0 then transformations[field].call
+      when 1 then transformations[field].call(value)
+      when 2 then transformations[field].call(value, record)
       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
+
+    def association_options
+      @association_options ||=
+        model.constantize.reflect_on_association(parent).options
+    end
+
+    def primary_key
+      @primary_key ||=
+        association_options.fetch(:primary_key, :id)
+    end
+
+    def foreign_key
+      @foreign_key ||=
+        association_options.fetch(:foreign_key, "#{parent}_id")
+    end
+
+    def parent_model
+      @parent_model ||=
+        association_options.fetch(:class_name, parent.to_s.classify)
+    end
+
+    def full_csv_name
+      @full_csv_name ||=
+        %W[#{csv_name}.csv #{csv_name}.csv.erb #{csv_name}.erb.csv]
+          .map { |f| Rails.root.join(Planter.config.csv_files_directory, f).to_s }
+          .find { |f| ::File.file?(f) }
+    end
+
+    def extract_data_from_csv
+      contents = ::File.read(full_csv_name)
+      if full_csv_name.include?('.erb')
+        contents = ERB.new(contents, trim_mode: erb_trim_mode).result(binding)
+      end
+
+      @data ||= ::CSV.parse(
+        contents,
+        headers: true,
+        header_converters: :symbol
+      ).map(&:to_hash)
+    end
   end
 end

data/lib/planter/version.rb

@@ -15,13 +15,13 @@ module Planter
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 0
+    MINOR = 1
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 14
+    PATCH = 3
 
     ##
     # Version as +[MAJOR, MINOR, PATCH]+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 0.1.3
 platform: ruby
 authors:
 - Evan Gray
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-27 00:00:00.000000000 Z
+date: 2022-01-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,20 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.3
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 6.1.3.1
+        version: 6.1.4.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.3
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 6.1.3.1
+        version: 6.1.4.4
 description: Create a seeder for each table in your database, and easily seed from
   CSV or custom methods
 email: