dm-constant-cache 0.2.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 tpitale
+
+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/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 [name of plugin creator]
+
+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.md

@@ -0,0 +1,103 @@
+# Constant Cache
+
+When your database has tables that store lookup data, there is a tendency 
+to provide those values as constants in the model.  If you have an
+account_statuses table with a corresponding model, your constants may look
+like this:
+
+    class AccountStatus
+      ACTIVE   = 1
+      PENDING  = 2
+      DISABLED = 3
+    end
+
+There are a couple of problems with this approach:
+
+As you add more lookup data to the table, you need to ensure that you're 
+updating your models along with the data.  
+
+The constants are stored as integer values and need to match up exactly 
+with the data that's in the table (not necessarily a bad thing), but this
+solution forces you to write code like this:
+
+    Account.new(:username => 'preagan', :status => AccountStatus.find(AccountStatus::PENDING))
+
+This requires multiple calls to find and obfuscates the code a bit.  Since classes
+in Ruby are executable code, we can cache the objects from the database at load time
+and use them in your application.
+
+## Changes
+
+### Major changes in version 0.2.0:
+
+Split versions for DM and AR. For dm use: gem 'dm-constant-cache', '0.2.0', :require => 'constant\_cache'
+
+### Major changes in version 0.1.0:
+
+In order to support DataMapper as well as ActiveRecord, and to reduce dependencies
+in the gem itself we've decided to make ConstantCache a module that must be included
+in the class you wish to call cache_constants on. If you wish to have all AR classes
+include the module, simply add an initializer to do ActiveRecord::Base.send(:include,
+ConstantCache)
+
+The cache now call #all instead of #find(:all) because it is supported by both ORMs.
+
+The only other major change in the is a change in the method name #caches_constants
+to #cache_constants (cache is a verb, implying an action or event)
+
+## Installation
+
+This code is packaged as a gem, so simply use the `gem` command to install:
+
+    gem install constant_cache
+
+## Example
+
+"Out of the box," the constant_cache gem assumes that you want to use the 'name' column to generate
+constants from a column called 'name' in your database table.  Assuming this schema:
+
+    create_table :account_statuses do |t|
+      t.string :name, :description
+    end
+
+    AccountStatus.create!(:name => 'Active',   :description => 'Active user account')
+    AccountStatus.create!(:name => 'Pending',  :description => 'Pending user account')
+    AccountStatus.create!(:name => 'Disabled', :description => 'Disabled user account')
+
+We can use the plugin to cache the data in the table:
+
+    class AccountStatus # uses ActiveRecord or DataMapper
+      include ConstantCache
+      
+      cache_constants
+    end
+
+Now you can write code that's a little cleaner and not use multiple unnecessary find calls:
+
+    Account.new(:username => 'preagan', :status => AccountStatus::PENDING)
+
+If the column you want to use as the constant isn't 'name', you can set that in the model. If
+we have :name, :slug, and :description, we can use 'slug' instead:
+
+    class AccountStatus # uses ActiveRecord or DataMapper
+      include ConstantCache
+      
+      cache_constants :key => :slug
+    end
+  
+The value for the constant is truncated at 64 characters by default, but you can adjust this as
+well:
+
+    class AccountStatus # uses ActiveRecord or DataMapper
+      include ConstantCache
+      
+      cache_constants :limit => 16
+    end
+
+## Acknowlegements
+
+Thanks to Dave Thomas for inspiring me to write this during his Metaprogramming talk at a Rails Edge 
+conference in early 2007.
+
+Copyright (c) 2009 [Patrick Reagan](mailto:patrick.reagan@viget.com) and [Tony Pitale](mailto:tony.pitale@viget.com)
+of Viget Labs, released under the MIT license

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name              = "dm-constant-cache"
+    gem.summary           = ""
+    gem.description       = ""
+    gem.authors           = ["Tony Pitale", "Patrick Reagan"]
+    gem.email             = "tony.pitale@viget.com"
+    gem.homepage          = "http://www.viget.com/extend/"
+    gem.files = %w(MIT-LICENSE README.md Rakefile) + Dir.glob("{lib,test}/**/*")
+
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList["test/**/*_test.rb"]
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+
+  desc "Generate RCov coverage report"
+  Rcov::RcovTask.new(:rcov) do |t|
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts << "-x lib/constant_cache.rb"
+  end
+rescue LoadError
+  nil
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "constant_cache #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/constant_cache/cache_methods.rb

