earth_tools 0.0.1 → 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+Find the changes below for each version.
+
+## 0.1.0
+* Add cache handling
+
+## 0.0.1
+* Initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,136 @@
+# earth_tools
+[![Gem Version](https://badge.fury.io/rb/earth_tools.png)](http://badge.fury.io/rb/earth_tools) [![Dependency Status](https://gemnasium.com/mckramer/earth_tools.png?travis)](https://gemnasium.com/mckramer/earth_tools) [![Code Climate](https://codeclimate.com/github/mckramer/earth_tools.png)](https://codeclimate.com/github/mckramer/earth_tools) [![Build Status](https://secure.travis-ci.org/mckramer/earth_tools.png?branch=master)](http://travis-ci.org/mckramer/earth_tools)
+
+`earth_tools` is a wrapper around the wonderful [earthtools.org webservices](http://www.earthtools.org/webservices.htm), which allows you to determine the sea level height, time zone, and surise/sunset times from a set of coordinates.
+
+## Compatibility
+
+* Supports Ruby 1.9.2 & 1.9.3
+
+Will be testing on other versions in the future.
+
+## Installation instructions
+
+Add to your Gemfile:
+
+  `gem 'earth_tools'`
+
+and then bundle your gemfile:
+
+  `bundle install`
+  
+and you are done!
+
+## API
+
+The run down of the 3 major functions available
+
+### Time zone
+
+    # API
+    result = EarthTools.time_zone(latitude, longitude)
+    # Example
+    result = EarthTools.time_zone(40.71417, -74.00639) # New York City
+    result.iso_time   # => 2012-06-14 12:56:40 -0500
+    result.utc_offset # => -5
+    result.utc_time   # => 2012-06-14 17:56:40 +0000
+
+### Height above/below sea level
+
+    # API
+    result = EarthTools.height(latitude, longitude)
+    # Example
+    result = EarthTools.height(52.4822, -1.8946) # Birmingham, AL
+    result.meters # => 141
+    result.feet   # => 462.6
+    result.height # => 462.6 (when EarthTools::Configuration.units is set to :english units)
+
+### Sunrise/sunset times
+
+    # API
+    result = EarthTools.sunrise_sunset(latitude, longitude, month, day, timezone, dst)
+    # Example
+    result = EarthTools.sunrise_sunset(40.71417, -74.00639, 12, 4, -5, 0) # New York City, December 4th
+    result.sunrise     # => 2012-12-04 07:05:50 -0500
+    result.sunset      # => 2012-12-04 16:26:59 -0500
+
+### Configuration
+
+    # Configure block (set to defaults)
+    EarthTools.configure do |config|
+      config.always_raise = []              # Add any errors that you would like to be custom handled, see "Error handling" section below
+      config.cache = nil                    # Cache object (see Caching section for what methods are required)
+      config.cache_prefix = "earth_tools:"  # Prefix to use for cache keys
+      config.timeout = 3                    # Timeout in seconds
+      config.units = :english               # Also, can specify :metric
+    end
+    # Static call
+    EarthTools::Configuration.timeout = 5   # Set timeout to 5 seconds
+
+## Earth Tool API restrictions
+
+### Limits
+
+Earth Tools imposes some [usage restrictions](http://www.earthtools.org/webservices.htm#usage) that are duplicated below (these restrictions may not be kept up-to-date, so please check the website):
+
+1. You *must not* make more than 1 (one) request per second to these webservices.
+2. You *must* cache results if you believe that you will need to make another identical request within any 24-hour period.
+3. You *must* delete any cached data when you no longer need it and in any case after 14 days. You should then make a new request for the data in line with the previous two rules. If you wish to keep access to data I am able to license the data for use in this way.
+
+### Caching
+
+It is recommended to cache retrieved data when relying on an external service. You can configure a cache store:
+
+    EarthTools::Configuration.cache = Redis.new
+    EarthTools::Configuration.cache_prefix = "..." # Provide a custom cache prefix, defaults to 'earth_tools:'
+
+The cache store can be any object that supports the following methods:
+
+<table>
+    <tr>
+        <th>Method</th><th>Description</th><th>Examples</th>
+    </tr>
+    <tr>
+        <td><code>#[](key)</code></td><td>Retrieves a value by with the key</td><td></td>
+    </tr>
+    <tr>
+        <td><code>#[]=(key, value)</code></td><td>Stores a value with the key</td><td></td>
+    </tr>
+    <tr>
+        <td><code>#keys</code></td><td>Retrieves all keys</td><td></td>
+    </tr>
+    <tr>
+        <td>
+            <div><code>#del</code></div>
+            <div>or</div>
+            <div><code>#delete</code></div>
+        </td>
+        <td>Deletes a key</td>
+        <td></td>
+    </tr>
+</table>
+
+If you need to expire cached content:
+
+    EarthTools.cache.expire("http://...") # Expire cached result for a URL
+    EarthTools.cache.expire(:all)         # Expire all cached results
+
+There is no need to include the prefix when passing a URL to be expired. Expiring `:all` will only expire keys with the configured prefix (won't kill every entry in your key/value store).
+
+## Error handling
+
+By default Earth Tools will rescue any exceptions raised by calls to the webservice and return an empty array (using warn() to inform you of the error). You can override this and implement custom error handling for certain exceptions by using the `:always_raise` option:
+
+    EarthTools::Configuration.always_raise = [SocketError, TimeoutError]
+
+## Issues & contributing
+
+No outstanding issues right now.  Please post any issues to the [issues queue on github](https://github.com/mckramer/earth_tools/issues).
+
+## Future
+
+I would love to see this functionality brought into the `geocoder` gem or similar in the future.
+
+# License and attributions
+
+This gem's structure and design borrows heavily from `geocoder`, so thanks to its author.  Find me on twitter [@maxckramer](https://twitter.com/maxckramer).

data/Rakefile

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+desc 'Default: run unit tests'
+task :default => :test
+
+desc 'Run all tests' 
+task :test_all => [:test, :integration_test]
+
+desc 'Run unit tests'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Run integration tests (require to set proxy in test_helper.rb if needed)'
+Rake::TestTask.new(:integration_test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/integration/*_test.rb'
+  t.verbose = true
+end

data/lib/earth_tools/cache.rb

@@ -0,0 +1,80 @@
+module EarthTools
+  
+  ##
+  # The Earth Tools cache wrapper.
+  #
+  # Must respond to:
+  # -> []   -- read
+  # -> []=  -- write
+  # -> del  -- delete
+  # -> keys -- list of keys
+  #
+  class Cache
+    
+    ##
+    # @constructor
+    def initialize(store, prefix)
+      @store = store
+      @prefix = prefix
+    end
+    
+    ##
+    # Read from the cache.
+    # @return the object saved in the cache
+    def [](url)
+      @store[key_for(url)]
+    end
+    
+    ##
+    # Write to the cache.
+    def []=(url, value)
+      @store[key_for(url)] = value
+    end
+    
+    ##
+    # Delete cache entry for given URL,
+    # or pass <tt>:all</tt> to clear all URLs.
+    def expire(url)
+      if url == :all
+        urls.each{ |u| expire(u) }
+      else
+        @store.send(@store.respond_to?(:del) ? :del : :delete, key_for(url))
+      end
+    end
+    
+  private
+    
+    attr_reader :prefix, :store
+    
+    ##
+    # Cache key for a given URL.
+    # @return [String] the cache key
+    def key_for(url)
+      [@prefix, url].join
+    end
+    
+    ##
+    # Array of keys with the currently configured prefix
+    # that have non-nil values.
+    # @return [Array] the list of keys
+    def keys
+      @store.keys.select{ |k| k.match /^#{@prefix}/ and cleave(@store[k]) }
+    end
+    
+    ##
+    # Array of cached URLs.
+    # @return [Array] the list of cached URLs
+    def urls
+      keys.map{ |k| k[/^#{@prefix}(.*)/, 1] }
+    end
+    
+    ##
+    # Convert empty string to nil.
+    # (Some key/value stores return empty string instead of nil.)
+    # @return [Object, nil] the object or nil
+    def cleave(value)
+      value == "" ? nil : value
+    end
+    
+  end
+end

data/lib/earth_tools/configuration.rb

@@ -1,9 +1,10 @@
 require 'singleton'
 module EarthTools
 
-  ## This method can be used to change some functional aspects, like,
-  # the geocoding service provider, or the units of calculations.
-  # Please see {include:Configuration}
+  ##
+  # This method can be used to change some functional aspects, like
+  # the cache client or the units of calculations.
+  # See {include:Configuration}.
   def self.configure(&block)
     if block_given?
       block.call(Configuration.instance)
@@ -12,9 +13,12 @@ module EarthTools
     end
   end
   
+  ##
+  # The singleton that maintains the configuration settings for plugin.
   class Configuration
     include Singleton
     
+    # The available options
     OPTIONS = [
       :timeout,
       :proxy,
@@ -29,24 +33,24 @@ module EarthTools
     def initialize  # :nodoc
       set_defaults
     end
-
-    # This method will set the configuration options to the default values
+    
+    ##
+    # Sets the configuration options to the default values
     def set_defaults
-      @timeout      = 3               # geocoding service timeout (secs)
+      @timeout      = 3               # Geocoding service timeout (secs)
       @proxy        = nil             # HTTP proxy server (user:pass@host:port)
-      @cache        = nil             # cache object (must respond to #[], #[]=, and #keys)
-      @cache_prefix = "earth_tools:"  # prefix (string) to use for all cache keys
-
-      # exceptions that should not be rescued by default
+      @cache        = nil             # Cache object (must respond to #[], #[]=, #keys, and #delete)
+      @cache_prefix = "earth_tools:"  # Prefix (string) to use for all cache keys
+      
+      # Exceptions that should not be rescued by default
       # (if you want to implement custom error handling);
       # supports SocketError and Timeout::Error
       @always_raise = []
-
-      # calculation options
+      
+      # Calculation options
       @units     = :english # :metric or :english
     end
     
-
     # Delegates getters and setters for all configuration settings,
     # and +set_defaults+ to the singleton instance.
     instance_eval(OPTIONS.map do |option|
@@ -55,15 +59,15 @@ module EarthTools
       def #{o}
         instance.#{o}
       end
-
+      
       def #{o}=(value)
         instance.#{o} = value
       end
       EOS
     end.join("\n\n"))
-
+    
     class << self
-      # This method will set the configuration options to the default values
+      # Sets the configuration options to the default values
       def set_defaults
         instance.set_defaults
       end

data/lib/earth_tools/exceptions.rb

@@ -1,29 +1,27 @@
 module EarthTools
-
+  
+  ##
+  # Common error, extended by more specific errors.
   class Error < StandardError
   end
-
+  
   ##
-  #
-  #
+  # Error thrown when there is an issue setting/getting configuration.
   class ConfigurationError < Error
   end
-
+  
   ##
-  #
-  #
+  # Error thrown when too many requests have been made to EarthTools service in.
   class OverQueryLimitError < Error
   end
   
   ##
-  #
-  #
+  # Error thrown when invalid input is provided to the service when querying.
   class InvalidInputError < Error
   end
   
   ##
-  #
-  #
+  # Error thrown when unsupported operation is attempted on the service.
   class UnsupportedOperationError < Error
   end
   

data/lib/earth_tools/lookup/base.rb

@@ -6,96 +6,97 @@ module EarthTools
   module Lookup
     
     ##
-    #
+    # Base lookup object.
     #
     class Base
       
       ##
       # Query the Earth Tools service and return a EarthTools::Result object.
-      # @return [EarthTools::Result, nil] 
+      # @return [EarthTools::Result, nil] the results object
       def search(*options)
         begin
           Timeout::timeout(EarthTools::Configuration.timeout) do
-            raw_results = retrieve(query(options))
-            parse_results(raw_results, :xml)
+            uri = query(options)
+            if cache && results = cache[uri]
+              # Boom, cached
+            else
+              # Not cached, so go get the data
+              raw_results = retrieve(uri)
+              results = parse_xml(raw_results)
+              # Save results to cache, if available
+              cache(uri, results) if cache && results
+            end
+            results
           end
         rescue Timeout::Error => err
           raise_error(err) or warn "Earth Tools API took too long to respond. See EarthTools::Configuration to set the timeout time (currently set to #{EarthTools::Configuration.timeout} seconds)."
         end
       end
-    
+      
       private
       
       ##
-      # The base URL for the web service endpoint (protocol and server)
+      # The base URL for the web service endpoint (protocol and server).
       # @return [String] the base URL
       def base_service_url
         "http://www.earthtools.org"
       end
       
       ##
-      # URL to use for querying the geocoding engine.
-      # @return [String]
-      def query(*options)
-        base_service_url + query_base + options.join('/')
+      # Gets the cache.
+      # @return [EarthTools::Cache] the cache
+      def cache
+        EarthTools::Configuration.cache
       end
       
       ##
-      # Parse results depending on if xml or json
-      #
-      def parse_results(raw_results, type)
-        case type
-        when :xml
-          parse_xml(XmlSimple.xml_in( raw_results, { 'ForceArray' => false } ))
-        when :json
-          raise UnsupportedOperationError, "JSON is not supported"
-        end
+      # URL to use for querying the geocoding engine.
+      # @return [String] the url
+      def query(*options)
+        base_service_url + query_base + options.join('/')
+        # ([base_service_url, query_base] + options).join('/')
       end
       
       ##
-      # Handle XML results by validating them
-      #
-      def parse_xml(xml)
+      # Handle XML results by validating them.
+      # @param raw_xml the xml to parse
+      # @return [Height, SunriseSunset, TimeZone] the result
+      def parse_xml(raw_xml)
+        xml = XmlSimple.xml_in( raw_xml, { 'ForceArray' => false } )
         if xml['location']
           result_class.new(xml)
         else
           warn "Invalid request."
-          puts xml
         end
       end
       
       ##
-      # Handles running query
-      #
+      # Handles running query.
+      # @return [xml] the results
       def retrieve(query)
         RestClient.proxy = EarthTools::Configuration.proxy if EarthTools::Configuration.proxy
-        #puts "Trying to connect to endpoint(#{query})"
-        #puts "Using proxy (#{RestClient.proxy})" if RestClient.proxy
         RestClient.get query
       end
       
       ##
       # Raise exception if configuration specifies it should be raised.
-      # Return false if exception not raised.
-      #
+      # @return [boolean] false, if exception not raised
       def raise_error(error, message = nil)
-        if EarthTools::Configuration.always_raise.include?( error.is_a?(Class) ? error : error.class )
-          raise error, message
-        else
-          false
-        end
+        raise error, message if EarthTools::Configuration.always_raise.include?( error.is_a?(Class) ? error : error.class )
+        false
       end
       
       ##
-      # 
-      #
+      # The base of the query for the function.
+      # @return [String] the base of the query
+      # @throws NotImplementedError when child class does not implement method
       def query_base
         raise NotImplementedError
       end
       
       ##
-      #
-      # 
+      # The class for the result.
+      # @return [EarthTools::Result::Height, EarthTools::Result::SunriseSunset, EarthTools::Result::TimeZone] the result class
       def result_class
         EarthTools::Result.const_get(self.class.to_s.split(":").last)
       end

data/lib/earth_tools/lookup/height.rb

@@ -4,12 +4,12 @@ require 'earth_tools/result/height'
 module EarthTools::Lookup
   
   ##
-  #
+  # The height lookup.
   #
   class Height < Base
     
     private
-
+    
     def query_base
       "/height/"
     end

data/lib/earth_tools/lookup/sunrise_sunset.rb

@@ -2,10 +2,13 @@ require 'earth_tools/lookup/base'
 require 'earth_tools/result/sunrise_sunset'
 
 module EarthTools::Lookup
+  
+  ##
+  # The Sunrise/Sunset lookup.
   class SunriseSunset < Base
     
     private
-
+    
     def query_base
       "/sun/"
     end

data/lib/earth_tools/lookup/time_zone.rb

@@ -2,10 +2,14 @@ require 'earth_tools/lookup/base'
 require 'earth_tools/result/time_zone'
 
 module EarthTools::Lookup
+  
+  ##
+  # The Time Zone lookup.
+  #
   class TimeZone < Base
     
     private
-
+    
     def query_base
       "/timezone/"
     end

data/lib/earth_tools/result/base.rb

@@ -2,48 +2,50 @@ module EarthTools
   module Result
   
     ##
-    #
+    # The base result object.
+    # 
+    # Contains shared domain fields.  Extended by different results.
     #
     class Base
       attr_accessor :data
-
+      
       ##
       # Takes a hash of result data from a parsed Google result document.
-      #
+      # @param [Object] the 
       def initialize(data)
         @data = data
       end
-
+      
       ##
       # Get the geographical location
-      # @returns [Array] a two-element array: [latitude, longitude]
+      # @return [Array] a two-element array: [latitude, longitude]
       def location
         [latitude, longitude]
       end
-
+      
       ##
       # Get the latitude
       # See {http://en.wikipedia.org/wiki/Latitude}.
-      # @returns [Float] the latitude
+      # @return [Float] the latitude
       def latitude
         @data['latitude'].to_f
       end
-
+      
       ##
       # Get the longitude
       # See {http://en.wikipedia.org/wiki/Longitude}.
-      # @returns the longitude
+      # @return the longitude
       def longitude
         @data['longitude'].to_f
       end
       
       ##
       # The version of the response format
-      # @returns [Float] the version
+      # @return [Float] the version
       def version
         @data['version'].to_f
       end
-
+      
     end
   end
 end

data/lib/earth_tools/result/height.rb

@@ -4,10 +4,9 @@ require 'earth_tools/configuration'
 module EarthTools::Result
   
   ##
-  #
-  #  
+  # The height result.
   class Height < Base
-
+    
     ##
     # Returns height based on unit requested in configuration
     # @return [float] 

data/lib/earth_tools/result/sunrise_sunset.rb

@@ -3,17 +3,16 @@ require 'earth_tools/result/base'
 module EarthTools::Result
 
   ##
-  # The sunrise/sunset result object
-  #
+  # The sunrise/sunset result.
   class SunriseSunset < Base
-  
+    
     ##
     # The date of the sunrise/sunset data as a hash
     # @return [Hash] Hash containing year, month, and day as integers
     def date
       { :year => Time.now.year, :month => @data['date']['month'].to_i, :day => @data['date']['day'].to_i }
     end
-
+    
     ##
     # The sunrise time
     # @return [Time] the sunrise time

data/lib/earth_tools/result/time_zone.rb

@@ -3,10 +3,11 @@ require 'earth_tools/result/base'
 module EarthTools::Result
   
   ##
+  # The Time Zone result.
   #
-  #
+  # @see http://www.earthtools.org/webservices.htm#timezone
   class TimeZone < Base
-
+    
     ##
     # Whether or not the {#local_time} and {#iso_time} is currently in DST. If they do, the value of this element will be 'True'. If they do not, the value will be 'False'. If it can't be determined whether or not daylight saving time should be used, the value will be 'Unknown'. 
     # @return [String] 'True' || 'False' || 'Unknown'
@@ -42,7 +43,7 @@ module EarthTools::Result
     def local_time
       iso_time
     end
-  
+    
     ##
     # The number of hours offset from UTC disregarding any correction for daylight saving time
     # See {http://en.wikipedia.org/wiki/UTC_offset}.
@@ -50,7 +51,7 @@ module EarthTools::Result
     def utc_offset
       @data['offset'].to_i
     end
-
+    
     ##
     # The nautical suffix for the time zone
     # See {http://en.wikipedia.org/wiki/Nautical_time}

data/lib/earth_tools/version.rb

@@ -1,4 +1,4 @@
 module EarthTools
   # The gem version
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/earth_tools.rb

@@ -4,30 +4,24 @@
 #
 module EarthTools
   extend self
-   
+  
   ##
   # Retrieve for time zone based on latitude and longitude.
-  #
-  # @returns [EarthTools::Result::TimeZone]
-  #
+  # @returns [EarthTools::Result::TimeZone] the time zone result
   def time_zone(latitude, longitude)
     get_lookup(:time_zone).search(latitude, longitude) if valid_input?(latitude, longitude)
   end
   
   ##
-  # Retrieve the sunrise & sunset values
-  #
-  # @returns [EarthTools::Result::SunriseSunset]
-  #
+  # Retrieve the sunrise & sunset values.
+  # @return [EarthTools::Result::SunriseSunset] the sunrise/sunset result
   def sunrise_sunset(latitude, longitude, month, day, timezone = 99, dst = false)
     get_lookup(:sunrise_sunset).search(latitude, longitude, day, month, timezone, dst ? 1 : 0)
   end
   
   ##
-  # Retrieve the land height for a given latitude and longitude
-  # 
-  # @returns [EarthTools::Result::Height]
-  #
+  # Retrieve the land height for a given latitude and longitude.
+  # @return [EarthTools::Result::Height] the height result
   def height(latitude, longitude)
     get_lookup(:height).search(latitude, longitude)
   end
@@ -36,7 +30,7 @@ module EarthTools
   
   ##
   # Retrieve a lookup object from the store.
-  #
+  # @return [? extends EarthTools::Lookup::Base]
   def get_lookup(name)
     @lookups = {} unless defined?(@lookups)
     @lookups[name] = spawn_lookup(name) unless @lookups.include?(name)
@@ -45,7 +39,7 @@ module EarthTools
   
   ##
   # Spawn a lookup of the given name.
-  #
+  # @return [? extends EarthTools::Lookup::Base] new lookup helper
   def spawn_lookup(name)
     name = name.to_s
     require "earth_tools/lookup/#{name}"
@@ -54,36 +48,36 @@ module EarthTools
   end
   
   ##
-  # Validates input
-  #
+  # Validates input.
+  # @return [Boolean] true, if coordinates are valid
   def valid_input?(latitude, longitude)
     coordinates?(latitude, longitude)
   end
   
   ##
-  # Validates input
-  #
+  # Validates input.
+  # @return [Boolean] true, if all values are valid
   def valid_full_input?(latitude, longitude, day, month, timezone, dst)
     coordinates?(latitude, longitude) && !blank?(day) && !blank(month) && !blank?(timezone) && !blank?(dst)
   end
   
   ##
-  # Validates a pair of coordinates
-  #
+  # Validates a pair of coordinates.
+  # @return [Boolean] true, if latitute and longitude are (sort of) valid coordinates
   def coordinates?(latitude, longitude)
     coordinate?(latitude) && coordinate?(longitude)
   end
   
   ##
-  # Determine if given value is a coordinate
-  #
+  # Determine if given value is a coordinate.
+  # @return [Boolean] true, if given value is a coordinate
   def coordinate?(value)
     !! value.to_f
   end
   
   ##
-  # Determine if given value is blank
-  #
+  # Determine if given value is blank.
+  # @return [Boolean] true, if value is nil or empty
   def blank?(value)
     value.nil? || value.to_s.empty?
   end

data/test/cache_test.rb

@@ -0,0 +1,47 @@
+# encoding: utf-8
+
+require 'test_helper'
+require 'earth_tools'
+require 'earth_tools/cache'
+
+##
+# Tests for the Cache.
+class CacheTest < MiniTest::Unit::TestCase
+  
+  def setup
+    @raw_cache = {}
+    @cache = EarthTools::Cache.new(@raw_cache, 'earth_tools:')
+  end
+  
+  def test_store_and_retrieve_from_cache
+    @cache['test/1'] = :data
+    
+    assert_equal :data, @cache['test/1'], 'The cache was not stored properly.'
+  end
+  
+  def test_remove_single_url
+    @cache['test/1'] = :data
+    @cache['test/2'] = :data
+    
+    @cache.expire('test/1')
+    
+    assert_nil @cache['test/1'], 'The cache should have deleted entry.'
+    assert_equal :data, @cache['test/2'], 'The cache should not have deleted entry.'
+  end
+  
+  def test_remove_all_prefixed_urls
+    @raw_cache['test']        = :data
+    @raw_cache['other:test']  = :data
+    @cache['test/1'] = :data
+    @cache['test/2'] = :data
+    @cache['test/3'] = :data
+    
+    @cache.expire(:all)
+    assert_equal :data, @raw_cache['test'], 'The cache should not affect non-prefixed entries.'
+    assert_equal :data, @raw_cache['other:test'], 'The cache should not affect non-prefixed entries.'
+    assert_nil @cache['test/1'], 'The cache should be empty of prefixed entries.'
+    assert_nil @cache['test/2'], 'The cache should be empty of prefixed entries.'
+    assert_nil @cache['test/3'], 'The cache should be empty of prefixed entries.'
+  end
+  
+end

data/test/configuration_test.rb

@@ -6,7 +6,7 @@ class ConfigurationTest < MiniTest::Unit::TestCase
   def setup
     EarthTools::Configuration.set_defaults
   end
- 
+  
   # --- class method configuration ---
   def test_configurated_by_class_method
     EarthTools::Configuration.units = :metric
@@ -18,7 +18,7 @@ class ConfigurationTest < MiniTest::Unit::TestCase
       refute_equal result.height, result.feet
     end
   end
- 
+  
   # --- EarthTools#configure distances configuration ---
   def test_configuration
     
@@ -26,7 +26,7 @@ class ConfigurationTest < MiniTest::Unit::TestCase
     EarthTools.configure do |config|
       config.units  = :metric
     end
- 
+    
     assert_equal EarthTools::Configuration.units, :metric
     result = EarthTools.height(52.4822, -1.8946)
     if result.height == 0
@@ -34,10 +34,10 @@ class ConfigurationTest < MiniTest::Unit::TestCase
     else
       refute_equal result.height, result.feet
     end
- 
+    
     # Direct
     EarthTools.configure.units  = :metric
- 
+    
     assert_equal EarthTools::Configuration.units, :metric
     result = EarthTools.height(52.4822, -1.8946)
     assert_equal result.height, result.meters

data/test/earth_tools_test.rb

@@ -7,6 +7,8 @@ require 'earth_tools/result/sunrise_sunset'
 require 'earth_tools/result/time_zone'
 require 'mock_lookup'
 
+##
+# Tests for module static methods.
 class EarthToolsTest < MiniTest::Unit::TestCase
   
   def test_time_zone_method_returns_result_object

data/test/height_test.rb

@@ -6,8 +6,7 @@ require 'earth_tools/result/height'
 require 'mock_lookup'
 
 ##
-#
-#
+# Tests for height lookups.
 class HeightTest < MiniTest::Unit::TestCase
 
   def setup

data/test/mock_lookup.rb

@@ -1,6 +1,10 @@
 require 'earth_tools/lookup/base'
-class EarthTools::Lookup::Base
 
+##
+# Mock Lookup class.
+# Overrides normal lookup base for testing.
+class EarthTools::Lookup::Base
+  
   private
   
   def read_fixture(file)
@@ -14,5 +18,5 @@ class EarthTools::Lookup::Base
     query = query.split('/')
     read_fixture "#{ query[3] }_(#{ query[4, query.size-1].join(',') }).xml"
   end
-
+  
 end

data/test/sunrise_sunset_test.rb

@@ -5,8 +5,10 @@ require 'earth_tools'
 require 'earth_tools/result/sunrise_sunset'
 require 'mock_lookup'
 
+##
+# Tests for Sunrise/Sunset lookups.
 class SunriseSunsetTest < MiniTest::Unit::TestCase
-
+  
   def setup
     @result = EarthTools.sunrise_sunset(40.71417, -74.00639, 12, 4)
   end
@@ -20,7 +22,7 @@ class SunriseSunsetTest < MiniTest::Unit::TestCase
   end
   
   def test_sunrise_parsed_correctly
-    assert_equal Time.new(2012, 12, 4, 7, 5, 50, '-05:00'), @result.sunrise, 'Sunrise was not parsed correctly'
+    assert_equal Time.new(Time.now.year, 12, 4, 7, 5, 50, '-05:00'), @result.sunrise, 'Sunrise was not parsed correctly'
   end
   
   # ---------------------------------------------------------------------------
@@ -32,7 +34,7 @@ class SunriseSunsetTest < MiniTest::Unit::TestCase
   end
   
   def test_sunset_parsed_correctly
-    assert_equal Time.new(2012, 12, 4, 16, 26, 59, '-05:00'), @result.sunset, 'Sunset was not parsed correctly'
+    assert_equal Time.new(Time.now.year, 12, 4, 16, 26, 59, '-05:00'), @result.sunset, 'Sunset was not parsed correctly'
   end
   
   # ---------------------------------------------------------------------------
@@ -49,12 +51,13 @@ class SunriseSunsetTest < MiniTest::Unit::TestCase
   end
   
   def test_twilight_parsed_correctly
-    assert_equal Time.new(2012, 12, 4, 5, 27, 39, '-05:00'), @result.twilight(:morning, :astronomical), 'Twilight was not parsed correctly'
-    assert_equal Time.new(2012, 12, 4, 6, 35, 6, '-05:00'), @result.twilight(:morning, :civil), 'Twilight was not parsed correctly'
-    assert_equal Time.new(2012, 12, 4, 6, 0, 50, '-05:00'), @result.twilight(:morning, :nautical), 'Twilight was not parsed correctly'
-    assert_equal Time.new(2012, 12, 4, 18, 5, 10, '-05:00'), @result.twilight(:evening, :astronomical), 'Twilight was not parsed correctly'
-    assert_equal Time.new(2012, 12, 4, 16, 57, 43, '-05:00'), @result.twilight(:evening, :civil), 'Twilight was not parsed correctly'
-    assert_equal Time.new(2012, 12, 4, 17, 31, 59, '-05:00'), @result.twilight(:evening, :nautical), 'Twilight was not parsed correctly'
+    year = Time.now.year
+    assert_equal Time.new(year, 12, 4, 5, 27, 39, '-05:00'), @result.twilight(:morning, :astronomical), 'Twilight was not parsed correctly'
+    assert_equal Time.new(year, 12, 4, 6, 35, 6, '-05:00'), @result.twilight(:morning, :civil), 'Twilight was not parsed correctly'
+    assert_equal Time.new(year, 12, 4, 6, 0, 50, '-05:00'), @result.twilight(:morning, :nautical), 'Twilight was not parsed correctly'
+    assert_equal Time.new(year, 12, 4, 18, 5, 10, '-05:00'), @result.twilight(:evening, :astronomical), 'Twilight was not parsed correctly'
+    assert_equal Time.new(year, 12, 4, 16, 57, 43, '-05:00'), @result.twilight(:evening, :civil), 'Twilight was not parsed correctly'
+    assert_equal Time.new(year, 12, 4, 17, 31, 59, '-05:00'), @result.twilight(:evening, :nautical), 'Twilight was not parsed correctly'
   end
   
   # ---------------------------------------------------------------------------
@@ -73,8 +76,8 @@ class SunriseSunsetTest < MiniTest::Unit::TestCase
     assert @result.morning_astronomical_twilight.is_a?(Time), 'Morning astronomical twilight should be a time'
   end
   
-  def test_twilight_parsed_correctly
-    assert_equal Time.new(2012, 12, 4, 5, 27, 39, '-05:00'), @result.morning_astronomical_twilight, 'Twilight was not parsed correctly'
+  def test_morning_astronomical_twilight_parsed_correctly
+    assert_equal Time.new(Time.now.year, 12, 4, 5, 27, 39, '-05:00'), @result.morning_astronomical_twilight, 'Twilight was not parsed correctly'
   end
   
   # ---------------------------------------------------------------------------
@@ -82,7 +85,7 @@ class SunriseSunsetTest < MiniTest::Unit::TestCase
   # ---------------------------------------------------------------------------
   
   def test_utc_offset_is_integer
-	assert @result.utc_offset.is_a?(Integer), 'UTC offset should be an integer'
+    assert @result.utc_offset.is_a?(Integer), 'UTC offset should be an integer'
   end
   
   def test_utc_offset_parsed_correctly

data/test/time_zone_test.rb

@@ -5,8 +5,10 @@ require 'earth_tools'
 require 'earth_tools/result/time_zone'
 require 'mock_lookup'
 
+##
+# Tests for Time Zone lookups.
 class TimeZoneTest < MiniTest::Unit::TestCase
-
+  
   def setup
     @result = EarthTools.time_zone(40.71417, -74.00639)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: earth_tools
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-09 00:00:00.000000000Z
+date: 2013-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &26402964 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,15 @@ dependencies:
         version: 1.6.1
   type: :runtime
   prerelease: false
-  version_requirements: *26402964
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.6.1
 - !ruby/object:Gem::Dependency
   name: xml-simple
-  requirement: &26402628 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,13 +37,27 @@ dependencies:
         version: 1.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *26402628
-description: Client library to query the earthtools.org web services
-email: max@maxkramer.me
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+description: ! "  \n    The earth_tools gem is a client library to query the earthtools.org
+  web services.\n    Available features include determining time zone, sunset/sunrise
+  times, and height\n    above sea level for a given longitute/latitude pair.  See
+  the README for more\n    information.  Also, please follow the web service restrictions
+  for use described \n    in the README.\n  \n"
+email: max@maxckramer.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- CHANGELOG.md
+- Gemfile
+- Rakefile
+- lib/earth_tools/cache.rb
 - lib/earth_tools/configuration.rb
 - lib/earth_tools/exceptions.rb
 - lib/earth_tools/lookup/base.rb
@@ -51,6 +70,7 @@ files:
 - lib/earth_tools/result/time_zone.rb
 - lib/earth_tools/version.rb
 - lib/earth_tools.rb
+- test/cache_test.rb
 - test/configuration_test.rb
 - test/earth_tools_test.rb
 - test/fixtures/height_(52.4822,-1.8946).xml
@@ -85,9 +105,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Client library to query the earthtools.org web services
+summary: Client library to query the earthtools.org web services.
 test_files: []
-has_rdoc: