geocoder 1.1.5 → 1.1.6

data/examples/autoexpire_cache.rb

@@ -25,6 +25,4 @@ class AutoexpireCache
   end
 end
 
-Geocoder.configure do |config|
-  config.cache = AutoexpireCache.new(Redis.new)
-end
+Geocoder.configure(:cache => AutoexpireCache.new(Redis.new))

data/lib/generators/geocoder/config/templates/initializer.rb

@@ -1,25 +1,21 @@
-Geocoder.configure do |config|
-  ## Configurable parameters: if you wish to change some configurable
-  ## behaviour in Geocoder, feel free to uncomment the following lines
-  ## and provide custom parameters.
+Geocoder.configure(
+  # geocoding options
+  # :timeout      => 3,           # geocoding service timeout (secs)
+  # :lookup       => :google,     # name of geocoding service (symbol)
+  # :language     => :en,         # ISO-639 language code
+  # :use_https    => false,       # use HTTPS for lookup requests? (if supported)
+  # :http_proxy   => nil,         # HTTP proxy server (user:pass@host:port)
+  # :https_proxy  => nil,         # HTTPS proxy server (user:pass@host:port)
+  # :api_key      => nil,         # API key for geocoding service
+  # :cache        => nil,         # cache object (must respond to #[], #[]=, and #keys)
+  # :cache_prefix => "geocoder:", # prefix (string) to use for all cache keys
 
-  # config.timeout      = 3           # geocoding service timeout (secs)
-  # config.lookup       = :google     # name of geocoding service (symbol)
-  # config.language     = :en         # ISO-639 language code
-  # config.use_https    = false       # use HTTPS for lookup requests? (if supported)
-  # config.http_proxy   = nil         # HTTP proxy server (user:pass@host:port)
-  # config.https_proxy  = nil         # HTTPS proxy server (user:pass@host:port)
-  # config.api_key      = nil         # API key for geocoding service
-  # config.cache        = nil         # cache object (must respond to #[], #[]=, and #keys)
-  # config.cache_prefix = "geocoder:" # 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 TimeoutError
+  # :always_raise => [],
 
-  ## exceptions that should not be rescued by default
-  ## (if you want to implement custom error handling);
-  ## supports SocketError and TimeoutError
-  # config.always_raise = []
-
-  ## Calculation options
-  # config.units     = :mi        # :km for kilometers or :mi for miles
-  # config.distances = :linear    # :spherical or :linear
+  # calculation options
+  # :units     => :mi,       # :km for kilometers or :mi for miles
+  # :distances => :linear    # :spherical or :linear
 end
-

data/lib/geocoder.rb

@@ -43,10 +43,8 @@ module Geocoder
   # The working Cache object, or +nil+ if none configured.
   #
   def cache
-    if @cache.nil? and store = Configuration.cache
-      @cache = Cache.new(store, Configuration.cache_prefix)
-    end
-    @cache
+    warn "WARNING: Calling Geocoder.cache is DEPRECATED. The #cache method now belongs to the Geocoder::Lookup object."
+    Geocoder::Lookup.get(Geocoder.config.lookup).send(:configuration).cache
   end
 end
 

data/lib/geocoder/cache.rb

@@ -78,7 +78,8 @@ module Geocoder
     end
 
     def expire_single_url(url)
-      store.del(key_for(url))
+      key = key_for(url)
+      store.respond_to?(:del) ? store.del(key) : store.delete(key)
     end
   end
 end

data/lib/geocoder/calculations.rb

@@ -40,7 +40,7 @@ module Geocoder
     # Distance spanned by one degree of latitude in the given units.
     #
     def latitude_degree_distance(units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       2 * Math::PI * earth_radius(units) / 360
     end
 
@@ -49,7 +49,7 @@ module Geocoder
     # This ranges from around 69 miles at the equator to zero at the poles.
     #
     def longitude_degree_distance(latitude, units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       latitude_degree_distance(units) * Math.cos(to_radians(latitude))
     end
 
@@ -67,12 +67,12 @@ module Geocoder
     # The options hash supports:
     #
     # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
-    #   See Geocoder::Configuration to know how configure default units.
+    #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def distance_between(point1, point2, options = {})
 
       # set default options
-      options[:units] ||= Geocoder::Configuration.units
+      options[:units] ||= Geocoder.config.units
 
       # convert to coordinate arrays
       point1 = extract_coordinates(point1)
@@ -103,14 +103,14 @@ module Geocoder
     #   the spherical method is "correct" in that it returns the shortest path
     #   (one along a great circle) but the linear method is less confusing
     #   (returns due east or west when given two points with the same latitude).
-    #   See Geocoder::Configuration to know how configure default method.
+    #   Use Geocoder.configure(:distances => ...) to configure calculation method.
     #
     # Based on: http://www.movable-type.co.uk/scripts/latlong.html
     #
     def bearing_between(point1, point2, options = {})
 
       # set default options
-      options[:method] ||= Geocoder::Configuration.distances
+      options[:method] ||= Geocoder.config.distances
       options[:method] = :linear unless options[:method] == :spherical
 
       # convert to coordinate arrays
@@ -197,12 +197,12 @@ module Geocoder
     # ways of specifying the point. Also accepts an options hash:
     #
     # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>.
-    #   See Geocoder::Configuration to know how configure default units.
+    #   Use Geocoder.configure(:units => ...) to configure default units.
     #
     def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
-      units   = options[:units] || Geocoder::Configuration.units
+      units   = options[:units] || Geocoder.config.units
       [
         lat - (radius / latitude_degree_distance(units)),
         lon - (radius / longitude_degree_distance(lat, units)),
@@ -240,12 +240,12 @@ module Geocoder
     end
 
     def distance_to_radians(distance, units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       distance.to_f / earth_radius(units)
     end
 
     def radians_to_distance(radians, units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       radians * earth_radius(units)
     end
 
@@ -265,10 +265,10 @@ module Geocoder
 
     ##
     # Radius of the Earth in the given units (:mi or :km).
-    # See Geocoder::Configuration to know how configure default units.
+    # Use Geocoder.configure(:units => ...) to configure default units.
     #
     def earth_radius(units = nil)
-      units ||= Geocoder::Configuration.units
+      units ||= Geocoder.config.units
       units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
     end
 

data/lib/geocoder/cli.rb

@@ -13,34 +13,33 @@ module Geocoder
         opts.separator "\nOptions: "
 
         opts.on("-k <key>", "--key <key>",
-          "Key for geocoding API (optional for most). For Google Premier use 'key client channel' separated by spaces") do |key|
-          premier_key = key.split(' ')
-          if premier_key.length == 3
-            Geocoder::Configuration.api_key = premier_key
+          "Key for geocoding API (usually optional). Enclose multi-part keys in quotes and separate parts by spaces") do |key|
+          if (key_parts = key.split(/\s+/)).size > 1
+            Geocoder.configure(:api_key => key_parts)
           else
-            Geocoder::Configuration.api_key = key
+            Geocoder.configure(:api_key => key)
           end
         end
 
         opts.on("-l <language>", "--language <language>",
           "Language of output (see API docs for valid choices)") do |language|
-          Geocoder::Configuration.language = language
+          Geocoder.configure(:language => language)
         end
 
         opts.on("-p <proxy>", "--proxy <proxy>",
           "HTTP proxy server to use (user:pass@host:port)") do |proxy|
-          Geocoder::Configuration.http_proxy = proxy
+          Geocoder.configure(:http_proxy => proxy)
         end
 
         opts.on("-s <service>", Geocoder::Lookup.all_services_except_test, "--service <service>",
           "Geocoding service: #{Geocoder::Lookup.all_services_except_test * ', '}") do |service|
-          Geocoder::Configuration.lookup = service.to_sym
-          Geocoder::Configuration.ip_lookup = service.to_sym
+          Geocoder.configure(:lookup => service.to_sym)
+          Geocoder.configure(:ip_lookup => service.to_sym)
         end
 
         opts.on("-t <seconds>", "--timeout <seconds>",
           "Maximum number of seconds to wait for API response") do |timeout|
-          Geocoder::Configuration.timeout = timeout.to_i
+          Geocoder.configure(:timeout => timeout.to_i)
         end
 
         opts.on("-j", "--json", "Print API's raw JSON response") do
@@ -80,7 +79,7 @@ module Geocoder
 
       if show_url
         q = Geocoder::Query.new(query)
-        out << q.lookup.send(:query_url, q) + "\n"
+        out << q.url + "\n"
         exit 0
       end
 

data/lib/geocoder/configuration.rb

@@ -1,39 +1,49 @@
 require 'singleton'
+require 'geocoder/configuration_hash'
 
 module Geocoder
 
   ##
-  # Provides convenient access to the Configuration singleton.
+  # Configuration options should be set by passing a hash:
   #
-  def self.configure(&block)
+  #   Geocoder.configure(
+  #     :timeout  => 5,
+  #     :lookup   => :yandex,
+  #     :api_key  => "2a9fsa983jaslfj982fjasd",
+  #     :units    => :km
+  #   )
+  #
+  def self.configure(options = nil, &block)
     if block_given?
+      warn "WARNING: Passing a block to Geocoder.configure is DEPRECATED. Please pass a hash instead (eg: Geocoder.configure(:units => ..., :api_key => ...))."
       block.call(Configuration.instance)
+    elsif !options.nil?
+      Configuration.instance.configure(options)
     else
+      warn "WARNING: Use of Geocoder.configure to read or write single config options is DEPRECATED. To write to the config please pass a hash (eg: Geocoder.configure(:units => ...)). To read config options please use the Geocoder.config object (eg: Geocoder.config.units)."
       Configuration.instance
     end
   end
 
   ##
-  # This class handles geocoder Geocoder configuration
-  # (geocoding service provider, caching, units of measurement, etc).
-  # Configuration can be done in two ways:
-  #
-  # 1) Using Geocoder.configure and passing a block
-  #    (useful for configuring multiple things at once):
-  #
-  #   Geocoder.configure do |config|
-  #     config.timeout      = 5
-  #     config.lookup       = :yandex
-  #     config.api_key      = "2a9fsa983jaslfj982fjasd"
-  #     config.units        = :km
-  #   end
+  # Read-only access to the singleton's config data.
   #
-  # 2) Using the Geocoder::Configuration singleton directly:
-  #
-  #   Geocoder::Configuration.language = 'pt-BR'
-  #
-  # Default values are defined in Configuration#set_defaults.
+  def self.config
+    Configuration.instance.data
+  end
+
+  ##
+  # Read-only access to lookup-specific config data.
   #
+  def self.config_for_lookup(lookup_name)
+    data = config.clone
+    data.reject!{ |key,value| !Configuration::OPTIONS.include?(key) }
+    if config.has_key?(lookup_name)
+      data.merge!(config[lookup_name])
+    end
+    data
+  end
+
   class Configuration
     include Singleton
 
@@ -54,53 +64,67 @@ module Geocoder
       :distances
     ]
 
-    attr_accessor *OPTIONS
+    attr_accessor :data
+
+    def self.set_defaults
+      instance.set_defaults
+    end
+
+    OPTIONS.each do |o|
+      define_method o do
+        @data[o]
+      end
+      define_method "#{o}=" do |value|
+        @data[o] = value
+      end
+    end
+
+    def configure(options)
+      @data.rmerge!(options)
+    end
 
     def initialize # :nodoc
+      @data = Geocoder::ConfigurationHash.new
       set_defaults
     end
 
     def set_defaults
-      @timeout      = 3           # geocoding service timeout (secs)
-      @lookup       = :google     # name of street address geocoding service (symbol)
-      @ip_lookup    = :freegeoip  # name of IP address geocoding service (symbol)
-      @language     = :en         # ISO-639 language code
-      @http_headers = {}          # HTTP headers for lookup
-      @use_https    = false       # use HTTPS for lookup requests? (if supported)
-      @http_proxy   = nil         # HTTP proxy server (user:pass@host:port)
-      @https_proxy  = nil         # HTTPS proxy server (user:pass@host:port)
-      @api_key      = nil         # API key for geocoding service
-      @cache        = nil         # cache object (must respond to #[], #[]=, and #keys)
-      @cache_prefix = "geocoder:" # prefix (string) to use for all cache keys
+
+      # geocoding options
+      @data[:timeout]      = 3           # geocoding service timeout (secs)
+      @data[:lookup]       = :google     # name of street address geocoding service (symbol)
+      @data[:ip_lookup]    = :freegeoip  # name of IP address geocoding service (symbol)
+      @data[:language]     = :en         # ISO-639 language code
+      @data[:http_headers] = {}          # HTTP headers for lookup
+      @data[:use_https]    = false       # use HTTPS for lookup requests? (if supported)
+      @data[:http_proxy]   = nil         # HTTP proxy server (user:pass@host:port)
+      @data[:https_proxy]  = nil         # HTTPS proxy server (user:pass@host:port)
+      @data[:api_key]      = nil         # API key for geocoding service
+      @data[:cache]        = nil         # cache object (must respond to #[], #[]=, and #keys)
+      @data[:cache_prefix] = "geocoder:" # 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 TimeoutError
-      @always_raise = []
+      @data[:always_raise] = []
 
       # calculation options
-      @units     = :mi     # :mi or :km
-      @distances = :linear # :linear or :spherical
+      @data[:units]     = :mi      # :mi or :km
+      @data[:distances] = :linear  # :linear or :spherical
     end
 
     instance_eval(OPTIONS.map do |option|
       o = option.to_s
       <<-EOS
       def #{o}
-        instance.#{o}
+        instance.data[:#{o}]
       end
 
       def #{o}=(value)
-        instance.#{o} = value
+        instance.data[:#{o}] = value
       end
       EOS
     end.join("\n\n"))
 
-    class << self
-      def set_defaults
-        instance.set_defaults
-      end
-    end
-
   end
 end

data/lib/geocoder/configuration_hash.rb

@@ -0,0 +1,11 @@
+require 'hash_recursive_merge'
+
+module Geocoder
+  class ConfigurationHash < Hash
+    include HashRecursiveMerge
+
+    def method_missing(meth, *args, &block)
+      has_key?(meth) ? self[meth] : super
+    end
+  end
+end

data/lib/geocoder/exceptions.rb

@@ -15,4 +15,7 @@ module Geocoder
   class InvalidRequest < Error
   end
 
+  class InvalidApiKey < Error
+  end
+
 end

data/lib/geocoder/lookup.rb

@@ -37,7 +37,7 @@ module Geocoder
     # All IP address lookup services, default first.
     #
     def ip_services
-      [:freegeoip]
+      [:freegeoip, :maxmind]
     end
 
     ##

data/lib/geocoder/lookups/base.rb

@@ -16,6 +16,21 @@ module Geocoder
 
     class Base
 
+      ##
+      # Human-readable name of the geocoding API.
+      #
+      def name
+        fail
+      end
+
+      ##
+      # Symbol which is used in configuration to refer to this Lookup.
+      #
+      def handle
+        str = self.class.to_s
+        str[str.rindex(':')+1..-1].gsub(/([a-z\d]+)([A-Z])/,'\1_\2').downcase.to_sym
+      end
+
       ##
       # Query the geocoding API and return a Geocoder::Result object.
       # Returns +nil+ on timeout or error.
@@ -43,16 +58,37 @@ module Geocoder
         nil
       end
 
+      ##
+      # Array containing string descriptions of keys required by the API.
+      # Empty array if keys are optional or not required.
+      #
+      def required_api_key_parts
+        []
+      end
+
+      ##
+      # URL to use for querying the geocoding engine.
+      #
+      def query_url(query)
+        fail
+      end
 
       private # -------------------------------------------------------------
 
+      ##
+      # An object with configuration data for this particular lookup.
+      #
+      def configuration
+        Geocoder.config_for_lookup(handle)
+      end
+
       ##
       # Object used to make HTTP requests.
       #
       def http_client
-        protocol = "http#{'s' if Geocoder::Configuration.use_https}"
+        protocol = "http#{'s' if configuration.use_https}"
         proxy_name = "#{protocol}_proxy"
-        if proxy = Geocoder::Configuration.send(proxy_name)
+        if proxy = configuration.send(proxy_name)
           proxy_url = protocol + '://' + proxy
           begin
             uri = URI.parse(proxy_url)
@@ -83,13 +119,6 @@ module Geocoder
         )
       end
 
-      ##
-      # URL to use for querying the geocoding engine.
-      #
-      def query_url(query)
-        fail
-      end
-
       ##
       # Key to use for caching a geocoding result. Usually this will be the
       # request URL, but in cases where OAuth is used and the nonce,
@@ -112,7 +141,7 @@ module Geocoder
       # Return false if exception not raised.
       #
       def raise_error(error, message = nil)
-        exceptions = Geocoder::Configuration.always_raise
+        exceptions = configuration.always_raise
         if exceptions == :all or exceptions.include?( error.is_a?(Class) ? error : error.class )
           raise error, message
         else
@@ -129,7 +158,7 @@ module Geocoder
         raise_error(err) or warn "Geocoding API connection cannot be established."
       rescue TimeoutError => err
         raise_error(err) or warn "Geocoding API not responding fast enough " +
-          "(see Geocoder::Configuration.timeout to set limit)."
+          "(use Geocoder.configure(:timeout => ...) to set limit)."
       end
 
       ##
@@ -150,7 +179,7 @@ module Geocoder
       # Set in configuration but not available for every service.
       #
       def protocol
-        "http" + (Geocoder::Configuration.use_https ? "s" : "")
+        "http" + (configuration.use_https ? "s" : "")
       end
 
       ##
@@ -162,6 +191,7 @@ module Geocoder
         if cache and body = cache[key]
           @cache_hit = true
         else
+          check_api_key_configuration!(query)
           response = make_api_request(query)
           body = response.body
           if cache and (200..399).include?(response.code.to_i)
@@ -177,11 +207,21 @@ module Geocoder
       # return the response object.
       #
       def make_api_request(query)
-        timeout(Geocoder::Configuration.timeout) do
+        timeout(configuration.timeout) do
           uri = URI.parse(query_url(query))
           client = http_client.new(uri.host, uri.port)
-          client.use_ssl = true if Geocoder::Configuration.use_https
-          client.get(uri.request_uri, Geocoder::Configuration.http_headers)
+          client.use_ssl = true if configuration.use_https
+          client.get(uri.request_uri, configuration.http_headers)
+        end
+      end
+
+      def check_api_key_configuration!(query)
+        key_parts = query.lookup.required_api_key_parts
+        if key_parts.size > Array(configuration.api_key).size
+          parts_string = key_parts.size == 1 ? key_parts.first : key_parts
+          raise Geocoder::ConfigurationError,
+            "The #{query.lookup.name} API requires a key to be configured: " +
+            parts_string.inspect
         end
       end
 
@@ -189,7 +229,10 @@ module Geocoder
       # The working Cache object.
       #
       def cache
-        Geocoder.cache
+        if @cache.nil? and store = configuration.cache
+          @cache = Cache.new(store, configuration.cache_prefix)
+        end
+        @cache
       end
 
       ##