geocoder 1.1.1 → 1.1.2

data/.gitignore

@@ -2,3 +2,4 @@ pkg/*
 rdoc/*
 *.gem
 .bundle
+Gemfile.lock

data/CHANGELOG.rdoc

@@ -2,6 +2,17 @@
 
 Per-release changes to Geocoder.
 
+== 1.1.2 (2012 May 24)
+
+* Add ability to specify default units and distance calculation method (thanks github.com/abravalheri).
+* Add new (optional) configuration syntax (thanks github.com/abravalheri).
+* Add support for cache stores that provide :get and :set methods.
+* Add support for custom HTTP request headers (thanks github.com/robotmay).
+* Add Result#cache_hit attribute (thanks github.com/s01ipsist).
+* Fix: rake geocode:all wasn't properly loading namespaced classes.
+* Fix: properly recognize IP addresses with ::ffff: prefix (thanks github.com/brian-ewell).
+* Fix: avoid exception during calculations when coordinates not known (thanks github.com/flori).
+
 == 1.1.1 (2012 Feb 16)
 
 * Add distance_from_sql class method to geocoded class (thanks github.com/dwilkie).

data/README.rdoc

@@ -83,6 +83,13 @@ Be sure to read <i>Latitude/Longitude Order</i> in the <i>Notes on MongoDB</i> s
 
 MongoMapper is very similar to Mongoid, just be sure to include <tt>Geocoder::Model::MongoMapper</tt>.
 
+=== Mongo Indices
+
+By default, the methods <tt>geocoded_by</tt> and <tt>reverse_geocoded_by</tt> create a geospatial index. You can avoid index creation with the <tt>:skip_index option</tt>, for example:
+
+  include Geocoder::Model::Mongoid
+  geocoded_by :address, :skip_index => true
+
 === Bulk Geocoding
 
 If you have just added geocoding to an existing application with a lot of objects you can use this Rake task to geocode them all:
@@ -191,7 +198,7 @@ If your model has +street+, +city+, +state+, and +country+ attributes you might
 For reverse geocoding you can also specify an alternate name attribute where the address will be stored, for example:
 
   reverse_geocoded_by :latitude, :longitude, :address => :location  # ActiveRecord
-  reverse_geocoded_by :coordinates, :address => :loc     # MongoDB
+  reverse_geocoded_by :coordinates, :address => :loc                # MongoDB
 
 
 == Advanced Geocoding
@@ -225,32 +232,30 @@ If you're familiar with the results returned by the geocoding service you're usi
 
 == Geocoding Services
 
-By default Geocoder uses Google's geocoding API to fetch coordinates and street addresses (FreeGeoIP is used for IP address info). However there are several other APIs supported, as well as a variety of settings. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). The configuration options are:
+By default Geocoder uses Google's geocoding API to fetch coordinates and street addresses (FreeGeoIP is used for IP address info). However there are several other APIs supported, as well as a variety of settings. Please see the listing and comparison below for details on specific geocoding services (not all settings are supported by all services). Some common configuration options are:
 
   # config/initializers/geocoder.rb
+  Geocoder.configure do |config|
 
-  # geocoding service (see below for supported options):
-  Geocoder::Configuration.lookup = :yahoo
+    # geocoding service (see below for supported options):
+    config.lookup = :yahoo
 
-  # to use an API key:
-  Geocoder::Configuration.api_key = "..."
+    # to use an API key:
+    config.api_key = "..."
 
-  # geocoding service request timeout, in seconds (default 3):
-  Geocoder::Configuration.timeout = 5
+    # geocoding service request timeout, in seconds (default 3):
+    config.timeout = 5
 
-  # use HTTPS for geocoding service connections:
-  Geocoder::Configuration.use_https = true
+    # set default units to kilometers:
+    config.units = :km
 
-  # language to use (for search queries and reverse geocoding):
-  Geocoder::Configuration.language = :de
+    # caching (see below for details):
+    config.cache = Redis.new
+    config.cache_prefix = "..."
 
-  # use a proxy to access the service:
-  Geocoder::Configuration.http_proxy  = "127.4.4.1"
-  Geocoder::Configuration.https_proxy = "127.4.4.2" # only if HTTPS is needed
+  end
 
-  # caching (see below for details)
-  Geocoder::Configuration.cache = Redis.new
-  Geocoder::Configuration.cache_prefix = "..."
+Please see lib/geocoder/configuration.rb for a complete list of configuration options.
 
 
 === Listing and Comparison
@@ -491,4 +496,4 @@ You cannot use the +near+ scope with another scope that provides an +includes+ o
 If anyone has a more elegant solution to this problem I am very interested in seeing it.
 
 
-Copyright (c) 2009-11 Alex Reisner, released under the MIT license
+Copyright (c) 2009-12 Alex Reisner, released under the MIT license

data/lib/generators/geocoder/config/config_generator.rb

@@ -0,0 +1,14 @@
+require 'rails/generators'
+
+module Geocoder
+  class ConfigGenerator < Rails::Generators::Base
+    source_root File.expand_path("../templates", __FILE__)
+
+    desc "This generator creates an initializer file at config/initializers, " +
+         "with the default configuration options for Geocoder."
+    def add_initializer
+      template "initializer.rb", "config/initializers/geocoder.rb"
+    end
+  end
+end
+

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

@@ -0,0 +1,25 @@
+Geocoder.configure do
+  ## Configurable parameters: if you wish to change some configurable
+  ## behaviour in Geocoder, feel free to uncomment the following lines
+  ## and provide custom parameters.
+
+  # 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
+  # config.always_raise = []
+
+  ## Calculation options
+  # config.units  = :mi        # :km for kilometers or :mi for miles
+  # config.method = :linear    # :spherical or :linear
+end
+

data/lib/geocoder.rb

@@ -3,9 +3,9 @@ require "geocoder/calculations"
 require "geocoder/exceptions"
 require "geocoder/cache"
 require "geocoder/request"
-require "geocoder/models/active_record"
-require "geocoder/models/mongoid"
-require "geocoder/models/mongo_mapper"
+require "geocoder/models/active_record" if defined?(::ActiveRecord)
+require "geocoder/models/mongoid" if defined?(::Mongoid)
+require "geocoder/models/mongo_mapper" if defined?(::MongoMapper)
 
 module Geocoder
   extend self
@@ -115,7 +115,7 @@ module Geocoder
   # dot-delimited numbers.
   #
   def ip_address?(value)
-    !!value.to_s.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+    !!value.to_s.match(/^(::ffff:)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
   end
 
   ##

data/lib/geocoder/cache.rb

@@ -10,14 +10,24 @@ module Geocoder
     # Read from the Cache.
     #
     def [](url)
-      interpret store[key_for(url)]
+      interpret case
+        when store.respond_to?(:[])
+          store[key_for(url)]
+        when store.respond_to?(:get)
+          store.get key_for(url)
+      end
     end
 
     ##
     # Write to the Cache.
     #
     def []=(url, value)
-      store[key_for(url)] = value
+      case
+        when store.respond_to?(:[]=)
+          store[key_for(url)] = value
+        when store.respond_to?(:set)
+          store.set key_for(url), value
+      end
     end
 
     ##

data/lib/geocoder/calculations.rb

@@ -21,10 +21,14 @@ module Geocoder
     #
     KM_IN_MI = 0.621371192
 
+    # Not a number constant
+    NAN = defined?(::Float::NAN) ? ::Float::NAN : 0 / 0.0
+
     ##
     # Distance spanned by one degree of latitude in the given units.
     #
-    def latitude_degree_distance(units = :mi)
+    def latitude_degree_distance(units = nil)
+      units ||= Geocoder::Configuration.units
       2 * Math::PI * earth_radius(units) / 360
     end
 
@@ -32,7 +36,8 @@ module Geocoder
     # Distance spanned by one degree of longitude at the given latitude.
     # This ranges from around 69 miles at the equator to zero at the poles.
     #
-    def longitude_degree_distance(latitude, units = :mi)
+    def longitude_degree_distance(latitude, units = nil)
+      units ||= Geocoder::Configuration.units
       latitude_degree_distance(units) * Math.cos(to_radians(latitude))
     end
 
@@ -49,12 +54,13 @@ module Geocoder
     #
     # The options hash supports:
     #
-    # * <tt>:units</tt> - <tt>:mi</tt> (default) or <tt>:km</tt>
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>
+    #   See Geocoder::Configuration to know how configure default units.
     #
     def distance_between(point1, point2, options = {})
 
       # set default options
-      options[:units] ||= :mi
+      options[:units] ||= Geocoder::Configuration.units
 
       # convert to coordinate arrays
       point1 = extract_coordinates(point1)
@@ -81,17 +87,18 @@ module Geocoder
     # See Geocoder::Calculations.distance_between for
     # ways of specifying the points. Also accepts an options hash:
     #
-    # * <tt>:method</tt> - <tt>:linear</tt> (default) or <tt>:spherical</tt>;
+    # * <tt>:method</tt> - <tt>:linear</tt> or <tt>:spherical</tt>;
     #   the spherical method is "correct" in that it returns the shortest path
-    #   (one along a great circle) but the linear method is the default as it
-    #   is less confusing (returns due east or west when given two points with
-    #   the same latitude)
+    #   (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.
     #
     # 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] = :linear unless options[:method] == :spherical
 
       # convert to coordinate arrays
@@ -177,12 +184,13 @@ module Geocoder
     # See Geocoder::Calculations.distance_between for
     # ways of specifying the point. Also accepts an options hash:
     #
-    # * <tt>:units</tt> - <tt>:mi</tt> (default) or <tt>:km</tt>
+    # * <tt>:units</tt> - <tt>:mi</tt> or <tt>:km</tt>.
+    #   See Geocoder::Configuration to know how configure default units.
     #
     def bounding_box(point, radius, options = {})
       lat,lon = extract_coordinates(point)
       radius  = radius.to_f
-      units   = options[:units] || :mi
+      units   = options[:units] || Geocoder::Configuration.units
       [
         lat - (radius / latitude_degree_distance(units)),
         lon - (radius / longitude_degree_distance(lat, units)),
@@ -219,11 +227,13 @@ module Geocoder
       end
     end
 
-    def distance_to_radians(distance, units = :mi)
+    def distance_to_radians(distance, units = nil)
+      units ||= Geocoder::Configuration.units
       distance.to_f / earth_radius(units)
     end
 
-    def radians_to_distance(radians, units = :mi)
+    def radians_to_distance(radians, units = nil)
+      units ||= Geocoder::Configuration.units
       radians * earth_radius(units)
     end
 
@@ -242,9 +252,11 @@ module Geocoder
     end
 
     ##
-    # Radius of the Earth in the given units (:mi or :km). Default is :mi.
+    # Radius of the Earth in the given units (:mi or :km).
+    # See Geocoder::Configuration to know how configure default units.
     #
-    def earth_radius(units = :mi)
+    def earth_radius(units = nil)
+      units ||= Geocoder::Configuration.units
       units == :km ? EARTH_RADIUS : to_miles(EARTH_RADIUS)
     end
 
@@ -270,10 +282,26 @@ module Geocoder
     #
     def extract_coordinates(point)
       case point
-        when Array; point
-        when String; Geocoder.coordinates(point)
-        else point.to_coordinates
+      when Array
+        if point.size == 2
+          lat, lon = point
+          if !lat.nil? && lat.respond_to?(:to_f) and
+            !lon.nil? && lon.respond_to?(:to_f)
+          then
+            return [ lat.to_f, lon.to_f ]
+          end
+        end
+      when String
+        point = Geocoder.coordinates(point) and return point
+      else
+        if point.respond_to?(:to_coordinates)
+          if Array === array = point.to_coordinates
+            return extract_coordinates(array)
+          end
+        end
       end
+      [ NAN, NAN ]
     end
   end
 end
+

data/lib/geocoder/configuration.rb

@@ -1,58 +1,103 @@
-module Geocoder
-  class Configuration
-
-    def self.options_and_defaults
-      [
-        # geocoding service timeout (secs)
-        [:timeout, 3],
+require 'singleton'
 
-        # name of geocoding service (symbol)
-        [:lookup, :google],
+module Geocoder
 
-        # ISO-639 language code
-        [:language, :en],
+  ##
+  # Provides convenient access to the Configuration singleton.
+  #
+  def self.configure(&block)
+    if block_given?
+      block.call(Configuration.instance)
+    else
+      Configuration.instance
+    end
+  end
 
-        # use HTTPS for lookup requests? (if supported)
-        [:use_https, false],
+  ##
+  # 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
+  #
+  # 2) Using the Geocoder::Configuration singleton directly:
+  #
+  #   Geocoder::Configuration.language = 'pt-BR'
+  #
+  # Default values are defined in Configuration#set_defaults.
+  #
+  class Configuration
+    include Singleton
 
-        # HTTP proxy server (user:pass@host:port)
-        [:http_proxy, nil],
+    OPTIONS = [
+      :timeout,
+      :lookup,
+      :language,
+      :http_headers,
+      :use_https,
+      :http_proxy,
+      :https_proxy,
+      :api_key,
+      :cache,
+      :cache_prefix,
+      :always_raise,
+      :units,
+      :distances
+    ]
 
-        # HTTPS proxy server (user:pass@host:port)
-        [:https_proxy, nil],
+    attr_accessor *OPTIONS
 
-        # API key for geocoding service
-        # for Google Premier use a 3-element array: [key, client, channel]
-        [:api_key, nil],
+    def initialize # :nodoc
+      set_defaults
+    end
 
-        # cache object (must respond to #[], #[]=, and #keys)
-        [:cache, nil],
+    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
 
-        # prefix (string) to use for all cache keys
-        [:cache_prefix, "geocoder:"],
+      # 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
-        [:always_raise, []]
-      ]
+      # calculation options
+      @units     = :mi     # :mi or :km
+      @distances = :linear # :linear or :spherical
     end
 
-    # define getters and setters for all configuration settings
-    self.options_and_defaults.each do |option, default|
-      class_eval(<<-END, __FILE__, __LINE__ + 1)
-
-        @@#{option} = default unless defined? @@#{option}
-
-        def self.#{option}
-          @@#{option}
-        end
+    instance_eval(OPTIONS.map do |option|
+      o = option.to_s
+      <<-EOS
+      def #{o}
+        instance.#{o}
+      end
 
-        def self.#{option}=(obj)
-          @@#{option} = obj
-        end
+      def #{o}=(value)
+        instance.#{o} = value
+      end
+      EOS
+    end.join("\n\n"))
 
-      END
+    class << self
+      def set_defaults
+        instance.set_defaults
+      end
     end
   end
 end