geocoder 1.1.3 → 1.1.6

data/lib/geocoder/sql.rb

@@ -0,0 +1,106 @@
+module Geocoder
+  module Sql
+    extend self
+
+    ##
+    # Distance calculation for use with a database that supports POWER(),
+    # SQRT(), PI(), and trigonometric functions SIN(), COS(), ASIN(),
+    # ATAN2(), DEGREES(), and RADIANS().
+    #
+    # Based on the excellent tutorial at:
+    # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
+    #
+    def full_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder.config.units
+      earth = Geocoder::Calculations.earth_radius(units)
+
+      "#{earth} * 2 * ASIN(SQRT(" +
+        "POWER(SIN((#{latitude.to_f} - #{lat_attr}) * PI() / 180 / 2), 2) + " +
+        "COS(#{latitude.to_f} * PI() / 180) * COS(#{lat_attr} * PI() / 180) * " +
+        "POWER(SIN((#{longitude.to_f} - #{lon_attr}) * PI() / 180 / 2), 2)" +
+      "))"
+    end
+
+    ##
+    # Distance calculation for use with a database without trigonometric
+    # functions, like SQLite. Approach is to find objects within a square
+    # rather than a circle, so results are very approximate (will include
+    # objects outside the given radius).
+    #
+    # Distance and bearing calculations are *extremely inaccurate*. To be
+    # clear: this only exists to provide interface consistency. Results
+    # are not intended for use in production!
+    #
+    def approx_distance(latitude, longitude, lat_attr, lon_attr, options = {})
+      units = options[:units] || Geocoder.config.units
+      dx = Geocoder::Calculations.longitude_degree_distance(30, units)
+      dy = Geocoder::Calculations.latitude_degree_distance(units)
+
+      # sin of 45 degrees = average x or y component of vector
+      factor = Math.sin(Math::PI / 4)
+
+      "(#{dy} * ABS(#{lat_attr} - #{latitude.to_f}) * #{factor}) + " +
+        "(#{dx} * ABS(#{lon_attr} - #{longitude.to_f}) * #{factor})"
+    end
+
+    def within_bounding_box(sw_lat, sw_lng, ne_lat, ne_lng, lat_attr, lon_attr)
+      spans = "#{lat_attr} BETWEEN #{sw_lat} AND #{ne_lat} AND "
+      # handle box that spans 180 longitude
+      if sw_lng.to_f > ne_lng.to_f
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND 180 OR " +
+        "#{lon_attr} BETWEEN -180 AND #{ne_lng}"
+      else
+        spans + "#{lon_attr} BETWEEN #{sw_lng} AND #{ne_lng}"
+      end
+    end
+
+    ##
+    # Fairly accurate bearing calculation. Takes a latitude, longitude,
+    # and an options hash which must include a :bearing value
+    # (:linear or :spherical).
+    #
+    # Based on:
+    # http://www.beginningspatial.com/calculating_bearing_one_point_another
+    #
+    def full_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      case options[:bearing] || Geocoder.config.distances
+      when :linear
+        "CAST(" +
+          "DEGREES(ATAN2( " +
+            "RADIANS(#{lon_attr} - #{longitude.to_f}), " +
+            "RADIANS(#{lat_attr} - #{latitude.to_f})" +
+          ")) + 360 " +
+        "AS decimal) % 360"
+      when :spherical
+        "CAST(" +
+          "DEGREES(ATAN2( " +
+            "SIN(RADIANS(#{lon_attr} - #{longitude.to_f})) * " +
+            "COS(RADIANS(#{lat_attr})), (" +
+              "COS(RADIANS(#{latitude.to_f})) * SIN(RADIANS(#{lat_attr}))" +
+            ") - (" +
+              "SIN(RADIANS(#{latitude.to_f})) * COS(RADIANS(#{lat_attr})) * " +
+              "COS(RADIANS(#{lon_attr} - #{longitude.to_f}))" +
+            ")" +
+          ")) + 360 " +
+        "AS decimal) % 360"
+      end
+    end
+
+    ##
+    # Totally lame bearing calculation. Basically useless except that it
+    # returns *something* in databases without trig functions.
+    #
+    def approx_bearing(latitude, longitude, lat_attr, lon_attr, options = {})
+      "CASE " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN  45.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} >= #{longitude.to_f}) THEN 135.0 " +
+        "WHEN (#{lat_attr} <  #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 225.0 " +
+        "WHEN (#{lat_attr} >= #{latitude.to_f} AND " +
+          "#{lon_attr} <  #{longitude.to_f}) THEN 315.0 " +
+      "END"
+    end
+  end
+end

