elephas 0.1.0 → 1.0.0

data/doc/Elephas.html

@@ -121,7 +121,7 @@ Licensed under the MIT license, which can be found at <a href="http://www.openso
 </div>
 
     <div id="footer">
-  Generated on Sat Jul 28 14:29:51 2012 by
+  Generated on Sun Jul 29 10:32:07 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>

data/doc/_index.html

@@ -198,7 +198,7 @@
 </div>
 
     <div id="footer">
-  Generated on Sat Jul 28 14:29:51 2012 by
+  Generated on Sun Jul 29 10:32:07 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>

data/doc/file.README.html

@@ -66,23 +66,49 @@
 <p><a href="http://travis-ci.org/ShogunPanda/elephas"><img src="https://secure.travis-ci.org/ShogunPanda/elephas.png?branch=master" alt="Build Status"></a>
 <a href="https://gemnasium.com/ShogunPanda/elephas"><img src="https://gemnasium.com/ShogunPanda/elephas.png?travis" alt="Dependency Status"></a></p>
 
-<p>A storage agnostic caching framework.
-<a href="http://github.com/ShogunPanda/elephas">http://github.com/ShogunPanda/elephas</a></p>
+<p>A storage agnostic caching framework.</p>
+
+<p><a href="http://github.com/ShogunPanda/elephas">http://github.com/ShogunPanda/elephas</a></p>
 
 <h2>Usage</h2>
 
-<p><em>TODO</em></p>
+<p>The usage of the framework is really simple.</p>
+
+<p>At first you have to setup a provider (that is, a storage) for the Elephas. By default it uses an internal hash, and also Rails is supported.</p>
+
+<pre class="code ruby"><code><span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Cache</span><span class='period'>.</span><span class='id identifier rubyid_provider'>provider</span> <span class='op'>=</span> <span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Providers</span><span class='op'>::</span><span class='const'>RubyOnRails</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
+</code></pre>
+
+<p>After that, you can query the framework for a value use the <code>use</code> method.</p>
+
+<p>You should also pass a block to the method, so that the framework use that for computing the value of the cache entry.</p>
+
+<pre class="code ruby"><code><span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Cache</span><span class='period'>.</span><span class='id identifier rubyid_use'>use</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>KEY</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_options'>options</span><span class='op'>|</span>
+  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>VALUE</span><span class='tstring_end'>&quot;</span></span>
+<span class='kw'>end</span>
+<span class='comment'># =&gt; &quot;VALUE&quot;
+</span></code></pre>
+
+<p>The next time you issue this call, the block won&#39;t be called.</p>
+
+<p>The block takes an argument, which contains all the options for the entry.</p>
+
+<p>You can see <code>Elephas::Cache.setup_options</code> documentation to see what options are supported.</p>
+
+<p>For now, you just have to know that you can set the <code>:ttl</code> option to specify how long the value will stay in the cache (in milliseconds). Setting it to a non-positive value means to never cache the value.</p>
 
 <p>See documentation for more informations.</p>
 
+<p><strong>You&#39;re done!</strong></p>
+
 <h2>Contributing to elephas</h2>
 
 <ul>
-<li>Check out the latest master to make sure the feature hasn&#39;t been implemented or the bug hasn&#39;t been fixed yet</li>
-<li>Check out the issue tracker to make sure someone already hasn&#39;t requested it and/or contributed it</li>
-<li>Fork the project</li>
-<li>Start a feature/bugfix branch</li>
-<li>Commit and push until you are happy with your contribution</li>
+<li>Check out the latest master to make sure the feature hasn&#39;t been implemented or the bug hasn&#39;t been fixed yet.</li>
+<li>Check out the issue tracker to make sure someone already hasn&#39;t requested it and/or contributed it.</li>
+<li>Fork the project.</li>
+<li>Start a feature/bugfix branch.</li>
+<li>Commit and push until you are happy with your contribution.</li>
 <li>Make sure to add tests for it. This is important so I don&#39;t break it in a future version unintentionally.</li>
 <li>Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.</li>
 </ul>
@@ -94,7 +120,7 @@ Licensed under the MIT license, which can be found at <a href="http://www.openso
 </div></div>
 
     <div id="footer">
-  Generated on Sat Jul 28 14:29:51 2012 by
+  Generated on Sun Jul 29 10:32:07 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>

data/doc/index.html

@@ -66,23 +66,49 @@
 <p><a href="http://travis-ci.org/ShogunPanda/elephas"><img src="https://secure.travis-ci.org/ShogunPanda/elephas.png?branch=master" alt="Build Status"></a>
 <a href="https://gemnasium.com/ShogunPanda/elephas"><img src="https://gemnasium.com/ShogunPanda/elephas.png?travis" alt="Dependency Status"></a></p>
 
-<p>A storage agnostic caching framework.
-<a href="http://github.com/ShogunPanda/elephas">http://github.com/ShogunPanda/elephas</a></p>
+<p>A storage agnostic caching framework.</p>
+
+<p><a href="http://github.com/ShogunPanda/elephas">http://github.com/ShogunPanda/elephas</a></p>
 
 <h2>Usage</h2>
 
-<p><em>TODO</em></p>
+<p>The usage of the framework is really simple.</p>
+
+<p>At first you have to setup a provider (that is, a storage) for the Elephas. By default it uses an internal hash, and also Rails is supported.</p>
+
+<pre class="code ruby"><code><span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Cache</span><span class='period'>.</span><span class='id identifier rubyid_provider'>provider</span> <span class='op'>=</span> <span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Providers</span><span class='op'>::</span><span class='const'>RubyOnRails</span><span class='period'>.</span><span class='id identifier rubyid_new'>new</span>
+</code></pre>
+
+<p>After that, you can query the framework for a value use the <code>use</code> method.</p>
+
+<p>You should also pass a block to the method, so that the framework use that for computing the value of the cache entry.</p>
+
+<pre class="code ruby"><code><span class='id identifier rubyid_value'>value</span> <span class='op'>=</span> <span class='const'>Elephas</span><span class='op'>::</span><span class='const'>Cache</span><span class='period'>.</span><span class='id identifier rubyid_use'>use</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>KEY</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_options'>options</span><span class='op'>|</span>
+  <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>VALUE</span><span class='tstring_end'>&quot;</span></span>
+<span class='kw'>end</span>
+<span class='comment'># =&gt; &quot;VALUE&quot;
+</span></code></pre>
+
+<p>The next time you issue this call, the block won&#39;t be called.</p>
+
+<p>The block takes an argument, which contains all the options for the entry.</p>
+
+<p>You can see <code>Elephas::Cache.setup_options</code> documentation to see what options are supported.</p>
+
+<p>For now, you just have to know that you can set the <code>:ttl</code> option to specify how long the value will stay in the cache (in milliseconds). Setting it to a non-positive value means to never cache the value.</p>
 
 <p>See documentation for more informations.</p>
 
+<p><strong>You&#39;re done!</strong></p>
+
 <h2>Contributing to elephas</h2>
 
 <ul>
-<li>Check out the latest master to make sure the feature hasn&#39;t been implemented or the bug hasn&#39;t been fixed yet</li>
-<li>Check out the issue tracker to make sure someone already hasn&#39;t requested it and/or contributed it</li>
-<li>Fork the project</li>
-<li>Start a feature/bugfix branch</li>
-<li>Commit and push until you are happy with your contribution</li>
+<li>Check out the latest master to make sure the feature hasn&#39;t been implemented or the bug hasn&#39;t been fixed yet.</li>
+<li>Check out the issue tracker to make sure someone already hasn&#39;t requested it and/or contributed it.</li>
+<li>Fork the project.</li>
+<li>Start a feature/bugfix branch.</li>
+<li>Commit and push until you are happy with your contribution.</li>
 <li>Make sure to add tests for it. This is important so I don&#39;t break it in a future version unintentionally.</li>
 <li>Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.</li>
 </ul>
