geocoder 1.1.3 → 1.1.6

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/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
@@ -184,7 +184,7 @@ module Geocoder
     end
 
     ##
-    # Returns coordinates of the lower-left and upper-right corners of a box
+    # Returns coordinates of the southwest and northeast corners of a box
     # with the given point at its center. The radius is the shortest distance
     # from the center point to any side of the box (the length of each side
     # is twice the radius).
@@ -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,33 +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.street_lookups, "--service <service>",
-          "Geocoding service: #{Geocoder.street_lookups * ', '}") do |service|
-          Geocoder::Configuration.lookup = service.to_sym
+        opts.on("-s <service>", Geocoder::Lookup.all_services_except_test, "--service <service>",
+          "Geocoding service: #{Geocoder::Lookup.all_services_except_test * ', '}") do |service|
+          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
@@ -78,21 +78,19 @@ module Geocoder
       end
 
       if show_url
-        lookup = Geocoder.send(:lookup, query)
-        reverse = lookup.send(:coordinates?, query)
-        out << lookup.send(:query_url, query, reverse) + "\n"
+        q = Geocoder::Query.new(query)
+        out << q.url + "\n"
         exit 0
       end
 
       if show_json
-        lookup = Geocoder.send(:lookup, query)
-        reverse = lookup.send(:coordinates?, query)
-        out << lookup.send(:fetch_raw_data, query, reverse) + "\n"
+        q = Geocoder::Query.new(query)
+        out << q.lookup.send(:fetch_raw_data, q) + "\n"
         exit 0
       end
 
       if (result = Geocoder.search(query).first)
-        lookup = Geocoder.send(:get_lookup, :google)
+        google = Geocoder::Lookup.get(:google)
         lines = [
           ["Latitude",       result.latitude],
           ["Longitude",      result.longitude],
@@ -101,7 +99,7 @@ module Geocoder
           ["State/province", result.state],
           ["Postal code",    result.postal_code],
           ["Country",        result.country],
-          ["Google map",     lookup.map_link_url(result.coordinates)],
+          ["Google map",     google.map_link_url(result.coordinates)],
         ]
         lines.each do |line|
           out << (line[0] + ": ").ljust(18) + line[1].to_s + "\n"

data/lib/geocoder/configuration.rb

@@ -1,45 +1,56 @@
 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       = :yahoo
-  #     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
 
     OPTIONS = [
       :timeout,
       :lookup,
+      :ip_lookup,
       :language,
       :http_headers,
       :use_https,
@@ -53,52 +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 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

@@ -0,0 +1,81 @@
+module Geocoder
+  module Lookup
+    extend self
+
+    ##
+    # Array of valid Lookup service names.
+    #
+    def all_services
+      street_services + ip_services
+    end
+
+    ##
+    # Array of valid Lookup service names, excluding :test.
+    #
+    def all_services_except_test
+      all_services - [:test]
+    end
+
+    ##
+    # All street address lookup services, default first.
+    #
+    def street_services
+      [
+        :google,
+        :google_premier,
+        :yahoo,
+        :bing,
+        :geocoder_ca,
+        :yandex,
+        :nominatim,
+        :mapquest,
+        :test
+      ]
+    end
+
+    ##
+    # All IP address lookup services, default first.
+    #
+    def ip_services
+      [:freegeoip, :maxmind]
+    end
+
+    ##
+    # Retrieve a Lookup object from the store.
+    # Use this instead of Geocoder::Lookup::X.new to get an
+    # already-configured Lookup object.
+    #
+    def get(name)
+      @services = {} unless defined?(@services)
+      @services[name] = spawn(name) unless @services.include?(name)
+      @services[name]
+    end
+
+
+    private # -----------------------------------------------------------------
+
+    ##
+    # Spawn a Lookup of the given name.
+    #
+    def spawn(name)
+      if all_services.include?(name)
+        Geocoder::Lookup.const_get(classify_name(name)).new
+      else
+        valids = all_services.map(&:inspect).join(", ")
+        raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
+          "(#{name.inspect} is not one of: #{valids})."
+      end
+    end
+
+    ##
+    # Convert an "underscore" version of a name into a "class" version.
+    #
+    def classify_name(filename)
+      filename.to_s.split("_").map{ |i| i[0...1].upcase + i[1..-1] }.join
+    end
+  end
+end
+
+Geocoder::Lookup.all_services.each do |name|
+  require "geocoder/lookups/#{name}"
+end