data/lib/geocoder/stores/active_record.rb

@@ -1,3 +1,4 @@
+require 'geocoder/sql'
 require 'geocoder/stores/base'
 
 ##
@@ -36,11 +37,13 @@ module Geocoder::Store
           if Geocoder::Calculations.coordinates_present?(latitude, longitude)
             near_scope_options(latitude, longitude, *args)
           else
-            where(false_condition) # no results if no lat/lon given
+            # If no lat/lon given we don't want any results, but we still
+            # need distance and bearing columns so you can add, for example:
+            # .order("distance")
+            select(select_clause(nil, "NULL", "NULL")).where(false_condition)
           end
         }
 
-
         ##
         # Find all objects within the area of a given bounding box.
         # Bounds must be an array of locations specifying the southwest
@@ -49,14 +52,15 @@ module Geocoder::Store
         #
         scope :within_bounding_box, lambda{ |bounds|
           sw_lat, sw_lng, ne_lat, ne_lng = bounds.flatten if bounds
-          return where(false_condition) unless sw_lat && sw_lng && ne_lat && ne_lng
-          spans = "#{geocoder_options[:latitude]} BETWEEN #{sw_lat} AND #{ne_lat} AND "
-          spans << if sw_lng > ne_lng   # Handle a box that spans 180
-            "#{geocoder_options[:longitude]} BETWEEN #{sw_lng} AND 180 OR #{geocoder_options[:longitude]} BETWEEN -180 AND #{ne_lng}"
+          if sw_lat && sw_lng && ne_lat && ne_lng
+            {:conditions => Geocoder::Sql.within_bounding_box(
+              sw_lat, sw_lng, ne_lat, ne_lng,
+              full_column_name(geocoder_options[:latitude]),
+              full_column_name(geocoder_options[:longitude])
+            )}
           else
-            "#{geocoder_options[:longitude]} BETWEEN #{sw_lng} AND #{ne_lng}"
+            select(select_clause(nil, "NULL", "NULL")).where(false_condition)
           end
-          { :conditions => spans }
         }
       end
     end
@@ -69,7 +73,7 @@ module Geocoder::Store
       def distance_from_sql(location, *args)
         latitude, longitude = Geocoder::Calculations.extract_coordinates(location)
         if Geocoder::Calculations.coordinates_present?(latitude, longitude)
-          distance_from_sql_options(latitude, longitude, *args)
+          distance_sql(latitude, longitude, *args)
         end
       end
 
@@ -83,170 +87,99 @@ module Geocoder::Store
       # * +:units+   - <tt>:mi</tt> or <tt>:km</tt>; to be used.
       #   for interpreting radius as well as the +distance+ attribute which
       #   is added to each found nearby object.
-      #   See Geocoder::Configuration to know how configure default units.
+      #   Use Geocoder.configure[:units] to configure default units.
       # * +:bearing+ - <tt>:linear</tt> or <tt>:spherical</tt>.
       #   the method to be used for calculating the bearing (direction)
       #   between the given point and each found nearby point;
-      #   set to false for no bearing calculation.
-      #   See Geocoder::Configuration to know how configure default method.
+      #   set to false for no bearing calculation. Use
+      #   Geocoder.configure[:distances] to configure default calculation method.
       # * +:select+  - string with the SELECT SQL fragment (e.g. “id, name”)
-      # * +:order+   - column(s) for ORDER BY SQL clause; default is distance
+      # * +:order+   - column(s) for ORDER BY SQL clause; default is distance;
+      #                set to false or nil to omit the ORDER BY clause
       # * +:exclude+ - an object to exclude (used by the +nearbys+ method)
       #
       def near_scope_options(latitude, longitude, radius = 20, options = {})
-        if using_sqlite?
-          approx_near_scope_options(latitude, longitude, radius, options)
-        else
-          full_near_scope_options(latitude, longitude, radius, options)
-        end
-      end
+        options[:units] ||= (geocoder_options[:units] || Geocoder.config.units)
+        bearing = bearing_sql(latitude, longitude, options)
+        distance = distance_sql(latitude, longitude, options)
+
+        b = Geocoder::Calculations.bounding_box([latitude, longitude], radius, options)
+        args = b + [
+          full_column_name(geocoder_options[:latitude]),
+          full_column_name(geocoder_options[:longitude])
+        ]
+        bounding_box_conditions = Geocoder::Sql.within_bounding_box(*args)
 
-      def distance_from_sql_options(latitude, longitude, options = {})
         if using_sqlite?
-          approx_distance_from_sql(latitude, longitude, options)
+          conditions = bounding_box_conditions
         else
-          full_distance_from_sql(latitude, longitude, options)
+          conditions = [bounding_box_conditions + " AND #{distance} <= ?", radius]
         end
+        {
+          :select => select_clause(options[:select], distance, bearing),
+          :conditions => add_exclude_condition(conditions, options[:exclude]),
+          :order => options.include?(:order) ? options[:order] : "distance ASC"
+        }
       end
 
       ##
-      # Scope options hash for use with a database that supports POWER(),
-      # SQRT(), PI(), and trigonometric functions SIN(), COS(), ASIN(),
-      # ATAN2(), DEGREES(), and RADIANS().
-      #
-      # Bearing calculation based on:
-      # http://www.beginningspatial.com/calculating_bearing_one_point_another
+      # SQL for calculating distance based on the current database's
+      # capabilities (trig functions?).
       #
