geo_tools 1.0.1 → 1.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.rbenv-version

@@ -0,0 +1 @@
+1.9.3-p0

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec

data/README.md

@@ -1,6 +1,5 @@
 # GeoTools
 
-
 You have lots of plugin choices if you want to geocode North American addresses, or find all the locations near somewhere.  But few help you with forms and validation.
 
 This plugin does four things:
@@ -11,49 +10,56 @@ This plugin does four things:
 * Gives you a `within` named scope to find all lcoations within a given bounding box, such as you would have on a Google map.
 
 
+## Compatibility
+
+Works on Ruby 1.8+ and 1.9+.
+
+Designed for Rails 2.3.
+
+
 ## Assumptions
 
 * Any model that acts_as_location has integers defined for each component of the latitude and longitude:
 
-    # In your model's migration's self.up method:
-    create_table :thingies do |t|
-      # Your model's various fields.
-      t.string :name
-      t.timestamps
-      ...
-
-      # Stuff GeoTools needs:
-      t.integer :latitude_degrees,  :latitude_minutes,  :latitude_decimal_minutes, :latitude_decimal_minutes_width
-      t.string  :latitude_hemisphere
-      t.integer :longitude_degrees, :longitude_minutes, :longitude_decimal_minutes, :longitude_decimal_minutes_width
-      t.string  :longitude_hemisphere
-    end
+        # In your model's migration's self.up method:
+        create_table :thingies do |t|
+          # Your model's various fields.
+          t.string :name
+          t.timestamps
+          ...
+
+          # Stuff GeoTools needs:
+          t.integer :latitude_degrees,  :latitude_minutes,  :latitude_decimal_minutes, :latitude_decimal_minutes_width
+          t.string  :latitude_hemisphere
+          t.integer :longitude_degrees, :longitude_minutes, :longitude_decimal_minutes, :longitude_decimal_minutes_width
+          t.string  :longitude_hemisphere
+        end
 
-  Storing the components separately like this avoids the round-trip rounding errors you get when using floating point numbers.  If you need a floating point representation in the database, for example to use a mapping plugin, simply add an after_update callback to your model to write the float value to the database.
+    Storing the components separately like this avoids the round-trip rounding errors you get when using floating point numbers.  If you need a floating point representation in the database, for example to use a mapping plugin, simply add an after_update callback to your model to write the float value to the database.
 
 * A latitude should be entered on a form like this:
 
-    xx <degree symbol> yy <decimal point> zz h
+        xx <degree symbol> yy <decimal point> zz h
 
-  where:
+    where:
 
-  xx is degrees (0 <= integer <= 90; maximum length of 2 digits)
-  yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
-  zz is decimal-minutes (0 <= integer <= 99; maximum length of 2 digits; optional; defaults to 0)
-  h is hemisphere ('N' or 'S')
+        xx is degrees (0 <= integer <= 90; maximum length of 2 digits)
+        yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
+        zz is decimal-minutes (0 <= integer <= 99; maximum length of 2 digits; optional; defaults to 0)
+        h is hemisphere ('N' or 'S')
 
-  Note with decimal minutes 2, 20 and 200000 are equivalent.  This is because 3.2, 3.20 and 3.200000 are equivalent.
+    Note with decimal minutes 2, 20 and 200000 are equivalent.  This is because 3.2, 3.20 and 3.200000 are equivalent.
 
 * Similarly, a longitude should be entered on a form like this:
 
-    xxx <degree symbol> yy <decimal point> zz h
+        xxx <degree symbol> yy <decimal point> zz h
 
-  where:
+    where:
 
-  xxx is degrees (0 <= integer <= 180; maximum length of 3 digits)
-  yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
-  zz is decimal-minutes (0 <= integer <= 99; maximum length of 2 digits; optional; defaults to 0)
-  h is hemisphere ('E' or 'W')
+        xxx is degrees (0 <= integer <= 180; maximum length of 3 digits)
+        yy is minutes (0 <= integer <= 59; maximum length of 2 digits; optional; defaults to 0)
+        zz is decimal-minutes (0 <= integer <= 99; maximum length of 2 digits; optional; defaults to 0)
+        h is hemisphere ('E' or 'W')
 
 
 ## Example
@@ -87,20 +93,14 @@ Here's an example script/console session:
     -12.576
 
 
-## To Do
+## Someday / Maybe
 