@@ -94,7 +120,7 @@ Licensed under the MIT license, which can be found at <a href="http://www.openso
 </div></div>
 
     <div id="footer">
-  Generated on Sat Jul 28 14:29:51 2012 by
+  Generated on Sun Jul 29 10:32:07 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>

data/doc/method_list.html

@@ -47,25 +47,25 @@
         
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/Hash.html#data-instance_method" title="Elephas::Providers::Hash#data (method)">#data</a></span>
+    <span class='object_link'><a href="Elephas/Entry.html#%3D%3D-instance_method" title="Elephas::Entry#== (method)">#==</a></span>
     
-      <small>Elephas::Providers::Hash</small>
+      <small>Elephas::Entry</small>
     
   </li>
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Elephas/Providers/RubyOnRails.html#delete-instance_method" title="Elephas::Providers::RubyOnRails#delete (method)">#delete</a></span>
+    <span class='object_link'><a href="Elephas/Providers/Hash.html#data-instance_method" title="Elephas::Providers::Hash#data (method)">#data</a></span>
     
-      <small>Elephas::Providers::RubyOnRails</small>
+      <small>Elephas::Providers::Hash</small>
     
   </li>
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/Base.html#delete-instance_method" title="Elephas::Providers::Base#delete (method)">#delete</a></span>
+    <span class='object_link'><a href="Elephas/Cache.html#default_prefix-class_method" title="Elephas::Cache.default_prefix (method)">default_prefix</a></span>
     
-      <small>Elephas::Providers::Base</small>
+      <small>Elephas::Cache</small>
     
   </li>
   
@@ -79,6 +79,14 @@
   
 
   <li class="r1 ">
+    <span class='object_link'><a href="Elephas/Providers/RubyOnRails.html#delete-instance_method" title="Elephas::Providers::RubyOnRails#delete (method)">#delete</a></span>
+    
+      <small>Elephas::Providers::RubyOnRails</small>
+    
+  </li>
+  
+
+  <li class="r2 ">
     <span class='object_link'><a href="Elephas/Cache.html#delete-class_method" title="Elephas::Cache.delete (method)">delete</a></span>
     
       <small>Elephas::Cache</small>
@@ -86,6 +94,14 @@
   </li>
   
 
+  <li class="r1 ">
+    <span class='object_link'><a href="Elephas/Providers/Base.html#delete-instance_method" title="Elephas::Providers::Base#delete (method)">#delete</a></span>
+    
+      <small>Elephas::Providers::Base</small>
+    
+  </li>
+  
+
   <li class="r2 ">
     <span class='object_link'><a href="Elephas/Entry.html#ensure-class_method" title="Elephas::Entry.ensure (method)">ensure</a></span>
     
@@ -95,33 +111,33 @@
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/Base.html#exists%3F-instance_method" title="Elephas::Providers::Base#exists? (method)">#exists?</a></span>
+    <span class='object_link'><a href="Elephas/Providers/Hash.html#exists%3F-instance_method" title="Elephas::Providers::Hash#exists? (method)">#exists?</a></span>
     
-      <small>Elephas::Providers::Base</small>
+      <small>Elephas::Providers::Hash</small>
     
   </li>
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Elephas/Providers/Hash.html#exists%3F-instance_method" title="Elephas::Providers::Hash#exists? (method)">#exists?</a></span>
+    <span class='object_link'><a href="Elephas/Cache.html#exists%3F-class_method" title="Elephas::Cache.exists? (method)">exists?</a></span>
     