-      def full_near_scope_options(latitude, longitude, radius, options)
-        lat_attr = geocoder_options[:latitude]
-        lon_attr = geocoder_options[:longitude]
-        options[:bearing] ||= (options[:method] ||
-                               geocoder_options[:method] ||
-                               Geocoder::Configuration.distances)
-        bearing = case options[:bearing]
-        when :linear
-          "CAST(" +
-            "DEGREES(ATAN2( " +
-              "RADIANS(#{full_column_name(lon_attr)} - #{longitude}), " +
-              "RADIANS(#{full_column_name(lat_attr)} - #{latitude})" +
-            ")) + 360 " +
-          "AS decimal) % 360"
-        when :spherical
-          "CAST(" +
-            "DEGREES(ATAN2( " +
-              "SIN(RADIANS(#{full_column_name(lon_attr)} - #{longitude})) * " +
-              "COS(RADIANS(#{full_column_name(lat_attr)})), (" +
-                "COS(RADIANS(#{latitude})) * SIN(RADIANS(#{full_column_name(lat_attr)}))" +
-              ") - (" +
-                "SIN(RADIANS(#{latitude})) * COS(RADIANS(#{full_column_name(lat_attr)})) * " +
-                "COS(RADIANS(#{full_column_name(lon_attr)} - #{longitude}))" +
-              ")" +
-            ")) + 360 " +
-          "AS decimal) % 360"
-        end
-        options[:units] ||= (geocoder_options[:units] || Geocoder::Configuration.units)
-        distance = full_distance_from_sql(latitude, longitude, options)
-        conditions = ["#{distance} <= ?", radius]
-        default_near_scope_options(latitude, longitude, radius, options).merge(
-          :select => "#{options[:select] || full_column_name("*")}, " +
-            "#{distance} AS distance" +
-            (bearing ? ", #{bearing} AS bearing" : ""),
-          :conditions => add_exclude_condition(conditions, options[:exclude])
+      def distance_sql(latitude, longitude, options = {})
+        method_prefix = using_sqlite? ? "approx" : "full"
+        Geocoder::Sql.send(
+          method_prefix + "_distance",
+          latitude, longitude,
+          full_column_name(geocoder_options[:latitude]),
+          full_column_name(geocoder_options[:longitude]),
+          options
         )
       end
 
-
-      # Distance calculations based on the excellent tutorial at:
-      # http://www.scribd.com/doc/2569355/Geo-Distance-Search-with-MySQL
-
-      def full_distance_from_sql(latitude, longitude, options)
-        lat_attr = geocoder_options[:latitude]
-        lon_attr = geocoder_options[:longitude]
-
-        earth = Geocoder::Calculations.earth_radius(options[:units] || :mi)
-
-        "#{earth} * 2 * ASIN(SQRT(" +
-          "POWER(SIN((#{latitude} - #{full_column_name(lat_attr)}) * PI() / 180 / 2), 2) + " +
-          "COS(#{latitude} * PI() / 180) * COS(#{full_column_name(lat_attr)} * PI() / 180) * " +
-          "POWER(SIN((#{longitude} - #{full_column_name(lon_attr)}) * PI() / 180 / 2), 2) ))"
-      end
-
-      def approx_distance_from_sql(latitude, longitude, options)
-        lat_attr = geocoder_options[:latitude]
-        lon_attr = geocoder_options[:longitude]
-
-        dx = Geocoder::Calculations.longitude_degree_distance(30, options[:units] || :mi)
-        dy = Geocoder::Calculations.latitude_degree_distance(options[:units] || :mi)
-
-        # sin of 45 degrees = average x or y component of vector
-        factor = Math.sin(Math::PI / 4)
-
-        "(#{dy} * ABS(#{full_column_name(lat_attr)} - #{latitude}) * #{factor}) + " +
-          "(#{dx} * ABS(#{full_column_name(lon_attr)} - #{longitude}) * #{factor})"
-      end
-
       ##
-      # Scope options hash for use with a database without trigonometric
-      # functions, like SQLite. Approach is to find objects within a square
-      # rather than a circle, so results are very approximate (will include
-      # objects outside the given radius).
-      #
-      # Distance and bearing calculations are *extremely inaccurate*. They
-      # only exist for interface consistency--not intended for production!
+      # SQL for calculating bearing based on the current database's
+      # capabilities (trig functions?).
       #
-      def approx_near_scope_options(latitude, longitude, radius, options)
-        lat_attr = geocoder_options[:latitude]
-        lon_attr = geocoder_options[:longitude]
-        unless options.include?(:bearing)
-          options[:bearing] = (options[:method] || \
-                               geocoder_options[:method] || \
-                               Geocoder::Configuration.distances)
+      def bearing_sql(latitude, longitude, options = {})
+        if !options.include?(:bearing)
+          options[:bearing] = Geocoder.config.distances
         end
         if options[:bearing]
-          bearing = "CASE " +
-            "WHEN (#{full_column_name(lat_attr)} >= #{latitude} AND #{full_column_name(lon_attr)} >= #{longitude}) THEN  45.0 " +
-            "WHEN (#{full_column_name(lat_attr)} <  #{latitude} AND #{full_column_name(lon_attr)} >= #{longitude}) THEN 135.0 " +
-            "WHEN (#{full_column_name(lat_attr)} <  #{latitude} AND #{full_column_name(lon_attr)} <  #{longitude}) THEN 225.0 " +
-            "WHEN (#{full_column_name(lat_attr)} >= #{latitude} AND #{full_column_name(lon_attr)} <  #{longitude}) THEN 315.0 " +
-          "END"
-        else
-          bearing = false
+          method_prefix = using_sqlite? ? "approx" : "full"
+          Geocoder::Sql.send(
+            method_prefix + "_bearing",
+            latitude, longitude,
+            full_column_name(geocoder_options[:latitude]),
+            full_column_name(geocoder_options[:longitude]),
+            options
+          )
         end
-
-        options[:units] ||= (geocoder_options[:units] || Geocoder::Configuration.units)
-        distance = approx_distance_from_sql(latitude, longitude, options)
-
-        b = Geocoder::Calculations.bounding_box([latitude, longitude], radius, options)
-        conditions = [
-          "#{full_column_name(lat_attr)} BETWEEN ? AND ? AND #{full_column_name(lon_attr)} BETWEEN ? AND ?"] +
-          [b[0], b[2], b[1], b[3]
-        ]
-        default_near_scope_options(latitude, longitude, radius, options).merge(
-          :select => "#{options[:select] || full_column_name("*")}, " +
-            "#{distance} AS distance" +
-            (bearing ? ", #{bearing} AS bearing" : ""),
-          :conditions => add_exclude_condition(conditions, options[:exclude])
-        )
       end
 
       ##
-      # Options used for any near-like scope.
+      # Generate the SELECT clause.
       #
-      def default_near_scope_options(latitude, longitude, radius, options)
-        {
-          :order  => options[:order] || "distance",
-          :limit  => options[:limit],
-          :offset => options[:offset]
-        }
+      def select_clause(columns, distance = nil, bearing = nil)
+        if columns == :id_only
+          return full_column_name(primary_key)
+        elsif columns == :geo_only
+          clause = ""
+        else
+          clause = (columns || full_column_name("*")) + ", "
+        end
+        clause + "#{distance} AS distance" +
+          (bearing ? ", #{bearing} AS bearing" : "")
       end
 
       ##
       # Adds a condition to exclude a given object by ID.
-      # The given conditions MUST be an array.
+      # Expects conditions as an array or string. Returns array.
       #
       def add_exclude_condition(conditions, exclude)
+        conditions = [conditions] if conditions.is_a?(String)
         if exclude
-          conditions[0] << " AND #{full_column_name(:id)} != ?"
+          conditions[0] << " AND #{full_column_name(primary_key)} != ?"
           conditions << exclude.id
         end
         conditions
@@ -280,8 +213,8 @@ module Geocoder::Store
       do_lookup(false) do |o,rs|
         if r = rs.first
           unless r.latitude.nil? or r.longitude.nil?
-            o.send :write_attribute, self.class.geocoder_options[:latitude],  r.latitude
-            o.send :write_attribute, self.class.geocoder_options[:longitude], r.longitude
+            o.__send__  "#{self.class.geocoder_options[:latitude]}=",  r.latitude
+            o.__send__  "#{self.class.geocoder_options[:longitude]}=", r.longitude
           end
           r.coordinates
         end
@@ -298,7 +231,7 @@ module Geocoder::Store
       do_lookup(true) do |o,rs|
         if r = rs.first
           unless r.address.nil?
-            o.send :write_attribute, self.class.geocoder_options[:fetched_address], r.address
+            o.__send__ "#{self.class.geocoder_options[:fetched_address]}=", r.address
           end
           r.address
         end

data/lib/geocoder/stores/base.rb

@@ -58,10 +58,11 @@ module Geocoder
       ##
       # Get nearby geocoded objects.
       # Takes the same options hash as the near class method (scope).
+      # Returns nil if the object is not geocoded.
       #
       def nearbys(radius = 20, options = {})
-        return [] unless geocoded?
-        options.merge!(:exclude => self)
+        return nil unless geocoded?
+        options.merge!(:exclude => self) unless send(self.class.primary_key).nil?
         self.class.near(self, radius, options)
       end
 

data/lib/geocoder/stores/mongo_base.rb

@@ -59,7 +59,7 @@ module Geocoder::Store
       do_lookup(false) do |o,rs|
         if r = rs.first
           unless r.coordinates.nil?
-            o.send :write_attribute, self.class.geocoder_options[:coordinates], r.coordinates.reverse
+            o.__send__ "#{self.class.geocoder_options[:coordinates]}=", r.coordinates.reverse
           end
           r.coordinates
         end
@@ -74,7 +74,7 @@ module Geocoder::Store
       do_lookup(true) do |o,rs|
         if r = rs.first
           unless r.address.nil?
-            o.send :write_attribute, self.class.geocoder_options[:fetched_address], r.address
+            o.__send__ "#{self.class.geocoder_options[:fetched_address]}=", r.address
           end
           r.address
         end

data/lib/geocoder/version.rb

@@ -1,3 +1,3 @@
 module Geocoder
-  VERSION = "1.1.3"
+  VERSION = "1.1.6"
 end

data/lib/geocoder.rb

@@ -1,8 +1,10 @@
 require "geocoder/configuration"
+require "geocoder/query"
 require "geocoder/calculations"
 require "geocoder/exceptions"
 require "geocoder/cache"
 require "geocoder/request"
+require "geocoder/lookup"
 require "geocoder/models/active_record" if defined?(::ActiveRecord)
 require "geocoder/models/mongoid" if defined?(::Mongoid)
 require "geocoder/models/mongo_mapper" if defined?(::MongoMapper)
@@ -13,15 +15,16 @@ module Geocoder
   ##
   # Search for information about an address or a set of coordinates.
   #
-  def search(query)
-    blank_query?(query) ? [] : lookup(query).search(query)
+  def search(query, options = {})
+    query = Geocoder::Query.new(query, options) unless query.is_a?(Geocoder::Query)
+    query.blank? ? [] : query.execute
   end
 
   ##
   # Look up the coordinates of the given street or IP address.
   #
-  def coordinates(address)
-    if (results = search(address)).size > 0
+  def coordinates(address, options = {})
+    if (results = search(address, options)).size > 0
       results.first.coordinates
     end
   end
@@ -30,8 +33,8 @@ module Geocoder
   # Look up the address of the given coordinates ([lat,lon])
   # or IP address (string).
   #
-  def address(query)
-    if (results = search(query)).size > 0
+  def address(query, options = {})
+    if (results = search(query, options)).size > 0
       results.first.address
     end
   end
@@ -40,89 +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
-  end
-
-  ##
-  # Array of valid Lookup names.
-  #
-  def valid_lookups
-    street_lookups + ip_lookups
-  end
-
-  ##
-  # All street address lookups, default first.
-  #
-  def street_lookups
-    [:google, :google_premier, :yahoo, :bing, :geocoder_ca, :yandex, :nominatim, :mapquest, :test]
-  end
-
-  ##
-  # All IP address lookups, default first.
-  #
-  def ip_lookups
-    [:freegeoip]
-  end
-
-
-  private # -----------------------------------------------------------------
-
-  ##
-  # Get a Lookup object (which communicates with the remote geocoding API).
-  # Takes a search query and returns an IP or street address Lookup
-  # depending on the query contents.
-  #
-  def lookup(query)
-    if ip_address?(query)
-      get_lookup(ip_lookups.first)
-    else
-      get_lookup(Configuration.lookup || street_lookups.first)
-    end
-  end
-
-  ##
-  # Retrieve a Lookup object from the store.
-  #
-  def get_lookup(name)
-    @lookups = {} unless defined?(@lookups)
-    @lookups[name] = spawn_lookup(name) unless @lookups.include?(name)
-    @lookups[name]
-  end
-
-  ##
-  # Spawn a Lookup of the given name.
-  #
-  def spawn_lookup(name)
-    if valid_lookups.include?(name)
-      name = name.to_s
-      require "geocoder/lookups/#{name}"
-      klass = name.split("_").map{ |i| i[0...1].upcase + i[1..-1] }.join
-      Geocoder::Lookup.const_get(klass).new
-    else
-      valids = valid_lookups.map(&:inspect).join(", ")
-      raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
-        "(#{name.inspect} is not one of: #{valids})."
-    end
-  end
-
-  ##
-  # Does the given value look like an IP address?
-  #
-  # Does not check for actual validity, just the appearance of four
-  # dot-delimited numbers.
-  #
-  def ip_address?(value)
-    !!value.to_s.match(/^(::ffff:)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
-  end
-
-  ##
-  # Is the given search query blank? (ie, should we not bother searching?)
-  #
-  def blank_query?(value)
-    !!value.to_s.match(/^\s*$/)
+    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/hash_recursive_merge.rb

@@ -0,0 +1,74 @@
+# 
+# = Hash Recursive Merge
+# 
+# Merges a Ruby Hash recursively, Also known as deep merge.
+# Recursive version of Hash#merge and Hash#merge!.
+# 
+# Category::    Ruby
+# Package::     Hash
+# Author::      Simone Carletti <weppos@weppos.net>
+# Copyright::   2007-2008 The Authors
+# License::     MIT License
+# Link::        http://www.simonecarletti.com/
+# Source::      http://gist.github.com/gists/6391/
+#
+module HashRecursiveMerge
+
+  #
+  # Recursive version of Hash#merge!
+  # 
+  # Adds the contents of +other_hash+ to +hsh+, 
+  # merging entries in +hsh+ with duplicate keys with those from +other_hash+.
+  # 
+  # Compared with Hash#merge!, this method supports nested hashes.
+  # When both +hsh+ and +other_hash+ contains an entry with the same key,
+  # it merges and returns the values from both arrays.
+  # 
+  #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+  #    h2 = {"b" => 254, "c" => {"c1" => 16, "c3" => 94}}
+  #    h1.rmerge!(h2)   #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+  #    
+  # Simply using Hash#merge! would return
+  # 
+  #    h1.merge!(h2)    #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+  # 
+  def rmerge!(other_hash)
+    merge!(other_hash) do |key, oldval, newval|
+      oldval.class == self.class ? oldval.rmerge!(newval) : newval
+    end
+  end
+
+  #
+  # Recursive version of Hash#merge
+  # 
+  # Compared with Hash#merge!, this method supports nested hashes.
+  # When both +hsh+ and +other_hash+ contains an entry with the same key,
+  # it merges and returns the values from both arrays.
+  # 
+  # Compared with Hash#merge, this method provides a different approch
+  # for merging nasted hashes.
+  # If the value of a given key is an Hash and both +other_hash+ abd +hsh
+  # includes the same key, the value is merged instead replaced with
+  # +other_hash+ value.
+  # 
+  #    h1 = {"a" => 100, "b" => 200, "c" => {"c1" => 12, "c2" => 14}}
+  #    h2 = {"b" => 254, "c" => {"c1" => 16, "c3" => 94}}
+  #    h1.rmerge(h2)    #=> {"a" => 100, "b" => 254, "c" => {"c1" => 16, "c2" => 14, "c3" => 94}}
+  #    
+  # Simply using Hash#merge would return
+  # 
+  #    h1.merge(h2)     #=> {"a" => 100, "b" = >254, "c" => {"c1" => 16, "c3" => 94}}
+  # 
+  def rmerge(other_hash)
+    r = {}
+    merge(other_hash) do |key, oldval, newval|
+      r[key] = oldval.class == self.class ? oldval.rmerge(newval) : newval
+    end
+  end
+
+end
+
+
+class Hash
+  include HashRecursiveMerge
+end