RubyGems - elephas - Versions diffs - 0.1.0 - Mend

elephas 0.1.0

Files changed (45) hide show

data/.gitignore +5 -0
data/.travis.yml +8 -0
data/.yardopts +1 -0
data/Gemfile +9 -0
data/README.md +28 -0
data/Rakefile +18 -0
data/doc/Elephas/Cache.html +815 -0
data/doc/Elephas/Entry.html +1085 -0
data/doc/Elephas/Exceptions.html +115 -0
data/doc/Elephas/Providers/Base.html +701 -0
data/doc/Elephas/Providers/Hash.html +775 -0
data/doc/Elephas/Providers/RubyOnRails.html +609 -0
data/doc/Elephas/Providers.html +129 -0
data/doc/Elephas/Version.html +189 -0
data/doc/Elephas.html +130 -0
data/doc/_index.html +207 -0
data/doc/class_list.html +53 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +57 -0
data/doc/css/style.css +328 -0
data/doc/file.README.html +103 -0
data/doc/file_list.html +55 -0
data/doc/frames.html +28 -0
data/doc/index.html +103 -0
data/doc/js/app.js +214 -0
data/doc/js/full_list.js +173 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +300 -0
data/doc/top-level-namespace.html +112 -0
data/elephas.gemspec +34 -0
data/lib/elephas/cache.rb +89 -0
data/lib/elephas/entry.rb +86 -0
data/lib/elephas/provider.rb +57 -0
data/lib/elephas/providers/hash.rb +65 -0
data/lib/elephas/providers/ruby_on_rails.rb +57 -0
data/lib/elephas/version.rb +25 -0
data/lib/elephas.rb +20 -0
data/spec/coverage_helper.rb +19 -0
data/spec/elephas/cache_spec.rb +41 -0
data/spec/elephas/entry_spec.rb +11 -0
data/spec/elephas/provider_spec.rb +46 -0
data/spec/elephas/providers/hash_spec.rb +80 -0
data/spec/elephas/providers/ruby_on_rails_spec.rb +86 -0
data/spec/spec_helper.rb +16 -0
metadata +231 -0

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,112 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.8.2.1
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  hasFrames = window.top.frames.main ? true : false;
+  relpath = '';
+  framesUrl = "frames.html#!" + escape(window.location.href);
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div id="header">
+      <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
+</div>
+      <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+      Class List
+    </a>
+    <a class="full_list_link" id="method_list_link"
+        href="method_list.html">
+      Method List
+    </a>
+    <a class="full_list_link" id="file_list_link"
+        href="file_list.html">
+      File List
+    </a>
+</div>
+      <div class="clear"></div>
+    </div>
+    <iframe id="search_frame"></iframe>
+    <div id="content"><h1>Top Level Namespace
+</h1>
+<dl class="box">
+</dl>
+<div class="clear"></div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Elephas.html" title="Elephas (module)">Elephas</a></span>
+</p>
+</div>
+    <div id="footer">
+  Generated on Sat Jul 28 14:29:51 2012 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.8.2.1 (ruby-1.9.2).
+</div>
+  </body>
+</html>

data/elephas.gemspec ADDED Viewed

@@ -0,0 +1,34 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+require File.expand_path('../lib/elephas/version', __FILE__)
+Gem::Specification.new do |gem|
+  gem.name = "elephas"
+  gem.version = Elephas::Version::STRING
+  gem.homepage = "http://github.com/ShogunPanda/elephas"
+  gem.summary = %q{A storage agnostic caching framework.}
+  gem.description = %q{A storage agnostic caching framework.}
+  gem.rubyforge_project = "elephas"
+  gem.authors = ["Shogun"]
+  gem.email = ["shogun_panda@me.com"]
+  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.require_paths = ["lib"]
+  gem.add_dependency("cowtech-extensions", "~> 2.7.0")
+  gem.add_development_dependency("rspec", "~> 2.11.0")
+  gem.add_development_dependency("rake", "~> 0.9.0")
+  gem.add_development_dependency("simplecov", "~> 0.6.0")
+  gem.add_development_dependency("pry", "~> 0.9.10")
+  gem.add_development_dependency("yard", "~> 0.8.0")
+  gem.add_development_dependency("redcarpet", "~> 2.1.0")
+  gem.add_development_dependency("github-markup", "~> 0.7.0")
+end

data/lib/elephas/cache.rb ADDED Viewed

@@ -0,0 +1,89 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+module Elephas
+  # This is the main class of the framework. Use only this class to access the cache.
+  class Cache
+    class << self
+      # The provider used for the caching.
+      attr_accessor :provider
+      # This is the main method of the framework.
+      # It tries reading a key from the cache. If it doesn't find it, it uses the provided block to compute its value and then store it into the cache for later usages.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Object|Entry] The found or newly-set value associated to the key.
+      def use(key, options = {})
+        rv = nil
+        # Get options
+        options = {} if !options.is_a?(::Hash)
+        options = {:ttl => 1.hour, :force => false, :as_entry => false}.merge(options)
+        options[:ttl] == [options[:ttl].to_integer, 0].max
+        options[:force] = options[:force].to_boolean
+        options[:prefix] = options[:prefix].present? ? options[:prefix] : "elephas-#{::Elephas::Version::STRING}-cache"
+        # Wrap the final key to ensure we don't have colliding namespaces.
+        fkey = "#{options[:prefix]}[#{key}]"
+        # Compute the hash key used for referencing this value
+        options[:hash] = options[:hash] || ::Elephas::Entry.hashify_key(fkey.ensure_string)
+        # Check if the storage has the value (if we don't have to skip the cache)
+        rv = self.provider.read(options[:hash]) if options[:force] == false && options[:ttl] > 0
+        if rv.nil? && block_given? then # Try to compute the value from the block
+          rv = yield(key, options)
+          if rv && options[:ttl] > 0 then # We have a value and we have to store it
+            rv = ::Elephas::Entry.ensure(rv, key, options) # Make sure is an entry
+            Elephas::Cache.write(fkey, value, options)
+          end
+        end
+        # Return value
+        options[:as_entry] ? rv : rv.value.dup
+      end
+      # Reads a value from the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Object|NilClass] The read value or `nil`.
+      def read(key)
+        self.provider.read(key)
+      end
+      # Writes a value to the cache.
+      #
+      # @param key [String] The key to associate the value with.
+      # @param value [Object] The value to write. Setting a value to `nil` **doesn't** mean *deleting* the value.
+      # @param options [Hash] A list of options for writing.
+      # TODO: Insert options documentation.
+      # @return [Object] The value itself.
+      def write(key, value, options = {})
+        # TODO: Handle options
+        self.provider.write(key, value, options)
+      end
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The key to delete.
+      # @return [TrueClass|FalseClass] `true` if the key was in the cache, `false` otherwise.
+      def delete(key)
+        self.provider.delete(key)
+      end
+      # Checks if a key exists in the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [TrueClass|FalseClass] `true` if the key is in the cache, `false` otherwise.
+      def exists?(key)
+        self.provider.exists?(key)
+      end
+    end
+  end
+end

data/lib/elephas/entry.rb ADDED Viewed

@@ -0,0 +1,86 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+module Elephas
+  # This represents a cache entry.
+  class Entry
+    # The key for this entry.
+    attr_accessor :key
+    # The hashed (unique) key for this entry.
+    attr_accessor :hash
+    # The value contained in this entry.
+    attr_accessor :value
+    # The expected TTL of the entry, in milliseconds.
+    attr_accessor :ttl
+    # The last update date of the entry, in UNIX timestamp (with milliseconds).
+    attr_accessor :updated_at
+    # Creates a new entry.
+    #
+    # @param key [String] The key for this entry.
+    # @param value [Object] The value contained in this entry.
+    # @param hash [String] The hash for this entry. Should be unique. It is automatically created if not provided.
+    # @param ttl [Integer] The time to live (TTL) for this entry. If set to 0 then the entry is not cached.
+    def initialize(key, value, hash = nil, ttl = 3600)
+      hash = self.class.hashify_key(key) if hash.blank?
+      self.key = key
+      self.hash = hash
+      self.value = value
+      self.ttl = ttl
+      self.refresh
+    end
+    # Refreshes the entry.
+    #
+    # @param save [Boolean] If to save the refresh value in the cache.
+    def refresh(save = false)
+      self.updated_at = Time.now.to_f
+      # TODO: Set this value in the cache
+    end
+    # Checks if the entry is still valid.
+    #
+    # @param provider [Provider::Base] The provider to use for the check.
+    # @return [Boolean] `true` if the entry is still valid, `false` otherwise.
+    def valid?(provider = nil)
+      provider ||= ::Elephas::Cache.provider
+      provider.now - self.updated_at < self.ttl
+    end
+    # Returns a unique hash for the key.
+    #
+    # @param key [String] The key to hashify.
+    # @return [String] An unique hash for the key.
+    def self.hashify_key(key)
+      Digest::SHA2.hexdigest(key.ensure_string)
+    end
+    # Ensure that the value is an Entry.
+    #
+    # @param value [Object] The object to check.
+    # @param key [Object] The key associated to this object.
+    # @return [Entry] The wrapped object.
+    def self.ensure(value, key, options = {})
+      rv = value
+      if !rv.is_a?(::Elephas::Entry) then
+        options = {} if !options.is_a?(Hash)
+        ttl = [options[:ttl].to_integer, 0].max
+        hash = options[:hash] || ::Elephas::Entry.hashify_key(key.ensure_string)
+        rv = ::Elephas::Entry.new(key, rv, hash, ttl)
+      end
+      rv
+    end
+  end
+end

data/lib/elephas/provider.rb ADDED Viewed

@@ -0,0 +1,57 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+module Elephas
+  # This module hosts all the storage system for the caches.
+  module Providers
+    # The base provider, with all methods a valid provider should override.
+    module Base
+      extend ActiveSupport::Concern
+      # Reads a value from the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Entry|NilClass] The read value or `nil`.
+      def read(key)
+        raise ArgumentError.new("A Elephas::Providers subclass should override this module.")
+      end
+      # Writes a value to the cache.
+      #
+      # @param key [String] The key to associate the value with.
+      # @param value [Object] The value to write. **Setting a value to `nil` doesn't mean *deleting* the value.
+      # @param options [Hash] A list of options for writing. @see Elephas::Cache.write
+      # @return [Object] The value itself.
+      def write(key, value, options = {})
+        raise ArgumentError.new("A Elephas::Providers subclass should override this module.")
+      end
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The key to delete.
+      # @return [TrueClass|FalseClass] `true` if the key was in the cache, `false` otherwise.
+      def delete(key)
+        raise ArgumentError.new("A Elephas::Providers subclass should override this module.")
+      end
+      # Checks if a key exists in the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [TrueClass|FalseClass] `true` if the key is in the cache, `false` otherwise.
+      def exists?(key)
+        raise ArgumentError.new("A Elephas::Providers subclass should override this module.")
+      end
+      # Returns the current time for comparing with entries TTL.
+      #
+      # @return [Object] A representation of the current time.
+      def now
+        ::Time.now.to_f
+      end
+    end
+  end
+end

data/lib/elephas/providers/hash.rb ADDED Viewed

@@ -0,0 +1,65 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+module Elephas
+  module Providers
+    # This is a simple providers, which uses an hash for storing the values.
+    class Hash
+      include Elephas::Providers::Base
+      # The internal hash used by the provider.
+      attr_accessor :data
+      # Initialize the provider
+      # @param data [Hash] The initial data stored.
+      def initialize(data = nil)
+        data = {} if !data || !data.is_a?(::Hash)
+        @data = data
+      end
+      # Reads a value from the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Entry|NilClass] The read value or `nil`.
+      def read(key)
+        self.exists?(key) ? @data[key.ensure_string] : nil
+      end
+      # Writes a value to the cache.
+      #
+      # @param key [String] The key to associate the value with.
+      # @param value [Object] The value to write. **Setting a value to `nil` doesn't mean *deleting* the value.
+      # @param options [Hash] A list of options for writing. @see Elephas::Cache.write
+      # @return [Object] The value itself.
+      def write(key, value, options = {})
+        fvalue = ::Elephas::Entry.ensure(value, key, options)
+        fvalue.refresh
+        @data[key.ensure_string] = fvalue
+        value
+      end
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The key to delete.
+      # @return [Boolean] `true` if the key was in the cache, `false` otherwise.
+      def delete(key)
+        fkey = key.ensure_string
+        rv = @data.has_key?(fkey)
+        @data.delete(fkey)
+        rv
+      end
+      # Checks if a key exists in the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Boolean] `true` if the key is in the cache, `false` otherwise.
+      def exists?(key)
+        fkey = key.ensure_string
+        @data.has_key?(fkey) && @data[fkey].valid?
+      end
+    end
+  end
+end

data/lib/elephas/providers/ruby_on_rails.rb ADDED Viewed

@@ -0,0 +1,57 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+module Elephas
+  module Providers
+    # This is a Ruby on Rails providers, which uses Rails.cache.
+    class RubyOnRails
+      include Elephas::Providers::Base
+      # Reads a value from the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Entry|NilClass] The read value or `nil`.
+      def read(key)
+        self.exists?(key) ? Rails.cache.read(key) : nil
+      end
+      # Writes a value to the cache.
+      #
+      # @param key [String] The key to associate the value with.
+      # @param value [Object] The value to write. **Setting a value to `nil` doesn't mean *deleting* the value.
+      # @param options [Hash] A list of options for writing. @see Elephas::Cache.write
+      # @return [Object] The value itself.
+      def write(key, value, options = {})
+        ttl = [options[:ttl].to_integer, 0].max
+        fvalue = ::Elephas::Entry.ensure(value, key, options)
+        fvalue.refresh
+        Rails.cache.write(key, value, :expires_in => ttl)
+        value
+      end
+      # Deletes a value from the cache.
+      #
+      # @param key [String] The key to delete.
+      # @return [Boolean] `true` if the key was in the cache, `false` otherwise.
+      def delete(key)
+        fkey = key.ensure_string
+        rv = Rails.cache.exist?(fkey)
+        Rails.cache.delete(fkey)
+        rv
+      end
+      # Checks if a key exists in the cache.
+      #
+      # @param key [String] The key to lookup.
+      # @return [Boolean] `true` if the key is in the cache, `false` otherwise.
+      def exists?(key)
+        fkey = key.ensure_string
+        Rails.cache.exist?(fkey) && Rails.cache.read(fkey).valid?
+      end
+    end
+  end
+end

data/lib/elephas/version.rb ADDED Viewed

@@ -0,0 +1,25 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+# This is the top level module for elephas gem.
+module Elephas
+  # The current version of elephas, according to semantic versioning.
+  #
+  # @see http://semver.org
+  module Version
+    # The major version.
+    MAJOR = 0
+    # The minor version.
+    MINOR = 1
+    # The patch version.
+    PATCH = 0
+    # The current version of elephas.
+    STRING = [MAJOR, MINOR, PATCH].compact.join(".")
+  end
+end

data/lib/elephas.rb ADDED Viewed

@@ -0,0 +1,20 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+$KCODE='UTF8' if RUBY_VERSION < '1.9'
+require "cowtech-extensions"
+require "digest/sha2"
+Cowtech::Extensions.load!("boolean", "math", "object")
+require "elephas/version" if !defined?(Elephas::Version)
+require "elephas/entry"
+require "elephas/provider"
+require "elephas/providers/hash"
+require "elephas/providers/ruby_on_rails"
+require "elephas/cache"
+Elephas::Cache.provider = defined?(Rails) ? Elephas::Providers::RubyOnRails.new : Elephas::Providers::Hash.new

data/spec/coverage_helper.rb ADDED Viewed

@@ -0,0 +1,19 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+require "simplecov"
+require "pathname"
+if ENV["ELEPHAS_COVERAGE"] == "TRUE" then
+  root = Pathname.new(File.dirname(__FILE__)) + ".."
+  SimpleCov.start do
+    add_filter do |src_file|
+      path = Pathname.new(src_file.filename).relative_path_from(root).to_s
+      path !~ /^lib/
+    end
+  end
+end

data/spec/elephas/cache_spec.rb ADDED Viewed

@@ -0,0 +1,41 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+require "spec_helper"
+describe Elephas::Cache do
+  pending ".use" do
+  end
+  describe ".read" do
+    it "should be forwarded to the provider" do
+      Elephas::Cache.provider.should_receive(:read)
+      Elephas::Cache.read("KEY")
+    end
+  end
+  describe ".write" do
+    it "should be forwarded to the provider" do
+      Elephas::Cache.provider.should_receive(:write)
+      Elephas::Cache.write("KEY", "VALUE")
+    end
+  end
+  describe ".delete" do
+    it "should be forwarded to the provider" do
+      Elephas::Cache.provider.should_receive(:delete)
+      Elephas::Cache.delete("KEY")
+    end
+  end
+  describe ".exists?" do
+    it "should be forwarded to the provider" do
+      Elephas::Cache.provider.should_receive(:exists?)
+      Elephas::Cache.exists?("KEY")
+    end
+  end
+end

data/spec/elephas/entry_spec.rb ADDED Viewed

@@ -0,0 +1,11 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+require "spec_helper"
+describe Elephas::Entry do
+end

data/spec/elephas/provider_spec.rb ADDED Viewed

@@ -0,0 +1,46 @@
+# encoding: utf-8
+#
+# This file is part of the elephas gem. Copyright (C) 2012 and above Shogun <shogun_panda@me.com>.
+# Licensed under the MIT license, which can be found at http://www.opensource.org/licenses/mit-license.php.
+#
+require "spec_helper"
+describe Elephas::Providers::Base do
+  class BaseProvider
+    include Elephas::Providers::Base
+  end
+  let(:provider) { BaseProvider.new }
+  describe ".read" do
+    it "should raise an ArgumentError exception" do
+      expect{ provider.read("KEY") }.to raise_error(ArgumentError)
+    end
+  end
+  describe ".write" do
+    it "should raise an ArgumentError exception" do
+      expect{ provider.write("KEY", "VALUE") }.to raise_error(ArgumentError)
+    end
+  end
+  describe ".delete" do
+    it "should raise an ArgumentError exception" do
+      expect{ provider.delete("KEY") }.to raise_error(ArgumentError)
+    end
+  end
+  describe ".exists?" do
+    it "should raise an ArgumentError exception" do
+      expect{ provider.exists?("KEY") }.to raise_error(ArgumentError)
+    end
+  end
+  describe "#now" do
+    it "return a representation for the current time" do
+      Time.stub(:now).and_return(123.456)
+      expect(provider.now).to eq(Time.now.to_f)
+    end
+  end
+end