-* Get tests to run transactionally so we don't have to clean out database in every single #setup method.
+* Refactor the multiple string columns into a single string column (per lat. and per lng.), and use virtual attributes to map the single db field back and forth to multiple form fields.  Add a float to 'cache' the lat/lng values.  This will simplify the code significantly.
 * Add a validation for the overall latitude and longitude values (to catch for example 90°00.01′N).
 * Use `method` in the form helpers so user can give database columns different names (e.g. my_lat_degrees, etc).
   See the way Paperclip allows different attachment names.
 * DRY up form helper methods.
 * DRY up location.rb.
-* Investigate implementing with ActiveRecord's multiparameter assignment.
-
-
-## Feedback
-
-Yes please!  --> boss@airbladesoftware.com
 
 
 ## Intellectual Property

data/Rakefile

@@ -1,37 +1 @@
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-
-desc 'Default: run unit tests.'
-task :default => :test
-
-desc 'Test the geo_tools plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
-
-desc 'Generate documentation for the geo_tools plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'GeoTools'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = 'geo_tools'
-    gemspec.summary = 'View helpers, validations, and named scopes for locations.'
-    gemspec.email = 'boss@airbladesoftware.com'
-    gemspec.homepage = 'http://github.com/airblade/geo_tools'
-    gemspec.authors = ['Andy Stewart']
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts 'Jeweler not available. Install it with: gem install jeweler'
-end
+require 'bundler/gem_tasks'

data/geo_tools.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "geo_tools/version"
+
+Gem::Specification.new do |s|
+  s.name        = 'geo_tools'
+  s.version     = GeoTools::VERSION
+  s.authors     = ['Andy Stewart']
+  s.email       = ['boss@airbladesoftware.com']
+  s.homepage    = 'https://github.com/airblade/geo_tools'
+  s.summary     = 'Makes using latitudes and longitudes on forms easier.'
+  s.description = s.summary
+
+  s.rubyforge_project = 'geo_tools'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_runtime_dependency 'rails', '~> 2.3'
+
+  s.add_development_dependency 'sqlite3-ruby'
+  s.add_development_dependency 'shoulda-context', '~> 1.0.0'
+end

data/lib/geo_tools.rb

@@ -1,3 +1,4 @@
-require File.dirname(__FILE__) + '/air_blade/geo_tools/validations'
-require File.dirname(__FILE__) + '/air_blade/geo_tools/location'
-require File.dirname(__FILE__) + '/air_blade/geo_tools/form_helpers'
+require 'geo_tools/validations'
+require 'geo_tools/location'
+require 'geo_tools/form_helpers'
+require 'geo_tools/version'

data/lib/geo_tools/form_helpers.rb

@@ -0,0 +1,103 @@
+# encoding: utf-8
+module GeoTools
+  module FormHelpers
+
+    # Options:
+    #   :latitude
+    #     :degrees
+    #       :symbol
+    #     :minutes
+    #       :symbol
+    #     :decimal_minutes
+    #       :symbol
+    #       :maxlength
+    #
+    # Assumes the latitude field is called 'latitude'.
+    #
+    # The 'method' argument is for consistency with other field helpers.  We don't use it
+    # when using the normal Rails form builder.
+    #
+    # 1/100th of a minute of latitude (or equitorial longitude) is approximately 20m.
+    def latitude_field(method, options = {})
+      opts = {
+        :degrees         => { :symbol => '°' },
+        :minutes         => { :symbol => '.'     },
+        :decimal_minutes => { :symbol => '′', :maxlength => 2 },
+      }
+      lat_options = options.delete :latitude
+      opts.merge! lat_options if lat_options
+      
+      output = []
+
+      # Degrees
+      width = 2
+      output << text_field("latitude_degrees",
+                           options.merge(:maxlength => width,
+                                         :value     => "%0#{width}d" % (@object.send("latitude_degrees") || 0)))
+      output << opts[:degrees][:symbol]
+
+      # Minutes
+      width = 2
+      output << text_field("latitude_minutes",
+                           options.merge(:maxlength => width,
+                                         :value     => "%0#{width}d" % (@object.send("latitude_minutes") || 0)))
+      output << opts[:minutes][:symbol]
+
+      # Decimal minutes
+      width = opts[:decimal_minutes][:maxlength]
+      output << text_field("latitude_decimal_minutes",
+                           options.merge(:maxlength => width,
+                                         :value     => @object.send("latitude_decimal_minutes_as_string").ljust(width, '0')))
+      output << opts[:decimal_minutes][:symbol]
+
+      # Hemisphere.
+      # Hmm, we pass the options in the html_options position.
+      output << select("latitude_hemisphere", %w( N S ), {}, options)
+
+      output.join "\n"
+    end
+
+    def longitude_field(method, options = {})
+      opts = {
+        :degrees         => { :symbol => '&deg;' },
+        :minutes         => { :symbol => '.'     },
+        :decimal_minutes => { :symbol => '&prime;', :maxlength => 2 },
+      }
+      long_options = options.delete :longitude
+      opts.merge! long_options if long_options
+
+      output = []
+      
+      # Degrees
+      width = 3
+      output << text_field("longitude_degrees",
+                           options.merge(:maxlength => width,
+                                         :value     => "%0#{width}d" % (@object.send("longitude_degrees") || 0)))
+      output << opts[:degrees][:symbol]
+
+      # Minutes
+      width = 2
+      output << text_field("longitude_minutes",
+                           options.merge(:maxlength => width,
+                                         :value     => "%0#{width}d" % (@object.send("longitude_minutes") || 0)))
+      output << opts[:minutes][:symbol]
+
+      # Decimal minutes
+      width = opts[:decimal_minutes][:maxlength]
+      output << text_field("longitude_decimal_minutes",
+                           options.merge(:maxlength => width,
+                                         :value     => @object.send("longitude_decimal_minutes_as_string").ljust(width, '0')))
+      output << opts[:decimal_minutes][:symbol]
+
+      # Hemisphere.
+      # Hmm, we pass the options in the html_options position.
+      output << select("longitude_hemisphere", %w( E W ), {}, options)
+
+      output.join "\n"
+    end
+
+  end
+end
+
+
+ActionView::Helpers::FormBuilder.send :include, GeoTools::FormHelpers

data/lib/geo_tools/location.rb

@@ -0,0 +1,259 @@
+# encoding: utf-8
+module GeoTools
+  module Location
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def acts_as_location
+        include InstanceMethodsOnActivation
+
+        validates_numericality_of_for :latitude_degrees,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :less_than_or_equal_to    => 90,
+                                      :message                  => 'Degrees are invalid',
+                                      :for                      => :latitude
+
+        validates_numericality_of_for :latitude_minutes,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :less_than                => 60,
+                                      :message                  => 'Minutes are invalid',
+                                      :for                      => :latitude
+
+        validates_numericality_of_for :latitude_decimal_minutes,
+                                      :only_integer              => true,
+                                      :greater_than_or_equal_to  => 0,
+                                      :message                   => 'Decimal minutes are invalid',
+                                      :for                       => :latitude
+
+        validates_numericality_of_for :latitude_decimal_minutes_width,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :for                      => :latitude
+
+        validates_inclusion_of_for    :latitude_hemisphere,
+                                      :in      => %w( N S ),
+                                      :message => 'Hemisphere is invalid',
+                                      :for     => :latitude
+
+        validates_numericality_of_for :longitude_degrees,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :less_than_or_equal_to    => 180,
+                                      :message                  => 'Degrees are invalid',
+                                      :for                      => :longitude
+
+        validates_numericality_of_for :longitude_minutes,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :less_than                => 60,
+                                      :message                  => 'Minutes are invalid',
+                                      :for                      => :longitude
+
+        validates_numericality_of_for :longitude_decimal_minutes,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :message                  => 'Decimal minutes are invalid',
+                                      :for                      => :longitude
+
+        validates_numericality_of_for :longitude_decimal_minutes_width,
+                                      :only_integer             => true,
+                                      :greater_than_or_equal_to => 0,
+                                      :for                      => :longitude
+
+        validates_inclusion_of_for    :longitude_hemisphere,
+                                      :in      => %w( E W ),
+                                      :message => 'Hemisphere is invalid',
+                                      :for     => :longitude
+
+        before_validation :set_empty_values
+
+        # Returns all locations within the given bounding box, to an accuracy of 1 minute.
+        #
+        # This is useful for finding all locations within the area covered by a Google map.
+        #
+        # The parameters should be positive/negative floats.
+        named_scope :within, lambda { |sw_lat, sw_lng, ne_lat, ne_lng|
+          sw_lat_degs = sw_lat.to_i.abs
+          sw_lat_mins = ((sw_lat - sw_lat.to_i) * 60.0).round.abs
+          ne_lat_degs = ne_lat.to_i.abs
+          ne_lat_mins = ((ne_lat - ne_lat.to_i) * 60.0).round.abs
+
+          sw_lng_degs = sw_lng.to_i.abs
+          sw_lng_mins = ((sw_lng - sw_lng.to_i) * 60.0).round.abs
+          ne_lng_degs = ne_lng.to_i.abs
+          ne_lng_mins = ((ne_lng - ne_lng.to_i) * 60.0).round.abs
+
+          # Latitude conditions.
+          if sw_lat > 0 && ne_lat > 0       # northern hemisphere
+            condition_lat_h  = 'latitude_hemisphere = "N"'
+            condition_lat_sw = ["(latitude_degrees > ?) OR (latitude_degrees = ? AND latitude_minutes >= ?)", sw_lat_degs, sw_lat_degs, sw_lat_mins]
+            condition_lat_ne = ["(latitude_degrees < ?) OR (latitude_degrees = ? AND latitude_minutes <= ?)", ne_lat_degs, ne_lat_degs, ne_lat_mins]
+            condition_lat    = merge_conditions condition_lat_h, condition_lat_sw, condition_lat_ne
+
+          elsif sw_lat < 0 && ne_lat < 0    # southern hemisphere
+            condition_lat_h  = 'latitude_hemisphere = "S"'
+            condition_lat_sw = ["(latitude_degrees < ?) OR (latitude_degrees = ? AND latitude_minutes <= ?)", sw_lat_degs, sw_lat_degs, sw_lat_mins]
+            condition_lat_ne = ["(latitude_degrees > ?) OR (latitude_degrees = ? AND latitude_minutes >= ?)", ne_lat_degs, ne_lat_degs, ne_lat_mins]
+            condition_lat    = merge_conditions condition_lat_h, condition_lat_sw, condition_lat_ne
+
+          elsif sw_lat <= 0 && ne_lat >= 0  # straddles equator
+            condition_lat_h  = 'latitude_hemisphere = "S"'
+            condition_lat_sw = ["(latitude_degrees < ?) OR (latitude_degrees = ? AND latitude_minutes <= ?)", sw_lat_degs, sw_lat_degs, sw_lat_mins]
+            condition_lat_s  = merge_conditions condition_lat_h, condition_lat_sw
+
+            condition_lat_h  = 'latitude_hemisphere = "N"'
+            condition_lat_ne = ["(latitude_degrees < ?) OR (latitude_degrees = ? AND latitude_minutes <= ?)", ne_lat_degs, ne_lat_degs, ne_lat_mins]
+            condition_lat_n  = merge_conditions condition_lat_h, condition_lat_ne
+
+            condition_lat    = merge_or_conditions condition_lat_s, condition_lat_n
+          end
+
+          # Longitude conditions.
+          if sw_lng > 0 && ne_lng > 0       # eastern hemisphere
+            condition_lng_h  = 'longitude_hemisphere = "E"'
+            condition_lng_sw = ["(longitude_degrees > ?) OR (longitude_degrees = ? AND longitude_minutes >= ?)", sw_lng_degs, sw_lng_degs, sw_lng_mins]
+            condition_lng_ne = ["(longitude_degrees < ?) OR (longitude_degrees = ? AND longitude_minutes <= ?)", ne_lng_degs, ne_lng_degs, ne_lng_mins]
+            condition_lng    = merge_conditions condition_lng_h, condition_lng_sw, condition_lng_ne
+
+          elsif sw_lng < 0 && ne_lng < 0    # western hemisphere
+            condition_lng_h  = 'longitude_hemisphere = "W"'
+            condition_lng_sw = ["(longitude_degrees < ?) OR (longitude_degrees = ? AND longitude_minutes <= ?)", sw_lng_degs, sw_lng_degs, sw_lng_mins]
+            condition_lng_ne = ["(longitude_degrees > ?) OR (longitude_degrees = ? AND longitude_minutes >= ?)", ne_lng_degs, ne_lng_degs, ne_lng_mins]
+            condition_lng    = merge_conditions condition_lng_h, condition_lng_sw, condition_lng_ne
+
+          elsif sw_lng <= 0 && ne_lng >= 0  # straddles prime meridian
+            condition_lng_h  = 'longitude_hemisphere = "W"'
+            condition_lng_sw = ["(longitude_degrees < ?) OR (longitude_degrees = ? AND longitude_minutes <= ?)", sw_lng_degs, sw_lng_degs, sw_lng_mins]
+            condition_lng_w  = merge_conditions condition_lng_h, condition_lng_sw
+
+            condition_lng_h  = 'longitude_hemisphere = "E"'
+            condition_lng_ne = ["(longitude_degrees < ?) OR (longitude_degrees = ? AND longitude_minutes <= ?)", ne_lng_degs, ne_lng_degs, ne_lng_mins]
+            condition_lng_e  = merge_conditions condition_lng_h, condition_lng_ne
+
+            condition_lng    = merge_or_conditions condition_lng_w, condition_lng_e
+          end
+
+          # Combined latitude and longitude conditions.
+          {:conditions => merge_conditions(condition_lat, condition_lng)}
+        }
+
+        private
+
+        # Merges conditions so that the result is a valid +condition+.
+        # Adapted from ActiveRecord::Base#merge_conditions.
+        def merge_or_conditions(*conditions)
+          segments = []
+
+          conditions.each do |condition|
+            unless condition.blank?
+              sql = sanitize_sql(condition)
+              segments << sql unless sql.blank?
+            end
+          end
+
+          "(#{segments.join(') OR (')})" unless segments.empty?
+        end
+
+      end # def acts_as_location
+    end # module ClassMethods
+
+
+    module InstanceMethodsOnActivation
+      def latitude_decimal_minutes=(value)
+        unless value.nil?
+          width = value.to_s.length
+          value = value.to_i
+
+          write_attribute :latitude_decimal_minutes, value
+          write_attribute :latitude_decimal_minutes_width, width
+        end
+      end
+
+      def latitude_decimal_minutes_as_string
+        "%0#{latitude_decimal_minutes_width}d" % (latitude_decimal_minutes || 0)
+      end
+
+      def longitude_decimal_minutes=(value)
+        unless value.nil?
+          width = value.to_s.length
+          value = value.to_i
+
+          write_attribute :longitude_decimal_minutes, value
+          write_attribute :longitude_decimal_minutes_width, width
+        end
+      end
+
+      def longitude_decimal_minutes_as_string
+        "%0#{longitude_decimal_minutes_width}d" % (longitude_decimal_minutes || 0)
+      end
+
+      def latitude
+        to_float latitude_degrees, latitude_minutes, latitude_decimal_minutes,
+                 latitude_decimal_minutes_width, latitude_hemisphere
+      end
+
+      def longitude
+        to_float longitude_degrees, longitude_minutes, longitude_decimal_minutes,
+                 longitude_decimal_minutes_width, longitude_hemisphere
+      end
+
+      def to_s
+        # Unicode degree symbol, full stop, Unicode minute symbol.
+        units = [ "\xc2\xb0", '.',  "\xe2\x80\xb2" ]
+
+        lat_fields = ["%02d" % (latitude_degrees || 0),
+                      "%02d" % (latitude_minutes || 0),
+                      latitude_decimal_minutes_as_string.ljust(2, '0'),
+                      latitude_hemisphere]
+        lat = lat_fields.zip(units).map{ |f| f.join }.join
+
+        long_fields = ["%02d" % (longitude_degrees || 0),
+                       "%02d" % (longitude_minutes || 0),
+                       longitude_decimal_minutes_as_string.ljust(2, '0'),
+                       longitude_hemisphere]
+        long = long_fields.zip(units).map{ |f| f.join }.join
+
+        "#{lat}, #{long}"
+      end
+
+      private
+
+      def to_float(degrees, minutes, decimal_minutes, decimal_minutes_width, hemisphere)
+        return nil if degrees.nil? and minutes.nil? and decimal_minutes.nil?
+        degrees ||= 0
+        minutes ||= 0
+        decimal_minutes ||= 0
+
+        f = degrees.to_f
+        f = f + (minutes.to_f + decimal_minutes.to_f / 10 ** decimal_minutes_width) / 60.0
+        f = f * -1 if hemisphere == 'S' or hemisphere == 'W'
+        f
+      end
+
+      # If some of the fields are empty, set them to zero.  This is to speed up data entry.
+      # If all the fields are empty, leave them empty.
+      def set_empty_values
+        unless latitude_degrees.blank? and latitude_minutes.blank? and latitude_decimal_minutes.blank?
+          self.latitude_degrees = 0         if latitude_degrees.blank?
+          self.latitude_minutes = 0         if latitude_minutes.blank?
+          self.latitude_decimal_minutes = 0 if latitude_decimal_minutes.blank?
+        end
+
+        unless longitude_degrees.blank? and longitude_minutes.blank? and longitude_decimal_minutes.blank?
+          self.longitude_degrees = 0         if longitude_degrees.blank?
+          self.longitude_minutes = 0         if longitude_minutes.blank?
+          self.longitude_decimal_minutes = 0 if longitude_decimal_minutes.blank?
+        end
+      end
+    end # InstanceMethodsOnActivation
+
+  end # module Location
+end # module GeoTools
+
+
+ActiveRecord::Base.send :include, GeoTools::Location