hummingbird 1.0.0 → 1.0.1

data/.gitignore

@@ -12,5 +12,9 @@ Gemfile.lock
 # SimpleCov
 /coverage/
 
+# Yard
+/.yardoc/
+/doc/
+
 # OS X
 .DS_Store

data/Rakefile

@@ -1,5 +1,6 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'yard'
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
@@ -7,4 +8,6 @@ Rake::TestTask.new do |t|
   t.verbose = true
 end
 
+YARD::Rake::YardocTask.new
+
 task :default => :test

data/hummingbird.gemspec

@@ -22,10 +22,12 @@ DESC
   gem.add_dependency 'sequel'
   gem.add_dependency 'optimism'
 
-  gem.add_development_dependency 'rake'
-  gem.add_development_dependency 'minitest'
   gem.add_development_dependency 'guard'
   gem.add_development_dependency 'guard-minitest'
+  gem.add_development_dependency 'minitest'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'redcarpet'
   gem.add_development_dependency 'simplecov'
   gem.add_development_dependency 'sqlite3'
+  gem.add_development_dependency 'yard'
 end

data/lib/hummingbird.rb

@@ -3,5 +3,7 @@ require 'hummingbird/configuration'
 require 'hummingbird/plan'
 require 'hummingbird/database'
 
-class Hummingbird
+# Empty module to facilitate loading {Hummingbird::Configuration},
+# {Hummingbird::Database}, and {Hummingbird::Plan}.
+module Hummingbird
 end

data/lib/hummingbird/configuration.rb

@@ -1,10 +1,54 @@
 require 'optimism'
 
-class Hummingbird
+module Hummingbird
+  # Helper class to handle reading configuration options from YAML
+  # files.
   class Configuration
+    # The name of the default configuration file.
     CONFIG_FILE = 'hummingbird.yml'
+    # The name of the default user specific configuration file.  Used
+    # for overriding settings in the default configuration file, or
+    # providing values for settings missing from there.
     USER_CONFIG_FILE = '.hummingbird.yml'
 
+    # Provides access to the settings found in the configuration file,
+    # and user specific configuration file.  By default it will look
+    # for {CONFIG_FILE}, and {USER_CONFIG_FILE} in the specified
+    # `config_dir`.  These can be overridden.
+    #
+    # The YAML configuration files should be in the format:
+    #
+    #     ---
+    #     basedir: 'sql'
+    #     planfile: 'application.plan'
+    #     migrations_dir: 'migrations-dir'
+    #     migrations_table: 'application_migrations'
+    #     connection_string: 'sequel connection string'
+    #
+    # See the individual access methods for details about each
+    # setting.
+    #
+    # @see #basedir
+    # @see #planfile
+    # @see #migrations_dir
+    # @see #migrations_table
+    # @see #connection_string
+    #
+    # @param [String] config_dir The directory in which to look for
+    #   configuration files.
+    #
+    # @param [Hash] opts Overrides for the default configuration file
+    #   names and locations.
+    #
+    # @option opts [String] :config_file Override the default
+    #   configuration file name and location.  This can be either a
+    #   path relative to the `config_dir`, or an absolute path to the
+    #   configuration file.
+    #
+    # @option opts [String] :user_config_file Override the default
+    #   user specific configuration file name and location.  This can
+    #   be either a path relative to the `config_dir`, or an absolute
+    #   path to the configuration file.
     def initialize(config_dir,opts={})
       opts[:config_file]      ||= CONFIG_FILE
       opts[:user_config_file] ||= USER_CONFIG_FILE
@@ -17,22 +61,55 @@ class Hummingbird
       @config = Optimism.require(*config_file_names)
     end
 
+    # The directory on which to base relative paths of other settings.
+    # This directory itself is relative to `Dir.getwd` unless
+    # specified as an absolute path.  This defaults to '.' (the
+    # current working directory).
+    #
+    # @return [String] The absolute path to the directory specified in
+    #   the config file.
     def basedir
       @basedir ||= File.expand_path(@config[:basedir] || '.', @config_dir)
     end
 
+    # The file containing the list of migrations to be run in the
+    # order that they should be run.  This is relative to {#basedir}
+    # when specified in the configuration file, unless specified as an
+    # absolute path.  Defaults to `hummingbird.plan`.
+    #
+    # @see #basedir
+    #
+    # @return [String] The absolute path to the plan file.
     def planfile
       @planfile ||= File.expand_path(@config[:planfile] || 'hummingbird.plan', basedir)
     end
 
+    # The base directory for all migration files.  This is relative to
+    # {#basedir} when specified in the configuration file, unless
+    # specified as an absolute path.  Defaults to `migrations`.
+    #
+    # @see #basedir
+    #
+    # @return [String] The absolute path to the plan file.
     def migrations_dir
       @migrations_dir ||= File.expand_path(@config[:migrations_dir] || 'migrations', basedir)
     end
 