@@ -0,0 +1,82 @@
+module ConstantCache
+
+  CHARACTER_LIMIT = 64
+
+  def self.included(model)
+    model.extend(ClassMethods)
+    (@descendants ||= []) << model
+  end
+
+  def self.cache!
+    @descendants.each {|klass| klass.all.each {|instance| instance.set_instance_as_constant }}
+  end
+
+  #
+  # Error raised when duplicate constant defined
+  #
+  class DuplicateConstantError < StandardError; end
+
+  module ClassMethods
+    #
+    # The caches_constants method is the core of the functionality behind this mix-in.  It provides
+    # a simple interface to cache the data in the corresponding table as constants on the model:
+    #
+    #   class Status
+    #     caches_constants
+    #   end
+    # 
+    # It makes certain assumptions about your schema: the constant created is based off of a <tt>name</tt>
+    # column in the database and long names are truncated to ConstantCache::CHARACTER_LIMIT characters before 
+    # being set as constants. If there is a 'Pending' status in the database, you will now have a 
+    # Status::PENDING constant that points to an instance of ActiveRecord or DataMapper::Resource.
+    #
+    # Beyond the basics, some configuration is allowed. You can change both the column that is used to generate
+    # the constant and the truncation length:
+    #
+    #   class State
+    #     include ConstantCache
+    # 
+    #     caches_constants :key => :abbreviation, :limit => 2
+    #   end
+    #
+    # This will use the <tt>abbreviation</tt> column to generate constants and will truncate constant names to 2 
+    # characters at the maximum.
+    #
+    # Note: In the event that a generated constant conflicts with an existing constant, a 
+    # ConstantCache::DuplicateConstantError is raised.
+
+    def cache_as(key)
+      self.cache_options[:key] = key
+    end
+
+    def cache_limit(limit)
+      self.cache_options[:limit] = (limit > 0 ? limit : CHARACTER_LIMIT)
+    end
+
+    def cache_options
+      # @cache_options = {:key => :name, :limit => CHARACTER_LIMIT}.merge(@cache_options || {})
+      @cache_options ||= {:key => :name, :limit => CHARACTER_LIMIT}
+    end
+
+    def reset_cache_options
+      @cache_options = {:key => :name, :limit => CHARACTER_LIMIT}
+    end
+  end
+
+  # 
+  # Create a constant on the class that pointing to an instance
+  #
+  def set_instance_as_constant
+    unless constant_name.nil? || self.class.const_defined?(constant_name)
+      self.class.const_set(constant_name, self)
+    end
+  end
+
+  def constant_name #:nodoc:
+    name = self.send(self.class.cache_options[:key].to_sym)
+    if name.is_a?(String) && name != ''
+      @constant_name ||= name.constant_name[0,self.class.cache_options[:limit]]
+    end
+  end
+  private :constant_name
+end

data/lib/constant_cache/core_ext.rb

@@ -0,0 +1,15 @@
+class String
+
+  #
+  # A method to create a constant name from the existing string.  This method condenses
+  # multiple non-word characters into a single underscore:
+  #
+  #   'abc'.constant_name                => 'ABC'
+  #   'Restaurants & Bars'.constant_name => 'RESTAURANTS_BARS'
+  #
+  def constant_name
+    value = self.strip.gsub(/\s+/, '_').gsub(/[^\w_]/, '').gsub(/_{2,}/, '_').upcase
+    (value == '') ? nil : value
+  end
+
+end

data/lib/constant_cache.rb

@@ -0,0 +1,2 @@
+require 'constant_cache/core_ext'
+require 'constant_cache/cache_methods'

data/test/constant_cache/cache_methods_test.rb