-      <small>Elephas::Providers::Hash</small>
+      <small>Elephas::Cache</small>
     
   </li>
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/RubyOnRails.html#exists%3F-instance_method" title="Elephas::Providers::RubyOnRails#exists? (method)">#exists?</a></span>
+    <span class='object_link'><a href="Elephas/Providers/Base.html#exists%3F-instance_method" title="Elephas::Providers::Base#exists? (method)">#exists?</a></span>
     
-      <small>Elephas::Providers::RubyOnRails</small>
+      <small>Elephas::Providers::Base</small>
     
   </li>
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Elephas/Cache.html#exists%3F-class_method" title="Elephas::Cache.exists? (method)">exists?</a></span>
+    <span class='object_link'><a href="Elephas/Providers/RubyOnRails.html#exists%3F-instance_method" title="Elephas::Providers::RubyOnRails#exists? (method)">#exists?</a></span>
     
-      <small>Elephas::Cache</small>
+      <small>Elephas::Providers::RubyOnRails</small>
     
   </li>
   
@@ -183,17 +199,17 @@
   
 
   <li class="r2 ">
-    <span class='object_link'><a href="Elephas/Providers/Hash.html#read-instance_method" title="Elephas::Providers::Hash#read (method)">#read</a></span>
+    <span class='object_link'><a href="Elephas/Providers/Base.html#read-instance_method" title="Elephas::Providers::Base#read (method)">#read</a></span>
     
-      <small>Elephas::Providers::Hash</small>
+      <small>Elephas::Providers::Base</small>
     
   </li>
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/Base.html#read-instance_method" title="Elephas::Providers::Base#read (method)">#read</a></span>
+    <span class='object_link'><a href="Elephas/Cache.html#read-class_method" title="Elephas::Cache.read (method)">read</a></span>
     
-      <small>Elephas::Providers::Base</small>
+      <small>Elephas::Cache</small>
     
   </li>
   
@@ -207,9 +223,9 @@
   
 
   <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Cache.html#read-class_method" title="Elephas::Cache.read (method)">read</a></span>
+    <span class='object_link'><a href="Elephas/Providers/Hash.html#read-instance_method" title="Elephas::Providers::Hash#read (method)">#read</a></span>
     
-      <small>Elephas::Cache</small>
+      <small>Elephas::Providers::Hash</small>
     
   </li>
   
@@ -223,6 +239,14 @@
   
 
   <li class="r1 ">
+    <span class='object_link'><a href="Elephas/Cache.html#setup_options-class_method" title="Elephas::Cache.setup_options (method)">setup_options</a></span>
+    
+      <small>Elephas::Cache</small>
+    
+  </li>
+  
+
+  <li class="r2 ">
     <span class='object_link'><a href="Elephas/Entry.html#ttl-instance_method" title="Elephas::Entry#ttl (method)">#ttl</a></span>
     
       <small>Elephas::Entry</small>
@@ -230,7 +254,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="Elephas/Entry.html#updated_at-instance_method" title="Elephas::Entry#updated_at (method)">#updated_at</a></span>
     
       <small>Elephas::Entry</small>
@@ -238,7 +262,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="Elephas/Cache.html#use-class_method" title="Elephas::Cache.use (method)">use</a></span>
     
       <small>Elephas::Cache</small>
@@ -246,7 +270,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="Elephas/Entry.html#valid%3F-instance_method" title="Elephas::Entry#valid? (method)">#valid?</a></span>
     
       <small>Elephas::Entry</small>
@@ -254,7 +278,7 @@
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="Elephas/Entry.html#value-instance_method" title="Elephas::Entry#value (method)">#value</a></span>
     
       <small>Elephas::Entry</small>
@@ -262,15 +286,15 @@
   </li>
   
 
-  <li class="r2 ">
-    <span class='object_link'><a href="Elephas/Cache.html#write-class_method" title="Elephas::Cache.write (method)">write</a></span>
+  <li class="r1 ">
+    <span class='object_link'><a href="Elephas/Providers/Hash.html#write-instance_method" title="Elephas::Providers::Hash#write (method)">#write</a></span>
     
