elephant-cache 1.0.0

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2010, Jeffrey C. Reinecke
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the copyright holders nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL JEFFREY REINECKE BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.rdoc

@@ -0,0 +1,63 @@
+= Overview
+
+Elephant provides a caching module that may be included into a class for easy
+internal caching.  The code for this is simple, but is common enough of a design
+pattern that having a reusable module is handy.
+
+Usage is quite simple:
+
+1. include Elephant::Cache.
+2. In your object's initialize method, call +initialize_cache+.
+3. Create accessors for cachable quantities, using the +cache+ method.
+
+Example:
+
+ class Point
+
+   def initialize(x=0, y=0)
+     initialize_cache
+     self.x = x
+     self.y = y
+   end
+
+   attr_reader :x, :y
+
+   def magnitude
+     return cache(__method__) do
+       Math.sqrt(self.x**2 + self.y**2)
+     end
+   end
+
+ end
+
+Additionally, if you were to make the point mutable, you'd want to dirty the
+cache like so:
+
+ def x=(x)
+   dirty_cache(:magnitude)
+   @x = x
+ end
+
+ def y=(y)
+   dirty_cache(:magnitude)
+   @y = y
+ end
+
+Or, if you want to dirty the entire cache, call <code>dirty_cache()</code> with
+no arguments.
+
+See the Elephant::Cache module for more information.
+
+= Contact
+
+If you have any questions, comments, concerns, patches, or bugs, you can contact
+me via the github repository at:
+
+http://github.com/paploo/elephant
+
+or directly via e-mail at:
+
+mailto:jeff@paploo.net
+
+= Version History
+[1.0.0 - 2011-Aug-28] Initial release.

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake'
+require "rake/rdoctask"
+
+# ===== RDOC BUILDING =====
+# This isn't necessary if installing from a gem.
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.rdoc_files.add "lib/**/*.rb", "README.rdoc"
+end
+
+# ===== SPEC TESTING =====
+
+begin
+  require "spec/rake/spectask"
+  
+  Spec::Rake::SpecTask.new(:spec) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc']
+    spec.spec_files = ['spec']
+  end
+  
+  Spec::Rake::SpecTask.new(:spec_with_backtrace) do |spec|
+    spec.spec_opts = ['-c' '-f specdoc', '-b']
+    spec.spec_files = ['spec']
+  end
+rescue LoadError
+  task :spec do
+    puts "You must have rspec installed to run this task."
+  end
+end
+
+# ===== GEM BUILDING =====
+
+desc "Build the gem file for this package"
+task :build_gem do
+  STDOUT.puts `gem build elephant-cache.gemspec`
+end

data/lib/elephant/cache.rb

@@ -0,0 +1,52 @@
+module Elephant
+  # A simple caching API.
+  #
+  # To use, initialize the cache in your object initialize method, then
+  # simply call <code>cache(:lookup_key){...}</code> with the block generating the value
+  # that should be cached.  From then on, it'll use the cached value (unless
+  # you dirty the cache, of course).
+  #
+  # If you want to access a cached value outside of where it is created, it is
+  # best to cache the value in an accessor method and then call the accessor.
+  #
+  # Note: Outside of initialize_cache, the APIs are designed in a way that
+  # easily facilitates using any cache store, as long as it has hash-like access.
+  # Thus, one could make a mapper to Memcache or Mongo and override initialize_cache
+  # with a new implementation before calling it, and you'd be able to store anywhere.
+  module Cache
+
+    private
+
+    # Initializes the cache.  This should be called in your object's initialize
+    # method.  Note that this can be overriden to use any hash-like object you
+    # want as a cache store, allowing use of Memcache, Mongo, or SQL.
+    def initialize_cache
+      @elephant_cache = {}
+    end
+    
+    # Retrieves the value for the given key from the cache, calculating it from
+    # the block if necessary.
+    #
+    # Ex:
+    #  def foo
+    #    return cache_value(__method__) { ...do a lot of work... }
+    #  end
+    def cache_value(key)
+      unless(@elephant_cache.include?(key))
+        @elephant_cache[key] = yield if block_given?
+      end
+      return @elephant_cache[key]
+    end
+    
+    # Given a key, it dirties the cache for that key so that the next access
+    # will recalculate it.  If no key is given, it cleas the entire cache.
+    def dirty_cache(key=nil)
+      if(key.nil?)
+        @elephant_cache.clear
+      else
+        @elephant_cache.delete(key)
+      end
+    end
+
+  end
+end

data/lib/elephant.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'elephant', 'cache')

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification 
+name: elephant-cache
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Jeff Reinecke
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-08-29 00:00:00 Z
+dependencies: []
+
+description: "    A simple object caching design pattern in a reusable module.\n"
+email: jeff@paploo.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- LICENSE.txt
+- Rakefile
+- lib/elephant/cache.rb
+- lib/elephant.rb
+homepage: http://www.github.com/paploo/elephant
+licenses: 
+- BSD
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.7
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: A simple object caching design pattern in a reusable module.
+test_files: []
+