remi-aux_codes 1.0.1

data/README.markdown

@@ -0,0 +1,98 @@
+aux codes
+=========
+
+Way back when, when I was learning database development, a mentor of mine showed me 
+a technique that he liked to use to consolidate similar enumeration-esque database tables.
+
+Often, applications have enumeration-esque tables that merely store simply key / value pairs, 
+typically a unique ID and a string.  Take for instance, a `genders` table:
+
+    [  genders   ]
+    [id]    [name]
+    1       Male
+    2       Female
+
+That's a bit of a waste of a table, *especially* if your application has *TONS* of tables 
+just like this.  There's where aux codes (or auxilary codes) come in!
+
+    [  aux_codes  ]
+    [id]   [category_id]   [name]
+    1      0               Genders    <--- this defines a 'table' (because category_id = 0)
+    2      1               Male       <--- these are under category_id 1 (Genders)
+    3      1               Female
+    4      0               Colors     <--- defines a color 'table'
+    5      4               Red        <--- category_id 4 = 'Colors', so this is a color
+    6      4               Blue
+
+Simple, eh?
+
+Now, this is great, but this might get in the way of our business logic or it might 
+dirty up our code.  We don't want to always be using the AuxCode object with complex 
+queries ... we probable want a Gender object that behaves just like it would with a
+full-blown genders table.
+
+    Gender = AuxCode.category('Gender').aux_code_class
+
+    # the Gender class is a full-blown ActiveRecord class
+    # that should behave as if there's actually a `genders` table!
+
+    Gender.find_by_name 'Male'
+
+    Gender.find_or_create_by_name 'Female'
+
+    Gender.create :name => 'Female'
+
+    male = Gender.new :name => 'Male'
+    male.save
+
+    Gender.find :conditions => ['name = ?', 'Male']
+
+    Gender.count
+
+    Gender.codes
+    Gender.code_names
+    Gender.aux_code
+    Gender.aux_codes
+
+If you want to create all of these classes at once, as constants:
+
+    AuxCode.create_classes!
+
+You can also access codes with a Hash-like syntax
+
+    AuxCode['Genders']['Male']
+    AuxCode[:Genders][:Female]
+
+    Gender[:Male]
+
+Or with an Indifferent Hash-like syntax
+
+    AuxCode.genders['Male']
+    AuxCode.genders[:Male]
+    AuxCode.genders.male
+
+    Gender.male
+
+    # these all return the same result
+    Breed.find_by_name 'Golden Retriever'
+    Breed['Golden Retriever']
+    Breed[:golden_retriever]
+    Breed.golden_retriever
+    AuxCodes.breeds.golden_retriever
+
+TODO
+----
+
+ * custom fields, eg:
+   * `Breed#acronym`
+   * `Breed#description`
+   * `Breed#kennel_association_id` ...
+   * these need an easy way to be defined!  `alias_attribute`?
+   * this needs to work in development mode, when the models are constantly being reloaded!
+   * you shouldn't have to know the name of the special field to use it ... something like `attr_string :name` could just grab the (first) string column!
+ * create (or update) method(s) for helping with the original AuxCode migration and for creating the special additional fields
+
+NOTES
+-----
+
+this implementation is for ActiveRecord only!  i hope to eventually make a similar DataMapper implementation

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:patch: 1
+:major: 1
+:minor: 0

data/lib/aux_codes/migration.rb

@@ -0,0 +1,24 @@
+#
+# ActiveRecord migration for creating the aux_codes table
+#
+class CreateAuxCodes < ActiveRecord::Migration
+  
+  def self.up
+    create_table :aux_codes,   :comment => 'Auxilary Codes' do |t|
+
+      t.integer  :aux_code_id, :comment => 'ID of parent aux code (Category)',      :null => false
+      t.string   :name,        :comment => 'Name of Category code (or child code)', :null => false
+
+      %w( integer decimal string text boolean datetime ).each do |field_type|
+        t.column field_type.to_sym, "#{field_type}_field"
+      end
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :aux_codes
+  end
+
+end

data/lib/aux_codes.rb

@@ -0,0 +1,178 @@
+$:.unshift File.dirname(__FILE__)
+
+%w( rubygems activerecord aux_codes/migration ).each {|lib| require lib }
+
+class AuxCode < ActiveRecord::Base
+
+  validates_presence_of :name
+  validates_uniqueness_of :name, :scope => :aux_code_id
+
+  belongs_to :aux_code
+  alias code aux_code
+  alias category aux_code
+
+  has_many :aux_codes
+  alias codes aux_codes
+
+  before_create :set_default_values
+
+  def code_names
+    codes.map &:name
+  end
+
+  def is_a_category?
+    aux_code_id == 0
+  end
+
+  def class_name
+    name.gsub(/[^[:alpha:]]/,'_').titleize.gsub(' ','').singularize
+  end
+
+  def [] attribute_or_code_name
+    if attributes.include?attribute_or_code_name
+      attributes[attribute_or_code_name]
+    else
+      found = codes.select {|c| c.name.to_s =~ /#{attribute_or_code_name}/ }
+      if found.empty? # try case insensitive (sans underscores)
+        found = codes.select {|c| c.name.downcase.gsub('_',' ').to_s =~ 
+          /#{attribute_or_code_name.to_s.downcase.gsub('_',' ')}/ }
+      end
+      found.first if found
+    end
+  end
+
+  def method_missing_with_indifferent_hash_style_values name, *args, &block
+    method_missing_without_indifferent_hash_style_values name, *args, &block
+  rescue NoMethodError => ex
+    begin
+      self[name]
+    rescue
+      raise ex
+    end
+  end
+  alias_method_chain :method_missing, :indifferent_hash_style_values
+
+  def aux_code_class
+    klass = Class.new(AuxCode) do
+      class << self
+        attr_accessor :aux_code_id, :aux_code
+
+        def aux_code
+          # @aux_code ||= AuxCode.find aux_code_id
+          AuxCode.find aux_code_id
+        end
+
+        def count_with_aux_code_scope options = {}
+          with_scope(:find => { :conditions => ['aux_code_id = ?', self.aux_code_id] }) do
+            count_without_aux_code_scope options
+          end
+        end
+        def method_missing_with_aux_code_scope name, *args, &block
+          if name.to_s[/^find/]
+            if name.to_s[/or_create_by_/]
+              name = "#{name}_and_aux_code_id".to_sym
+              args << self.aux_code_id
+              # method_missing_without_aux_code_scope name, *args
+              AuxCode.send name, *args, &block
+            else
+              with_scope(:find => { :conditions => ['aux_code_id = ?', self.aux_code_id] }) do
+                method_missing_without_aux_code_scope name, *args, &block
+              end
+            end
+          else
+            method_missing_without_aux_code_scope name, *args, &block
+          end
+        rescue NoMethodError => ex
+          begin
+            aux_code.send name, *args, &block # try on the AuxCode instance for this class ...
+          rescue
+            raise ex
+          end
+        end
+        def find_with_aux_code_scope first_or_all, options = {}
+          with_scope(:find => { :conditions => ['aux_code_id = ?', self.aux_code_id] }) do
+            find_without_aux_code_scope first_or_all, options
+          end
+        end
+        def create_with_aux_code_scope options = {}
+          create_without_aux_code_scope options.merge({ :aux_code_id => self.aux_code_id })
+        end
+        def create_with_aux_code_scope! options = {}
+          create_without_aux_code_scope! options.merge({ :aux_code_id => self.aux_code_id })
+        end
+        def new_with_aux_code_scope options = {}
+          new_without_aux_code_scope options.merge({ :aux_code_id => self.aux_code_id })
+        end
+
+        alias_method_chain :count, :aux_code_scope
+        alias_method_chain :method_missing, :aux_code_scope
+        alias_method_chain :find, :aux_code_scope
+        alias_method_chain :create, :aux_code_scope
+        alias_method_chain :create!, :aux_code_scope
+        alias_method_chain :new, :aux_code_scope
+      end
+    end
+
+    klass.aux_code_id = self.id # the class needs to know its own aux_code_id
+    klass
+  end
+
+  class << self
+    def categories
+      AuxCode.find_all_by_aux_code_id(0)
+    end
+
+    def category_names
+      AuxCode.categories.map &:name
+    end
+
+    def category category_object_or_id_or_name
+      obj = category_object_or_id_or_name
+      return obj if obj.is_a?AuxCode
+      return AuxCode.find(obj) if obj.is_a?Fixnum
+      return AuxCode.find_by_name_and_aux_code_id(obj, 0) if obj.is_a?String
+      return AuxCode.find_by_name_and_aux_code_id(obj.to_s, 0) if obj.is_a?Symbol
+      raise "I don't know how to find an AuxCode of type #{ obj.class }"
+    end
+    alias [] category
+
+    def category_codes category_object_or_id_or_name
+      category( category_object_or_id_or_name ).codes
+    end
+    alias category_values category_codes
+
+    def category_code_names category_object_or_id_or_name
+      category( category_object_or_id_or_name ).code_names
+    end
+
+    def create_classes!
+      AuxCode.categories.each do |category|
+        Kernel::const_set category.class_name, category.aux_code_class
+      end
+    end
+
+    def method_missing_with_indifferent_hash_style_values name, *args, &block
+      unless self.respond_to?:aux_code_id # in which case, this is a *derived* class, not AuxCode
+        begin
+          method_missing_without_indifferent_hash_style_values name, *args, &block
+        rescue NoMethodError => ex
+          begin
+            self[name]
+          rescue
+            raise ex
+          end
+        end
+      else
+        method_missing_without_indifferent_hash_style_values name, *args, &block
+      end
+    end
+    alias_method_chain :method_missing, :indifferent_hash_style_values
+  end
+
+protected
+
+  def set_default_values
+    self.aux_code_id = 0 unless aux_code_id
+  end
+
+end

data/spec/aux_code_spec.rb

@@ -0,0 +1,205 @@
+require File.dirname(__FILE__) + '/spec_helper'
+
+describe AuxCode do
+
+  it 'should require a name' do
+    AuxCode.create( :name => nil ).should_not be_valid
+    AuxCode.create( :name => ' ' ).should_not be_valid
+    AuxCode.create( :name => 'foo' ).should be_valid
+  end
+
+  it 'should have many aux codes (if category)' do
+    code = AuxCode.create! :name => 'foo'
+    code.codes.should be_empty
+    w00t = code.codes.create :name => 'w00t'
+    code.codes.should include(w00t)
+  end
+  
+  it 'should have code names (if category)' do
+    code = AuxCode.create! :name => 'foo'
+    code.codes.create :name => 'chunky'
+    code.codes.create :name => 'bacon'
+    
+    code.codes.length.should == 2
+    code.code_names.length.should == 2
+    code.code_names.should include('chunky')
+    code.code_names.should include('bacon')
+  end
+
+  it "should know whether it's a category or a category value / code" do
+    code = AuxCode.create! :name => 'foo'
+    w00t = code.codes.create :name => 'w00t'
+
+    w00t.is_a_category?.should be_false
+    code.is_a_category?.should be_true
+  end
+
+  it 'should belong to a category (if not a category)' do
+    code = AuxCode.create! :name => 'foo'
+    w00t = code.codes.create! :name => 'w00t'
+    w00t.aux_code.should == code
+    w00t.code.should == code
+    w00t.category.should == code
+    w00t.category.codes.should include(w00t)
+
+    w00t.codes.should be_empty
+    code.category.should be_nil
+  end
+
+  it 'should require a name unique to category' do
+    first_category  = AuxCode.create! :name => 'foo'
+    second_category = AuxCode.create! :name => 'bar'
+
+    first_category.aux_codes.create( :name => 'w00t' ).should be_valid
+    first_category.aux_codes.create( :name => 'w00t' ).should_not be_valid
+    second_category.aux_codes.create( :name => 'w00t' ).should be_valid
+  end
+
+  it 'should be able to easily get all categories' do
+    AuxCode.categories.should be_empty
+
+    first_category  = AuxCode.create! :name => 'foo'
+    second_category = AuxCode.create! :name => 'bar'
+    code_1 = first_category.codes.create :name => 'w00t'
+    code_2 = first_category.codes.create :name => 'w00t'
+
+    AuxCode.categories.should include(first_category)
+    AuxCode.categories.should include(second_category)
+    AuxCode.categories.should_not include(code_1)
+    AuxCode.categories.should_not include(code_2)
+  end
+
+  it 'should be able to easily get all category names' do
+    AuxCode.category_names.should be_empty
+
+    first_category  = AuxCode.create! :name => 'foo'
+    second_category = AuxCode.create! :name => 'bar'
+    code_1 = first_category.codes.create :name => 'w00t'
+
+    AuxCode.category_names.should include('foo')
+    AuxCode.category_names.should include('bar')
+    AuxCode.category_names.should_not include('w00t')
+  end
+
+  it 'should be able to fetch a category give the category, its name, or its id' do
+    cat  = AuxCode.create! :name => 'foo'
+    AuxCode.category( cat ).should == cat
+    AuxCode.category( cat.id ).should == cat
+    AuxCode.category( cat.name ).should == cat
+    AuxCode.category( cat.name.to_sym ).should == cat
+  end
+
+  it 'should be able to easily get all values (codes) for a category' do
+    first_category  = AuxCode.create! :name => 'foo'
+    code_1 = first_category.codes.create :name => 'w00t'
+    code_2 = first_category.codes.create :name => 'chunky'
+    code_3 = first_category.codes.create :name => 'bacon'
+    
+    [ AuxCode.category_values( first_category ), AuxCode.category_values( 'foo' ) ].each do |codes|
+      codes.should include(code_1)
+      codes.should include(code_2)
+      codes.should include(code_3)
+      codes.should_not include(first_category)
+    end
+    AuxCode.category_values( first_category ).should == AuxCode.category_codes( first_category )
+  end
+
+  it 'should be able to easily get all value names (code names) for a category' do
+    first_category  = AuxCode.create! :name => 'foo'
+    code_1 = first_category.codes.create :name => 'w00t'
+    code_2 = first_category.codes.create :name => 'chunky'
+    code_3 = first_category.codes.create :name => 'bacon'
+    
+    [ AuxCode.category_code_names( first_category ), AuxCode.category_code_names( 'foo' ) ].each do |codes|
+      codes.should include('w00t')
+      codes.should include('chunky')
+      codes.should include('bacon')
+      codes.should_not include('foo')
+    end
+  end
+
+  it 'should be able to get a Class for each category' do
+    random_category = AuxCode.create! :name => 'random-category-name'
+    foo_category = AuxCode.create! :name => 'foo'
+    foo_class = foo_category.aux_code_class
+    foo_class.count.should == 0
+
+    x = foo_category.codes.create :name => 'chunky'
+    foo_class.count.should == 1
+
+    foo_class.create :name => 'bacon'
+    foo_class.count.should == 2
+
+    foo = foo_class.create! :name => 'foo'
+    foo_class.count.should == 3
+
+    bar = foo_class.new :name => 'bar'
+    bar.save
+    foo_class.count.should == 4
+
+    w00t = foo_class.new :name => 'w00t'
+    w00t.save!
+    foo_class.count.should == 5
+
+    foo_class.find( :first, :conditions => ['name = ?', 'foo'] ).should == foo
+    foo_class.find( :first, :conditions => ['name = ?', 'foo'] ).should_not == foo_category
+
+    foo_class.find_by_name( 'foo' ).should == foo
+    foo_class.find_by_name( 'foo' ).should_not == foo_category
+
+    foo_class.find_all_by_name( 'foo' ).should include(foo)
+    foo_class.find_all_by_name( 'foo' ).should_not include(foo_category)
+
+    foo_class.all.should include(foo)
+    foo_class.all.should_not include(foo_category)
+
+    foo_class.find_by_name( 'neat' ).should be_nil
+    foo_class.find_or_create_by_name( 'neat' ).should_not be_nil
+    foo_class.find_by_name( 'neat' ).should_not be_nil
+    foo_class.code_names.should include('neat')
+  end
+
+  it 'should create good class names from category names for #create_classes!' do
+    AuxCode.new( :name => 'foos' ).class_name.should == 'Foo'
+    AuxCode.new( :name => 'foo Bars' ).class_name.should == 'FooBar'
+    AuxCode.new( :name => 'foo Bar lar Tars' ).class_name.should == 'FooBarLarTar'
+    AuxCode.new( :name => 'foo_Bar lar-Tars' ).class_name.should == 'FooBarLarTar'
+    AuxCode.new( :name => 'foo_Bar0lar1Tar5s' ).class_name.should == 'FooBarLarTar'
+    AuxCode.new( :name => 'Dog' ).class_name.should == 'Dog'
+    AuxCode.new( :name => 'Dogs' ).class_name.should == 'Dog'
+  end
+
+  it 'should be able to get categories and their values using Hash syntax' do
+    foo_category = AuxCode.create! :name => 'foo'
+    bar_category = AuxCode.create! :name => 'bar'
+    chunky = foo_category.codes.create :name => 'chunky'
+    bacon  = foo_category.codes.create :name => 'bacon'
+    
+    AuxCode['foo'].should == foo_category
+    AuxCode[:foo].should == foo_category
+    
+    AuxCode['foo'][:chunky].should == chunky
+    AuxCode[:foo]['chunky'].should == chunky
+  end
+
+  it 'should be able to get categories and their values using indifferent Hash syntax' do
+    foo_category = AuxCode.create! :name => 'foo'
+    bar_category = AuxCode.create! :name => 'bar'
+    chunky = foo_category.codes.create :name => 'chunky'
+    bacon  = foo_category.codes.create :name => 'bacon'
+    
+    AuxCode.foo.should == foo_category
+    AuxCode.foo.chunky.should == chunky
+  end
+
+  it 'should be able to handle names with spaces (with Hash syntax)' do
+    foo_category = AuxCode.create! :name => 'foo'
+    bar_category = AuxCode.create! :name => 'bar'
+    chunky = foo_category.codes.create :name => 'I am Chunky'
+    bacon  = foo_category.codes.create :name => 'Yay for Bacon'
+
+    foo_category.i_am_chunky.should == chunky
+    foo_category[:yay_for_bacon].should == bacon
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+require File.dirname(__FILE__) + '/../lib/aux_codes'
+require 'spec'
+
+ActiveRecord::Base.establish_connection :adapter => 'sqlite3', :database => ':memory:'
+CreateAuxCodes.verbose = false
+CreateAuxCodes.migrate :up
+
+# use transactions
+AuxCode; # hit one of the AR classes
+Spec::Runner.configure do |config|
+  config.before(:each) do
+    ActiveRecord::Base.connection.increment_open_transactions
+    ActiveRecord::Base.connection.begin_db_transaction
+  end
+  config.after(:each) do
+    if ActiveRecord::Base.connection.open_transactions != 0
+      ActiveRecord::Base.connection.rollback_db_transaction
+      ActiveRecord::Base.connection.decrement_open_transactions
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: remi-aux_codes
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- remi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-27 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: ActiveRecord plugin for easily managing lots of enumeration-type data
+email: remi@remitaylor.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- VERSION.yml
+- README.markdown
+- lib/aux_codes
+- lib/aux_codes/migration.rb
+- lib/aux_codes.rb
+- spec/aux_code_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/remi/aux_codes
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: ActiveRecord plugin for easily managing lots of enumeration-type data
+test_files: []
+