= Cached Values
 
* http://github.com/JackDanger/cached_values/
 
A dead-simple way to calculate any value via Ruby or SQL and (optionally) have it saved in a database field.
 
== REQUIREMENTS:
 
* 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.
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 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 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
  
  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.
 
  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 :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
 
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/
 
Copyright (c) 2007 Jack Danger Canty @ http://6brand.com, released under the MIT license