-      <small>Elephas::Cache</small>
+      <small>Elephas::Providers::Hash</small>
     
   </li>
   
 
-  <li class="r1 ">
+  <li class="r2 ">
     <span class='object_link'><a href="Elephas/Providers/RubyOnRails.html#write-instance_method" title="Elephas::Providers::RubyOnRails#write (method)">#write</a></span>
     
       <small>Elephas::Providers::RubyOnRails</small>
@@ -278,7 +302,7 @@
   </li>
   
 
-  <li class="r2 ">
+  <li class="r1 ">
     <span class='object_link'><a href="Elephas/Providers/Base.html#write-instance_method" title="Elephas::Providers::Base#write (method)">#write</a></span>
     
       <small>Elephas::Providers::Base</small>
@@ -286,10 +310,10 @@
   </li>
   
 
-  <li class="r1 ">
-    <span class='object_link'><a href="Elephas/Providers/Hash.html#write-instance_method" title="Elephas::Providers::Hash#write (method)">#write</a></span>
+  <li class="r2 ">
+    <span class='object_link'><a href="Elephas/Cache.html#write-class_method" title="Elephas::Cache.write (method)">write</a></span>
     
-      <small>Elephas::Providers::Hash</small>
+      <small>Elephas::Cache</small>
     
   </li>
   

data/doc/top-level-namespace.html

@@ -103,7 +103,7 @@
 </div>
 
     <div id="footer">
-  Generated on Sat Jul 28 14:29:51 2012 by
+  Generated on Sun Jul 29 10:32:07 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>

data/lib/elephas/cache.rb

@@ -12,36 +12,43 @@ module Elephas
       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.
+      #
+      # It tries reading a key from the cache.
+      #
+      # If it doesn't find it, it uses the provided block (which receives options as argument) to compute its value and then store it into the cache for later usages.
+      #
+      # ```ruby
+      # value = Elephas::Cache.use("KEY") do |options|
+      #   "VALUE"
+      # end
+      #
+      # value
+      # # => "VALUE"
+      #
+      # value = Elephas::Cache.use("KEY") do |options|
+      #   "ANOTHER VALUE"
+      # end
+      #
+      # value
+      # # => "VALUE"
+      # ```
       #
       # @param key [String] The key to lookup.
       # @return [Object|Entry] The found or newly-set value associated to the key.
+      # @see
       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)
+        options = self.setup_options(options, key)
 
         # 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
+          rv = yield(options)
+          rv = ::Elephas::Entry.ensure(rv, options[:complete_key], options) # Make sure is an entry
+          Elephas::Cache.write(rv.hash, rv, options) if !rv.value.nil? && options[:ttl] > 0 # We have a value and we have to store it
         end
 
         # Return value
@@ -61,18 +68,16 @@ module Elephas
       # @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.
+      # @see .setup_options
       # @return [Object] The value itself.
       def write(key, value, options = {})
-        # TODO: Handle options
-
-        self.provider.write(key, value, options)
+        self.provider.write(key, value, self.setup_options(options, key))
       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.
+      # @return [Boolean] `true` if the key was in the cache, `false` otherwise.
       def delete(key)
         self.provider.delete(key)
       end
@@ -80,10 +85,48 @@ module Elephas
       # 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.
+      # @return [Boolean] `true` if the key is in the cache, `false` otherwise.
       def exists?(key)
         self.provider.exists?(key)
       end
+
+      # Returns the default prefix for cache entries.
+      #
+      # @return [String] The default prefix for cache entries.
+      def default_prefix
+        "elephas-#{::Elephas::Version::STRING}-cache"
+      end
+
+      # Setups options for use into the framework.
+      # Valid options are:
+      #
+      #   * **:ttl**: The TTL (time to live, in milliseconds) of the entry. It means how long will the value stay in cache. Setting it to 0 or less means never cache the entry.
+      #   * **:force**: Setting it to `true` will always skip the cache.
+      #   * **:key**: The key associated to this value. **You should never set this option directly.**
+      #   * **:prefix**: The prefix used in cache. This is used to avoid conflicts with other caching frameworks.
+      #   * **:complete_key**: The complete key used for computing the hash. By default is concatenation of `:key` and `:prefix` options.
+      #   * **:hash**: The hash used to store the key in the cache. Should be unique
+      #   * **:as_entry**: In `Elephas::Cache.use`, setting this to `true` will return the entire `Entry` object rather than the value only.
+      #
+      # @param options [Object] An initial setup.
+      # @param key [String] The key to associate to this options.
+      # @return [Hash] An options hash.
+      def setup_options(options, key)
+        options = {} if !options.is_a?(::Hash)
+        options = {:ttl => 1.hour * 1000, :force => false, :as_entry => false}.merge(options)
+        options[:key] ||= key.ensure_string
+        options[:ttl] == options[:ttl].blank? ? 1.hour * 1000 : [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.
+        options[:complete_key] ||= "#{options[:prefix]}[#{options[:key]}]"
+
+        # Compute the hash key used for referencing this value
+        options[:hash] ||= ::Elephas::Entry.hashify_key(options[:complete_key])
+
+        options
+      end
     end
   end
 end

data/lib/elephas/entry.rb

@@ -5,7 +5,7 @@
 #
 
 module Elephas
-  # This represents a cache entry.
+  # Represents a cache entry.
   class Entry
     # The key for this entry.
     attr_accessor :key
@@ -28,7 +28,7 @@ module Elephas
     # @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)
+    def initialize(key, value, hash = nil, ttl = 360000)
       hash = self.class.hashify_key(key) if hash.blank?
       self.key = key
       self.hash = hash
@@ -40,10 +40,12 @@ module Elephas
     # Refreshes the entry.
     #
     # @param save [Boolean] If to save the refresh value in the cache.
+    # @return [Float] The new updated_at value.
     def refresh(save = false)
       self.updated_at = Time.now.to_f
 
-      # TODO: Set this value in the cache
+      Elephas::Cache.provider.write(self.hash, self) if save
+      self.updated_at
     end
 
     # Checks if the entry is still valid.
@@ -52,7 +54,15 @@ module Elephas
     # @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
+      provider.now - self.updated_at < self.ttl / 1000
+    end
+
+    # Compare to another Entry.
+    #
+    # @param other [Entry] The entry to compare with
+    # @return [Boolean] `true` if the entries are the same, `false` otherwise.
+    def ==(other)
+      other.is_a?(::Elephas::Entry) && [self.key, self.hash, self.value] == [other.key, other.hash, other.value]
     end
 
     # Returns a unique hash for the key.

data/lib/elephas/provider.rb

@@ -17,17 +17,18 @@ module Elephas
       # @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.")
+        raise ArgumentError.new("A Elephas::Providers subclass must override this method.")
       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
+      # @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.setup_options
       # @return [Object] The value itself.
       def write(key, value, options = {})
-        raise ArgumentError.new("A Elephas::Providers subclass should override this module.")
+        raise ArgumentError.new("A Elephas::Providers subclass must override this method.")
       end
 
       # Deletes a value from the cache.
@@ -35,7 +36,7 @@ module Elephas
       # @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.")
+        raise ArgumentError.new("A Elephas::Providers subclass must override this method.")
       end
 
       # Checks if a key exists in the cache.
@@ -43,7 +44,7 @@ module Elephas
       # @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.")
+        raise ArgumentError.new("A Elephas::Providers subclass must override this method.")
       end
 
       # Returns the current time for comparing with entries TTL.

data/lib/elephas/providers/hash.rb

@@ -31,8 +31,9 @@ module Elephas
       # 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
+      # @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.setup_options
       # @return [Object] The value itself.
       def write(key, value, options = {})
         fvalue = ::Elephas::Entry.ensure(value, key, options)