mini_cache 1.0.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mini_cache.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Derrick Reimer
+
+MIT License
+
+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,150 @@
+# MiniCache
+
+MiniCache is a lightweight in-memory key-value store for Ruby objects.
+This gem has no external dependencies and can be used in a Ruby project
+(including Rails apps).
+
+## Motivation
+
+It is common practice to cache certain values on an object that are 
+computationally expensive to obtain, such as a property that requires a 
+database query. 
+
+The simplest way to do this is by storing the value in an instance variable:
+
+```ruby
+class Account
+  def calculate_balance
+    # Do something expensive.
+  end
+  
+  def balance
+    @balance ||= self.calculate_balance
+  end
+end
+```
+
+While this method works in many scenarios, it fails when the value you 
+need to cache is:
+
+- Either `nil` or `false`
+- Dependent on a particular argument passed to the method
+
+Here's a demonstration of how MiniCache solves this problem:
+
+```ruby
+class Account
+  def lookup_role(user)
+    # Execute a database query to find the user's role.
+  end
+  
+  def role(user)
+    # Perform the lookup once and cache the value. We can't use
+    #
+    #   @role ||= lookup_user(user)
+    #
+    # because the value depends on the user argument. Also, the
+    # value could be nil if the user does not actually have a role.
+    # You can probably see how the solution could get pretty ugly.
+    # This is where MiniCache comes into play.
+    self.cache.get_or_set("role-#{user.id}") do
+      self.lookup_role(user)
+    end
+  end
+  
+  def cache
+    @cache ||= MiniCache::Store.new
+  end
+end
+```
+
+The `#get_or_set` method works similarly to the `||=` operator, except it 
+knows how to handle `false` and `nil` values and it's keyed off of a unique string ID.
+Problem solved!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'mini_cache'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mini_cache
+
+## Usage
+
+To create a new MiniCache store object, just initialize it:
+
+```ruby
+store = MiniCache::Store.new
+
+# Optionally pass in a Hash of data
+store = MiniCache::Store.new(:name => "Derrick", :occupation => "Developer")
+```
+
+Set and retrieve data using `#get` and `#set`:
+
+```ruby
+# Pass in the value as an argument or block
+store.set("age", 24)
+store.set("birth_year") { 1988 }
+
+store.get("birth_year")
+=> 1988
+```
+
+Use the `#get_or_set` method to either set the value if it hasn't already been
+set, or get the value that was already set.
+
+```ruby
+store.set("birth_year") { 1988 }
+=> 1988
+
+store.get_or_set("birth_year") { 1964 }
+=> 1988  # Did not overwrite previously set value
+```
+
+Other convenience methods:
+
+- `#set?(key)`: Checks to see if a value has been set for a given key
+- `#unset(key)`: Removes a key-value pair for a given key.
+- `#reset`: Clears the cache.
+- `#load(hash)`: Loads a hash of data into the cache (appended to existing data).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Copyright © 2012 Derrick Reimer
+
+MIT License
+
+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/Rakefile

@@ -0,0 +1,12 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+
+desc "Run tests"
+task :default => :test

data/lib/mini_cache/store.rb