+    # The name of the migrations table used to keep track of which
+    # migrations have been successfully run, and when they were run.
+    # Defaults to `hummingbird_migrations`.
+    #
+    # @return [Symbol] The name of the migrations table as a symbol.
     def migrations_table
       @migrations_table ||= (@config[:migrations_table] || :hummingbird_migrations).to_sym
     end
 
+    # The {http://sequel.rubyforge.org/ Sequel} compatible connection
+    # string.  This has no default, and must be specified in the
+    # configuration file, or provided by another means.
+    #
+    # @return [String] Connection string to be passed to
+    #   {http://sequel.rubyforge.org/ Sequel}.
     def connection_string
       @connection_string ||= @config[:connection_string]
     end

data/lib/hummingbird/database.rb

@@ -1,21 +1,59 @@
 require 'sequel'
 
-class Hummingbird
+module Hummingbird
+  # Class to handle retrieving recorded migrations, as well as running
+  # new migrations and recording that they have been run.
   class Database
+    # @param [String] connection_string A
+    #   {http://sequel.rubyforge.org/ Sequel} compatible connection string.
+    #
+    # @param [Symbol] migrations_table The name of the table used to
+    #   keep track of migrations.
     def initialize(connection_string, migrations_table)
       @sequel_db                     = Sequel.connect(connection_string)
       @migrations_table_name         = migrations_table
       @prepared_run_migration_insert = nil
     end
 
+    # @return [true, false] Whether or not the migrations table is
+    #   present in the database.
     def initialized?
       @sequel_db.tables.include?(@migrations_table_name)
     end
 
+    # If the database has yet to be initialized with the migrations
+    # table, or if the migrations table has no recorded migrations,
+    # this will return an empty array.
+    #
+    # If there are recorded migrations, this will return an array
+    # of hashes.  Where the hashes have the following format:
+    #
+    #     {
+    #       :migration_name => 'name/of/migration.sql',
+    #       :run_on         => 1350683387
+    #     }
+    #
+    # `:migration_name` is the path of the migration file relative to
+    # the migrations directory.  `:run_on` is the time the migration
+    # was run, as a unix epoch.
+    #
+    # @return [Array<Hash{Symbol => String, Number}>] The list of
+    #   migrations that have already been run, along with when they
+    #   were run as a unix epoch.
     def already_run_migrations
       initialized? ? @sequel_db[@migrations_table_name].order(:run_on).to_a : []
     end
 
+    # Run the provided SQL in a transaction (provided the DB in
+    # question supports transactions).  If the SQL successfully runs,
+    # then also record the migration in the migration table.  The time
+    # recorded for the `run_on` of the migration is when the migration
+    # _finished_, not when it _started_.
+    #
+    # @param [String] name The name of the migration to run (as listed
+    #   in the .plan file).
+    #
+    # @param [String] sql The SQL to run.
     def run_migration(name,sql)
       @prepared_run_migration_insert ||= @sequel_db[@migrations_table_name].prepare(:insert, :record_migration, migration_name: :$name, run_on: :$date)
 

data/lib/hummingbird/plan.rb

@@ -2,27 +2,75 @@ require 'hummingbird/plan_error'
 
 require 'pathname'
 
-class Hummingbird
+module Hummingbird
+  # This is responsible for parsing the `.plan` file, and for
+  # verifying it against the migrations stored on disk.
   class Plan
-    attr_reader :migration_dir, :planned_files
-
+    # @return [String] The base directory for all of the migration
+    #   files referenced in the `.plan` file.
+    attr_reader :migration_dir
+
+    # This list has not been verified against the files on disk, or
+    # against the database in any way.
+    #
+    # @return [Array<String>] The list of all files referenced in the
+    #   `.plan` file.
+    attr_reader :planned_files
+
+    # @param [String] planfile The path to the `.plan` file.
+    #
+    # @param [String] migration_dir The path to the base directory for
+    #   all of the migration files referenced in the `.plan` file.
     def initialize(planfile, migration_dir)
       @planned_files = parse_plan(planfile)
       @migration_dir = migration_dir
     end
 
+    # @return [Array<String>] All files found under {#migration_dir}.
     def migration_files
       @migration_files ||= get_migration_files
     end
 
+    # @return [Array<String>] All {#migration_files} that are not in
+    #   {#planned_files}.
     def files_missing_from_plan
       migration_files - planned_files
     end
 
+    # If this list is not empty, there is probably an error as there
+    # are files that have been planned to run that do not exist on
+    # disk.
+    #
+    # @return [Array<String>] All {#planned_files} that are not in
+    #   {#migration_files}.
     def files_missing_from_migration_dir
       planned_files - migration_files
     end
 
