RubyGems - elephas - Versions diffs - 0.1.0 - Mend

elephas 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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