geo_tools 1.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,108 @@
+# 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:
+
+* Adds `latitude_field` and `longitude_field` form helpers to Rails' default form builder.
+* Lets your model acts_as_location, to work seamlessly with the form helpers.
+* Validates the location data entered on the form and in the database.
+* Gives you a `within` named scope to find all lcoations within a given bounding box, such as you would have on a Google map.
+
+
+## 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
+
+  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
+
+  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')
+
+  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
+
+  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')
+
+
+## Example
+
+    # Model
+    class Treasure < ActiveRecord::Base
+      acts_as_location
+    end
+
+    # View
+    <% form_for @treasure do |f| %>
+      <%= f.text_field :spot_marked_by %>
+      <%= f.latitude_field :latitude %>
+      <%= f.longitude_field :longitude %>
+    <% end %>
+
+    # Controller
+    # ...same as usual...
+
+You'll get validation on every field (degrees, minutes, decimal-minutes, hemisphere) generated by the form helpers, though not the overall value any more (TBD).
+
+Here's an example script/console session:
+
+    >> puts Treasure.find(:first).location
+    12°34.56′N, 012°34.56′W   # N.B. If this looks weird online, set your browser's text encoding to UTF-8.
+
+    >> puts Treasure.find(:first).location.latitude
+    12.576
+
+    >> puts Treasure.find(:first).location.longitude
+    -12.576
+
+
+## To Do
+
+* Get tests to run transactionally so we don't have to clean out database in every single #setup method.
+* 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
+
+Copyright (c) 2010 Andy Stewart, AirBlade Software Ltd.  Released under the MIT license

data/Rakefile

@@ -0,0 +1,37 @@
+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

data/VERSION

@@ -0,0 +1 @@
+1.0.1

data/init.rb

@@ -0,0 +1 @@
+require 'geo_tools'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/air_blade/geo_tools/form_helpers.rb

@@ -0,0 +1,166 @@
+module AirBlade
+  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 << plain_text_field("latitude_degrees",
+                             options.merge(:maxlength => width,
+                                           :value     => "%0#{width}d" % @object.send("latitude_degrees")))
+        output << opts[:degrees][:symbol]
+
+        # Minutes
+        width = 2
+        output << plain_text_field("latitude_minutes",
+                             options.merge(:maxlength => width,
+                                           :value     => "%0#{width}d" % @object.send("latitude_minutes")))
+        output << opts[:minutes][:symbol]
+
+        # Decimal minutes
+        width = opts[:decimal_minutes][:maxlength]
+        output << plain_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 << plain_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 << plain_text_field("longitude_degrees",
+                             options.merge(:maxlength => width,
+                                           :value     => "%0#{width}d" % @object.send("longitude_degrees")))
+        output << opts[:degrees][:symbol]
+
+        # Minutes
+        width = 2
+        output << plain_text_field("longitude_minutes",
+                             options.merge(:maxlength => width,
+                                           :value     => "%0#{width}d" % @object.send("longitude_minutes")))
+        output << opts[:minutes][:symbol]
+
+        # Decimal minutes
+        width = opts[:decimal_minutes][:maxlength]
+        output << plain_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 << plain_select("longitude_hemisphere", %w( E W ), {}, options)
+
+        output.join "\n"
+      end
+
+      # A layer of indirection to allow us always to use a plain field helpers,
+      # regardless of the form builder being used.
+
+      def plain_text_field(*a, &b)
+        text_field(*a, &b)
+      end
+
+      def plain_select(*a, &b)
+        select(*a, &b)
+      end
+    end
+
+
+    module AirBuddFormHelpers
+      include AirBlade::GeoTools::FormHelpers
+      alias_method :plain_latitude_field,  :latitude_field
+      alias_method :plain_longitude_field, :longitude_field
+
+      # Override latitude_field to wrap it with the custom form builder gubbins.
+      # http://github.com/airblade/air_budd_form_builder/tree/master/lib/air_blade/air_budd/form_builder.rb
+      def latitude_field(method, options = {}, html_options = {})
+        @template.content_tag('p',
+          label_element(method, options, html_options) +
+          (
+            plain_latitude_field method, options
+          ) +
+          hint_element(options),
+          (errors_for?(method) ? {:class => 'error'} : {})
+        )
+      end
+
+      # Override longitude_field to wrap it with the custom form builder gubbins.
+      # http://github.com/airblade/air_budd_form_builder/tree/master/lib/air_blade/air_budd/form_builder.rb
+      def longitude_field(method, options = {}, html_options = {})
+        @template.content_tag('p',
+          label_element(method, options, html_options) +
+          (
+            plain_longitude_field method, options
+          ) +
+          hint_element(options),
+          (errors_for?(method) ? {:class => 'error'} : {})
+        )
+      end
+
+      # Use the standard Rails helpers for text fields and selects.
+      # These are overridden by the AirBudd form builder, so we define
+      # them ourselves.
+
+      def plain_text_field(method, options = {})
+        # From ActionView::Helpers::FormBuilder
+        @template.send('text_field', @object_name, method, objectify_options(options))
+      end
+      def plain_select(method, choices, options = {}, html_options = {})
+        # From ActionView::Helpers::FormOptionsHelper::FormBuilder
+        @template.select(@object_name, method, choices, objectify_options(options), @default_options.merge(html_options))
+      end
+    end
+
+  end
+end
+
+
+# Integrate with standard Rails form builder.
+ActionView::Helpers::FormBuilder.send :include, AirBlade::GeoTools::FormHelpers
+
+# Integrate with custom AirBudd form builder.
+AirBlade::AirBudd::FormBuilder.send(:include, AirBlade::GeoTools::AirBuddFormHelpers) rescue nil

data/lib/air_blade/geo_tools/location.rb

@@ -0,0 +1,266 @@
+module AirBlade
+  module GeoTools
+    module Location
+
+      def self.included(base)
+        # Lazy loading pattern.
+        base.extend ActMethods
+      end
+
+      module ActMethods
+        def acts_as_location
+          unless included_modules.include? InstanceMethods
+            extend ClassMethods
+            include InstanceMethods
+
+            code = <<-END
+              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
+            END
+            class_eval code, __FILE__, __LINE__
+
+            # 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)}
+            }
+
+          end
+        end
+      end
+
+      module ClassMethods
+        # 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
+
+      module InstanceMethods
+
+        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
+        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
+        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,
+                        "%02d" % latitude_minutes,
+                        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,
+                         "%02d" % longitude_minutes,
+                         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
+
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, AirBlade::GeoTools::Location

data/lib/air_blade/geo_tools/validations.rb

@@ -0,0 +1,75 @@
+module AirBlade
+  module GeoTools
+    module Validations
+
+      # Sames as validates_numericality_of but additionally supports :for option
+      # which lets you attach an error to a different attribute.
+      def validates_inclusion_of_for(*attr_names)
+        configuration = { :on => :save }
+        configuration.update(attr_names.extract_options!)
+
+        enum = configuration[:in] || configuration[:within]
+
+        raise(ArgumentError, "An object with the method include? is required must be supplied as the :in option of the configuration hash") unless enum.respond_to?(:include?)
+
+        validates_each(attr_names, configuration) do |record, attr_name, value|
+          unless enum.include?(value)
+            attr_for = configuration[:for] || attr_name
+            record.errors.add(attr_for, :inclusion, :default => configuration[:message], :value => value) 
+          end
+        end
+      end
+
+      # Sames as validates_numericality_of but additionally supports :for option
+      # which lets you attach an error to a different attribute.
+      def validates_numericality_of_for(*attr_names)
+        configuration = { :on => :save, :only_integer => false, :allow_nil => false }
+        configuration.update(attr_names.extract_options!)
+
+        numericality_options = ActiveRecord::Validations::ClassMethods::ALL_NUMERICALITY_CHECKS.keys & configuration.keys
+
+        (numericality_options - [ :odd, :even ]).each do |option|
+          raise ArgumentError, ":#{option} must be a number" unless configuration[option].is_a?(Numeric)
+        end
+
+        validates_each(attr_names,configuration) do |record, attr_name, value|
+          raw_value = record.send("#{attr_name}_before_type_cast") || value
+
+          next if configuration[:allow_nil] and raw_value.nil?
+
+          attr_for = configuration[:for] || attr_name
+
+          if configuration[:only_integer]
+            unless raw_value.to_s =~ /\A[+-]?\d+\Z/
+              record.errors.add(attr_for, :not_a_number, :value => raw_value, :default => configuration[:message])
+              next
+            end
+            raw_value = raw_value.to_i
+          else
+            begin
+              raw_value = Kernel.Float(raw_value)
+            rescue ArgumentError, TypeError
+              record.errors.add(attr_for, :not_a_number, :value => raw_value, :default => configuration[:message])
+              next
+            end
+          end
+
+          numericality_options.each do |option|
+            case option
+            when :odd, :even
+              unless raw_value.to_i.method( ActiveRecord::Validations::ClassMethods::ALL_NUMERICALITY_CHECKS[option])[]
+                record.errors.add(attr_for, option, :value => raw_value, :default => configuration[:message]) 
+              end
+            else
+              record.errors.add(attr_for, option, :default => configuration[:message], :value => raw_value, :count => configuration[option]) unless raw_value.method( ActiveRecord::Validations::ClassMethods::ALL_NUMERICALITY_CHECKS[option])[configuration[option]]
+            end
+          end
+        end
+      end
+
+    end
+  end
+end
+
+
+ActiveRecord::Base.send :extend, AirBlade::GeoTools::Validations

data/lib/geo_tools.rb

@@ -0,0 +1,3 @@
+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'

data/tasks/geo_tools_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :geo_tools do
+#   # Task goes here
+# end

data/test/geo_tools_test.rb

@@ -0,0 +1,160 @@
+require 'test_helper'
+
+class Treasure < ActiveRecord::Base
+  acts_as_location
+end
+
+class GeoToolsTest < ActiveSupport::TestCase
+
+  context 'A location model' do
+    setup { @treasure = Treasure.new }
+
+    should 'convert northern hemisphere latitude fields to a positive float' do
+      @treasure.update_attributes location
+      assert_in_delta 42.95583, @treasure.latitude, 0.0001
+    end
+
+    should 'convert southern hemisphere latitude fields to a negative float' do
+      @treasure.update_attributes location(:latitude_hemisphere => 'S')
+      assert_in_delta -42.95583, @treasure.latitude, 0.0001
+    end
+
+    should 'convert eastern hemisphere longitude fields to a positive float' do
+      @treasure.update_attributes location
+      assert_in_delta 153.37117, @treasure.longitude, 0.0001
+    end
+
+    should 'convert western hemisphere longitude fields to a negative float' do
+      @treasure.update_attributes location(:longitude_hemisphere => 'W')
+      assert_in_delta -153.37117, @treasure.longitude, 0.0001
+    end
+
+    should 'display a pretty #to_s' do
+      @treasure.update_attributes location
+      assert_equal "42°57.35′N, 153°22.27′E", @treasure.to_s
+    end
+
+    teardown { Treasure.destroy_all }
+  end
+
+  context 'Location#within' do
+    # TODO: use Factory Girl.
+
+    context 'NE quadrant' do
+      setup do
+        @a = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'E', :latitude_minutes => '12', :longitude_minutes => '47'
+        @b = Treasure.create :latitude_degrees => '43', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'E'
+        @c = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '154', :longitude_hemisphere => 'E'
+      end
+      should 'return locations to nearest minute' do
+        assert_same_elements [],           Treasure.within(1, 1, 42, 153)
+        assert_same_elements [@a, @b, @c], Treasure.within(1, 1, 43, 154)
+        assert_same_elements [@c],         Treasure.within(1, 1, f(42, 11), 154)
+        assert_same_elements [@a, @c],     Treasure.within(1, 1, f(42, 12), 154)
+        assert_same_elements [@b],         Treasure.within(1, 1, 43, f(153, 46))
+        assert_same_elements [@a, @b],     Treasure.within(1, 1, 43, f(153, 47))
+      end
+      teardown { Treasure.destroy_all }
+    end
+
+    context 'NW quadrant' do
+      setup do
+        @a = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'W', :latitude_minutes => '12', :longitude_minutes => '47'
+        @b = Treasure.create :latitude_degrees => '43', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'W'
+        @c = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '154', :longitude_hemisphere => 'W'
+      end
+      should 'return locations to nearest minute' do
+        assert_same_elements [],           Treasure.within(1, -153, 42, -1)
+        assert_same_elements [@a, @b, @c], Treasure.within(1, -154, 43, -1)
+        assert_same_elements [@c],         Treasure.within(1, -154, f(42, 11), -1)
+        assert_same_elements [@a, @c],     Treasure.within(1, -154, f(42, 12), -1)
+        assert_same_elements [@b],         Treasure.within(1, f(-153, 46), 43, -1)
+        assert_same_elements [@a, @b],     Treasure.within(1, f(-153, 47), 43, -1)
+      end
+      teardown { Treasure.destroy_all }
+    end
+
+    context 'SE quadrant' do
+      setup do
+        @a = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'E', :latitude_minutes => '12', :longitude_minutes => '47'
+        @b = Treasure.create :latitude_degrees => '43', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'E'
+        @c = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '154', :longitude_hemisphere => 'E'
+      end
+      should 'return locations to nearest minute' do
+        assert_same_elements [],           Treasure.within(-42, 1, -1, 153)
+        assert_same_elements [@a, @b, @c], Treasure.within(-43, 1, -1, 154)
+        assert_same_elements [@c],         Treasure.within(f(-42, 11), 1, -1, 154)
+        assert_same_elements [@a, @c],     Treasure.within(f(-42, 12), 1, -1, 154)
+        assert_same_elements [@b],         Treasure.within(-43, 1, -1, f(153, 46))
+        assert_same_elements [@a, @b],     Treasure.within(-43, 1, -1, f(153, 47))
+      end
+      teardown { Treasure.destroy_all }
+    end
+
+    context 'SW quadrant' do
+      setup do
+        @a = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'W', :latitude_minutes => '12', :longitude_minutes => '47'
+        @b = Treasure.create :latitude_degrees => '43', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'W'
+        @c = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '154', :longitude_hemisphere => 'W'
+      end
+      should 'return locations to nearest minute' do
+        assert_same_elements [],           Treasure.within(-42, -153, -1, -1)
+        assert_same_elements [@a, @b, @c], Treasure.within(-43, -154, -1, -1)
+        assert_same_elements [@c],         Treasure.within(f(-42, 11), -154, -1, -1)
+        assert_same_elements [@a, @c],     Treasure.within(f(-42, 12), -154, -1, -1)
+        assert_same_elements [@b],         Treasure.within(-43, f(-153, 46), -1, -1)
+        assert_same_elements [@a, @b],     Treasure.within(-43, f(-153, 47), -1, -1)
+      end
+      teardown { Treasure.destroy_all }
+    end
+
+    context 'straddling equator and prime meridian' do
+      setup do
+        @a = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'E', :latitude_minutes => '12', :longitude_minutes => '47'
+        @b = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'N', :longitude_degrees => '153', :longitude_hemisphere => 'W', :latitude_minutes => '12', :longitude_minutes => '47'
+        @c = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'E', :latitude_minutes => '12', :longitude_minutes => '47'
+        @d = Treasure.create :latitude_degrees => '42', :latitude_hemisphere => 'S', :longitude_degrees => '153', :longitude_hemisphere => 'W', :latitude_minutes => '12', :longitude_minutes => '47'
+      end
+      should 'return locations to nearest degree' do
+        assert_same_elements [],               Treasure.within(-42, -153, 42, 153)
+        assert_same_elements [@a, @b, @c, @d], Treasure.within(-43, -154, 43, 154)
+
+        assert_same_elements [@a, @b],         Treasure.within(f(-42, 11), -154, 43, 154)
+        assert_same_elements [@a, @b, @c, @d], Treasure.within(f(-42, 12), -154, 43, 154)
+
+        assert_same_elements [@a, @c],         Treasure.within(-43, f(-153, 46), 43, 154)
+        assert_same_elements [@a, @b, @c, @d], Treasure.within(-43, f(-153, 47), 43, 154)
+
+        assert_same_elements [@c, @d],         Treasure.within(-43, -154, f(42, 11), 154)
+        assert_same_elements [@a, @b, @c, @d], Treasure.within(-43, -154, f(42, 12), 154)
+
+        assert_same_elements [@b, @d],         Treasure.within(-43, -154, 43, f(153, 46))
+        assert_same_elements [@a, @b, @c, @d], Treasure.within(-43, -154, 43, f(153, 47))
+      end
+      teardown { Treasure.destroy_all }
+    end
+  end
+
+
+  private
+
+  # TODO: use FactoryGirl instead.
+
+  def location(params = {})
+    { :latitude_degrees          => 42,
+      :latitude_minutes          => 57,
+      :latitude_decimal_minutes  => 35,
+      :latitude_hemisphere       => 'N',
+      :longitude_degrees         => 153,
+      :longitude_minutes         => 22,
+      :longitude_decimal_minutes => 27,
+      :longitude_hemisphere      => 'E' }.merge params
+  end
+
+  # Degrees: positive or negative.
+  # Minutes: always positive.
+  def f(degrees, minutes = 0)
+    degrees >= 0 ? degrees + (minutes / 60.0) : degrees - (minutes / 60.0)
+  end
+
+end