+    # The names, and SQL for migrations that have yet to be run
+    # according to the list of already run migrations in
+    # `already_run_migrations`.
+    #
+    # This delegates to {#to_be_run_migration_file_names} and attaches
+    # the associated SQL to each migration.
+    #
+    # @see #to_be_run_migration_file_names
+    # @see Hummingbird::Database#already_run_migrations
+    #
+    # @param [Array<Hash{Symbol => String}>] already_run_migrations
+    #   This takes the same format array as output by
+    #   {Hummingbird::Database#already_run_migrations}.
+    #
+    # @return [Array<Hash{Symbol => String}>] This is the list of
+    #   migrations to be run, with their associated SQL as
+    #   `[{ :migration_name => String, :sql => String }, ...]`.
+    #
+    # @raise [Hummingbird::PlanError] If any of the
+    #   already_run_migrations are not in the list of planned files.
+    #
+    # @raise [Hummingbird::PlanError] If any of the
+    #   if any of the files in already_run_migrations appear out of
+    #   order relative to the planned files.
     def migrations_to_be_run(already_run_migrations)
       to_be_run_migration_file_names(already_run_migrations).map do |f|
         {
@@ -32,6 +80,25 @@ class Hummingbird
       end
     end
 
+    # It compares `already_run_migrations` against the list of planned
+    # migrations, and return the list of migrations that have yet to
+    # be run.
+    #
+    # @see Hummingbird::Database#already_run_migrations
+    #
+    # @param [Array<Hash{Symbol => String}>] already_run_migrations
+    #   This takes the same format array as output by
+    #   {Hummingbird::Database#already_run_migrations}.
+    #
+    # @return [Array<String>] The list of migration names that have
+    #   not yet been run.
+    #
+    # @raise [Hummingbird::PlanError] If any of the
+    #   already_run_migrations are not in the list of planned files.
+    #
+    # @raise [Hummingbird::PlanError] If any of the
+    #   if any of the files in already_run_migrations appear out of
+    #   order relative to the planned files.
     def to_be_run_migration_file_names(already_run_migrations)
       return planned_files if already_run_migrations.empty?
 
@@ -53,6 +120,12 @@ class Hummingbird
       files
     end
 
+    # Return the contents of the specified migration file.
+    #
+    # @param [String] migration_file The path to the desired migration
+    #   file, relative to {#migration_dir}.
+    #
+    # @return [String] The contents of the specified migration file.
     def get_migration_contents(migration_file)
       File.read(File.expand_path(migration_file, @migration_dir))
     end

data/lib/hummingbird/plan_error.rb

@@ -1,7 +1,34 @@
-class Hummingbird
+module Hummingbird
+  # Exception class with extra information available to examine what
+  # caused a validation error comparing the planned migrations against
+  # the recorded migrations.
   class PlanError < Exception
-    attr_reader :already_run_migrations, :planned_files
+    # @see Hummingbird::Database#already_run_migrations
+    #
+    # @return [Array<Hash{Symbol => String}>] The
+    #   {Hummingbird::Database#already_run_migrations} at the time of
+    #   the plan error.
+    attr_reader :already_run_migrations
 
+    # @see Hummingbird::Plan#planned_files
+    #
+    # @return [Array<String>] The {Hummingbird::Plan#planned_files} at
+    #   the time of the plan error.
+    attr_reader :planned_files
+
+    # @see Hummingbird::Database#already_run_migrations
+    # @see Hummingbird::Plan#planned_files
+    #
+    # @param [String] msg A user friendly explanation of what
+    #   triggered the PlanError.
+    #
+    # @param [Array<String>] planned_files The
+    #   {Hummingbird::Plan#planned_files} at the time of the plan
+    #   error.
+    #
+    # @param [Array<Hash{Symbol => String}>] already_run_migrations
+    #   The {Hummingbird::Database#already_run_migrations} at the time
+    #   of the plan error.
     def initialize(msg,planned_files,already_run_migrations)
       super(msg)
       @planned_files = planned_files

data/lib/hummingbird/version.rb

@@ -1,3 +1,4 @@
-class Hummingbird
-  VERSION = "1.0.0"
+module Hummingbird
+  # The version of Hummingbird.
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hummingbird
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-18 00:00:00.000000000 Z
+date: 2012-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -44,7 +44,23 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-minitest
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -76,7 +92,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: guard
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -92,7 +108,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: guard-minitest
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
@@ -139,6 +155,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Write your DB migrations in SQL and run them, hold the magic.
 email:
 - jacob@technosorcery.net
@@ -205,7 +237,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2384325587943083337
+      hash: -2188429721350549035
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24
@@ -237,3 +269,4 @@ test_files:
 - test/lib/hummingbird/version_test.rb
 - test/test_helper.rb
 - test/test_helper_test.rb
+has_rdoc: