acts_as_lookup 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+# Copyright (c) 2010 Umamibud, Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,47 @@
+= acts_as_lookup
+
+== Overview
+
+Provides an easy means for creating models that act like enumerations or lookup tables. You can specify the lookup values in your Rails models and can lazily push these to the associated db tables (or not). Also dynamically adds helpful class-level methods to access singleton instances of each value in your lookup
+
+== What to do
+
+=== Rails models
+
+==== Defining a lookup model
+
+In your model, do something like:
+
+  def MyLookup < ActiveRecord::Base
+    VALS = [ { :id => 1, :name => "value 1", ... other attributes },
+             { :id => 2, :name => "value 2", ... other attributes },
+             ... other lookup values ...
+           ]
+    acts_as_lookup :values => VALS, ... other options ...
+  end
+
+==== Associating a model with a lookup model
+
+In your model, you can specify an association to a lookup using +has_lookup+:
+
+  def MyModel < ActiveRecord::Base
+    has_lookup :my_lookup
+  end
+
+Alternatively, you can explicitly state the class name of the associated lookup:
+
+  def MyModel < ActiveRecord::Base
+    has_lookup :my_association, :class_name => 'MyLookup'
+  end
+
+==== Alternative: table-less lookups and associations
+
+TODO: probably won't work yet...at least need to add an _id attribute to the associating class....
+
+=== Other (FUTURE)
+
+Some work is yet to be done to support general classes using acts_as_lookup
+
+== Configuration acts_as_lookup
+
+TODO: go through the options (enabled and FUTURE)

data/TODO

