sqrbl 0.1.2 → 0.2.0

data/History.txt

@@ -1,6 +1,29 @@
+== 0.2.0 / 2009-09-03
+
+* API change: switch to using the word "conversion" instead of
+  "migration" throughout the library.  While this was mostly a
+  find-and-replace job, I'm bumping the version number to indicate the
+  API breakage.
+
+  I'd found that using the word "migration" got people thinking in terms
+  of ActiveRecord, which isn't quite the intended purpose of this
+  library.  SQrbL was written to manage the process of doing one-off
+  database conversions in a repeatable way.
+
+  (At raSANTIAGO, I helped a few organizations switch from other
+  programs to CiviCRM, and I wrote SQrbL to help me keep track of all
+  the various steps involved in importing their legacy
+  constituent-management data to CiviCRM.)
+
+== 0.1.3 / 2009-08-07
+
+* Added Step#helpers method for code cosmetics.
+
 == 0.1.2 / 2009-08-06
 
-* No changes -- just want to make sure the latest release is actually usable after flailing around trying to use the 'bones' and 'rubyforge' gems.
+* No changes -- just want to make sure the latest release is actually
+  usable after flailing around trying to use the 'bones' and 'rubyforge'
+  gems.
 
 == 0.1.0 / 2009-08-06
 

data/README.txt

