seed-fu 1.2.3 → 2.0.0

data/lib/seed-fu/seeder.rb

@@ -0,0 +1,77 @@
+require 'active_support/core_ext/hash/keys'
+
+module SeedFu
+  # Creates or updates seed records with data.
+  #
+  # It is not recommended to use this class directly. Instead, use `Model.seed`, and `Model.seed_once`,
+  # where `Model` is your Active Record model.
+  #
+  # @see ActiveRecordExtension
+  class Seeder
+    # @param [ActiveRecord::Base] model_class The model to be seeded
+    # @param [Array<Symbol>] constraints A list of attributes which identify a particular seed. If
+    #   a record with these attributes already exists then it will be updated rather than created.
+    # @param [Array<Hash>] data Each item in this array is a hash containing attributes for a
+    #   particular record.
+    # @param [Hash] options
+    # @option options [Boolean] :quiet (SeedFu.quiet) If true, output will be silenced
+    # @option options [Boolean] :insert_only (false) If true then existing records which match the
+    #   constraints will not be updated, even if the seed data has changed
+    def initialize(model_class, constraints, data, options = {})
+      @model_class = model_class
+      @constraints = constraints.to_a.empty? ? [:id] : constraints
+      @data        = data.to_a || []
+      @options     = options.symbolize_keys
+
+      @options[:quiet] ||= SeedFu.quiet
+
+      validate_constraints!
+      validate_data!
+    end
+
+    # Insert/update the records as appropriate. Validation is skipped while saving.
+    # @return [Array<ActiveRecord::Base>] The records which have been seeded
+    def seed
+      @model_class.transaction do
+        @data.map { |record_data| seed_record(record_data.symbolize_keys) }
+      end
+    end
+
+    private
+
+      def validate_constraints!
+        unknown_columns = @constraints.map(&:to_s) - @model_class.column_names
+        unless unknown_columns.empty?
+          raise(ArgumentError,
+            "Your seed constraints contained unknown columns: #{column_list(unknown_columns)}. " +
+            "Valid columns are: #{column_list(@model_class.column_names)}.")
+        end
+      end
+
+      def validate_data!
+        raise ArgumentError, "Seed data missing" if @data.empty?
+      end
+
+      def column_list(columns)
+        '`' + columns.join("`, `") + '`'
+      end
+
+      def seed_record(data)
+        record = find_or_initialize_record(data)
+        return if @options[:insert_only] && !record.new_record?
+        record.send(:attributes=, data, false)
+        puts " - #{@model_class} #{data.inspect}" unless @options[:quiet]
+        record.save(:validate => false)
+        record
+      end
+
+      def find_or_initialize_record(data)
+        @model_class.where(constraint_conditions(data)).first ||
+        @model_class.new
+      end
+
+      def constraint_conditions(data)
+        Hash[@constraints.map { |c| [c, data[c.to_sym]] }]
+      end
+  end
+end

data/lib/seed-fu/version.rb

@@ -0,0 +1,4 @@
+module SeedFu
+  # The current version of Seed Fu
+  VERSION = '2.0.0'
+end

data/lib/seed-fu/writer.rb

@@ -1,3 +1,132 @@
-require File.join( File.dirname(__FILE__), 'writer', 'abstract' )
-require File.join( File.dirname(__FILE__), 'writer', 'seed' )
-require File.join( File.dirname(__FILE__), 'writer', 'seed_many' )
+module SeedFu
+  # {Writer} is used to programmatically generated seed files. For example, you might want to write
+  # a script which converts data in a CSV file to a valid Seed Fu seed file, which can then be
+  # imported.
+  #
+  # @example Basic usage
+  #   SeedFu::Writer.write('path/to/file.rb', :class_name => 'Person', :constraints => [:first_name, :last_name]) do |writer|
+  #     writer.write(:first_name => 'Jon',   :last_name => 'Smith',    :age => 21)
+  #     writer.write(:first_name => 'Emily', :last_name => 'McDonald', :age => 24)
+  #   end
+  #
+  #   # Writes the following to the file:
+  #   #
+  #   # Person.seed(:first_name, :last_name,
+  #   #   {:first_name=>"Jon", :last_name=>"Smith", :age=>21},
+  #   #   {:first_name=>"Emily", :last_name=>"McDonald", :age=>24}
+  #   # )
+  class Writer
+    cattr_accessor :default_options
+    @@default_options = {
+      :chunk_size  => 100,
+      :constraints => [:id],
+      :seed_type   => :seed
+    }
+
+    # @param [Hash] options
+    # @option options [String] :class_name *Required* The name of the Active Record model to
+    #   generate seeds for
+    # @option options [Fixnum] :chunk_size (100) The number of seeds to write before generating a
+    #   `# BREAK EVAL` line. (Chunking reduces memory usage when loading seeds.)
+    # @option options [:seed, :seed_once] :seed_type (:seed) The method to use when generating
+    #   seeds. See {ActiveRecordExtension} for details.
+    # @option options [Array<Symbol>] :constraints ([:id]) The constraining attributes for the seeds
+    def initialize(options = {})
+      @options = self.class.default_options.merge(options)
+      raise ArgumentError, "missing option :class_name" unless @options[:class_name]
+    end
+
+    # Creates a new instance of {Writer} with the `options`, and then calls {#write} with the
+    # `io_or_filename` and `block`
+    def self.write(io_or_filename, options = {}, &block)
+      new(options).write(io_or_filename, &block)
+    end
+
+    # Writes the necessary headers and footers, and yields to a block within which the actual
+    # seed data should be writting using the `#<<` method.
+    #
+    # @param [IO] io_or_filename The IO to which writes will be made. (If an `IO` is given, it is
+    #   your responsibility to close it after writing.)
+    # @param [String] io_or_filename The filename of a file to make writes to. (Will be opened and
+    #   closed automatically.)
+    # @yield [self] make calls to `#<<` within the block
+    def write(io_or_filename, &block)
+      raise ArgumentError, "missing block" unless block_given?
+
+      if io_or_filename.respond_to?(:write)
+        write_to_io(io_or_filename, &block)
+      else
+        File.open(io_or_filename, 'w') do |file|
+          write_to_io(file, &block)
+        end
+      end
+    end
+
+    # Add a seed. Must be called within a block passed to {#write}.
+    # @param [Hash] seed The attributes for the seed
+    def <<(seed)
+      raise "You must add seeds inside a SeedFu::Writer#write block" unless @io
+
+      buffer = ''
+
+      if chunk_this_seed?
+        buffer << seed_footer
+        buffer << "# BREAK EVAL\n"
+        buffer << seed_header
+      end
+
+      buffer << ",\n"
+      buffer << '  ' + seed.inspect
+
+      @io.write(buffer)
+
+      @count += 1
+    end
+    alias_method :add, :<<
+
+    private
+
+      def write_to_io(io)
+        @io, @count = io, 0
+        @io.write(file_header)
+        @io.write(seed_header)
+        yield(self)
+        @io.write(seed_footer)
+        @io.write(file_footer)
+      ensure
+        @io, @count = nil, nil
+      end
+
+      def file_header
+        <<-END
+# DO NOT MODIFY THIS FILE, it was auto-generated.
+#
+# Date: #{Time.now}
+# Seeding #{@options[:class_name]}
+# Written with the command:
+#
+#   #{$0} #{$*.join}
+#
+        END
+      end
+
+      def file_footer
+        <<-END
+# End auto-generated file.
+        END
+      end
+
+      def seed_header
+        constraints = @options[:constraints] && @options[:constraints].map(&:inspect).join(', ')
+        "#{@options[:class_name]}.#{@options[:seed_type]}(#{constraints}"
+      end
+
+      def seed_footer
+        "\n)\n"
+      end
+
+      def chunk_this_seed?
+        @count != 0 && (@count % @options[:chunk_size]) == 0
+      end
+  end
+end

data/lib/tasks/seed_fu.rake

@@ -0,0 +1,43 @@
+require 'seed-fu'
+
+namespace :db do
+  desc <<-EOS
+    Loads seed data for the current environment. It will look for
+    ruby seed files in <RAILS_ROOT>/db/fixtures/ and
+    <RAILS_ROOT>/db/fixtures/<RAILS_ENV>/.
+
+    By default it will load any ruby files found. You can filter the files
+    loaded by passing in the FILTER environment variable with a comma-delimited
+    list of patterns to include. Any files not matching the pattern will
+    not be loaded.
+
+    You can also change the directory where seed files are looked for
+    with the FIXTURE_PATH environment variable.
+
+    Examples:
+      # default, to load all seed files for the current environment
+      rake db:seed
+
+      # to load seed files matching orders or customers
+      rake db:seed FILTER=orders,customers
+
+      # to load files from RAILS_ROOT/features/fixtures
+      rake db:seed FIXTURE_PATH=features/fixtures
+  EOS
+  task :seed_fu => :environment do
+    if ENV["SEED"]
+      puts "DEPRECATED: The SEED option to db:seed_fu is deprecated. Please use FILTER instead."
+      ENV["FILTER"] = ENV["SEED"]
+    end
+
+    if ENV["FILTER"]
+      filter = /#{ENV["FILTER"].gsub(/,/, "|")}/
+    end
+
+    if ENV["FIXTURE_PATH"]
+      fixture_paths = [ENV["FIXTURE_PATH"], ENV["FIXTURE_PATH"] + '/' + Rails.env]
+    end
+
+    SeedFu.seed(fixture_paths, filter)
+  end
+end

metadata

@@ -1,77 +1,120 @@
 --- !ruby/object:Gem::Specification 
 name: seed-fu
 version: !ruby/object:Gem::Version 
-  version: 1.2.3
+  prerelease: false
+  segments: 
+  - 2
+  - 0
+  - 0
+  version: 2.0.0
 platform: ruby
 authors: 
 - Michael Bleigh
+- Jon Leighton
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-01-20 00:00:00 -05:00
+date: 2010-11-05 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rails
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
   type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 2
+        - 0
+        - 0
+        version: 2.0.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: sqlite3
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: "2.1"
-    version: 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
 description: Seed Fu is an attempt to once and for all solve the problem of inserting and maintaining seed data in a database. It uses a variety of techniques gathered from various places around the web and combines them to create what is hopefully the most robust seed data system around.
-email: michael@intridea.com
+email: 
+- michael@intridea.com
+- j@jonathanleighton.com
 executables: []
 
 extensions: []
 
-extra_rdoc_files: 
-- README.rdoc
+extra_rdoc_files: []
+
 files: 
-- README.rdoc
-- Rakefile
-- VERSION
-- lib/seed-fu.rb
+- lib/tasks/seed_fu.rake
+- lib/seed-fu/block_hash.rb
+- lib/seed-fu/runner.rb
+- lib/seed-fu/active_record_extension.rb
+- lib/seed-fu/seeder.rb
+- lib/seed-fu/railtie.rb
+- lib/seed-fu/version.rb
 - lib/seed-fu/writer.rb
-- lib/seed-fu/writer/abstract.rb
-- lib/seed-fu/writer/seed.rb
-- lib/seed-fu/writer/seed_many.rb
-- rails/init.rb
-- spec/schema.rb
-- spec/seed_fu_spec.rb
-- spec/spec_helper.rb
+- lib/seed-fu.rb
+- LICENSE
+- README.md
+- CHANGELOG.md
 has_rdoc: true
-homepage: http://github.com/mblegih/seed-fu
+homepage: http://github.com/mbleigh/seed-fu
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: Allows easier database seeding of tables in Rails.
-test_files: 
-- spec/schema.rb
-- spec/seed_fu_spec.rb
-- spec/spec_helper.rb
+summary: Easily manage seed data in your Active Record application
+test_files: []
+

data/README.rdoc

@@ -1,125 +0,0 @@
-= Seed Fu
-
-Seed Fu is an attempt to once and for all solve the problem of inserting and maintaining seed data in a database. It uses a variety of techniques gathered from various places around the web and combines them to create what is hopefully the most robust seed data system around.
-
-
-== Simple Usage
-
-Seed data is taken from the <tt>db/fixtures</tt> directory. Simply make descriptive .rb files in that directory (they can be named anything, but users.rb for the User model seed data makes sense, etc.). These scripts will be run whenever the <tt>db:seed</tt> (<tt>db:seed_fu</tt> for Rails 2.3.5 and greater) rake task is called, and in order (you can use <tt>00_first.rb</tt>, <tt>00_second.rb</tt>, etc). You can put arbitrary Ruby code in these files, but remember that it will be executed every time the rake task is called, so it needs to be runnable multiple times on the same database.
-
-You can also have environment-specific seed data placed in  <tt>db/fixtures/ENVIRONMENT</tt> that will only be loaded if that is the current environment.
-
-Let's say we want to populate a few default users. In <tt>db/fixtures/users.rb</tt> we write the following code:
-
-    User.seed(:login, :email) do |s|
-      s.login = "bob"
-      s.email = "bob@bobson.com"
-      s.first_name = "Bob"
-      s.last_name = "Bobson"
-    end
-    
-    User.seed(:login, :email) do |s|
-      s.login = "bob"
-      s.email = "bob@stevenson.com"
-      s.first_name = "Bob"
-      s.last_name = "Stevenson"
-    end
-
-That's all you have to do! You will now have two users created in the system and you can change their first and last names in the users.rb file and it will be updated as such.
-
-The arguments passed to the <tt><ActiveRecord>.seed</tt> method are the constraining attributes: these must remain unchanged between db:seed calls to avoid data duplication. By default, seed data will constrain to the id like so:
-
-    Category.seed do |s|
-      s.id = 1
-      s.name = "Buttons"
-    end
-    
-    Category.seed do |s|
-      s.id = 2
-      s.name = "Bobbins"
-      s.parent_id = 1
-    end
-    
-Note that any constraints that are passed in must be present in the subsequent seed data setting.
-
-== Seed-many Usage
-
-The default <tt>.seed` syntax is very verbose.  An alternative is the `.seed_many</tt> syntax. Look at this refactoring of the first seed usage example above:
-
-    User.seed_many(:login, :email, [
-      { :login => "bob", :email => "bob@bobson.com",    :first_name => "Bob", :last_name = "Bobson" },
-      { :login => "bob", :email => "bob@stevenson.com", :first_name => "Bob", :last_name = "Stevenson" }
-    ])
-
-Not as pretty, but much more concise.
-
-== Handling Large SeedFu Files
-
-Seed files can be huge.  To handle large files (over a million rows), try these tricks:
-
-* Gzip your fixtures.  Seed Fu will read .rb.gz files happily.  <tt>gzip -9</tt> gives the   best compression, and with Seed Fu's repetitive syntax, a 160M file can shrink to 16M.
-* Add lines reading <tt># BREAK EVAL</tt> in your big fixtures, and Seed Fu will avoid loading the whole file into memory.  If you use SeedFu::Writer, these breaks are built into your generated fixtures.
-* Load a single fixture with the <tt>SEED</tt> environment variable: <tt>SEED=cities,states rake db:seed > seed_log`.  Each argument to `SEED</tt> is used as a regex to filter fixtures by filename.
-
-== Generating SeedFu Files
-
-Say you have a CSV you need to massage and store as seed files.  You can create an import script using SeedFu::Writer.
-
-    #!/usr/bin/env ruby
-    #
-    # This is: script/generate_cities_seed_from_csv
-    #
-    require 'rubygems'
-    require 'fastercsv'
-    require File.join( File.dirname(__FILE__), '..', 'vendor/plugins/seed-fu/lib/seed-fu/writer' )
-
-    # Maybe SEEF_FILE could be $stdout, hm.
-    #
-    CITY_CSV  = File.join( File.dirname(__FILE__), '..', 'city.csv' )
-    SEED_FILE = File.join( File.dirname(__FILE__), '..', 'db', 'fixtures', 'cities.rb' )
-
-    # Create a seed_writer, walk the CSV, add to the file.
-    #
-
-    seed_writer = SeedFu::Writer::SeedMany.new(
-      :seed_file  => SEED_FILE,
-      :seed_model => 'City',
-      :seed_by    => [ :city, :state ]
-    )
-
-    FasterCSV.foreach( CITY_CSV,
-      :return_headers => false,
-      :headers => :first_row
-    ) do |row|
-
-      # Skip all but the US
-      #
-      next unless row['country_code'] == 'US'
-
-      unless us_state
-        puts "No State Match for #{row['region_name']}"
-        next
-      end
-
-      # Write the seed
-      #
-      seed_writer.add_seed({
-        :zip => row['zipcode'],
-        :state => row['state'],
-        :city => row['city'],
-        :latitude => row['latitude'],
-        :longitude => row['longitude']
-      })
-
-    end
-
-    seed_writer.finish
-
-There is also a SeedFu::Writer::Seed in case you prefere the seed()
-syntax over the seen_many() syntax.  Easy-peasy.
-
-== Contributors
-
-* Thanks to Matthew Beale for his great work in adding the writer, making it faster and better.
-
-Copyright (c) 2008-2009 Michael Bleigh released under the MIT license