has_named_bootstraps 0.0.2 → 0.1.0

data/README

@@ -1,16 +1,15 @@
 = HasNamedBootstraps
 
-*This is alpha code.  The API is subject (and almost certain) to change.  It shouldn't hurt your computer or data, but if it does, I am not obligated to do anything, even feel sorry for you.*
+This is alpha code.  The API is subject (and almost certain) to change.  It shouldn't hurt your computer or data, but if it does, I am not obligated to do anything, even feel sorry for you.
 
-has_named_bootstraps is a simple way to load bootstrapped records into class-level constants, and generate a list in another constant of all such bootstraps.  This is handy for generating <select>s and writing certain kinds of tests.
+has_named_bootstraps is a simple way to load bootstrapped records into class-level constants, making application-level data integrity easier.  You can also generate a list in another constant of all such bootstraps, which is handy for generating <select>s and writing certain kinds of tests.
 
-Getting the bootstrapped data in beforehand is up to you.  I like seed_fu (http://github.com/mbleigh/seed-fu) for this.
+Getting the bootstrapped data in beforehand is up to you.  I like seed_fu (http://github.com/mbleigh/seed-fu) for this personally.  If has_named_bootstraps can't find a bootstrap, by default it'll raise an error.  It's also possible to have it log a warning and continue, or continue silently.
 
 = Example
 
     class Department < ActiveRecord::Base
       has_named_bootstraps(
-        :VALID_DEPARTMENTS,    # name of the constant that'll hold the list of all bootstrap constants
         :R_AND_D         => 'R&D',
         :MARKETING       => 'Marketing', 
         :HANDSOME_DEVILS => 'Web Development' 
@@ -25,15 +24,37 @@ Getting the bootstrapped data in beforehand is up to you.  I like seed_fu (http:
     => #<Department id: 2, name: "Marketing">
     >> Department::HANDSOME_DEVILS
     => #<Department id: 3, name: "Web Development">
-    >> Department::VALID_DEPARTMENTS
-    => [#<Department id: 1, name: "R&D">, #<Department id: 2, name: "Marketing">, #<Department id: 3, name: "Web Development">]
+
+With a master list:
+
+    class Dog < ActiveRecord::Base
+      has_named_bootstraps(
+        {:FIDO => 'Fido', :ROVER => 'Rover', :SPOT  => 'Spot'},
+        :master_list => :GOOD_DOGS
+      )
+    end
+
+    >> Dog.find(:all)
+    => [#<Dog id: 1, name: "Spot">, #<Dog id: 2, name: "Fido">, #<Dog id: 3, name: "Rover">]
+    >> Dog::GOOD_DOGS
+    => [#<Dog id: 1, name: "Spot">, #<Dog id: 2, name: "Fido">, #<Dog id: 3, name: "Rover">]
+
+See HasNamedBootstraps::ClassMethods for other options.
 
 = TODO
 
-  -make master constant list optional
-  -allow caller to specify an attribute to use to find record (currently hardcoded to "name")
-  -write tests for shoulda macros, document same
+make should_have_named_bootstraps detect multiple missing bootstraps (not just the first)
+
+write tests for shoulda macros, document same
+
+Rails 3 compatibility
+
+Markdown README for GitHub
 
 = License and copyright
 
 Copyright (c) 2010 Children's Hospital Boston, released under the GNU Lesser General Public License.
+
+= Acknowledgements
+
+Thanks to Wyatt Greene for feedback, Dan Croak for patches and Harold Gimenez for Markdown advice.  Boston.rb can beat up your Ruby group.

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.1.0

data/lib/has_named_bootstraps.rb

@@ -1,32 +1,108 @@
 module HasNamedBootstraps
+  class MissingBootstrapError < Exception; end
+
   def self.included(other)
     other.extend(ClassMethods)
   end
 
   module ClassMethods
-    # For each key/value pair in constant_hash, look up the record with the value in the "name" attribute, and assign it to the constant denoted by the key.  Assign a list of all such created constants to the constant named by valid_list_name.
+    # For each key/value pair in constant_hash, look up the record with the value in the "name" attribute (by default), and assign it to the constant denoted by the key.
     #
     # Example:
     #
     #   class Department < ActiveRecord::Base
     #     has_named_bootstraps(
-    #       :VALID_DEPARTMENTS,    
     #       :R_AND_D         => 'R&D',
     #       :MARKETING       => 'Marketing', 
     #       :HANDSOME_DEVILS => 'Web Development' 
     #     )
     #   end
     #
-    # Department::R_AND_D, Department::MARKETING and Department::HANDSOME_DEVILS are now all defined and point to an ActiveRecord object.  Deparment::VALID_DEPARTMENTS is a list of those constants.
+    # Department::R_AND_D, Department::MARKETING and Department::HANDSOME_DEVILS are now all defined and point to an ActiveRecord object.
+    #
+    # Valid options:
+    #
+    # +master_list+:: Assign to the given constant name a list of all constants that has_named_bootstraps creates.  Example:
+    #
+    #   class Dog < ActiveRecord::Base
+    #     has_named_bootstraps(
+    #       {:FIDO => 'Fido', :ROVER => 'Rover', :SPOT  => 'Spot'},
+    #       :master_list => :GOOD_DOGS
+    #     )
+    #   end
+    #
+    # Dog::FIDO, Dog::ROVER, and Dog::SPOT are now defined as above, but there's also another constant, Dog::GOOD_DOGS, which contains a list of those three dogs.
+    #
+    #
+    #
+    # +name_field+:: Look up bootstrapped constants by the specified field, rather than +name+.  Example:
+    #
+    #   class Part < ActiveRecord::Base
+    #     has_named_bootstraps(
+    #       {
+    #         :BANANA_GRABBER => '423-GOB-127', 
+    #         :TURNIP_TWADDLER => 'ZOMG-6-5000', 
+    #         :MOLE_WHACKER => '520-23-17X'
+    #       },
+    #       :name_field => :serial_number
+    #     )
+    #   end
+    #
+    #   >> Part.all
+    #   => [#<Part id: 1, serial_number: "423-GOB-127">, #<Part id: 2, serial_number: "ZOMG-6-5000">, #<Part id: 3, serial_number: "520-23-17X">]
+    #   >> Part::BANANA_GRABBER
+    #   => #<Part id: 1, serial_number: "423-GOB-127">
+    #
+    #
+    #
+    #
+    # +handle_missing_bootstrap+:: What to do if an expected bootstrap doesn't exist.  Valid values are:
+    # 
+    # * +raise+ (default):: Raise a HasNamedBootstraps::MissingBootstrapError
+    # * +warn+:: Log a warning in the Rails log and leave the constant set to nil.
+    # * +silent+:: Leave the constant set to nil as in +warn+, but without any warning logged.
+
+    def has_named_bootstraps(constant_hash, options={})
+      name_field = options[:name_field] || :name
+
+      handle_missing_bootstrap_strategy = options[:handle_missing_bootstrap] || :raise
+      unless %w(raise warn silent).include?(handle_missing_bootstrap_strategy.to_s)
+        raise ArgumentError, "Invalid :handle_missing_bootstrap option \"#{handle_missing_bootstrap_strategy}\""
+      end
 
-    def has_named_bootstraps(valid_list_name, constant_hash)
-      valid_list = []
+      # If the master_list option isn't set, we're just going to throw this
+      # list away, but it's clearer to just check once at the end if it's set
+      # rather than check repeatedly.
+      master_list = []
 
       constant_hash.each do |constant_name, record_name|
-        valid_list << self.const_set(constant_name, self.find_by_name(record_name).freeze)
+        bootstrapped_record = self.find(:first, :conditions => {name_field => record_name})
+
+        unless bootstrapped_record
+          handle_missing_bootstrap(handle_missing_bootstrap_strategy, name_field, record_name)
+        end
+
+        master_list << self.const_set(constant_name, bootstrapped_record.freeze)
       end
 
-      self.const_set(valid_list_name, valid_list.freeze)
+      master_list_name = options[:master_list]
+      if master_list_name
+        self.const_set(master_list_name, master_list.freeze)
+      end
+    end
+
+    def handle_missing_bootstrap(handle_missing_bootstrap_strategy, name_field, record_name) #:nodoc:
+      error_message = "Couldn't find bootstrap #{self} with #{name_field} \"#{record_name}\""
+
+      case handle_missing_bootstrap_strategy
+      when :raise
+        raise MissingBootstrapError, error_message
+      when :warn
+        Rails.logger.warn error_message
+      when :silent
+        # Don't raise anything, don't log a warning, just let the constant be 
+        # silently set to nil.
+      end
     end
   end
 end

data/test/test_has_named_bootstraps.rb

@@ -1,47 +1,146 @@
 require 'test_helper'
 
 class HasNamedBootstrapsTest < ActiveSupport::TestCase
-  CONSTANT_HASH = {
+  DEPARTMENT_CONSTANT_HASH = {
     :R_AND_D         => 'R&D',
     :MARKETING       => 'Marketing', 
     :HANDSOME_DEVILS => 'Web Development' 
   }
 
-  setup do
-    CONSTANT_HASH.values.each do |department_name|
-      Department.create!(:name => department_name)
+  DOG_CONSTANT_HASH = {
+    :FIDO  => 'Fido',
+    :ROVER => 'Rover',
+    :SPOT  => 'Spot'
+  }
+
+  PART_CONSTANT_HASH = {
+    :BANANA_GRABBER  => '423-GOB-127',
+    :TURNIP_TWADDLER => 'ZOMG-6-5000',
+    :MOLE_WHACKER    => '520-23-17X'
+  }
+
+  def self.create_records_from_hash_values(klass, hash, name_field_sym = :name)
+    klass.delete_all
+    hash.values.each do |record_name|
+      klass.create!(name_field_sym => record_name)
     end
+  end
+
+  setup do
+    create_records_from_hash_values(Department, DEPARTMENT_CONSTANT_HASH)
+    create_records_from_hash_values(Dog, DOG_CONSTANT_HASH)
+    create_records_from_hash_values(Part, PART_CONSTANT_HASH, :serial_number)
 
-    Department.class_eval do
-      include HasNamedBootstraps
-
-      # Ignore "already initialized constant WHATEVER" warnings that we
-      # would otherwise get due to load_named_bootstraps running before every
-      # test, redefining constants as we go (which we want in this case)
-     
-      old_verbose = $VERBOSE
-      $VERBOSE = nil
-      has_named_bootstraps(
-        :VALID_DEPARTMENTS,
-        CONSTANT_HASH
-      )
-      $VERBOSE = old_verbose
+    quietly do
+      Department.class_eval do
+        has_named_bootstraps(DEPARTMENT_CONSTANT_HASH)
+      end
+
+      Dog.class_eval do
+        has_named_bootstraps(
+          DOG_CONSTANT_HASH,
+          :master_list => :GOOD_DOGS # who's a good dog?
+        )
+      end
+
+      Part.class_eval do
+        has_named_bootstraps(
+          PART_CONSTANT_HASH,
+          :name_field => :serial_number
+        )
+      end
     end
   end
 
   context "#has_named_bootstraps" do
     should "create each expected constant" do
-      CONSTANT_HASH.each do |constant_name, department_name|
+      DEPARTMENT_CONSTANT_HASH.each do |constant_name, department_name|
         bootstrapped_constant = Department.const_get(constant_name)
-        assert_equal department_name, bootstrapped_constant.name
+        expected_department = Department.find_by_name(department_name)
+        
+        assert expected_department # ensure not nil
+        assert_equal expected_department, bootstrapped_constant
       end
     end
 
-    should "add each expected constant to the list of valid constants" do
-      expected_object_ids = CONSTANT_HASH.keys.map{|hash_symbol| Department.const_get(hash_symbol)}.map(&:id)
-      actual_object_ids = Department::VALID_DEPARTMENTS.map(&:id)
+    context "when an expected bootstrap is missing" do
+      setup do
+        @bad_country_name = "Erewhon"
+        @bad_country_const_name = "EREWHON"
+        @bad_bootstrap_hash_string = "{'#{@bad_country_const_name}' => '#{@bad_country_name}'}"
 
-      assert_same_elements expected_object_ids, actual_object_ids
+        stub(Rails.logger).warn
+        assert_nil Country.find_by_name(@bad_country_const_name)
+      end
+
+      should "raise a HasNamedBootstraps::MissingBootstrapError" do
+        assert_raise HasNamedBootstraps::MissingBootstrapError do
+          # Using stringwise form of class_eval so we can interpolate
+          # @bad_bootstrap_hash_string, which otherwise this wants to interpret 
+          # as an instance variable of Department.
+
+          quietly do
+            Country.class_eval <<-END_CLASS_EVAL
+              has_named_bootstraps(#{@bad_bootstrap_hash_string})
+            END_CLASS_EVAL
+          end
+        end
+      end
+
+      context "when :handle_missing_bootstrap is set to :warn" do
+        setup do
+          quietly do
+            Country.class_eval <<-END_CLASS_EVAL 
+              has_named_bootstraps(#{@bad_bootstrap_hash_string}, :handle_missing_bootstrap => :warn)
+            END_CLASS_EVAL
+          end
+        end
+
+        should "log a warning" do
+          assert_received(Rails.logger) {|logger| logger.warn(/#{@bad_country_name}/)}
+        end
+
+        should "leave that constant set to nil" do
+          assert_nil Country.const_get(@bad_country_const_name)
+        end
+      end
+
+      context "when :handle_missing_bootstrap is set to :silent" do
+        setup do
+          dont_allow(Rails.logger).warn
+
+          quietly do
+            Country.class_eval <<-END_CLASS_EVAL 
+              has_named_bootstraps(#{@bad_bootstrap_hash_string}, :handle_missing_bootstrap => :silent)
+            END_CLASS_EVAL
+          end
+        end
+
+        should "leave that constant set to nil" do
+          assert_nil Country.const_get(@bad_country_const_name)
+        end
+      end
+    end
+
+    context "when the :master_list option is set" do
+      should "add each expected constant to the list of valid constants" do
+        expected_objects = DOG_CONSTANT_HASH.keys.map{|hash_symbol| Dog.const_get(hash_symbol)}
+        actual_objects = Dog::GOOD_DOGS
+
+        expected_objects.each {|expected_object| assert expected_object} # ensure not nil
+        assert_same_elements expected_objects, actual_objects
+      end
+    end
+
+    context "when the :name_field option is set" do
+      should "look up bootstrapped constants by that field" do
+        PART_CONSTANT_HASH.each do |constant_name, serial_number|
+          expected_constant = Part.find_by_serial_number(serial_number)
+          actual_constant = Part.const_get(constant_name)
+
+          assert_equal expected_constant, actual_constant
+        end
+      end
     end
   end
 end

data/test/test_helper.rb

@@ -4,7 +4,16 @@ require 'active_support/test_case'
 require 'active_record'
 require 'active_record/fixtures'
 require 'shoulda'
-require 'ruby-debug'
+
+require 'rr'
+class Test::Unit::TestCase
+  include RR::Adapters::TestUnit
+end
+
+begin
+  require 'ruby-debug'
+rescue LoadError
+end
 
 require 'lib/has_named_bootstraps'
 
@@ -17,7 +26,51 @@ ActiveRecord::Schema.define do
   create_table 'departments', :force => true do |t|
     t.column 'name', :string
   end
+
+  create_table 'dogs', :force => true do |t|
+    t.column 'name', :string
+  end
+
+  create_table 'parts', :force => true do |t|
+    t.column 'serial_number', :string
+  end
+
+  create_table 'countries', :force => true do |t|
+    t.column 'name', :string
+  end
 end
 
 class Department < ActiveRecord::Base
+  include HasNamedBootstraps
+end
+
+class Dog < ActiveRecord::Base
+  include HasNamedBootstraps
+end
+
+class Part < ActiveRecord::Base
+  include HasNamedBootstraps
+end
+
+class Country < ActiveRecord::Base
+  include HasNamedBootstraps
+end
+
+# We're going to be redefining a lot of constants in the tests, so supress
+# warnings of the same.
+
+def quietly
+  old_verbose = $VERBOSE
+  $VERBOSE = nil
+  yield
+  $VERBOSE = old_verbose
+end
+
+# Dummy Rails logger, for testing warnings.
+module Rails
+  FAKE_LOGGER = Object.new
+
+  def self.logger
+    FAKE_LOGGER
+  end
 end

metadata

@@ -5,9 +5,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 2
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors: 
 - Phil Darnowsky
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-28 00:00:00 -04:00
+date: 2010-06-26 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency