drifter-rails 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in drifter-rails.gemspec
+gemspec

data/README

@@ -0,0 +1,72 @@
+== drifter-rails
+
+drifter-rails is a simple gem that provides distance calculations and queries
+for ActiveRecord.  It currently supports postgresql and mysql on rails 3.
+
+=== Installation
+
+  # in Gemfile
+  config.gem 'drifter-rails'
+
+  # optionally, in config/intiailizers/drifter.rb, one of these:
+  Drifter.default_units = :miles
+  Drifter.default_units = :km
+
+  # in your model
+  class Place < ActiveRecord::Base
+    acts_as_drifter
+  end
+
+=== Usage
+
+To return a calculated 'distance' value along with your queries:
+
+  >> origin = [52.123, -2.5432]
+  >> results = Place.near(origin)
+  >> results.first.distance
+  => 12.33228393
+
+origin can be a two item [lat,lng] array, any acts_as_drifter object or any object that
+responds to lat() and lng().
+
+To return objects within a specific distance of a point of origin:
+
+  >> origin = [52.123, -2.5432]
+  >> Place.near(origin, :within => 10)
+  >> Place.near(origin, :within => 10, :units => :km)
+  => "#<ActiveRecord::Relation:0xafb1e18>"
+
+The near() method returns an ActiveRecord::Relation that you can use the same as any
+other scope, including ordering by distance:
+
+  >> Place.near(origin, :within => 10).includes(:visitors).order("distance ASC")
+  => "#<ActiveRecord::Relation:0xafb1e18>"
+
+Each acts_as_drifter object also gets a distance_to() method that can calculate the
+distance to another location:
+
+  >> place = Place.first
+  >> place.distance_to(other_place)
+  >> place.distance_to( [10.321, -5.432] )
+  >> place.distance_to( [10.321, -5.432], :units => :km )
+
+The location() and location=() methods provide a shortcut for setting lat() and lng():
+
+  >> place = Place.new
+  >> place.location = [2.222, 3.333]
+
+  >> place.lat
+  => 2.222
+  >> place.lng
+  => 3.333
+
+Finally, you can use custom names for the lat and lng columns:
+  
+  class Place < ActiveRecord::Base
+    acts_as_drifter :lat_column => :latitude, :lng_column => :longitude
+  end
+
+
+=== License
+
+MIT License. Copyright 2011 Ahmed Adam (http://github.com/ahmedrb)

data/README.rdoc

@@ -0,0 +1,72 @@
+== drifter-rails
+
+drifter-rails is a simple gem that provides distance calculations and queries
+for ActiveRecord.  It currently supports postgresql and mysql on rails 3.
+
+=== Installation
+
+  # in Gemfile
+  config.gem 'drifter-rails'
+
+  # optionally, in config/intiailizers/drifter.rb, one of these:
+  Drifter.default_units = :miles
+  Drifter.default_units = :km
+
+  # in your model
+  class Place < ActiveRecord::Base
+    acts_as_drifter
+  end
+
+=== Usage
+
+To return a calculated 'distance' value along with your queries:
+
+  >> origin = [52.123, -2.5432]
+  >> results = Place.near(origin)
+  >> results.first.distance
+  => 12.33228393
+
+origin can be a two item [lat,lng] array, any acts_as_drifter object or any object that
+responds to lat() and lng().
+
+To return objects within a specific distance of a point of origin:
+
+  >> origin = [52.123, -2.5432]
+  >> Place.near(origin, :within => 10)
+  >> Place.near(origin, :within => 10, :units => :km)
+  => "#<ActiveRecord::Relation:0xafb1e18>"
+
+The near() method returns an ActiveRecord::Relation that you can use the same as any
+other scope, including ordering by distance:
+
+  >> Place.near(origin, :within => 10).includes(:visitors).order("distance ASC")
+  => "#<ActiveRecord::Relation:0xafb1e18>"
+
+Each acts_as_drifter object also gets a distance_to() method that can calculate the
+distance to another location:
+
+  >> place = Place.first
+  >> place.distance_to(other_place)
+  >> place.distance_to( [10.321, -5.432] )
+  >> place.distance_to( [10.321, -5.432], :units => :km )
+
+The location() and location=() methods provide a shortcut for setting lat() and lng():
+
+  >> place = Place.new
+  >> place.location = [2.222, 3.333]
+
+  >> place.lat
+  => 2.222
+  >> place.lng
+  => 3.333
+
+Finally, you can use custom names for the lat and lng columns:
+  
+  class Place < ActiveRecord::Base
+    acts_as_drifter :lat_column => :latitude, :lng_column => :longitude
+  end
+
+
+=== License
+
+MIT License. Copyright 2011 Ahmed Adam (http://github.com/ahmedrb)

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake/testtask'
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+
+def run_tests(name)
+  task_name = "test_#{name}"
+  Rake::TestTask.new(task_name) do |t|
+    t.test_files = FileList['test/*_test.rb']
+    t.verbose = true
+  end
+  Rake::Task[task_name].invoke
+end
+
+
+namespace :test do
+
+  desc "Run tests using the mysql adapater"
+  task :mysql do
+    puts "\nRunning test using mysql\n\n"
+    ENV['DB'] = 'mysql'
+    run_tests :mysql
+  end
+
+  desc "Run tests using the postgresql adapater"
+  task :postgresql do
+    puts "\nRunning test using postgresql\n\n"
+    ENV['DB'] = 'postgresql'
+    run_tests :postgresql
+  end
+
+  desc "Run tests using each db adapter in succession"
+  task :all do
+    Rake::Task["test:mysql"].invoke
+    Rake::Task["test:postgresql"].invoke
+  end
+
+end

data/drifter-rails.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "drifter-rails/version"
+
+Gem::Specification.new do |s|
+  s.name        = "drifter-rails"
+  s.version     = Drifter::Rails::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Ahmed Adam"]
+  s.homepage    = "http://github.com/ahmedrb/drifter-rails"
+  s.summary     = %q{Distance queries for ActiveRecord 3}
+
+  s.rubyforge_project = "drifter-rails"
+
+  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_dependency 'drifter', '0.1.0'
+  s.add_dependency 'activerecord', '~> 3.0.0'
+
+  s.add_development_dependency 'mysql'
+  s.add_development_dependency 'pg'
+  s.add_development_dependency 'ruby-debug'
+  s.add_development_dependency 'yaml'
+end

data/lib/drifter-rails.rb

@@ -0,0 +1,27 @@
+require 'active_record'
+require 'drifter'
+require 'drifter-rails/class_methods'
+require 'drifter-rails/instance_methods'
+
+module Drifter
+  module Rails
+
+    # supported_options:
+    #   :lat_column - the name of the column holding latitude values (default is lat)
+    #   :lng_column - the name of the column holding longitude values (default is lng)
+    def acts_as_drifter(options={})
+      # determine the names of the lat and lng columns
+      lat_col = options[:lat_column] || :lat
+      lng_col = options[:lng_column] || :lng
+
+      eval("def self.lat_column_name; :#{lat_col}; end")
+      eval("def self.lng_column_name; :#{lng_col}; end")
+
+      extend Drifter::Rails::ClassMethods
+      include Drifter::Rails::InstanceMethods
+    end
+
+
+  end
+end
+ActiveRecord::Base.send :extend, Drifter::Rails

data/lib/drifter-rails/class_methods.rb

@@ -0,0 +1,49 @@
+module Drifter
+  module Rails
+    module ClassMethods
+
+      # used by InstanceMethods to determine if lat/lng accessors need to be defined
+      def has_method?(name)
+        return true if column_names.include?(name.to_s)
+        return true if instance_methods.include?(name.to_s)
+        return false
+      end
+
+
+      # nodoc
+      def near(origin, options={})
+        options[:origin] = origin
+        options[:lat_column] = lat_column_name
+        options[:lng_column] = lng_column_name
+
+        adapter = self.connection.class.to_s.split('::').last
+        method_name = case adapter
+          when 'PostgreSQLAdapter' then :to_postgresql
+          when 'MysqlAdapter' then :to_mysql
+          else raise ArgumentError, "#{adapter} is not supported by drifter-rails"
+        end
+
+        distance_sql = Drifter::Distance::Haversine.send(method_name, options)
+        sql = "#{table_name}.*, (#{distance_sql}) AS distance"
+
+        scope = select(sql)
+        scope = add_conditions_for_within(scope, options, distance_sql)
+        return scope
+      end
+
+
+      private
+
+
+      # TODO: 'distance' column not visible to the where clause (postgres and mysql)
+      # so the calculation has to be repeated in the where clause. Can that be fixed?
+      def add_conditions_for_within(scope, options, distance_sql)
+        max_distance = options[:within].to_i
+        return scope unless max_distance > 0
+        return scope.where("(#{distance_sql}) < #{max_distance}")
+      end
+
+
+    end
+  end
+end

data/lib/drifter-rails/instance_methods.rb

@@ -0,0 +1,47 @@
+module Drifter
+  module Rails
+    module InstanceMethods
+
+      # nodoc
+      def self.included(base)
+        base.send :include, Drifter::Location::Locatable
+        base.send :include, LatAccessors unless base.has_method?(:lat)
+        base.send :include, LngAccessors unless base.has_method?(:lng)
+      end
+
+
+      # nodoc
+      module LatAccessors
+
+        # nodoc
+        def lat
+          self.send self.class.lat_column_name
+        end
+
+        # nodoc
+        def lat=(value)
+          writer = "#{self.class.lat_column_name}="
+          self.send writer, value
+        end
+      end
+
+
+      # nodoc
+      module LngAccessors
+
+        # nodoc
+        def lng
+          self.send self.class.lng_column_name
+        end
+
+        # nodoc
+        def lng=(value)
+          writer = "#{self.class.lng_column_name}="
+          self.send writer, value
+        end
+      end
+
+
+    end
+  end
+end

data/lib/drifter-rails/version.rb

@@ -0,0 +1,5 @@
+module Drifter
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/test/acts_as_drifter_test.rb

@@ -0,0 +1,34 @@
+require File.dirname(__FILE__) + '/test_helper'
+class ActsAsDrifterTest < Test::Unit::TestCase
+
+
+  def test_lat_column_id_method
+    Place.send :acts_as_drifter
+    assert_equal :lat, Place.lat_column_name
+  end
+
+  def test_lat_lng_accessors_with_default_column_names
+    Place.send :acts_as_drifter
+    i = Place.new :lat => 1, :lng => 2
+    assert_equal 1, i.lat
+    assert_equal 2, i.lng
+
+    i.lat= 10
+    i.lng= 20
+    assert_equal 10, i.lat
+    assert_equal 20, i.lng
+  end
+
+  def test_lat_lng_accessors_with_custom_column_names
+    Store.send :acts_as_drifter, :lat_column => :latitude, :lng_column => :longitude
+    i = Store.new :latitude => 1, :longitude => 2
+    assert_equal 1, i.lat
+    assert_equal 2, i.lng
+
+    i.lat= 10
+    i.lng= 20
+    assert_equal 10, i.latitude
+    assert_equal 20, i.longitude
+  end
+
+end

data/test/database.yml

@@ -0,0 +1,12 @@
+:postgresql:
+  :adapter: postgresql
+  :name: drifter_rails_test
+  :username: developer
+  :password: password
+
+:mysql:
+  :adapter: mysql
+  :name: drifter_rails_test
+  :username: developer
+  :password: password
+

data/test/near_test.rb

@@ -0,0 +1,75 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+# TODO: better fixtures
+class NearTest < Test::Unit::TestCase
+
+  # request places in ascending/descending order and checks that the order is correct
+  # TODO: this is tied very closely to the fixtures, too brittle
+  def check_order(order, klass)
+    order_by = "distance ASC"
+    origin = [53.57, -2.4333] # nr bolton
+    expected = ["Bolton", "Manchester", "Chester", "Nottingham", "London"]
+
+    if order == :desc
+      order_by = "distance DESC"
+      expected.reverse!
+    end
+
+    results = klass.near(origin).order(order_by)
+    names = results.collect { |p| p.name }
+    assert_equal expected, names
+
+    # check the distances too
+    distances = results.collect { |p| p.distance.to_f }
+    expected = distances.sort
+    expected = distances.sort.reverse if order == :desc
+    assert_equal expected, distances
+  end
+
+
+  # check the 'distance' column isn't dropped
+  def test_distance_attribute_with_includes_option
+    Place.send :acts_as_drifter
+    origin = [53.5, -2.4]
+    place = Place.near(origin).first
+
+    assert_not_nil place.distance
+    assert place.distance.to_f > 1
+
+    other = Place.near(origin).includes(:visitors).first
+    assert_equal place.distance, other.distance
+  end
+
+
+  def test_order_by_distance_using_default_column_names
+    Place.send :acts_as_drifter
+    check_order :asc, Place
+    check_order :desc, Place
+  end
+
+
+  def test_order_by_distance_using_custom_column_names
+    Store.send :acts_as_drifter, :lat_column => :latitude, :lng_column => :longitude
+    check_order :asc, Store
+    check_order :desc, Store
+  end
+
+
+  def test_near_plus_within_using_default_column_names
+    Place.send :acts_as_drifter
+    origin = [53.57, -2.4333] # nr bolton
+    results = Place.near(origin, :within => 50)
+    assert results.count == 3 
+    results.each { |r| assert r.distance.to_f <= 50 }
+  end
+
+
+  def test_near_plus_within_using_custom_column_names
+    Store.send :acts_as_drifter, :lat_column => :latitude, :lng_column => :longitude
+    origin = [53.57, -2.4333] # nr bolton
+    results = Store.near(origin, :within => 50)
+    assert results.count == 3 
+    results.each { |r| assert r.distance.to_f <= 50 }
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,120 @@
+# these library's will be loaded when the drifter-rails gem is loaded
+require 'rubygems'
+require 'active_record'
+require 'drifter'
+require 'pg'
+require 'yaml'
+
+# these are for testing only
+require 'ruby-debug'
+require 'test/unit'
+
+
+# AR::Base classes used for the tests, this one has lat, lng columns
+class Place < ActiveRecord::Base
+  has_many :visitors
+end
+
+# same as Place but with latitude and longitude columns
+class Store < ActiveRecord::Base
+  has_many :visitors
+end
+
+class Visitor < ActiveRecord::Base
+  belongs_to :place
+  belongs_to :visitor
+end
+
+
+# this migration is used to prepare the database for tests
+class PrepareDB < ActiveRecord::Migration
+
+  def self.up
+
+    drop_table :places if ActiveRecord::Base.connection.tables.include?("places")
+    drop_table :stores if ActiveRecord::Base.connection.tables.include?("stores")
+    drop_table :visitors if ActiveRecord::Base.connection.tables.include?("visitors")
+
+    create_table :places do |t|
+      t.string  :name
+      t.decimal :lat, :precision => 16, :scale => 12
+      t.decimal :lng, :precision => 16, :scale => 12
+    end
+    create_table :stores do |t|
+      t.string :name
+      t.decimal :latitude, :precision => 16, :scale => 12
+      t.decimal :longitude, :precision => 16, :scale => 12
+    end
+    create_table :visitors do |t|
+      t.integer :place_id
+      t.integer :store_id
+      t.string :name
+    end
+  end
+
+end
+
+
+# connects the given class to the given database. Connections params should be defined in database.yml
+def connect_to(db)
+  data = YAML.load_file(File.dirname(__FILE__) + '/database.yml')
+  db = data[db]
+  ActiveRecord::Base.remove_connection if ActiveRecord::Base.connected?
+  ActiveRecord::Base.establish_connection(
+    :adapter => db[:adapter],
+    :database => db[:name],
+    :username => db[:username],
+    :password => db[:password]
+  )
+end
+
+def places_attributes(lat=:lat, lng =:lng)
+  attrs = [
+    { :name => "Bolton", lat => 53.57845, lng => -2.426664 },
+    { :name => "Chester", lat => 53.18813, lng => -2.894369 },
+    { :name => "Manchester", lat => 53.417439, lng => -2.23156 },
+    { :name => "Nottingham", lat => 52.951199, lng => -1.13087 },
+    { :name => "London", lat => 51.5001524, lng => -0.1262362 }
+  ]
+end
+
+def add_places(attrs=false)
+  Place.delete_all
+  Place.create! places_attributes
+end
+
+def add_stores
+  attrs = places_attributes(:latitude, :longitude)
+  Store.delete_all
+  Store.create! attrs
+end
+
+def add_visitors
+  places = Place.all
+  stores = Store.all
+  %W(john mike jane emma paul).each do |name|
+    place_id = places[rand(places.size)].id
+    store_id = stores[rand(stores.size)].id
+    Visitor.create! :name => name, :place_id => place_id, :store_id => store_id
+  end
+end
+
+# the first time this file is loaded it connects to a db and runs the migration
+# specify the db using the DB environment variable ['mysql', 'postgresql']
+unless ActiveRecord::Base.connected?
+  db = ENV['DB'] || :postgresql
+  connect_to db.to_s.intern
+  PrepareDB.verbose = false
+  puts "Running migrations..."
+  PrepareDB.migrate :up
+  add_places
+  add_stores
+  add_visitors
+end
+
+# this will be set when loaded as a gem. Only needed for tests
+$LOAD_PATH << File.expand_path('../../lib/', __FILE__)
+
+# acts_as_drifter queries column names so this has to come after the connection
+# is established
+require 'drifter-rails'

metadata

@@ -0,0 +1,167 @@
+--- !ruby/object:Gem::Specification 
+name: drifter-rails
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ahmed Adam
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-22 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: drifter
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mysql
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: pg
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: yaml
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: 
+email: 
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README
+- README.rdoc
+- Rakefile
+- drifter-rails.gemspec
+- lib/drifter-rails.rb
+- lib/drifter-rails/class_methods.rb
+- lib/drifter-rails/instance_methods.rb
+- lib/drifter-rails/version.rb
+- test/acts_as_drifter_test.rb
+- test/database.yml
+- test/near_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/ahmedrb/drifter-rails
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: drifter-rails
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Distance queries for ActiveRecord 3
+test_files: []
+