@@ -0,0 +1,80 @@
+require 'test_helper'
+
+class Cached
+  include ConstantCache
+  
+  attr_accessor :name
+  attr_accessor :abbreviation
+end
+
+class CacheMethodsTest < Test::Unit::TestCase
+  context "A class with ConstantCache mixed in" do
+    should "have default options for the cache key and character limit" do
+      Cached.reset_cache_options
+      Cached.cache_options.should == {:key => :name, :limit => 64}
+    end
+
+    should "all overridden options for key and character limit" do
+      Cached.cache_as :abbreviation
+      Cached.cache_limit 20
+      Cached.cache_options.should == {:key => :abbreviation, :limit => 20}
+    end
+
+    should "revert the limit on characters if less than 1" do
+      Cached.cache_limit -10
+      Cached.cache_options.should == {:key => :name, :limit => 64}
+    end
+  end
+
+  context "ConstantCache" do
+    should "be able to cache all instances as constants" do
+      c1 = Cached.new
+      c1.name = 'al einstein'
+      c1.expects(:set_instance_as_constant)
+
+      c2 = Cached.new
+      c2.name = 'al franken'
+      c2.expects(:set_instance_as_constant)
+
+      Cached.expects(:all).returns([c1, c2])
+      ConstantCache.cache!
+    end
+  end
+
+  context "An instance of a class with ConstantCache mixed in" do
+    setup do
+      Cached.cache_limit 20
+      @cached = Cached.new
+    end
+
+    should "create a constant as a reference to the instance" do
+      @cached.name = 'al sharpton'
+      @cached.set_instance_as_constant
+      Cached.constants.include?("AL_SHARPTON").should == true
+      Cached::AL_SHARPTON.should == @cached
+    end
+
+    should "not create a constant without a key value" do
+      size = Cached.constants.size
+      @cached.set_instance_as_constant
+      Cached.constants.size.should == size
+    end
+
+    should "not raise an exception on duplicate constant" do
+      @cached.name = 'buffalo'
+      assert_nothing_raised do
+        @cached.set_instance_as_constant
+        @cached.set_instance_as_constant
+      end
+    end
+
+    should "truncate long constant names" do
+      constant_name = ('a'*20).upcase
+
+      @cached.name = 'a'*65
+      @cached.set_instance_as_constant
+      
+      Cached.constants.include?(constant_name).should == true
+    end
+  end
+end

data/test/constant_cache/core_ext_test.rb

@@ -0,0 +1,33 @@
+require 'test_helper'
+
+class CoreExtTest < Test::Unit::TestCase
+  context "The String core extension" do
+    should "upcase its characters" do
+      'test'.constant_name.should == 'TEST'
+    end
+  
+    should "replace whitespace with a single underscore" do
+      "test this \tformat\nplease.".constant_name.should == 'TEST_THIS_FORMAT_PLEASE'
+    end
+  
+    should "remove leading and trailing whitespace" do
+      ' test '.constant_name.should == 'TEST'
+    end
+  
+    should "remove non-word characters" do
+      '!test?'.constant_name.should == 'TEST'
+    end
+  
+    should "not singularize plural name" do
+      'tests'.constant_name.should == 'TESTS'
+    end
+  
+    should "return nil when all characters are removed" do
+      '?'.constant_name.should be(nil)
+    end
+  
+    should "collapse multiple underscores" do
+      'test__me'.constant_name.should == 'TEST_ME'
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,14 @@
+$:.reject! { |e| e.include? 'TextMate' }
+
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+require 'matchy'
+require 'mocha'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'constant_cache'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification 
+name: dm-constant-cache
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Tony Pitale
+- Patrick Reagan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-21 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: ""
+email: tony.pitale@viget.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/constant_cache.rb
+- lib/constant_cache/cache_methods.rb
+- lib/constant_cache/core_ext.rb
+- test/constant_cache/cache_methods_test.rb
+- test/constant_cache/core_ext_test.rb
+- test/test_helper.rb
+- LICENSE
+has_rdoc: true
+homepage: http://www.viget.com/extend/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: ""
+test_files: 
+- test/constant_cache/cache_methods_test.rb
+- test/constant_cache/core_ext_test.rb
+- test/test_helper.rb