planter 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b346415e35c538e46222ced2131792a27f778fafe169143116c6908ddca88aac
-  data.tar.gz: ed3952a7fd92566b2acb31e0fee881549675f40aa579ebe9115db2f86f302eb0
+  metadata.gz: 85e12676f9e3c992f26939f709bb8ff9785a75cfbf13a5279075e2e84ae2adc9
+  data.tar.gz: 130e7dd566d20b09dcfb38c4d62c76d872b169b459f68eff0a2d8715c13f320a
 SHA512:
-  metadata.gz: d07501dd0544476e04b768277d870f035626f6c00218a9f248e6fe6f7dcae833757162b688a269066bc8daa5dae1d2fb6f20db7c45273245da60f900cde80f3f
-  data.tar.gz: '09e7ba1054d15f7aa68aedaac7915fdda444eac1bff9630402e5f5999f872283e978b5e60b9581310cdd2bbc9ea4688d73b3fd7d6c8781b802b8bb21cee7fb8c'
+  metadata.gz: 535f7b4909895f4f2ed6219919cbd620b3f283daecd693457ce52dfa7ec3d8281d49d7487dc530ced549a52d55719759e3f0975efa833763475fe03a1b863171
+  data.tar.gz: 36df7d4e59476de2f1526b66e1571d70221ff77204eac23e2d16408ddf7ca6bfcdacbfb351e0a9f4323ca2439c407afb5ecbd3a88725493d62ef8c0ac594f1f4

data/README.md

@@ -1,10 +1,9 @@
 # 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)
+![Language: Ruby](https://img.shields.io/static/v1?label=language&message=Ruby&color=CC342D&style=flat&logo=ruby&logoColor=CC342D)
 [![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.
@@ -21,10 +20,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.2.0'
 ```
 
 And then execute:
@@ -83,6 +82,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,13 +144,24 @@ 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`. When using ERB, instance variables set
+in the seeder can be used in the CSV.
+
+```ruby
+class UsersSeeder < Planter::Seeder
+  seeding_method :csv, csv_name: :people
+
+  def initialize
+    @name_prefix = 'Test User'
+  end
+end
+```
 
 ```
 participant_id,name
-<%= Participant.find_by(email: 'test1@example.com').id %>,"Test User1"
-<%= Participant.find_by(email: 'test2@example.com').id %>,"Test User2"
+<%= Participant.find_by(email: 'test1@example.com').id %>,<%= @name_prefix %> 1
+<%= Participant.find_by(email: 'test2@example.com').id %>,<%= @name_prefix %> 2
 ```
 
 Note that, if you need to change the trim mode for ERB, you can set a default in
@@ -175,6 +186,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
@@ -244,7 +287,7 @@ class UsersSeeder < Planter::Seeder
   }
 
   def seed
-    USERS.each { |email, attrs| User.where(email).first_or_create!(attrs) }
+    USERS.each { |email, attrs| User.where(email: email).first_or_create!(attrs) }
   end
 end
 ```

data/lib/planter/seeder.rb

@@ -102,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?
     #
@@ -142,7 +171,7 @@ module Planter
     # The csv file corresponding to the model.
     #
     # @return [String]
-    class_attribute :csv_file
+    class_attribute :csv_name
 
     ##
     # The seeding method specified.
@@ -151,79 +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] seed_method
-      #
-      # @kwarg [Integer] number_of_records
-      #
-      # @kwarg [String] model
-      #
-      # @kwarg [String] parent
-      #
-      # @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 seeding_method(
-        seed_method,
-        number_of_records: 1,
-        model: nil,
-        parent: nil,
-        csv_name: nil,
-        unique_columns: nil,
-        erb_trim_mode: nil
-      )
-        if !SEEDING_METHODS.include?(seed_method.intern)
-          raise ArgumentError, "Method must be: #{SEEDING_METHODS.join(', ')}"
-        end
-
-        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_file = determine_csv_filename(csv_name) if 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
+    # 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
 
-      private
-
-      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
 
     ##
@@ -231,11 +240,12 @@ 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 ? create_records_from_parent : create_records
     end
 
-    protected
+    private
 
     ##
     # Creates records from the +data+ attribute.
@@ -253,7 +263,7 @@ module Planter
 
     def create_record(record, parent_id: nil)
       number_of_records.times do
-        unique, attrs = split_record(record)
+        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)
@@ -263,18 +273,32 @@ module Planter
     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
 
@@ -304,5 +328,25 @@ module Planter
       @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,19 +15,21 @@ module Planter
     # Minor version.
     #
     # @return [Integer]
-    MINOR = 1
+    MINOR = 2
 
     ##
     # Patch version.
     #
     # @return [Integer]
-    PATCH = 1
+    PATCH = 0
+
+    module_function
 
     ##
     # Version as +[MAJOR, MINOR, PATCH]+
     #
     # @return [Array]
-    def self.to_a
+    def to_a
       [MAJOR, MINOR, PATCH]
     end
 
@@ -35,7 +37,7 @@ module Planter
     # Version as +MAJOR.MINOR.PATCH+
     #
     # @return [String]
-    def self.to_s
+    def to_s
       to_a.join('.')
     end
 
@@ -43,7 +45,7 @@ module Planter
     # Version as +{major: MAJOR, minor: MINOR, patch: PATCH}+
     #
     # @return [Hash]
-    def self.to_h
+    def to_h
       Hash[%i[major minor patch].zip(to_a)]
     end
   end

data/lib/planter.rb

@@ -24,11 +24,13 @@ require 'planter/seeder'
 #
 #   Planter.seed
 module Planter
+  module_function
+
   ##
   # The seeder configuration.
   #
   # @return [Planter::Config]
-  def self.config
+  def config
     @config ||= Planter::Config.new
   end
 
@@ -36,7 +38,7 @@ module Planter
   # Resets the config back to its initial state.
   #
   # @return [Planter::Config]
-  def self.reset_config
+  def reset_config
     @config = Planter::Config.new
   end
 
@@ -52,7 +54,7 @@ module Planter
   #     config.seeders_directory = 'db/seeds'
   #     config.csv_files_directory = 'db/seed_files'
   #   end
-  def self.configure
+  def configure
     config.tap { |c| yield c }
   end
 
@@ -65,7 +67,7 @@ module Planter
   # @example
   #   # db/seeds.rb, assuming your +configure+ block is in an initializer.
   #   Planter.seed
-  def self.seed
+  def seed
     seeders = ENV['SEEDERS']&.split(',') || config.seeders&.map(&:to_s)
     raise RuntimeError, 'No seeders specified' if seeders.blank?
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: planter
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Evan Gray
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-12-29 00:00:00.000000000 Z
+date: 2022-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.4.4
+        version: 7.0.2.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 6.1.4.4
+        version: 7.0.2.3
 description: Create a seeder for each table in your database, and easily seed from
   CSV or custom methods
 email:
@@ -66,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.2.33
 signing_key: 
 specification_version: 4
 summary: Framework for seeding rails applications.