activerecord-spatial 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NzVhNGNkYTg1MTBkYTM3MGFmYjI2NTBkOTEyMzRlNDhmZDZhMTM3ZQ==
+  data.tar.gz: !binary |-
+    MmUyYzQ0ZjU3ZDllYjhjOGFhNWY3ZmU5OTY1NDRkMjk2YzY1NmFlOQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    Yjk3MzU1MTllMzdkOWM4OWI2ZGQwNjUzYWQyMzI3ZTQ4MjAzNGRjZWYyN2Vi
+    YjNkYjZlYzAwNzk3MTFkZWEzMGMwMjNmODE2ZTgzYzI1NzFlNjEzMWIzZjRh
+    NjFlY2QxMzI1MTY5MTJiMTYzMzgwNGVjZWZjMDU2NTZlNWFhZGE=
+  data.tar.gz: !binary |-
+    OGI3NjI0ZDI5M2JjOWJiOWYxZDExYTJkMTNmMzg1NDYyNjZkZjhmZjA5NmIy
+    OGM4OTIxYWYxMTExYWQ3MGZjNmJkNmY0NTEzMzM4MTZlNTc2YTRjYjBhMDlm
+    NzgxOGIxYTUxMDQ0MGRhNTBhNjE0YzE4ZGQ4ZGU3YmQxMDBlNDI=

data/.gitignore

@@ -0,0 +1,16 @@
+*.orig
+.*.swp
+.*.swo
+*.tmp
+*.patch
+*~
+.DS_Store
+Thumbs.db
+Gemfile.lock
+Gemfile.local
+Guardfile.local
+debug.log
+test/local_database.yml
+doc/
+pkg/
+coverage/

data/Gemfile

@@ -0,0 +1,21 @@
+source 'https://rubygems.org'
+
+gemspec
+
+if RUBY_PLATFORM == "java"
+  gem "activerecord-jdbcpostgresql-adapter"
+else
+  gem "pg"
+end
+
+gem "rdoc", "~> 3.12"
+gem "rake", "~> 10.0"
+gem "minitest"
+gem "minitest-reporters"
+gem "guard-minitest"
+gem "simplecov"
+
+if File.exists?('Gemfile.local')
+  instance_eval File.read('Gemfile.local')
+end
+

data/Guardfile

@@ -0,0 +1,17 @@
+
+guard 'minitest', :test_folders => 'test', :test_file_patterns => '*_tests.rb' do
+  watch(%r|^test/(.+)_tests\.rb|)
+
+  watch(%r|^lib/(.*)([^/]+)\.rb|) do |m|
+    "test/#{m[1]}#{m[2]}_tests.rb"
+  end
+
+  watch(%r|^test/test_helper\.rb|) do
+    "test"
+  end
+end
+
+if File.exists?('Guardfile.local')
+  instance_eval File.read('Guardfile.local')
+end
+

data/MIT-LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2013 2167961 Ontario Inc., Zoocasa <code@zoocasa.com>
+
+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.rdoc

@@ -0,0 +1,169 @@
+
+= ActiveRecord Spatial
+
+ActiveRecord Spatial is a collection of spatially-aware extensions that help
+ActiveRecord work the spatial tables. This gem used to be integrated with our
+geos-extensions gem available at https://github.com/zoocasa/geos-extensions but
+we have separated the two and extended ActiveRecord Spatial's capabilities
+in the process.
+
+At the moment, ActiveRecord Spatial is focused completely on PostgreSQL and
+PostGIS databases. This may change in the future, but for our purposes,
+PostGIS is our spatial database of choice and we haven't really had the need
+to use any of the alternatives such as Spatialite or the MySQL spatial
+extensions.
+
+== Features
+
+* automatic detection of geometry columns and just-in-time conversions
+  for input and output to and from WKB when using PostGIS. This allows
+  you to do stuff like this with your ActiveRecord models:
+
+    m = MyModel.find(12345)
+
+    m.the_geom
+    # => spits out the untouched geometry value as a string in WKB
+
+    m.the_geom_geos
+    # => spits out the geometry wrapped in a Geos::Geometry object
+
+    m.the_geom = 'POINT(0 0)'
+    # => setters will automatically make conversions from any of the formats
+    #    that the Geos.read can recognize, so Google Maps formats, WKT, WKB,
+    #    etc. are all converted automatically.
+
+    m.the_geom_wkt
+    # => automatically converts to a WKT string
+
+    m.the_geom_wkb_bin
+    # => automatically converts to WKB in binary
+
+  There's also some funky SRID handling code that will automatically
+  look in the geometry_columns table to make conversions for you when
+  necessary. Saving WKT as "SRID=default; POINT(0 0)" for instance will
+  automatically set the SRID when saving the ActiveRecord, or the SRID
+  can be specified manually.
+
+* multiple geometry columns are supported and detected for
+  automatically. These column accessors are all generated dynamically at
+  run time.
+
+* automatic generation of named scopes for ActiveRecord models. The
+  usual suspects are supported such as +st_contains+, +st_intersects+, etc.
+
+* ordering scopes are also included such as +order_by_st_area+,
+  +order_by_st_length+, etc.
+
+* together, the various spatial scopes let you chain together scopes to build
+  geospatial queries:
+
+    neighbourhood = Neighbourhood.find(12345)
+    my_model = MyModel.active.
+      recent.
+      st_within(neighbourhood.the_geom_geos.envelope).
+      st_dwithin(point, 0.1).
+      order_by_st_area.
+      all(
+        :limit => 10
+      )
+
+* spatial associations via the +has_many_spatially+ association method. This
+  method essentially operates like a standard +has_many+ association with
+  the added ability to define a spatial relationship with the +:relationship+
+  option rather than relying on direct equality. This allows you to set up
+  relationships like the following:
+
+    class Neighbourhood < ActiveRecord::Base
+      has_many_spatially :cities,
+        :relationship => :contains
+    end
+
+    class City < ActiveRecord::Base
+      has_many_spatially :neighbourhoods,
+        :relationship => :within
+    end
+
+    Neighbourhood.first.cities
+    #=> All cities that the neighbourhood is within
+
+    City.first.neighbourhoods
+    #=> All neighbourhoods contained by the city
+
+    City.includes(:neighbourhoods).first.neighbourhoods
+    #=> Eager loading works too
+
+
+  See the documentation for ActiveRecordSpatial::Associations for details.
+
+== Running ActiveRecord Tests
+
+The test helper attempts to install PostGIS on the test database, but in the
+event that it cannot find your PostGIS files you can either help to guide
+the PostGIS detection by setting a +POSTGIS_PATH+ environment variable that
+points to your +postgis.sql+ and +spatial_ref_sys.sql+ files.
+
+You can set up local database settings in the test/local_database.yml file.
+See the test/database.yml file for example settings.
+
+== ActiveRecord Versions Supported
+
+We're starting to standardize on Rails 3+ for our purposes, so future versions
+this gem function on versions of Rails 3 and above. To use spatial scopes on
+previous versions of ActiveRecord, see our geos-extensions gem available at
+https://github.com/zoocasa/geos-extensions . We have pulled the ActiveRecord
+extensions out of that gem and are instead packaging them here, thus allowing
+you to use the actual Geos extensions in an unfettered way. If you wish to
+use the spatial extensions with versions of Rails prior to 3, see versions of
+the geos-extensions gem prior to version 0.3.0 where the split occured.
+
+== PostGIS and PostgreSQL Versions Supported
+
+As of this writing, things look good for PostgreSQL 9.1 and 9.2 for both
+PostGIS 1.5 and 2.0. Some features are only available in PostGIS 2.0, such
+as the +st_3dintersects+ scope and the like, as that spatial relationship
+function was added in PostGIS 2.0.
+
+PostgreSQL 9.0 and below are currently not supported as some of the SQL we
+produce to create the spatial queries is not supported in older PostgreSQL
+versions.
+
+In any event, it is recommended that you use current versions of both
+PostgreSQL and PostGIS where possible.
+
+== Migrating from geos-extensions
+
+There are a few changes with ActiveRecord Spatial that aren't backwards
+compatible with older versions of geos-extensions. The migration path is
+pretty easy all the same and should only require a handful of changes for
+most projects.
+
+* The Geos::ActiveRecord module has been renamed to ActiveRecordSpatial.
+  This means you'll have to include ActiveRecordSpatial::SpatialColumns into
+  your models instead of Geos::ActiveRecord::SpatialColumns, for instance.
+
+* ActiveRecordSpatial::SpatialScopes is no longer automatically included
+  when ActiveRecordSpatial::SpatialColumns is included. This allows you to
+  optionally include SpatialScopes, as sometimes folks just don't want to use
+  our spatial scopes.
+
+* In an effort to move away from PostgreSQL/PostGIS-specifics (even if we're
+  not fully there yet), we've removed the PostgreSQLSpatialColumn class and
+  made everything use ActiveRecordSpatial::GeometryColumn and
+  ActiveRecordSpatial::GeographyColumn ActiveRecord models directly. These
+  are full-fledged ActiveRecord models now and can be accessed as such, but
+  they should be considered read-only models (and are marked as such). In
+  PostGIS 2.0+, for instance, these are both read-only views.
+
+* The pseudo constant methods for UNKNOWN_SRID and POSTGIS and such are now
+  real constants under ActiveRecordSpatial.
+
+* The +order_by_*+ scopes have all been renamed to +order_by_st_*+ to better
+  reflect that they are calling ST functions, to improve consistency with
+  the relationship scopes, and to lessen potential name clashes with other
+  existing scopes that may be named with similar conventions.
+
+== License
+
+This gem is licensed under an MIT-style license. See the +MIT-LICENSE+ file for
+details.
+