@@ -0,0 +1,145 @@
+module MiniCache
+  class Store
+    include Enumerable
+    
+    # Public: Returns the hash of key-value pairs.
+    attr_reader :data
+
+    # Public: Initializes a new TinyCache object.
+    #
+    # data - A Hash of key-value pairs (optional).
+    #
+    # Returns nothing.
+    def initialize(data = {})
+      @data = {}
+      self.load(data)
+    end
+
+    # Public: Retrieves the value for a given key.
+    #
+    # key - A String or Symbol representing the key.
+    #
+    # Returns the value set for the key; if nothing is
+    #   set, returns nil.
+    def get(key)
+      check_key!(key)
+      @data[key.to_s]
+    end
+
+    # Public: Sets a value for a given key either as
+    # an argument or block.
+    #
+    # key   - A String or Symbol representing the key.
+    # value - Any object that represents the value (optional).
+    #         Not used if a block is given.
+    # block - A block of code that returns the value to set
+    #         (optional).
+    #
+    # Examples
+    #
+    #   cache.set("name", "Derrick")
+    #   => "Derrick"
+    #
+    #   cache.set("name") { "Joe" }
+    #   => "Joe"
+    #
+    # Returns the value given.
+    def set(key, value = nil)
+      check_key!(key)
+      @data[key.to_s] = block_given? ? yield : value
+    end
+
+    # Public: Determines whether a value has been set for
+    # a given key.
+    #
+    # key - A String or Symbol representing the key.
+    #
+    # Returns a Boolean.
+    def set?(key)
+      check_key!(key)
+      @data.keys.include?(key.to_s)
+    end
+
+    # Public: Retrieves the value for a given key if it
+    # has already been set; otherwise, sets the value
+    # either as an argument or block.
+    #
+    # key   - A String or Symbol representing the key.
+    # value - Any object that represents the value (optional).
+    #         Not used if a block is given.
+    # block - A block of code that returns the value to set
+    #         (optional).
+    #
+    # Examples
+    #
+    #   cache.set("name", "Derrick")
+    #   => "Derrick"
+    #
+    #   cache.get_or_set("name", "Joe")
+    #   => "Derrick"
+    #
+    #   cache.get_or_set("occupation") { "Engineer" }
+    #   => "Engineer"
+    #
+    #   cache.get_or_set("occupation") { "Pilot" }
+    #   => "Engineer"
+    #
+    # Returns the value.
+    def get_or_set(key, value = nil)
+      return get(key) if set?(key)
+      set(key, block_given? ? yield : value)
+    end
+
+    # Public: Removes the key-value pair from the cache
+    # for a given key.
+    #
+    # key - A String or Symbol representing the key.
+    #
+    # Returns the value.
+    def unset(key)
+      check_key!(key)
+      @data.delete(key.to_s)
+    end
+    
+    # Public: Clears all key-value pairs.
+    #
+    # Returns nothing.
+    def reset
+      @data = {}
+    end
+
+    # Public: Iterates over all key-value pairs.
+    #
+    # block - A block of code that will be send the key
+    #         and value of each pair.
+    #
+    # Yields the String key and value.
+    def each(&block)
+      @data.each { |k, v| yield(k, v) }
+    end
+    
+    # Public: Loads a hash of data into the cache.
+    #
+    # data - A Hash of data with either String or Symbol keys.
+    #
+    # Returns nothing.
+    def load(data)
+      data.each do |key, value|
+        check_key!(key)
+        @data[key.to_s] = value
+      end
+    end
+    
+    private
+    
+      # Internal: Raises an error if the key is not a String
+      # or a Symbol.
+      #
+      # key - A key provided by the user.
+      def check_key!(key)
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise TypeError, "key must be a String or Symbol"
+        end
+      end
+  end
+end

data/lib/mini_cache/version.rb

@@ -0,0 +1,3 @@
+module MiniCache
+  VERSION = "1.0.0"
+end

data/lib/mini_cache.rb

@@ -0,0 +1,2 @@
+require "mini_cache/version"
+require "mini_cache/store"

data/mini_cache.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/mini_cache/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Derrick Reimer"]
+  gem.email         = ["derrickreimer@gmail.com"]
+  gem.description   = %q{A lightweight, in-memory cache for Ruby objects}
+  gem.summary       = %q{MiniCache is a lightweight, in-memory key-value store for Ruby objects}
+  gem.homepage      = "https://github.com/djreimer/mini_cache"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "mini_cache"
+  gem.require_paths = ["lib"]
+  gem.version       = MiniCache::VERSION
+  
+  gem.add_development_dependency "shoulda-context"
+end

data/test/mini_cache/store_test.rb