@@ -0,0 +1,30 @@
+Things to work on:
+
+* find a better workaround for the cached instance problem (see https://rails.lighthouseapp.com/projects/8994/tickets/1339, for example) than explicit requiring of lookup classes (see acts_as_lookup.rb : ActsAsLookupHasLookupClassMethods#has_lookup)
+* for now, it's required to include :id in the values hashes; enhance to allow leaving :id off (by specifying :uniqueness_column) and fetch them from db (option will only be available for :sync_with_db == true)
+* allow gem to be used outside Rails by specifying alternative implementations for db-hitting methods....e.g. add configuration values that specify method names to call to load/write/remove from db. see +acts_as_lookup_fetch_values+ method comment.
+* add the following configuration options:
+** sync_with_db: if false, no inserts/retrievals of db will be performed at all. this means the model will operate as an enum-like thing...a lot like rapleaf_enum where the class just defines the mapping and when associations are formed, the id gets inserted.
+*** plan for this to work even if there is no lookup table in db at all...eg if we didn't care about foreign keys and just wanted to store some ids instead of strings....just need to make sure that associations work properly...like user.status = UserAccountStatus.active needs to set user.status_id = UserAccountStatus.active
+*** this might be kind of tricky to do without mucking with the active record association methods (belongs_to() etc.)
+*** if false, don't have the requirement that there's an :id column specified
+*** so maybe this no-table business will be FUTURE only...
+*** default will be true
+** write_to_db: if true will insert values specified in model into db table if the row doesn't exist (based on id)
+*** default will be true
+** remove_from_db: if there is an id in the table not specified in the model, will remove that row (removal will happen before any inserts)
+*** allows for there to be values in lookup table that aren't relevant for the rails app (e.g. something that only some other process needs)
+*** default will be false
+** indexed_columns: which columns can be used in lookup_by_column methods
+*** allows for specifying other values in the model that don't need to be lookupable columns, e.g. if there are columns with non-unique values, foreign keys to other tables etc.
+*** default will be to use all columns specified in the model
+** uniqueness_column: which column defines uniqueness of a record if :id is not set in model
+*** allows to leave off the id when specifying the rows in model if it doesn't really matter, but still do the inserting/removing of rows automatically
+*** default will be :name (if :name not specified in the data in the model, then if uniqueness_column isn't set, there will be errors)
+** shortcut_method_column: which column to use to create shortcut lookup methods by value
+*** this is used to do the UserAccountStatus.active thing, allowing for doing it with a different column name other than :name if desired
+*** default will be :name
+*** see acts_as_lookup_add_shortcut method
+** Config this in initializer or env.rb file (might want to be env-specific), hopefully we're fine with it being global to all lookup classes
+*** initialize_on_class_load: force values to load and methods to be created when the class loads, instead of being done lazily
+**** default will be false

data/acts_as_lookup.gemspec

@@ -0,0 +1,46 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{acts_as_lookup}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brian Percival"]
+  s.date = %q{2010-04-05}
+  s.description = %q{Provides an easy means for creating models that act like enumerations or lookup
+tables. You can specify the lookup values in your Rails models and can lazily
+push these to the associated db tables (or not). Also dynamically adds helpful
+class-level methods to access singleton instances of each value in your lookup
+table.
+}
+  s.email = %q{percivalatumamibuddotcom}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc",
+     "TODO"
+  ]
+  s.files = [
+    "README.rdoc",
+     "acts_as_lookup.gemspec",
+     "lib/acts_as_lookup.rb"
+  ]
+  s.homepage = %q{http://github.com/bmpercy/acts_as_lookup}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Helpful for creating lookup-table-like models}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/lib/acts_as_lookup.rb

@@ -0,0 +1,208 @@
+# contains methods and logic to be added to classes that call the acts_as_lookup
+# method
+#-------------------------------------------------------------------------------
+module ActsAsLookupClassMethods
+  def acts_as_lookup_options=(options)
+    @@acts_as_lookup_options = options
+  end
+
+  def acts_as_lookup_options
+    @@acts_as_lookup_options
+  end
+
+
+  # FUTURE: allow for dynamically specifying which columns can be used for
+  #         cache lookups
+  #-----------------------------------------------------------------------------
+  def lookup_by_id(id)
+    @@acts_as_lookup_by_id[id]
+  end
+  def lookup_by_name(name)
+    @@acts_as_lookup_by_name[name]
+  end
+
+
+  # check if the current lookup class has been initialized for lookup use
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_initialized?
+    if !defined?(@@acts_as_lookup_initialized)
+      @@acts_as_lookup_initialized = false
+    end
+
+    @@acts_as_lookup_initialized
+  end
+
+
+  # initialize the current lookup class for lookup use if it isn't already
+  #
+  # NOTE: early edition of this gem assumes id, name columns. FUTURE will allow
+  #       more flexibility through configuration
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_initialize
+    Thread.exclusive do
+      # double-check in case of race condition in calling code
+      unless self.acts_as_lookup_initialized?
+        @@acts_as_lookup_by_id = {}
+        @@acts_as_lookup_by_name = {}
+
+        if @@acts_as_lookup_options[:sync_with_db]
+          acts_as_lookup_fetch_values
+          if @@acts_as_lookup_options[:write_to_db]
+            acts_as_lookup_write_missing_values
+          end
+        else
+          @@acts_as_lookup_values = @acts_as_lookup_options[:values]
+          self.acts_as_lookup_refresh_caches
+        end
+
+        @@acts_as_lookup_initialized = true
+      end
+
+      # FUTURE: allow for a different column to be used for generating class
+      #         accessor methods
+      @@acts_as_lookup_by_name.each_pair do |name,val|
+        self.acts_as_lookup_add_shortcut name
+      end
+
+    end
+  end
+
+
+  # fetches existing records from the db and merges them into the cached values
+  #
+  # FUTURE: if this gem is to be used outside of a Rails' ActiveRecord::Base
+  # descendant, will need to allow calling class to specify an alternative
+  # implementation (maybe add a config value that specifies a method to
+  # call)
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_fetch_values
+    @@acts_as_lookup_values = self.all
+    self.acts_as_lookup_refresh_caches
+  end
+
+
+  # writes any missing values to the db
+  #
+  # NOTE: does NOT overwrite any values found in the db, so it is possible for
+  #       the values specified in the class to be superceded by values in the
+  #       database
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_write_missing_values
+
+    # FUTURE: if :ids aren't provided, use the uniqueness_column to determine
+    #         which values are missing from existing caches
+    @@acts_as_lookup_options[:values].each do |val|
+      next if @@acts_as_lookup_by_id.include?(val[:id])
+
+      # allow for attr_accessible protection, assign attributes one-by-one
+      new_val = self.new
+      val.each_pair do |attr,value|
+        new_val.send("#{attr.to_s}=".to_sym, value)
+      end
+      new_val.save!
+
+      @@acts_as_lookup_values << new_val
+    end
+
+    self.acts_as_lookup_refresh_caches
+  end
+
+
+  # updates the lookup cache hashes from @@acts_as_lookup_values
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_refresh_caches
+    @@acts_as_lookup_values.each do |val|
+      @@acts_as_lookup_by_id.reverse_merge! val.id => val
+    end
+    @@acts_as_lookup_values.each do |val|
+      @@acts_as_lookup_by_name.reverse_merge! val.name => val
+    end
+  end
+
+
+  # adds a class method to access a particular lookup value via a shortcut
+  # method
+  #
+  # FUTURE: will allow for any column to be used here; for now, hardcoded
+  #       to lookup by name
+  #-----------------------------------------------------------------------------
+  def acts_as_lookup_add_shortcut(name)
+    instance_eval "def #{name}; self.lookup_by_name '#{name}'; end"
+  end
+
+end
+
+# modify object to allow any class to act like a lookup class
+#------------------------------------------------------------------------------
+class Object
+
+  # converts the calling class to act like a lookup model.
+  #
+  # NOTE: for now, the values' name column should not have spaces in it,
+  #       for cleanliness, though this can be addressed by gsubbing.
+  #-----------------------------------------------------------------------------
+  def self.acts_as_lookup(options = {})
+    self.extend ActsAsLookupClassMethods
+
+    options.reverse_merge! :sync_with_db => true,
+                           :write_to_db => true  #,
+# FUTURE:
+#                           :remove_from_db => false,
+#                           :shortcut_method_column => :name
+
+    self.acts_as_lookup_options = options
+
+    # lazy initialize? but for now explicitly initialize here
+    self.acts_as_lookup_initialize
+  end
+
+end
+
+# class methods for ActiveRecord associations
+if defined?(ActiveRecord)
+  module ActsAsLookupHasLookupClassMethods
+
+    # create an association from the current rails model to a lookup model,
+    # providing a name for the association (default will assume the
+    # association name follows rails association naming conventions).
+    #
+    # options:
+    #  :class_name: override the default assumption of class name from
+    #               +assocaition_name+ argument and explicitly pass in the
+    #               classname (in CamelCase) for the association.
+    #---------------------------------------------------------------------------
+    def has_lookup(association_name, options = {})
+
+      class_name = options[:class_name] || association_name.to_s.camelize
+
+      # this is a hack that is not at all pretty but seems to get around the
+      # double-class loading problems that arise in rails: see for example
+      # https://rails.lighthouseapp.com/projects/8994/tickets/1339
+      # it may create other problems though, so be careful....
+      require File.join(RAILS_ROOT, 'app', 'models', class_name.underscore)
+
+      # this is inspired/borrowed from Rapleaf's has_rap_enum
+      klass = Kernel.const_get(class_name)
+      unless(klass && klass.is_a?(ActsAsLookupClassMethods))
+        raise "#{class_name.to_s.camelize} is not an acts_as_lookup class"
+      end
+
+      # create the reader method for the lookup association
+      define_method(association_name) do
+        klass.lookup_by_id(send("#{association_name}_id"))
+      end
+
+      # create the writer method for the lookup association
+      define_method("#{association_name}=") do |assoc|
+        unless (assoc.class.name == klass.name) || assoc.nil?
+          raise "Argument not of type #{klass.name}"
+        end
+        send("#{association_name}_id=", assoc && assoc.id)
+      end
+    end
+
+  end
+
+  ActiveRecord::Base.extend ActsAsLookupHasLookupClassMethods
+
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: acts_as_lookup
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Brian Percival
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-05 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: |
+  Provides an easy means for creating models that act like enumerations or lookup
+  tables. You can specify the lookup values in your Rails models and can lazily
+  push these to the associated db tables (or not). Also dynamically adds helpful
+  class-level methods to access singleton instances of each value in your lookup
+  table.
+
+email: percivalatumamibuddotcom
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+- TODO
+files: 
+- README.rdoc
+- acts_as_lookup.gemspec
+- lib/acts_as_lookup.rb
+- LICENSE
+- TODO
+has_rdoc: true
+homepage: http://github.com/bmpercy/acts_as_lookup
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --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.3.5
+signing_key: 
+specification_version: 3
+summary: Helpful for creating lookup-table-like models
+test_files: []
+