data/Rakefile

@@ -0,0 +1,28 @@
+
+# -*- ruby -*-
+
+require 'rubygems'
+require 'rubygems/package_task'
+require 'rake/testtask'
+require 'rdoc/task'
+require 'bundler/gem_tasks'
+
+$:.push File.expand_path(File.dirname(__FILE__), 'lib')
+
+version = ActiveRecordSpatial::VERSION
+
+desc 'Test ActiveRecord Spatial'
+Rake::TestTask.new(:test) do |t|
+  t.test_files = FileList['test/**/*_tests.rb']
+  t.verbose = !!ENV['VERBOSE_TESTS']
+  t.warning = !!ENV['WARNINGS']
+end
+
+desc 'Build docs'
+Rake::RDocTask.new do |t|
+  t.main = 'README.rdoc'
+  t.title = "ActiveRecord Spatial #{version}"
+  t.rdoc_dir = 'doc'
+  t.rdoc_files.include('README.rdoc', 'MIT-LICENSE', 'lib/**/*.rb')
+end
+

data/activerecord-spatial.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path('../lib/activerecord-spatial/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name = "activerecord-spatial"
+  s.version = ActiveRecordSpatial::VERSION
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["J Smith"]
+  s.description = "ActiveRecord Spatial gives AR the ability to work with PostGIS columns."
+  s.summary = s.description
+  s.email = "code@zoocasa.com"
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = `git ls-files`.split($\)
+  s.executables = s.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  s.test_files = s.files.grep(%r{^(test|spec|features)/})
+  s.homepage = "https://github.com/zoocasa/activerecord-spatial"
+  s.require_paths = ["lib"]
+
+  s.add_dependency("rails", [">= 3.2"])
+  s.add_dependency("geos-extensions", [">= 0.3.0.dev"])
+end
+

data/lib/activerecord-spatial.rb

@@ -0,0 +1,32 @@
+
+require 'geos-extensions'
+
+require 'activerecord-spatial/active_record/connection_adapters/postgresql/adapter_extensions'
+
+module ActiveRecordSpatial
+  BASE_PATH = File.dirname(__FILE__)
+
+  class << self
+    def geometry_columns?
+      ::ActiveRecord::Base.connection.geometry_columns?
+    end
+
+    def geography_columns?
+      ::ActiveRecord::Base.connection.geography_columns?
+    end
+
+    def default_column_name
+      @default_column_name ||= :the_geom
+    end
+
+    # Allows you to modify the default geometry column name for all of
+    # ActiveRecordSpatial. This is useful when you have a common column name
+    # for all of your geometry columns, such as +wkb+, +feature+, +geom+, etc.
+    def default_column_name=(column_name)
+      @default_column_name = column_name
+    end
+  end
+end
+
+require 'activerecord-spatial/active_record'
+

data/lib/activerecord-spatial/active_record.rb

@@ -0,0 +1,14 @@
+
+module ActiveRecordSpatial
+  autoload :SpatialFunction, 'activerecord-spatial/spatial_function'
+  autoload :SpatialColumns, 'activerecord-spatial/spatial_columns'
+  autoload :SpatialScopeConstants, 'activerecord-spatial/spatial_scope_constants'
+  autoload :SpatialScopes, 'activerecord-spatial/spatial_scopes'
+  autoload :SpatialColumn, 'activerecord-spatial/active_record/models/spatial_column'
+  autoload :SpatialRefSys, 'activerecord-spatial/active_record/models/spatial_ref_sys'
+  autoload :GeometryColumn, 'activerecord-spatial/active_record/models/geometry_column'
+  autoload :GeographyColumn, 'activerecord-spatial/active_record/models/geography_column'
+end
+
+require 'activerecord-spatial/associations'
+

data/lib/activerecord-spatial/active_record/connection_adapters/postgresql/adapter_extensions.rb

@@ -0,0 +1,36 @@
+
+require 'active_record/connection_adapters/postgresql_adapter'
+
+module ActiveRecord
+  module ConnectionAdapters
+    class PostgreSQLColumn
+      def simplified_type_with_spatial_type(field_type)
+        if field_type =~ /^geometry(\(|$)/
+          :geometry
+        elsif field_type =~ /^geography(\(|$)/
+          :geography
+        else
+          simplified_type_without_spatial_type(field_type)
+        end
+      end
+      alias_method_chain :simplified_type, :spatial_type
+    end
+
+    class PostgreSQLAdapter
+      def geometry_columns?
+        true
+      end
+
+      def geography_columns?
+        ActiveRecordSpatial::POSTGIS[:lib] >= '1.5'
+      end
+    end
+  end
+end
+
+module ActiveRecordSpatial
+  autoload :POSTGIS, 'activerecord-spatial/active_record/connection_adapters/postgresql/postgis'
+  autoload :UNKNOWN_SRID, 'activerecord-spatial/active_record/connection_adapters/postgresql/unknown_srid'
+  autoload :UNKNOWN_SRIDS, 'activerecord-spatial/active_record/connection_adapters/postgresql/unknown_srid'
+end
+

data/lib/activerecord-spatial/active_record/connection_adapters/postgresql/postgis.rb

@@ -0,0 +1,24 @@
+
+module ActiveRecordSpatial
+  POSTGIS = begin
+    if (version_string = ::ActiveRecord::Base.connection.select_rows("SELECT postgis_full_version()").flatten.first).present?
+      hash = {
+        :use_stats => version_string =~ /USE_STATS/
+      }
+
+      {
+        :lib => /POSTGIS="([^"]+)"/,
+        :geos => /GEOS="([^"]+)"/,
+        :proj => /PROJ="([^"]+)"/,
+        :libxml => /LIBXML="([^"]+)"/
+      }.each do |k, v|
+        hash[k] = version_string.scan(v).flatten.first
+      end
+
+      hash.freeze
+    else
+      {}.freeze
+    end
+  end
+end
+

data/lib/activerecord-spatial/active_record/connection_adapters/postgresql/unknown_srid.rb

@@ -0,0 +1,21 @@
+
+module ActiveRecordSpatial
+  UNKNOWN_SRIDS = begin
+    if ActiveRecordSpatial::POSTGIS[:lib] >= '2.0'
+      {
+        :geography => 0,
+        :geometry  => 0
+      }.freeze
+    else
+      {
+        :geography =>  0,
+        :geometry  => -1
+      }.freeze
+    end
+  end
+
+  UNKNOWN_SRID = begin
+    ActiveRecordSpatial::UNKNOWN_SRIDS[:geometry]
+  end
+end
+