rs_spatial_adapter 1.2.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+Copyright (c) 2010 Pete Deffendol <pete@fragility.us>
+
+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,197 @@
+= Spatial Adapter for ActiveRecord
+
+This is the Spatial Adapter for ActiveRecord.  It enhances ActiveRecord to
+handle spatial datatypes in the following databases:
+
+- PostgreSQL (using PostGIS)
+- MySQL (using Spatial Extensions)
+
+== Dependencies
+
+The following gems are required:
+
+- GeoRuby
+- ActiveRecord (version 2.2.2 and up)
+
+For PostgreSQL:
+
+- PostGIS version 1.4.0 or higher should be installed in your database
+ 
+== Installation
+
+Choose ONE of the following installation methods.  You shouldn't have to do both.
+
+=== From RubyGems
+
+This is the preferred method of installation, and will pull in the required
+dependencies as well.
+
+  gem install spatial_adapter
+  
+In a Rails 2.x app, you can add a gem dependency in environment.rb:
+
+  config.gem 'spatial_adapter'
+  
+In a Rails 3 app, add a gem dependency to Gemfile:
+
+  gem 'spatial_adapter'
+  
+=== As a Rails Plugin
+
+In your Rails project, run the following:
+
+script/plugin install git://github.com/fragility/spatial_adapter.git
+
+You need to have Git installed first.
+
+== Configuration
+
+Choose the database type for which you would like to use spatial_adapter, and
+load each with
+
+  require 'spatial_adapter/[database]'
+  
+where [database] should be replaced with one of the following:
+
+- postgresql
+- mysql
+  
+For example to use the PostgreSQL spatial adapter:
+
+  require 'spatial_adapter/postgresql'
+  
+In a Rails app, spatial_adapter will automatically load the adapter for the database
+specified in your database.yml configuration.
+
+== Operations
+
+Geometric columns in your ActiveRecord models now appear just like any other
+column of other basic data types. They can also be dumped in ruby schema mode
+and loaded in migrations the same way as columns of basic types.
+
+=== Migrations
+
+Here is an example of code for the creation of a table with a geometric column
+in PostGIS, along with the addition of a spatial index on the column:
+ 
+  ActiveRecord::Schema.define do
+    create_table :table_points, :force => true do |t|
+      t.string :data
+      t.point :geom, :null => false, :srid => 123, :with_z => true
+    end
+  
+    add_index :table_points, :geom, :spatial => true
+  end
+
+Here is a related statement valid for MySql version <= 5.0.16:
+
+  ActiveRecord::Schema.define do
+    create_table "table_points", ;options=>"ENGINE=MyISAM", :force => true do |t|
+      t.string :data
+      t.point :geom, :null => false
+    end
+  
+    add_index :table_points, :geom, :spatial => true
+  end
+  
+=== Differences Between Databases
+
+- On all versions of MySQL, the :srid, :with_z, and :with_m options are ignored, since
+  they are not supported. 
+  
+- On MySQL versions <= 5.0.16, you have to add <tt>:options =>
+  "ENGINE=MyISAM"</tt> to the create_table statement, since only MyISAM tables
+  can have spatial columns.  In addition, only MyISAM tables may have spatial
+  indexes.
+
+=== Models
+
+Create your ActiveRecord models normally.  Spatial Adapter will automatically
+handle spatial columns, converting them to the appropriate GeoRuby type.
+
+  class TablePoint < ActiveRecord::Base
+  end
+
+=== Access
+
+Here is an example of row creation and access, using the model and the table
+defined above:
+
+  pt = TablePoint.new(
+    :data => "Hello!", 
+    :geom => Point.from_x_y_z(-1.6, 2.8, -3.4, 123))
+  pt.save
+  pt = TablePoint.find_first
+  puts pt.geom.x #access the geom column like any other
+
+=== Fixtures
+
+If you use fixtures for your unit tests, at some point, you will want to input
+a geometry. You could transform your geometries to a form suitable for YAML
+yourself every time but Spatial Adapter provides a method to do it for you:
++to_fixture_format+. You would use it like this, if the geometric column is a
+point:
+
+  fixture:
+    id: 1
+    data: HELLO
+    geom: <%= Point.from_x_y(123.5,321.9).to_fixture_format %>
+
+=== Finder Enhancements
+
+Enhancements to find_by_* and friends has been removed from this version of
+Spatial Adapter until a cleaner implementation can be made.  (The previous
+implementation made adapter-specific modifications to ActiveRecord::Base,
+which prevented multiple adapters from being loaded at once.)
+
+=== Geometric data types
+
+Ruby geometric datatypes are currently made available only through the GeoRuby
+library (http://georuby.rubyforge.org/): This is where the
+<tt>Point.from_x_y</tt> in the example above comes from.
+
+== Warning
+
+- Since ActiveRecord seems to keep only the string values directly returned
+  from the database, it translates from these to the correct types everytime
+  an attribute is read, which is probably ok for simple types, but might be
+  less than efficient for geometries, since the EWKB string has to be parsed
+  everytime. Also it means you cannot modify the geometry object returned from
+  an attribute directly:
+
+    place = Place.find_first
+    place.the_geom.y=123456.7 # this doesn't work
+ 
+  Since the translation to a geometry is performed every time the_geom is read,
+  the change to y will not be saved! You would have to do something like this:
+
+    place = Place.find_first
+    the_geom = place.the_geom
+    the_geom.y=123456.7
+    place.the_geom = the_geom
+
+== License
+
+The Spatial Adapter for ActiveRecord is released under the MIT license.
+
+== Latest Changes
+
+Spatial Adapter has been refactored and is now available as a Ruby gem. The
+dependency on Rails has been removed. Unfortunately, the current version is
+without some of the previous functionality, until a cleaner implementation is
+made.
+
+The previous release is available on the "legacy" branch.
+
+=== Removed Features in 0.2.0
+
+- Compatibility with ActiveRecord/Rails older than version 2.2.2
+- enhancements to find_by_* for spatial columns
+- to_fixture_format extension to the GeoRuby types
+
+These will hopefully be added back in the near future.
+
+== Support
+
+Any questions, enhancement proposals, bug notifications or corrections can be
+made via the project page at http://github.com/fragility/spatial_adapter

data/VERSION

@@ -0,0 +1 @@
+1.2.0

data/lib/spatial_adapter.rb

@@ -0,0 +1,41 @@
+# This file should typically not be directly require'd into your project. You
+# should require the database-specific adapter you desire, e.g.
+#
+#   require 'spatial_adapter/postgresql'
+#
+# Why is this file here?
+#
+# Mostly to keep Rails happy when using config.gem to specify dependencies.
+# The Rails init code (rails/init.rb) will then load the adapter that matches
+# your database.yml configuration.
+
+require 'geo_ruby'
+require 'active_record'
+
+include GeoRuby::SimpleFeatures
+
+module SpatialAdapter
+  # Translation of geometric data types
+  def geometry_data_types
+    {
+      :point => { :name => "POINT" },
+      :line_string => { :name => "LINESTRING" },
+      :polygon => { :name => "POLYGON" },
+      :geometry_collection => { :name => "GEOMETRYCOLLECTION" },
+      :multi_point => { :name => "MULTIPOINT" },
+      :multi_line_string => { :name => "MULTILINESTRING" },
+      :multi_polygon => { :name => "MULTIPOLYGON" },
+      :geometry => { :name => "GEOMETRY"}
+    }
+  end
+  
+  class NotCompatibleError < ::StandardError
+  end
+end
+
+require 'spatial_adapter/common/raw_geom_info'
+require 'spatial_adapter/common/spatial_column'
+require 'spatial_adapter/common/schema_definitions'
+require 'spatial_adapter/common/schema_dumper'
+require 'spatial_adapter/common/table_definition'
+require 'spatial_adapter/railtie' if defined?(Rails::Railtie)

data/lib/spatial_adapter/common/raw_geom_info.rb

@@ -0,0 +1,23 @@
+module SpatialAdapter
+  class RawGeomInfo < Struct.new(:type,:srid,:dimension,:with_z,:with_m) #:nodoc:
+    def convert!
+      self.type = "geometry" if self.type.nil? #if geometry the geometrytype constraint is not present : need to set the type here then
+    
+      if dimension == 4
+        self.with_m = true
+        self.with_z = true
+      elsif dimension == 3
+        if with_m
+          self.with_z = false
+          self.with_m = true 
+        else
+          self.with_z = true
+          self.with_m = false
+        end
+      else
+        self.with_z = false
+        self.with_m = false
+      end
+    end
+  end
+end

data/lib/spatial_adapter/common/schema_definitions.rb

@@ -0,0 +1,11 @@
+require 'active_record/connection_adapters/abstract_adapter'
+
+ActiveRecord::ConnectionAdapters::IndexDefinition.class_eval do
+  attr_accessor :spatial
+
+  alias_method :initialize_without_spatial, :initialize
+  def initialize(table, name, unique, columns, spatial = false)
+    initialize_without_spatial(table, name, unique, columns)
+    @spatial = spatial
+  end
+end

data/lib/spatial_adapter/common/schema_dumper.rb

@@ -0,0 +1,136 @@
+ActiveRecord::SchemaDumper.ignore_tables << "spatial_ref_sys" << "geometry_columns"
+
+ActiveRecord::SchemaDumper.class_eval do
+  # These are the valid options for a column specification (spatial options added)
+  VALID_COLUMN_SPEC_KEYS = [:name, :limit, :precision, :scale, :default, :null, :srid, :with_z, :with_m, :geographic]
+  
+  def table(table, stream)
+    columns = @connection.columns(table)
+    begin
+      tbl = StringIO.new
+
+      # first dump primary key column
+      if @connection.respond_to?(:pk_and_sequence_for)
+        pk, pk_seq = @connection.pk_and_sequence_for(table)
+      elsif @connection.respond_to?(:primary_key)
+        pk = @connection.primary_key(table)
+      end
+      
+      tbl.print "  create_table #{table.inspect}"
+      if columns.detect { |c| c.name == pk }
+        if pk != 'id'
+          tbl.print %Q(, :primary_key => "#{pk}")
+        end
+      else
+        tbl.print ", :id => false"
+      end
+      
+      # Added by Spatial Adapter to ensure correct MySQL table engine
+      if @connection.respond_to?(:options_for)
+        res = @connection.options_for(table)
+        tbl.print ", :options=>'#{res}'" if res
+      end
+      
+      tbl.print ", :force => true"
+      tbl.puts " do |t|"
+
+      # then dump all non-primary key columns
+      column_specs = columns.map do |column|
+        raise StandardError, "Unknown type '#{column.sql_type}' for column '#{column.name}'" if @types[column.type].nil?
+        next if column.name == pk
+        spec = column_spec(column)
+        (spec.keys - [:name, :type]).each{ |k| spec[k].insert(0, "#{k.inspect} => ")}
+        spec
+      end.compact
+
+      # find all migration keys used in this table
+      keys = VALID_COLUMN_SPEC_KEYS & column_specs.map(&:keys).flatten
+
+      # figure out the lengths for each column based on above keys
+      lengths = keys.map{ |key| column_specs.map{ |spec| spec[key] ? spec[key].length + 2 : 0 }.max }
+
+      # the string we're going to sprintf our values against, with standardized column widths
+      format_string = lengths.map{ |len| "%-#{len}s" }
+
+      # find the max length for the 'type' column, which is special
+      type_length = column_specs.map{ |column| column[:type].length }.max
+
+      # add column type definition to our format string
+      format_string.unshift "    t.%-#{type_length}s "
+
+      format_string *= ''
+
+      column_specs.each do |colspec|
+        values = keys.zip(lengths).map{ |key, len| colspec.key?(key) ? colspec[key] + ", " : " " * len }
+        values.unshift colspec[:type]
+        tbl.print((format_string % values).gsub(/,\s*$/, ''))
+        tbl.puts
+      end
+
+      tbl.puts "  end"
+      tbl.puts
+      
+      indexes(table, tbl)
+
+      tbl.rewind
+      stream.print tbl.read
+    rescue => e
+      stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
+      stream.puts "#   #{e.message}"
+      stream.puts
+    end
+    
+    stream
+  end
+  
+
+  def indexes(table, stream)
+    if (indexes = @connection.indexes(table)).any?
+      add_index_statements = indexes.map do |index|
+        statment_parts = [ ('add_index ' + index.table.inspect) ]
+        statment_parts << index.columns.inspect
+        statment_parts << (':name => ' + index.name.inspect)
+        statment_parts << ':unique => true' if index.unique
+        # Add spatial option (this is the only change from the original method)
+        statment_parts << ':spatial => true' if index.spatial
+
+        '  ' + statment_parts.join(', ')
+      end
+
+      stream.puts add_index_statements.sort.join("\n")
+      stream.puts
+    end
+  end
+  
+  private
+  
+  # Build specification for a table column
+  def column_spec(column)
+    spec = {}
+    spec[:name]      = column.name.inspect
+    
+    # AR has an optimisation which handles zero-scale decimals as integers.  This
+    # code ensures that the dumper still dumps the column as a decimal.
+    spec[:type]      = if column.type == :integer && [/^numeric/, /^decimal/].any? { |e| e.match(column.sql_type) }
+                         'decimal'
+                       else
+                         column.type.to_s
+                       end
+    spec[:limit]     = column.limit.inspect if column.limit != @types[column.type][:limit] && spec[:type] != 'decimal'
+    spec[:precision] = column.precision.inspect if !column.precision.nil?
+    spec[:scale]     = column.scale.inspect if !column.scale.nil?
+    spec[:null]      = 'false' if !column.null
+    spec[:default]   = default_string(column.default) if column.has_default?
+    
+    # Additions for spatial columns
+    if column.is_a?(SpatialColumn)
+      # Override with specific geometry type
+      spec[:type]    = column.geometry_type.to_s
+      spec[:srid]    = column.srid.inspect if column.srid != -1
+      spec[:with_z]  = 'true' if column.with_z
+      spec[:with_m]  = 'true' if column.with_m
+      spec[:geographic] = 'true' if column.geographic?
+    end
+    spec
+  end
+end

data/lib/spatial_adapter/common/spatial_column.rb

@@ -0,0 +1,70 @@
+module SpatialAdapter
+  module SpatialColumn
+    attr_reader  :geometry_type, :srid, :with_z, :with_m
+
+    def initialize(name, default, sql_type = nil, null = true, srid=-1, with_z=false, with_m=false)
+      super(name, default, sql_type, null)
+      @geometry_type = geometry_simplified_type(@sql_type)
+      @srid = srid
+      @with_z = with_z
+      @with_m = with_m
+    end
+  
+    def spatial?
+      !@geometry_type.nil?
+    end
+    
+    def geographic?
+      false
+    end
+
+    # Redefines type_cast to add support for geometries
+    # alias_method :type_cast_without_spatial, :type_cast
+    def type_cast(value)
+      return nil if value.nil?
+      spatial? ? self.class.string_to_geometry(value) : super
+    end
+
+    #Redefines type_cast_code to add support for geometries. 
+    #
+    #WARNING : Since ActiveRecord keeps only the string values directly returned from the database, it translates from these to the correct types everytime an attribute is read (using the code returned by this method), which is probably ok for simple types, but might be less than efficient for geometries. Also you cannot modify the geometry object returned directly or your change will not be saved. 
+    # alias_method :type_cast_code_without_spatial, :type_cast_code
+    def type_cast_code(var_name)
+      spatial? ? "#{self.class.name}.string_to_geometry(#{var_name})" : super
+    end
+
+
+    #Redefines klass to add support for geometries
+    # alias_method :klass_without_spatial, :klass
+    def klass
+      spatial? ? GeoRuby::SimpleFeatures::Geometry : super
+    end
+
+    private
+
+    # Maps additional data types to base Rails/Arel types
+    #
+    # For Rails 3, only the types defined by Arel can be used.  We'll
+    # use :string since the database returns the columns as hex strings.
+    def simplified_type(field_type)
+      case field_type
+      when /geography|geometry|point|linestring|polygon|multipoint|multilinestring|multipolygon|geometrycollection/i then :string
+      else super
+      end
+    end
+
+    # less simlpified geometric type to be use in migrations
+    def geometry_simplified_type(sql_type)
+      case sql_type
+      when /^point$/i then :point
+      when /^linestring$/i then :line_string
+      when /^polygon$/i then :polygon
+      when /^geometry$/i then :geometry
+      when /multipoint/i then :multi_point
+      when /multilinestring/i then :multi_line_string
+      when /multipolygon/i then :multi_polygon
+      when /geometrycollection/i then :geometry_collection
+      end
+    end
+  end
+end