jsoncache 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b8b7e2aa8007592f2c122d828b77bf832c495d93
-  data.tar.gz: e7edbb2504cb92aac6ac04dcf12802c71487f152
+  metadata.gz: 50c8df0787884ade8c2d7fa83e76b94301cb28b6
+  data.tar.gz: 39eef372973edf214e4f233e27d8eba77fd7cdad
 SHA512:
-  metadata.gz: 34ed662640fb70a27ee10b8cd42a2e938cb5a5626e1f4baf97fa9f637aab3b925645850da4a6ee7deb653f9cd9b60a14684644c65ba595c5ae77d67d9e79187d
-  data.tar.gz: 907ea8767eb4b034b087c9b8de095614c9c35167e103b21ca5c1a49c869d2752e41b62f5e3b4c33ef28c80d775ba2fef70ddf6b510e4e8da5114c9ca939bf9df
+  metadata.gz: 3bf6e7d37215465702e47e9346b9c1c063d2316be70ee7adf6e0af1adfd28ed13b7236eea465ddf8b07dc503e64db366c6773abc34504b70f7c48d91e93fce9f
+  data.tar.gz: e1c43c2594f07ae5dac8fbbe5b6b357260697441ba4c965ae372c5646067e1af8b7597c308483ed2b96cdaf850e3a58c16c7e18ba7924aa68c211249aa953ee1

data/lib/jsoncache.rb

@@ -1,17 +1,39 @@
 require 'json'
 
 # JSONCache is a simple interface to cache JSON based API calls
+#
+# Author::    Derek Stride  (mailto:djgstride@gmail.com)
+# License::   MIT
+#
+# This module provides an easy to use class method +cache+ which caches json
+# in a key-value fashion to the filesystem in /tmp/jsoncache.
 module JSONCache
   extend self
 
   # Retrieves cached data for the specified key and caches the data provided
-  # if the cache isn't valid.
-  # @param [String] key The key in which to check for cached data.
-  # @param [Hash] options A hash of the parameters to use when caching.
+  # if the cache isn't valid. Specify a code block after the method call that
+  # returns a hash and it will be cached.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +options+:: +Hash+ A hash of the parameters to use when caching.
+  #
+  # ==== Options
+  #
   # Accepted options parameters
-  # => [Boolean] symbolize
-  # => [String] cache_directory
-  # => [Fixnum] delta
+  #
+  # * +:symbolize+:: +Boolean+ Symbolize keys while parsing JSON.
+  # * +:cache_directory+:: +String+ The folder name in /tmp to use as the cache.
+  # * +:delta+:: +Fixnum+ The validity time of the cache in seconds.
+  #
+  # ==== Examples
+  #
+  #   def get_response(uri)
+  #     JSONCache.cache(uri_to_key(uri), delta: 120) do
+  #       query_some_json_api(uri)
+  #     end
+  #   end
   def cache(key, options = {})
     return retrieve_cache(key, options) if cached?(key, options)
     result = yield
@@ -26,8 +48,11 @@ module JSONCache
   ########################################################################
 
   # Determine whether a file is cached and healthy
-  # @param [String] key The key in which to check for cached data.
-  # @param [Hash] options A hash of the parameters to use when caching.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +options+:: +Hash+ A hash of the parameters to use when caching.
   def cached?(key, options = {})
     timestamp = timestamp_from_key(key, options[:cache_directory])
     delta = options[:delta] || 0
@@ -41,9 +66,12 @@ module JSONCache
   end
 
   # Cache the result from the uri
-  # @param [String] key The key in which to check for cached data.
-  # @param [Hash] data The response to cache.
-  # @param [Hash] options A hash of the parameters to use when caching.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +data+:: +Hash+ The data to cache.
+  # +options+:: +Hash+ A hash of the parameters to use when caching.
   def cache_file(key, data, options = {})
     return unless data.respond_to?(:to_h)
 
@@ -58,8 +86,11 @@ module JSONCache
   end
 
   # Retrieves a cached value from a key
-  # @param [String] key The key in which to check for cached data.
-  # @param [Hash] options A hash of the parameters to use when caching.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +options+:: +Hash+ A hash of the parameters to use when caching.
   def retrieve_cache(key, options = {})
     directory = options[:cache_directory]
     filename = filename_from_key(key, directory)
@@ -75,7 +106,10 @@ module JSONCache
   ########################################################################
 
   # Create, if necessary, and return a cache directory
-  # @param [String] directory The name of the cache directory.
+  #
+  # ==== Parameters
+  #
+  # +directory+:: +String+ The name of the cache directory.
   def cache_dir(directory)
     directory ||= 'jsoncache'
     cache_path = File.join('/tmp', directory)
@@ -84,8 +118,11 @@ module JSONCache
   end
 
   # Gets an existing file from a uri if it exists
-  # @param [String] key The key in which to check for cached data.
-  # @param [String] directory The name of the cache directory.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +directory+:: +String+ The name of the cache directory.
   def filename_from_key(key, directory)
     directory ||= 'jsoncache'
     Dir.foreach(cache_dir(directory)) do |filename|
@@ -95,8 +132,11 @@ module JSONCache
   end
 
   # Extracts a timestamp from an existing file
-  # @param [String] key The key in which to check for cached data.
-  # @param [String] directory The name of the cache directory.
+  #
+  # ==== Parameters
+  #
+  # +key+:: +String+ The key in which to check for cached data.
+  # +directory+:: +String+ The name of the cache directory.
   def timestamp_from_key(key, directory)
     path = filename_from_key(key, directory)
     return 0 if path.nil?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsoncache
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Derek Stride