@@ -1,4 +1,4 @@
-== SQrbL:  Making database migrations suck less since July 2009!
+== SQrbL:  Making database conversions suck less since July 2009!
 
 Copyright (c) 2009 raSANTIAGO + Associates LLC (http://www.rasantiago.com)
 
@@ -10,13 +10,13 @@ SQrbL's creator and primary author is Sam Livingston-Gray.
     
 == DESCRIPTION:
 
-SQrbL was created to help manage an extremely specific problem:  managing SQL-based database migrations.
+SQrbL was created to help manage an extremely specific problem:  managing SQL-based database conversions.
 
 In essence, SQrbL is a tool for managing multiple SQL queries using Ruby.  SQrbL borrows some terminology and ideas from ActiveRecord's schema migrations, but where ActiveRecord manages changes to your database schema over time, SQrbL was written to manage the process of transforming your data from one schema to another.  (Of course, you could use SQrbL for the former case as well -- just use it to write DDL queries -- but ActiveRecord has better tools for figuring out which migrations have already been applied.)
 
 ===How It Works:
 
-You describe the steps in your migration in a SQrbL file.  Each step can produce as much or as little SQL as you like.  Each step has an "up" and a "down" part -- so you can do and undo each step as many times as you need to, until you get it just right.  When you run your SQrbL file, it creates a tree of *.sql files containing the output from your migration steps, one file per step.  It also creates the combined files "all_up.sql" and "all_down.sql"; these contain all of your steps combined into one giant file so that, when Cutover Day arrives, you can copy/paste the whole thing into your SQL client and run it all at once.
+You describe the steps in your conversion in a SQrbL file.  Each step can produce as much or as little SQL as you like.  Each step has an "up" and a "down" part -- so you can do and undo each step as many times as you need to, until you get it just right.  When you run your SQrbL file, it creates a tree of *.sql files containing the output from your conversion steps, one file per step.  It also creates the combined files "all_up.sql" and "all_down.sql"; these contain all of your steps combined into one giant file so that, when Cutover Day arrives, you can copy/paste the whole thing into your SQL client and run it all at once.
 
 ===Why It Exists:
 
@@ -26,13 +26,21 @@ SQL is a fantastic DSL for describing queries.  It's not bad at doing transforma
 
 SQL.rb seemed a bit too pretentious, so I went with SQrbL -- as in, "You got Ruby in my SQL."  I pronounce it "squirble" (rhymes with "squirrel").  The proper capitalization can be annoying to type, so I've aliased the SQrbL class as Sqrbl.
 
+Note:  While not quite a literal pronunciation, "Screwball" is an accepted alternate.  Mostly 'cause it's funny.
+
 == SYNOPSIS:
 
 <i>(Note that, in the following code sample, I'm using the convention that do/end blocks are used primarily for their side effects, and curly-brace blocks are used primarily for their return value.)</i>
 
-  Sqrbl.migration "Convert from old widgets to new widgets" do
+  Sqrbl.conversion "Convert from old widgets to new widgets" do
     set_output_directory '/path/to/generated/sql'
 
+    helpers do
+      def widget_import_note
+        '"Imported from old_widgets"'
+      end
+    end
+
     group "Widgets" do
       step "Create widgets" do
         up do
@@ -42,7 +50,7 @@ SQL.rb seemed a bit too pretentious, so I went with SQrbL -- as in, "You got Rub
                 insert_into("new_widgets", {
                   :name     => 'widget_name',
                   :part_num => 'CONCAT("X_", part_number)',
-                  :note     => '"Imported from old_widgets"',
+                  :note     => widget_import_note,
                 })
               }
               FROM old_widgets
@@ -59,7 +67,7 @@ SQL.rb seemed a bit too pretentious, so I went with SQrbL -- as in, "You got Rub
     end
   end
 
-The above code sample describes a migration with one step:  migrating the data in an `old_widgets` table to a `new_widgets` table.  When run, this will generate a set of *.sql files in the directory /path/to/generated/sql.
+The above code sample describes a conversion with one step:  moving the data in an `old_widgets` table to a `new_widgets` table.  When run, this will generate a set of *.sql files in the directory /path/to/generated/sql.
 
 == REQUIREMENTS:
 

data/TODO.txt

@@ -1,11 +1,12 @@
+- Change verbiage: "conversion" instead of "migration".
+
+- Writers should create some sort of output to let you know that something happened.
+
 - bin/sqrbl should create an empty SQrbL file with the following simple template:
     require 'rubygems'
     require 'sqrbl'
-    Sqrbl.migration do
+    Sqrbl.conversion do
       # (copy the rest from README.txt)
     end
 
-- Writers should create some sort of output to let you know that something happened.
-
-- Define #helper(&block) as a simple wrapper to instance_eval on the same object.  (Purpose:  allow you to define helpers in a block that can be code-folded.)
-
+- Add some string-munging for pluralize(n, thing, things), and possibly move #unix_name into the string-munging module.

data/lib/sqrbl.rb

@@ -2,11 +2,11 @@
 # For more information, please see README.txt and LICENSE.txt in the project's root directory.
 #
 # Most of this was autogenerated by the 'bones' gem.
-# The primary domain-specific method of interest here is Sqrbl.migration.
+# The primary domain-specific method of interest here is Sqrbl.conversion.
 module Sqrbl
 
   # :stopdoc:
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
   LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
   PATH    = ::File.dirname(LIBPATH) + ::File::SEPARATOR
   # :startdoc:
@@ -46,22 +46,22 @@ module Sqrbl
     Dir.glob(search_me).sort.each {|rb| require rb}
   end
 
-  # Convenience method:  builds and writes a migration in one go.
-  def self.migration(&block)
-    returning(build_migration(&block)) do |mig|
-      write_migration!(mig)
+  # Convenience method:  builds and writes a conversion in one go.
+  def self.conversion(&block)
+    returning(build_conversion(&block)) do |cvn|
+      write_conversion!(cvn)
     end
   end
 
-  # Convenience method:  Calls Sqrbl::Migration.build and passes it the given block.
-  def self.build_migration(&block)
-    Sqrbl::Migration.build(&block)
+  # Convenience method:  Calls Sqrbl::Conversion.build and passes it the given block.
+  def self.build_conversion(&block)
+    Sqrbl::Conversion.build(&block)
   end
 
-  # Convenience method:  Write a Migration using all subclasses of BaseMigrationWriter.
-  def self.write_migration!(migration)
-    BaseMigrationWriter.subclasses.each do |writer_class|
-      writer_class.write_migration!(migration)
+  # Convenience method:  Write a Conversion using all subclasses of BaseConversionWriter.
+  def self.write_conversion!(conversion)
+    BaseConversionWriter.subclasses.each do |writer_class|
+      writer_class.write_conversion!(conversion)
     end
   end
 

data/lib/sqrbl/{base_migration_writer.rb → base_conversion_writer.rb}

@@ -1,9 +1,9 @@
 require 'fileutils'
 
 module Sqrbl
-  # Base class for other migration writers.
-  class BaseMigrationWriter
-    attr_accessor :migration, :output_directory
+  # Base class for other conversion writers.
+  class BaseConversionWriter
+    attr_accessor :conversion, :output_directory
 
     class << self
       # List all classes that inherit from this one
@@ -16,23 +16,23 @@ module Sqrbl
       end
 
       # Convenience method:  create a new instance and invoke <tt>write!</tt> on it.
-      def write_migration!(migration)
-        new(migration).write!
+      def write_conversion!(conversion)
+        new(conversion).write!
       end
     end
 
-    def initialize(migration) #:nodoc:
-      @migration = migration
+    def initialize(conversion) #:nodoc:
+      @conversion = conversion
       set_default_output_dir!
     end
 
     protected
     # Set the output_directory attribute based on the output_directory or creating_file
-    # attributes of the given migration, in that order
+    # attributes of the given conversion, in that order
     def set_default_output_dir!
-      raise "No migration given!" unless migration
-      self.output_directory ||= migration.output_directory
-      self.output_directory ||= migration.creating_file && File.join(File.expand_path(File.dirname(migration.creating_file)), 'sql')
+      raise "No conversion given!" unless conversion
+      self.output_directory ||= conversion.output_directory
+      self.output_directory ||= conversion.creating_file && File.join(File.expand_path(File.dirname(conversion.creating_file)), 'sql')
       raise "Unable to determine output directory!" unless self.output_directory
     end
 

data/lib/sqrbl/{migration.rb → conversion.rb}

@@ -4,27 +4,27 @@
 
 module Sqrbl
 
-  # The Migration class doesn't do much on its own; it's basically just a
+  # The Conversion class doesn't do much on its own; it's basically just a
   # container for a list of Group objects, which are created using #group.
   #
   # Note also that because Group includes the MethodMissingDelegation mixin,
-  # instance methods defined in the block given to Migration.build will become
+  # instance methods defined in the block given to Conversion.build will become
   # available to all groups (and their related objects) that belong to a
-  # Migration instance.  For more information, see MethodMissingDelegation.
-  class Migration
+  # Conversion instance.  For more information, see MethodMissingDelegation.
+  class Conversion
     attr_reader :groups, :creating_file, :output_directory
 
     include HasTodos
 
-    # Creates a new Migration object and evaluates the block in its binding.
+    # Creates a new Conversion object and evaluates the block in its binding.
     # As a result, any methods called within the block will affect the state
     # of that object (and that object only).
     #
-    # <i>(Eventually, this will also pass the migration to a helper object that
+    # <i>(Eventually, this will also pass the conversion to a helper object that
     # will create the tree of output *.sql files.)</i>
     def self.build(&block)
-      returning(self.new) do |migration|
-        migration.instance_eval(&block)
+      returning(self.new) do |conversion|
+        conversion.instance_eval(&block)
       end
     end
 
@@ -44,17 +44,17 @@ module Sqrbl
       groups << Group.new(self, name, &block)
     end
 
-    # Convenience method:  iterate all StepPair objects in the migration
+    # Convenience method:  iterate all StepPair objects in the conversion
     def step_pairs
       groups.map(&:steps).flatten
     end
 
-    # Convenience method:  iterate all 'up' steps in the migration
+    # Convenience method:  iterate all 'up' steps in the conversion
     def up_steps
       step_pairs.map(&:up_step)
     end
 
-    # Convenience method:  iterate all 'down' steps in the migration
+    # Convenience method:  iterate all 'down' steps in the conversion
     def down_steps
       step_pairs.map(&:down_step)
     end

data/lib/sqrbl/group.rb

@@ -3,21 +3,21 @@
 
 
 module Sqrbl
-  # Like the Migration class, Group doesn't do much on its own.
+  # Like the Conversion class, Group doesn't do much on its own.
   # It's basically a container for a list of StepPair objects, which are created using #step.
   #
-  # Group delegates +method_missing+ calls to its +migration+ object.
+  # Group delegates +method_missing+ calls to its +conversion+ object.
   # For more information, see MethodMissingDelegation.
   class Group
-    attr_reader :migration, :description, :block, :steps
+    attr_reader :conversion, :description, :block, :steps
 
     include Sqrbl::ExpectsBlockWithNew
     include Sqrbl::MethodMissingDelegation
-    delegate_method_missing_to :migration
+    delegate_method_missing_to :conversion
     include HasTodos
 
-    def initialize(migration, description, options = {}, &block)
-      @migration   = migration
+    def initialize(conversion, description, options = {}, &block)
+      @conversion   = conversion
       @description = description
       @block       = lambda(&block)
       @steps       = []

data/lib/sqrbl/{individual_migration_writer.rb → individual_conversion_writer.rb}

@@ -1,7 +1,7 @@
 module Sqrbl
-  # Writes one [numbered] file per migration step, in two main directories:  sql/up/ and sql/down/.
-  # Migration steps are contained in a [numbered] subfolder that corresponds to the group.
-  class IndividualMigrationWriter < BaseMigrationWriter
+  # Writes one [numbered] file per conversion step, in two main directories:  sql/up/ and sql/down/.
+  # Conversion steps are contained in a [numbered] subfolder that corresponds to the group.
+  class IndividualConversionWriter < BaseConversionWriter
     # Prepare the up and down directories and populate them with individual files.
     #
     # WARNING:  <b>RECURSIVELY DELETES ALL FILES</b> in output_directory/up and output_directory/down unless passed :safe_mode => true in the options hash!
@@ -22,7 +22,7 @@ module Sqrbl
 
     # Write out the contents of the individual files, each in its group's subfolder
     def write_individual_files!
-      migration.groups.each_with_index do |group, idx|
+      conversion.groups.each_with_index do |group, idx|
         group_dir   = "%0#{group_num_width}d_%s" % [idx + 1, group.unix_name]
         up_subdir   = File.join(output_directory, 'up',   group_dir)
         down_subdir = File.join(output_directory, 'down', group_dir)
@@ -38,7 +38,7 @@ module Sqrbl
     end
 
     def group_num_width # :nodoc:
-      migration.groups.length.to_s.length
+      conversion.groups.length.to_s.length
     end
 
     def step_num_width(step) # :nodoc:

data/lib/sqrbl/mixins/method_missing_delegation.rb

@@ -7,7 +7,7 @@ module Sqrbl
   # references to one another.  The graph will have the following general shape
   # (where --> indicates a relationship that is generally one-to-many):
   #
-  # Migration --> Group --> StepPair --> Step
+  # Conversion --> Group --> StepPair --> Step
   #
   # Also, because these various objects are created with blocks that are
   # instance_eval'd, those blocks can define helper methods that will be
@@ -16,14 +16,14 @@ module Sqrbl
   # Taken together, these two features (back-references and instance_eval)
   # let us provide a useful facility for defining helper methods inside a
   # block, and accessing them using scoping rules that work in an intuitive
-  # manner.  For example, if a Migration defines a method #foo, which is
+  # manner.  For example, if a Conversion defines a method #foo, which is
   # later called from inside a Step's block, the Step can catch that call
   # using method_missing and delegate it to its StepPair, which in turn
-  # will delegate to its Group, which in turn will delegate to its Migration.
+  # will delegate to its Group, which in turn will delegate to its Conversion.
   #
   # Confused yet?  Here's a slightly modified version of the example in README.txt:
   #
-  #   Sqrbl.migration "Convert from old widgets to new widgets" do
+  #   Sqrbl.conversion "Convert from old widgets to new widgets" do
   #     def new_widget_insert()
   #       insert_into("new_widgets", {
   #         :name     => 'widget_name',

data/lib/sqrbl/step.rb

@@ -54,6 +54,13 @@ EOF
       eval_block_on_initialize(options)
     end
 
+    # This method is purely cosmetic.  If you want to define a number
+    # of helpers and use your editor's code-folding features to
+    # collapse them all together, define them in a +helper+ block.
+    def helpers(&block)
+      yield
+    end
+
     # Writes a commented-out Todo item to +output+.
     #
     # Also, creates a Todo object that may be used to create console

data/lib/sqrbl/{unified_migration_writer.rb → unified_conversion_writer.rb}

@@ -2,7 +2,7 @@ module Sqrbl
   # Writes two files:  output_directory/all_up.sql and output_directory/all_down.sql.
   # * output_directory/all_up.sql contains all 'up' steps, in creation order.
   # * output_directory/all_down.sql contains all 'down' steps, in reverse creation order.
-  class UnifiedMigrationWriter < BaseMigrationWriter
+  class UnifiedConversionWriter < BaseConversionWriter
     # Create all_up.sql and all_down.sql in output_directory.
     def write!
       ensure_dir_exists(output_directory)
@@ -12,12 +12,12 @@ module Sqrbl
 
     # Output from all 'up' steps, in creation order
     def all_up_steps_output
-      migration.up_steps.map(&:output).join
+      conversion.up_steps.map(&:output).join
     end
 
     # Output from all 'down' steps, in reverse creation order
     def all_down_steps_output
-      migration.down_steps.reverse.map(&:output).join
+      conversion.down_steps.reverse.map(&:output).join
     end
 
     protected

data/spec/functional/base_conversion_writer_spec.rb

@@ -0,0 +1,12 @@
+require File.join(File.dirname(__FILE__), %w[.. spec_helper])
+
+include Sqrbl
+
+describe BaseConversionWriter do
+  it "should know what its subclasses are" do
+    BaseConversionWriter.subclasses.should == [
+      IndividualConversionWriter,
+      UnifiedConversionWriter,
+    ]
+  end
+end

data/spec/functional/{individual_migration_writer_spec.rb → individual_conversion_writer_spec.rb}

@@ -2,9 +2,9 @@ require File.join(File.dirname(__FILE__), %w[.. spec_helper])
 
 include Sqrbl
 
-describe IndividualMigrationWriter do
+describe IndividualConversionWriter do
   before(:each) do
-    @mig = Sqrbl.build_migration do
+    @cvn = Sqrbl.build_conversion do
       group 'Group one' do
         step 'Step one' do
           up   { write 'Step one up'   }
@@ -14,7 +14,7 @@ describe IndividualMigrationWriter do
     end
 
     @base_dir = File.expand_path(File.join(File.dirname(__FILE__), 'sql'))
-    @writer = IndividualMigrationWriter.new(@mig)
+    @writer = IndividualConversionWriter.new(@cvn)
   end
 
   it "should have a output_directory attribute" do
@@ -36,9 +36,9 @@ describe IndividualMigrationWriter do
     end
   end
 
-  describe "for a migration with two groups and three steps" do
+  describe "for a conversion with two groups and three steps" do
     before(:each) do
-      @mig = Sqrbl.build_migration do
+      @cvn = Sqrbl.build_conversion do
         group 'Group one' do
           step 'Step one' do
             up   { write 'Step one up'   }
@@ -58,11 +58,11 @@ describe IndividualMigrationWriter do
       end
 
       @base_dir = File.expand_path(File.join(File.dirname(__FILE__), 'sql'))
-      @writer = IndividualMigrationWriter.new(@mig)
+      @writer = IndividualConversionWriter.new(@cvn)
     end
 
     it "should create a separate subdirectory in [output_directory]/up for each group" do
-      @mig.groups.each_with_index do |group, idx|
+      @cvn.groups.each_with_index do |group, idx|
         group_dir   = "#{idx + 1}_#{group.unix_name}"
         up_subdir   = File.join(@writer.output_directory, 'up',   group_dir)
         down_subdir = File.join(@writer.output_directory, 'down', group_dir)
@@ -76,7 +76,7 @@ describe IndividualMigrationWriter do
     end
 
     it "should create a separate file for each step, in the subdirectory for that step's group" do
-      @mig.groups.each_with_index do |group, idx|
+      @cvn.groups.each_with_index do |group, idx|
         group_dir     = "#{idx + 1}_#{group.unix_name}"
         up_subdir   = File.join(@writer.output_directory, 'up',   group_dir)
         down_subdir = File.join(@writer.output_directory, 'down', group_dir)
@@ -93,9 +93,9 @@ describe IndividualMigrationWriter do
     end
   end
 
-  describe "for a migration with 10 groups" do
+  describe "for a conversion with 10 groups" do
     before(:each) do
-      @mig = Sqrbl.build_migration do
+      @cvn = Sqrbl.build_conversion do
         group 'Group one' do
           step 'Step one' do
             up   { write 'Step one up'   }
@@ -158,7 +158,7 @@ describe IndividualMigrationWriter do
         end
       end
 
-      @writer = IndividualMigrationWriter.new(@mig)
+      @writer = IndividualConversionWriter.new(@cvn)
     end
 
     it "should left-fill the group numbers with zeros" do

data/spec/functional/{unified_migration_writer_spec.rb → unified_conversion_writer_spec.rb}

@@ -2,26 +2,26 @@ require File.join(File.dirname(__FILE__), %w[.. spec_helper])
 
 include Sqrbl
 
-describe UnifiedMigrationWriter do
-  describe "for a migration with #output_directory set" do
-    it "should set #output_directory from the migration's #output_directory" do
-      mig = mock('Migration', :output_directory => '/path/to/sql', :creating_file => nil)
-      writer = UnifiedMigrationWriter.new(mig)
-      writer.output_directory.should == mig.output_directory
+describe UnifiedConversionWriter do
+  describe "for a conversion with #output_directory set" do
+    it "should set #output_directory from the conversion's #output_directory" do
+      cvn = mock('Conversion', :output_directory => '/path/to/sql', :creating_file => nil)
+      writer = UnifiedConversionWriter.new(cvn)
+      writer.output_directory.should == cvn.output_directory
     end
   end
 
-  describe "for a migration with output_directory blank" do
-    it "should set #output_directory using the dirname of the migration's #creating_file, plus /sql" do
-      mig = mock('Migration', :output_directory => nil, :creating_file => '/path/to/some/sqrbl_file.rb')
-      writer = UnifiedMigrationWriter.new(mig)
+  describe "for a conversion with output_directory blank" do
+    it "should set #output_directory using the dirname of the conversion's #creating_file, plus /sql" do
+      cvn = mock('Conversion', :output_directory => nil, :creating_file => '/path/to/some/sqrbl_file.rb')
+      writer = UnifiedConversionWriter.new(cvn)
       writer.output_directory.should == '/path/to/some/sql'
     end
   end
 
-  describe "for a migration with two groups and three steps" do
+  describe "for a conversion with two groups and three steps" do
     before(:each) do
-      @mig = Sqrbl.build_migration do
+      @cvn = Sqrbl.build_conversion do
         group 'Group one' do
           step 'Step one' do
             up   { write 'Step one up'   }
@@ -41,7 +41,7 @@ describe UnifiedMigrationWriter do
       end
 
       @base_dir = File.expand_path(File.join(File.dirname(__FILE__), 'sql'))
-      @writer = UnifiedMigrationWriter.new(@mig)
+      @writer = UnifiedConversionWriter.new(@cvn)
     end
 
     it "should not create the target directory if it already exists" do
@@ -65,7 +65,7 @@ describe UnifiedMigrationWriter do
     end
 
     it "should combine the contents of all up steps in order" do
-      @writer.all_up_steps_output.should == @mig.up_steps.map(&:output).join
+      @writer.all_up_steps_output.should == @cvn.up_steps.map(&:output).join
     end
 
     it "should write the contents of all up steps to the all_up.sql file" do
@@ -83,7 +83,7 @@ describe UnifiedMigrationWriter do
     end
 
     it "should combine the contents of all down steps in REVERSE order" do
-      @writer.all_down_steps_output.should == @mig.down_steps.reverse.map(&:output).join
+      @writer.all_down_steps_output.should == @cvn.down_steps.reverse.map(&:output).join
     end
 
     it "should write the contents of all down steps to the all_down.sql file" do

data/spec/spec_helper.rb

@@ -19,7 +19,7 @@ Spec::Runner.configure do |config|
 end
 
 
-# Stub out the various things that the migration writers do.
+# Stub out the various things that the conversion writers do.
 # Call this after defining the mocks you care about (because mocks created first take precedence).
 # Then, calling #write! shouldn't actually touch the filesystem.
 def stub_out_file_creation

data/spec/unit/{migration_spec.rb → conversion_spec.rb}

@@ -2,35 +2,35 @@ require File.join(File.dirname(__FILE__), %w[.. spec_helper])
 
 include Sqrbl
 
-describe Migration do
-  describe "A new migration" do
+describe Conversion do
+  describe "A new conversion" do
     it "should know the file that created it" do
-      mig = Migration.new
-      mig.creating_file.should == File.expand_path(__FILE__)
+      cvn = Conversion.new
+      cvn.creating_file.should == File.expand_path(__FILE__)
     end
   end
 
-  describe "A migration built with Migration.build" do
+  describe "A conversion built with Conversion.build" do
     it "should still know the file that created it" do
-      mig = Migration.build {}
-      mig.creating_file.should == File.expand_path(__FILE__)
+      cvn = Conversion.build {}
+      cvn.creating_file.should == File.expand_path(__FILE__)
     end
 
     describe "when the block calls #group once" do
       it "should have one group with the proper description" do
-        mig = Migration.build do
+        cvn = Conversion.build do
           group "first group" do
             'hello world'
           end
         end
-        mig.groups.all? { |group| group.should be_kind_of(Group) }
-        mig.groups.map(&:description).should == ['first group']
+        cvn.groups.all? { |group| group.should be_kind_of(Group) }
+        cvn.groups.map(&:description).should == ['first group']
       end
     end
 
     describe "when the block calls #group twice" do
       it "should have two group with the proper descriptions" do
-        mig = Migration.build do
+        cvn = Conversion.build do
           group "first group" do
             'hello world'
           end
@@ -38,31 +38,31 @@ describe Migration do
             'goodbye world'
           end
         end
-        mig.groups.all? { |group| group.should be_kind_of(Group) }
-        mig.groups.map(&:description).should == ['first group', 'second group']
+        cvn.groups.all? { |group| group.should be_kind_of(Group) }
+        cvn.groups.map(&:description).should == ['first group', 'second group']
       end
     end
 
     it "should pass itself as a dependency to any group it builds" do
-      mig = Migration.build do
+      cvn = Conversion.build do
         group("first group"    ) { '' }
         group("second group"   ) { '' }
         group("group the third") { '' }
       end
 
-      mig.groups.all? { |group| group.migration.should == mig }
+      cvn.groups.all? { |group| group.conversion.should == cvn }
     end
   end
 
   describe "when #todo is called" do
     it "should create a Todo object that saves the message" do
-      mig = Migration.build { todo 'foo' }
-      mig.todos.map(&:message).should == ['foo']
+      cvn = Conversion.build { todo 'foo' }
+      cvn.todos.map(&:message).should == ['foo']
     end
 
     it "should create a Todo object that saves the location of the #todo call" do
-      mig = Migration.build { todo 'foo' }; line_num = __LINE__
-      mig.todos.first.location.should == [__FILE__, line_num].join(':')
+      cvn = Conversion.build { todo 'foo' }; line_num = __LINE__
+      cvn.todos.first.location.should == [__FILE__, line_num].join(':')
     end
   end
 end

data/spec/unit/group_spec.rb

@@ -4,26 +4,26 @@ include Sqrbl
 
 describe Group do
   before(:each) do
-    @mig = mock('Migration')
+    @cvn = mock('Conversion')
   end
 
   it "should evaluate the block in its own context" do
-    group = Group.new(@mig, "foo", :skip_block_evaluation => true) do
+    group = Group.new(@cvn, "foo", :skip_block_evaluation => true) do
       hello_world()
     end
     group.should_receive(:hello_world)
     group.send(:evaluate_block!)
   end
 
-  it "should delegate method_missing calls back to the migration object" do
-    @mig.should_receive(:goodbye_world)
-    group = Group.new(@mig, "foo") do
+  it "should delegate method_missing calls back to the conversion object" do
+    @cvn.should_receive(:goodbye_world)
+    group = Group.new(@cvn, "foo") do
       goodbye_world()
     end
   end
 
   it "methods defined in the group block should become available as methods on the Group instance" do
-    group = Group.new(@mig, "foo") do
+    group = Group.new(@cvn, "foo") do
       def hello_world
         "Hello, world!"
       end
@@ -34,12 +34,12 @@ describe Group do
 
   describe "when #todo is called" do
     it "should create a Todo object that saves the message" do
-      group = Group.new(@mig, 'foo') { todo 'bar' }
+      group = Group.new(@cvn, 'foo') { todo 'bar' }
       group.todos.map(&:message).should == ['bar']
     end
 
     it "should create a Todo object that saves the location of the #todo call" do
-      group = Group.new(@mig, 'foo') { todo 'bar' }; line_num = __LINE__
+      group = Group.new(@cvn, 'foo') { todo 'bar' }; line_num = __LINE__
       group.todos.first.location.should == [__FILE__, line_num].join(':')
     end
   end
@@ -47,7 +47,7 @@ describe Group do
   describe "when #step is called" do
     it "should create a StepPair object and pass it the group, the description, and the block arg" do
       test_self = self
-      group = Group.new(@mig, "foo") do
+      group = Group.new(@cvn, "foo") do
         StepPair.should_receive(:new).with(self, 'do something').and_yield # Look weird?  See ./README.txt
         step('do something') {}
       end
@@ -56,18 +56,18 @@ describe Group do
 
   describe :valid? do
     it "should return false if steps is empty" do
-      group = Group.new(@mig, "foo") {}
+      group = Group.new(@cvn, "foo") {}
       group.should_not be_valid
     end
 
     it "should return false if steps is not empty, but any step is invalid" do
-      group = Group.new(@mig, "foo") { step("foo") {} }
+      group = Group.new(@cvn, "foo") { step("foo") {} }
       group.steps.map(&:valid?).should include(false)
       group.should_not be_valid
     end
 
     it "should return true if steps is not empty, and all steps are themselves valid" do
-      group = Group.new(@mig, "foo") do
+      group = Group.new(@cvn, "foo") do
         step("foo") do
           up {}
           down {}
@@ -78,7 +78,7 @@ describe Group do
   end
 
   it "should have a unix_name property that consists of the regular name with characters sanitized" do
-    group = Group.new(@mig, "This be a test, matey!  ARRR!!") {}
+    group = Group.new(@cvn, "This be a test, matey!  ARRR!!") {}
     group.unix_name.should == 'this_be_a_test_matey_arrr'
   end
 

data/spec/unit/sqrbl_spec.rb

@@ -3,25 +3,25 @@ require File.join(File.dirname(__FILE__), %w[.. spec_helper])
 include Sqrbl
 
 describe Sqrbl do
-  it ".build_migration should return an instance of Sqrbl::Migration" do
-    migration = Sqrbl.build_migration { 'hello, world!' }
-    migration.should be_kind_of(Sqrbl::Migration)
+  it ".build_conversion should return an instance of Sqrbl::Conversion" do
+    conversion = Sqrbl.build_conversion { 'hello, world!' }
+    conversion.should be_kind_of(Sqrbl::Conversion)
   end
 
-  it ".migration should take the return value from Sqrbl::Migration.build and pass it to write_migration" do
-    mig = mock('Migration')
-    Migration.should_receive(:build).and_yield.and_return(mig)
-    Sqrbl.should_receive(:write_migration!).with(mig)
-    Sqrbl.migration { 'Hello, world!' }
+  it ".conversion should take the return value from Sqrbl::Conversion.build and pass it to write_conversion" do
+    cvn = mock('Conversion')
+    Conversion.should_receive(:build).and_yield.and_return(cvn)
+    Sqrbl.should_receive(:write_conversion!).with(cvn)
+    Sqrbl.conversion { 'Hello, world!' }
   end
 
-  describe :write_migration! do
-    it "should take a migration object and pass it off to any and all writers that exist" do
-      mig = mock('Migration')
-      BaseMigrationWriter.subclasses.each do |writer_class|
-        writer_class.should_receive(:write_migration!).with(mig)
+  describe :write_conversion! do
+    it "should take a conversion object and pass it off to any and all writers that exist" do
+      cvn = mock('Conversion')
+      BaseConversionWriter.subclasses.each do |writer_class|
+        writer_class.should_receive(:write_conversion!).with(cvn)
       end
-      Sqrbl.write_migration!(mig)
+      Sqrbl.write_conversion!(cvn)
     end
   end
 

data/spec/unit/step_spec.rb

@@ -32,6 +32,18 @@ describe Step do
     step.hello_world.should == "Hello, world!"
   end
 
+  it "methods defined in a #helpers block should become available as methods on the Step instance" do
+    step = Step.new(@pair) do
+      helpers do
+        def hello_world
+          "Hello, world!"
+        end
+      end
+    end
+    step.should respond_to(:hello_world)
+    step.hello_world.should == "Hello, world!"
+  end
+
   describe "when #todo is called" do
     it "should create a Todo object that saves the message" do
       step = Step.new(@pair) { todo 'foo' }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: sqrbl
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors: 
 - Sam Livingston-Gray
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-08-06 00:00:00 -07:00
+date: 2009-09-04 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -23,7 +23,7 @@ dependencies:
         version: 2.5.1
     version: 
 description: |-
-  SQrbL was created to help manage an extremely specific problem:  managing SQL-based database migrations.
+  SQrbL was created to help manage an extremely specific problem:  managing SQL-based database conversions.
   
   In essence, SQrbL is a tool for managing multiple SQL queries using Ruby.  SQrbL borrows some terminology and ideas from ActiveRecord's schema migrations, but where ActiveRecord manages changes to your database schema over time, SQrbL was written to manage the process of transforming your data from one schema to another.  (Of course, you could use SQrbL for the former case as well -- just use it to write DDL queries -- but ActiveRecord has better tools for figuring out which migrations have already been applied.)
 email: geeksam@gmail.com
@@ -48,24 +48,24 @@ files:
 - lib/core_exts/object.rb
 - lib/core_exts/symbol.rb
 - lib/sqrbl.rb
-- lib/sqrbl/base_migration_writer.rb
+- lib/sqrbl/base_conversion_writer.rb
 - lib/sqrbl/call_stack.rb
+- lib/sqrbl/conversion.rb
 - lib/sqrbl/group.rb
-- lib/sqrbl/individual_migration_writer.rb
-- lib/sqrbl/migration.rb
+- lib/sqrbl/individual_conversion_writer.rb
 - lib/sqrbl/mixins/expects_block_with_new.rb
 - lib/sqrbl/mixins/has_todos.rb
 - lib/sqrbl/mixins/method_missing_delegation.rb
 - lib/sqrbl/step.rb
 - lib/sqrbl/step_pair.rb
-- lib/sqrbl/unified_migration_writer.rb
+- lib/sqrbl/unified_conversion_writer.rb
 - spec/README.txt
-- spec/functional/base_migration_writer_spec.rb
-- spec/functional/individual_migration_writer_spec.rb
-- spec/functional/unified_migration_writer_spec.rb
+- spec/functional/base_conversion_writer_spec.rb
+- spec/functional/individual_conversion_writer_spec.rb
+- spec/functional/unified_conversion_writer_spec.rb
 - spec/spec_helper.rb
+- spec/unit/conversion_spec.rb
 - spec/unit/group_spec.rb
-- spec/unit/migration_spec.rb
 - spec/unit/sqrbl_spec.rb
 - spec/unit/step_pair_spec.rb
 - spec/unit/step_spec.rb
@@ -110,6 +110,6 @@ rubyforge_project: sqrbl
 rubygems_version: 1.3.4
 signing_key: 
 specification_version: 3
-summary: "SQrbL was created to help manage an extremely specific problem:  managing SQL-based database migrations"
+summary: "SQrbL was created to help manage an extremely specific problem:  managing SQL-based database conversions"
 test_files: []
 

data/spec/functional/base_migration_writer_spec.rb

@@ -1,12 +0,0 @@
-require File.join(File.dirname(__FILE__), %w[.. spec_helper])
-
-include Sqrbl
-
-describe BaseMigrationWriter do
-  it "should know what its subclasses are" do
-    BaseMigrationWriter.subclasses.should == [
-      IndividualMigrationWriter,
-      UnifiedMigrationWriter,
-    ]
-  end
-end