@@ -1,14 +1,19 @@ -Cached Values -============== += Cached Values -* http://github.com/JackDanger/cached_values_gem/ +* http://github.com/JackDanger/cached_values/ -A dead-simple way to calculate any value via Ruby or SQL and have it saved in a database field. +A dead-simple way to calculate any value via Ruby or SQL and (optionally) have it saved in a database field. -Example -======= +== REQUIREMENTS: -USAGE: +* ObjectProxy + +== INSTALL: + +* as gem: sudo gem install cached_values +* as plugin: ./script/plugin install git://github.com/JackDanger/cached_values.git + +== USAGE: You can calculate values with a single line in any ActiveRecord model. To actually save those values you'll need to create an attribute in your schema. By default the cached_value instance will look for an attribute with the same name as itself. @@ -16,46 +21,46 @@ You can override this by specifying a :cache => :some_attribute option A very simple case in which cached_values works just like the .count method on a has_many association: - class Company < ActiveRecord::Base - caches_value :total_employees, :sql => 'select count(*) from employees where company_id = #{id}' + class Leprechaun < ActiveRecord::Base + caches_value :total_gold_coins, :sql => 'select count(*) from gold_coins where leprechaun_id = #{id}' end + + Company.find(4).total_employees # => 45 A more sophisticated example: - class User < ActiveRecord::Base - has_many :trinkets - has_many :sales, :through => :trinkets - caches_value :remaining_trinket_sales_allotted, :sql => '... very complicated sql here ...' + class Leprechaun < ActiveRecord::Base + has_many :lucky_charms + has_many :deceived_children, :through => :lucky_charms + caches_value :total_children_remaining_to_be_deceived, :sql => '... very complicated sql here ...' end - -reload() clears the cache and recalculates the value: - - user = User.find(:first) - user.remaining_trinket_sales_allotted # => 70 - Trinket.delete_all # <= any operation that would affect our value - user.remaining_trinket_sales_allotted # => 70 - user.remaining_trinket_sales_allotted.reload # => 113 -The same effect could be had by calling clear() which clears the cache and removes the cache instance from memory + Leprechaun.find(14).total_children_remaining_to_be_deceived # => 6,692,243,122 + +The values can be of any type. The plugin will attempt to cast SQL results to the type corresponding with their database cache +but calculations in Ruby are left alone. You can also calculate the value in Ruby using a string to be eval'ed or a Proc. Both are evaluated in the context of the record instance. - caches_value :expensive_calculation, :eval => "some_big_expensize_calculation(self.id)" - caches_value :other_expensive_process, :eval => Proc.new {|record| record.other_expensize_process } + class Leprechaun < ActiveRecord::Base + caches_value :total_gold, :eval => "some_archaic_and_silly_calculation(self.gold_coins)" + caches_value :total_lucky_charms, :eval => Proc.new {|record| record.calculate_total_lucky_charms } + end The cache is customizable, you can specify which attribute should be used as a cache: - caches_value :full_formula, :sql => '...' # uses 'full_formula' column if it exists - caches_value :standard_deviation, :sql => '...', :cache => 'std' # uses 'std' column if it exists - caches_value :id, , :sql => '...', :cache => false # does NOT save any cache. This avoids overwriting an attribute + caches_value :runic_formula, :sql => '...' # uses 'full_formula' column if it exists + caches_value :standard_deviation_of_gold_over_time, # uses 'std' column if it exists + :sql => '...', :cache => 'std' + caches_value :id, :sql => '...', :cache => false # does NOT save any cache. This avoids overwriting an attribute -Callbacks can be used to call load(), clear(), or reload() at certain times: +ActiveRecord callbacks can be used to call load (make sure the value is in memory), clear (flush the cache and +delete the instance), or reload (flush cache and reload instance) at certain times: caches_value :standard_deviation, :sql => '...', :reload => [:after_save, :before_validation] caches_value :full_formula, :sql => '...', :clear => :after_find - -Bugs can be filed at http://code.lighthouseapp.com/projects/4502-hoopla-rails-plugins/overview +Bugs can be filed at http://code.lighthouseapp.com/projects/4502-hoopla-rails-plugins/ Copyright (c) 2007 Jack Danger Canty @ http://6brand.com, released under the MIT license README.txt 0656cb6c35ffb0d5c0f344c4382f1a488c4907b0 Jack Danger Canty git@6brand.com http://github.com/JackDanger/cached_values/commit/6a4ee4d18992774d98172e33951534318dc358f2 6a4ee4d18992774d98172e33951534318dc358f2 2008-03-06T09:12:11-08:00 2008-03-06T09:12:11-08:00 converted README to Hoe format bcddd95ce702ad732b9e2d77481ac15d2896eeaf Jack Danger Canty git@6brand.com