@@ -0,0 +1,138 @@
+require File.dirname(__FILE__) + '/../test_helper.rb'
+
+class MiniCache::StoreTest < Test::Unit::TestCase
+  def setup
+    @store = MiniCache::Store.new
+  end
+  
+  context "initialize" do
+    should "default to empty data" do
+      store = MiniCache::Store.new
+      assert_equal Hash.new, store.data
+    end
+    
+    should "load seed data" do
+      data = { "name" => "Derrick" }
+      store = MiniCache::Store.new(data)
+      assert_equal data, store.data
+    end
+  end
+  
+  context "#get" do
+    should "return a value if set" do
+      @store.set("name", "Derrick")
+      assert_equal "Derrick", @store.get("name")
+    end
+    
+    should "return nil if not set" do
+      assert_nil @store.get("name")
+    end
+    
+    should "raise a TypeError if key is not valid" do
+      assert_raises(TypeError) { @store.get([1, 2]) }
+    end
+  end
+  
+  context "#set" do
+    should "accept the value as an argument" do
+      @store.set("name", "Derrick")
+      assert_equal "Derrick", @store.get("name")
+    end
+    
+    should "accept the value as a block" do
+      @store.set("name") { "Derrick" }
+      assert_equal "Derrick", @store.get("name")
+    end
+    
+    should "raise a TypeError if key is not valid" do
+      assert_raises(TypeError) { @store.set([1, 2], "foo") }
+    end
+  end
+  
+  context "#set?" do
+    should "be true if key has been set" do
+      @store.set("name", "Derrick")
+      assert_equal true, @store.set?("name")
+    end
+    
+    should "be false if key has not been set" do
+      assert_equal false, @store.set?("foobar")
+    end
+    
+    should "raise a TypeError if key is not valid" do
+      assert_raises(TypeError) { @store.set?([1, 2]) }
+    end
+  end
+  
+  context "#get_or_set" do
+    should "set the value if it hasn't already been set" do
+      @store.get_or_set("name", "Derrick")
+      assert_equal "Derrick", @store.get("name")
+    end
+    
+    should "not set the value if it has already been set" do
+      @store.set("name", "Derrick")
+      @store.get_or_set("name", "Joe")
+      assert_equal "Derrick", @store.get("name")
+    end
+    
+    should "return the value if not already set" do
+      assert_equal "Derrick", @store.get_or_set("name", "Derrick")
+    end
+    
+    should "return the value if already set" do
+      @store.set("name", "Derrick")
+      assert_equal "Derrick", @store.get_or_set("name", "Joe")
+    end
+    
+    should "accept the value as a block" do
+      @store.get_or_set("name") { "Joe" }
+      assert_equal "Joe", @store.get("name")
+    end
+    
+    should "raise a TypeError if key is not valid" do
+      assert_raises(TypeError) { @store.get_or_set([1, 2], "foo") }
+    end
+  end
+  
+  context "#unset" do
+    should "remove the key-value pair" do
+      @store.set("name", "Derrick")
+      @store.unset("name")
+      assert !@store.data.keys.include?("name")
+    end
+  end
+  
+  context "#reset" do
+    should "remove all data" do
+      @store.set("name", "Derrick")
+      @store.reset
+      assert_equal Hash.new, @store.data
+    end
+  end
+  
+  context "#load" do
+    should "append the data to the cache" do
+      @store.set("title", "Mr.")
+      
+      data = { "name" => "Derrick", "occupation" => "Developer" }
+      @store.load(data)
+      
+      all_data = { "title" => "Mr.", 
+        "name" => "Derrick", "occupation" => "Developer" }
+      assert_equal all_data, @store.data
+    end
+    
+    should "stringify the keys" do
+      data = { :name => "Derrick" }
+      @store.load(data)
+      stringified_data = { "name" => "Derrick" }
+      assert_equal stringified_data, @store.data
+    end
+    
+    should "raise a TypeError if an invalid key is encountered" do
+      data = { [1, 2] => "Derrick" }
+      assert_raises(TypeError) { @store.load(data) }
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,4 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'mini_cache'
+require 'minitest/autorun'
+require 'shoulda-context'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: mini_cache
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Derrick Reimer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-21 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda-context
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: A lightweight, in-memory cache for Ruby objects
+email: 
+- derrickreimer@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/mini_cache.rb
+- lib/mini_cache/store.rb
+- lib/mini_cache/version.rb
+- mini_cache.gemspec
+- test/mini_cache/store_test.rb
+- test/test_helper.rb
+homepage: https://github.com/djreimer/mini_cache
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: MiniCache is a lightweight, in-memory key-value store for Ruby objects
+test_files: 
+- test/mini_cache/store_test.rb
+- test/test_helper.rb