data/test/schema.rb

@@ -0,0 +1,9 @@
+ActiveRecord::Schema.define(:version => 0) do
+  create_table :treasures, :force => true do |t|
+    t.string  :name
+    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
+end

data/test/test_helper.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+
+require 'test/unit'
+require 'shoulda'
+
+require 'active_record'
+require 'action_view'
+require 'active_support'
+require 'active_support/test_case'
+
+require 'lib/geo_tools'
+
+ActiveRecord::Base.establish_connection(
+  :adapter  => "sqlite3",
+  :database => ":memory:"
+)
+load File.dirname(__FILE__) + '/schema.rb'
+
+class ActiveSupport::TestCase
+  # FIXME: why won't this work?
+  #self.use_transactional_fixtures = true
+end

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: geo_tools
+version: !ruby/object:Gem::Version 
+  version: 1.0.1
+platform: ruby
+authors: 
+- Andy Stewart
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-16 00:00:00 +00:00
+default_executable: 
+dependencies: []
+
+description: 
+email: boss@airbladesoftware.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.md
+files: 
+- MIT-LICENSE
+- README.md
+- Rakefile
+- VERSION
+- init.rb
+- install.rb
+- lib/air_blade/geo_tools/form_helpers.rb
+- lib/air_blade/geo_tools/location.rb
+- lib/air_blade/geo_tools/validations.rb
+- lib/geo_tools.rb
+- tasks/geo_tools_tasks.rake
+- test/geo_tools_test.rb
+- test/schema.rb
+- test/test_helper.rb
+- uninstall.rb
+has_rdoc: true
+homepage: http://github.com/airblade/geo_tools
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: View helpers, validations, and named scopes for locations.
+test_files: 
+- test/geo_tools_test.rb
+- test/schema.rb
+- test/test_helper.rb