mongoid-geospatial 5.0.0 → 7.0.0

data/README.md

@@ -1,244 +1,227 @@
-Mongoid Geospatial
-==================
-
+# Mongoid Geospatial
 
 A Mongoid Extension that simplifies the use of MongoDB spatial features.
 
-* Version 5.x -> Mongoid 5
-* Version 4.x -> Mongoid 4
-
-** Gem name has changed: 'mongoid-geospatial' (notice the hyphen) **
-Please change the underscore to a hyphen.
-That will require it correctly within bundler:
-`require 'mongoid/geospatial'`
-
 [![Gem Version](https://badge.fury.io/rb/mongoid-geospatial.svg)](http://badge.fury.io/rb/mongoid-geospatial)
-[![Code Climate](https://codeclimate.com/github/nofxx/mongoid-geospatial.svg)](https://codeclimate.com/github/nofxx/mongoid-geospatial)
-[![Coverage Status](https://coveralls.io/repos/nofxx/mongoid-geospatial/badge.svg?branch=master)](https://coveralls.io/r/nofxx/mongoid-geospatial?branch=master)
-[![Dependency Status](https://gemnasium.com/nofxx/mongoid-geospatial.svg)](https://gemnasium.com/nofxx/mongoid-geospatial)
-[![Build Status](https://travis-ci.org/nofxx/mongoid-geospatial.svg?branch=master)](https://travis-ci.org/nofxx/mongoid-geospatial)
+[![Code Climate](https://codeclimate.com/github/mongoid/mongoid-geospatial.svg)](https://codeclimate.com/github/mongoid/mongoid-geospatial)
+[![Coverage Status](https://coveralls.io/repos/github/mongoid/mongoid-geospatial/badge.svg?branch=master)](https://coveralls.io/github/mongoid/mongoid-geospatial?branch=master)
+[![Build Status](https://travis-ci.org/mongoid/mongoid-geospatial.svg?branch=master)](https://travis-ci.org/mongoid/mongoid-geospatial)
 
+## Quick Start
 
-Quick Start
------------
-
-This gem focus on (making helpers for) MongoDB's spatial features.
-But you may also use an external Geometric/Spatial gem alongside.
-
-    # Gemfile
-    gem 'mongoid-geospatial'
+This gem focuses on (making helpers for) MongoDB's spatial features using Mongoid 5, 6 and 7.
 
+```ruby
+# Gemfile
+gem 'mongoid-geospatial'
+```
 
 A `Place` to illustrate `Point`, `Line` and `Polygon`
 
-    class Place
-      include Mongoid::Document
+```ruby
+class Place
+  include Mongoid::Document
 
-      # Include the module
-      include Mongoid::Geospatial
+  # Include the module
+  include Mongoid::Geospatial
 
-      # Just like mongoid,
-      field :name,     type: String
+  # Just like mongoid,
+  field :name,     type: String
 
-      # define your field, but choose a geometry type:
-      field :location, type: Point
-      field :route,    type: Linestring
-      field :area,     type: Polygon
-
-      # To query on your points, don't forget to index:
-      # You may use a method:
-      sphere_index :location  # 2d
-      # or
-      spatial_index :location # 2dsphere
-
-      # Or use a helper directly on the `field`:
-      field :location, type: Point, spatial: true  # 2d
-      # or
-      field :location, type: Point, sphere: true   # 2dsphere
-    end
+  # define your field, but choose a geometry type:
+  field :location, type: Point
+  field :route,    type: LineString
+  field :area,     type: Polygon
 
+  # To query on your points, don't forget to index:
+  # You may use a method:
+  sphere_index :location  # 2dsphere
+  # or
+  spatial_index :location # 2d
 
+  # Or use a helper directly on the `field`:
+  field :location, type: Point, spatial: true  # 2d
+  # or
+  field :location, type: Point, sphere: true   # 2dsphere
+end
+```
 
 Generate indexes on MongoDB via rake:
 
-
-    rake db:mongoid:create_indexes
-
+```
+rake db:mongoid:create_indexes
+```
 
 Or programatically:
 
+```ruby
+Place.create_indexes
+```
 
-    Place.create_indexes
-
+## Points
 
+This gem defines a specific `Point` class under the Mongoid::Geospatial namespace. Make sure to use `type: ::Mongoid::Geospatial::Point` to avoid name errors or collisions with other `Point` classes you might already have defined `NameError`s.
 
-Points
-------
+Currently, MongoDB supports query operations on 2D points only, so that's what this lib does. All geometries apart from points are just arrays in the database. Here's is how you can input a point as:
 
-Currently, MongoDB supports query operations on 2D points only, so that's
-what this lib does. All geometries apart from points are just arrays
-in the database. Here's is how you can input a point as:
+- longitude latitude array in that order - [long,lat] ([x, y])
+- an unordered hash with latitude key(:lat, :latitude) and a longitude key(:lon, :long, :lng, :longitude)
+- an ordered hash with longitude as the first item and latitude as the second item; this hash does not have include the latitude and longitude keys
+- anything with the a method #to_xy or #to_lng_lat that converts itself to [long, lat] array
 
-* longitude latitude array in that order - [long,lat] ([x, y])
-* an unordered hash with latitude key(:lat, :latitude) and a longitude key(:lon, :long, :lng, :longitude)
-* an ordered hash with longitude as the first item and latitude as the second item
-  This hash does not have include the latitude and longitude keys
-  \*only works in ruby 1.9 and up because hashes below ruby 1.9 because they are not ordered
-* anything with the a method #to_xy or #to_lng_lat that converts itself to  [long, lat] array
+_Note: the convention of having longitude as the first coordinate may vary for other libraries. For instance, Google Maps often refer to "LatLng". Make sure you keep those differences in mind. See below for how to configure this library for LatLng._
 
 We store data in the DB as a [x, y] array then reformat when it is returned to you
 
-
-    cafe = Place.create(
-      name: 'Café Rider',
-      location: {:lat => 44.106667, :lng => -73.935833},
-      # or
-      location: {latitude: 40.703056, longitude: -74.026667}
-      #...
+```ruby
+cafe = Place.create(
+  name: 'Café Rider',
+  location: {:lat => 44.106667, :lng => -73.935833},
+  # or
+  location: {latitude: 40.703056, longitude: -74.026667}
+  #...
+```
 
 Now to access this spatial information we can do this
 
-    cafe.location  # => [-74.026667, 40.703056]
+```ruby
+cafe.location  # => [-74.026667, 40.703056]
+```
 
 If you need a hash
 
-    cafe.location.to_hsh   # => { x: -74.026667, y: 40.703056 }
+```ruby
+cafe.location.to_hsh   # => { x: -74.026667, y: 40.703056 }
+```
 
 If you are using GeoRuby or RGeo
 
-    cafe.location.to_geo   # => GeoRuby::Point
-
-    cafe.location.to_rgeo  # => RGeo::Point
+```ruby
+cafe.location.to_geo   # => GeoRuby::Point
 
+cafe.location.to_rgeo  # => RGeo::Point
+```
 
 Conventions:
 
 This lib uses #x and #y everywhere.
 It's shorter than lat or lng or another variation that also confuses.
-A point is a 2D mathematical notation, longitude/latitude is when you
-use that notation to map an sphere. In other words:
-All longitudes are 'xs' where not all 'xs' are longitudes.
+A point is a 2D mathematical notation, longitude/latitude is when you use that notation to map an sphere. In other words: all longitudes are 'xs' where not all 'xs' are longitudes.
 
-Distance and other geometrical calculations are delegated to the external
-library of your choice. More info about using RGeo or GeoRuby below.
-Some built in helpers for mongoid queries:
+Distance and other geometrical calculations are delegated to the external library of your choice. More info about using RGeo or GeoRuby below. Some built in helpers for mongoid queries:
 
-    # Returns middle point + radius
-    # Useful to search #within_circle
-    cafe.location.radius(5)        # [[-74.., 40..], 5]
-    cafe.location.radius_sphere(5) # [[-74.., 40..], 0.00048..]
-
-    # Returns hash if needed
-    cafe.location.to_hsh              # {:x => -74.., :y => 40..}
-    cafe.location.to_hsh(:lon, :lat)  # {:lon => -74.., :lat => 40..}
+```ruby
+# Returns middle point + radius
+# Useful to search #within_circle
+cafe.location.radius(5)        # [[-74.., 40..], 5]
+cafe.location.radius_sphere(5) # [[-74.., 40..], 0.00048..]
 
+# Returns hash if needed
+cafe.location.to_hsh              # {:x => -74.., :y => 40..}
+cafe.location.to_hsh(:lon, :lat)  # {:lon => -74.., :lat => 40..}
+```
 
 And for polygons and lines:
 
-    house.area.bbox    # Returns polygon bounding_box (envelope)
-    house.area.center  # Returns calculate middle point
-
-
-
-
+```ruby
+house.area.bbox    # Returns polygon bounding_box (envelope)
+house.area.center  # Returns calculate middle point
+```
 
-Model Setup
------------
+## Model Setup
 
 You can create Point, Line, Circle, Box and Polygon on your models:
 
+```ruby
+class CrazyGeom
+  include Mongoid::Document
+  include Mongoid::Geospatial
 
-    class CrazyGeom
-      include Mongoid::Document
-      include Mongoid::Geospatial
-
-      field :location,  type: Point, spatial: true, delegate: true
-
-      field :route,     type: Line
-      field :area,      type: Polygon
+  field :location,  type: Point, spatial: true, delegate: true
 
-      field :square,    type: Box
-      field :around,    type: Circle
+  field :route,     type: Line
+  field :area,      type: Polygon
 
-      # default mongodb options
-      spatial_index :location, {bit: 24, min: -180, max: 180}
+  field :square,    type: Box
+  field :around,    type: Circle
 
-      # query by location
-      spatial_scope :location
-    end
+  # default mongodb options
+  spatial_index :location, {bit: 24, min: -180, max: 180}
 
+  # query by location
+  spatial_scope :location
+end
+```
 
-Helpers
--------
+## Helpers
 
 You can use `spatial: true` to add a '2d' index automatically,
 No need for `spatial_index :location`:
 
+```ruby
+field :location,  type: Point, spatial: true
+```
 
-    field :location,  type: Point, spatial: true
-
-
-And you can use `sphere: true` to add a '2dsphere' index automatically,
-No need for `spatial_sphere :location`:
-
-
-    field :location,  type: Point, sphere: true
+And you can use `sphere: true` to add a '2dsphere' index automatically, no need for `spatial_sphere :location`:
 
+```ruby
+field :location,  type: Point, sphere: true
+```
 
 You can delegate some point methods to the instance itself:
 
-
-    field :location,  type: Point, delegate: true
-
+```ruby
+field :location,  type: Point, delegate: true
+```
 
 Now instead of `instance.location.x` you may call `instance.x`.
 
-
-Nearby
-------
+## Nearby
 
 You can add a `spatial_scope` on your models. So you can query:
 
-    Bar.nearby(my.location)
+```ruby
+Bar.nearby(my.location)
+```
 
 instead of
 
-    Bar.near(location: my.location)
+```ruby
+Bar.near(location: my.location)
+```
 
 Good when you're drunk. Just add to your model:
 
-    spatial_scope :<field>
-
-
+```ruby
+spatial_scope :<field>
+```
 
-Geometry
---------
+## Geometry
 
 You can also store Circle, Box, Line (LineString) and Polygons.
 Some helper methods are available to them:
 
+```ruby
+# Returns a geometry bounding box
+# Useful to query #within_geometry
+polygon.bbox
+polygon.bounding_box
 
-    # Returns a geometry bounding box
-    # Useful to query #within_geometry
-    polygon.bbox
-    polygon.bounding_box
-
-    # Returns a geometry calculated middle point
-    # Useful to query for #near
-    polygon.center
-
-    # Returns middle point + radius
-    # Useful to search #within_circle
-    polygon.radius(5)        # [[1.0, 1.0], 5]
-    polygon.radius_sphere(5) # [[1.0, 1.0], 0.00048..]
+# Returns a geometry calculated middle point
+# Useful to query for #near
+polygon.center
 
+# Returns middle point + radius
+# Useful to search #within_circle
+polygon.radius(5)        # [[1.0, 1.0], 5]
+polygon.radius_sphere(5) # [[1.0, 1.0], 0.00048..]
+```
 
-Query
------
+## Query
 
-Before you read about this gem have sure you read this:
+Before you proceed, make sure you have read this:
 
-http://mongoid.org/en/origin/docs/selection.html#standard
+http://mongoid.github.io/old/en/origin/docs/selection.html#standard
 
 All MongoDB queries are handled by Mongoid/Origin.
 
@@ -246,80 +229,75 @@ http://www.rubydoc.info/github/mongoid/origin/Origin/Selectable
 
 You can use Geometry instance directly on any query:
 
-* near
-
+- near
 
-```
+```ruby
 Bar.near(location: person.house)
 Bar.where(:location.near => person.house)
 ```
 
-* near_sphere
+- near_sphere
 
-```
+```ruby
 Bar.near_sphere(location: person.house)
 Bar.where(:location.near_sphere => person.house)
 ```
 
-* within_polygon
+- within_polygon
 
-```
+```ruby
 Bar.within_polygon(location: [[[x,y],...[x,y]]])
 # or with a bbox
 Bar.within_polygon(location: street.bbox)
 ```
 
+- intersects_line
+- intersects_point
+- intersects_polygon
 
-* intersects_line
-* intersects_point
-* intersects_polygon
-
-
-
-External Libraries
-------------------
+## External Libraries
 
 We currently support GeoRuby and RGeo.
 If you require one of those, a #to_geo and #to_rgeo, respectivelly,
 method(s) will be available to all spatial fields, returning the
 external library corresponding object.
 
-
 ### Use RGeo?
+
 https://github.com/dazuma/rgeo
 
 RGeo is a Ruby wrapper for Proj/GEOS.
 It's perfect when you need to work with complex calculations and projections.
 It'll require more stuff installed to compile/work.
 
-
 ### Use GeoRuby?
+
 https://github.com/nofxx/georuby
 
 GeoRuby is a pure Ruby Geometry Library.
 It's perfect if you want simple calculations and/or keep your stack in pure ruby.
 Albeit not full featured in maths it has a handful of methods and good import/export helpers.
 
-
 ### Example
 
-    class Person
-      include Mongoid::Document
-      include Mongoid::Geospatial
+```ruby
+class Person
+  include Mongoid::Document
+  include Mongoid::Geospatial
 
-      field :location, type: Point
-    end
+  field :location, type: Point
+end
 
-    me = Person.new(location: [8, 8])
+me = Person.new(location: [8, 8])
 
-    # Example with GeoRuby
-    point.class # Mongoid::Geospatial::Point
-    point.to_geo.class # GeoRuby::SimpleFeatures::Point
-
-    # Example with RGeo
-    point.class # Mongoid::Geospatial::Point
-    point.to_rgeo.class # RGeo::Geographic::SphericalPointImpl
+# Example with GeoRuby
+point.class # Mongoid::Geospatial::Point
+point.to_geo.class # GeoRuby::SimpleFeatures::Point
 
+# Example with RGeo
+point.class # Mongoid::Geospatial::Point
+point.to_rgeo.class # RGeo::Geographic::SphericalPointImpl
+```
 
 ## Configure
 
@@ -327,70 +305,82 @@ Assemble it as you need (use a initializer file):
 
 With RGeo
 
-    Mongoid::Geospatial.with_rgeo!
-    # Optional
-    # Mongoid::Geospatial.factory = RGeo::Geographic.spherical_factory
-
+```ruby
+Mongoid::Geospatial.with_rgeo!
+# Optional
+# Mongoid::Geospatial.factory = RGeo::Geographic.spherical_factory
+```
 
 With GeoRuby
 
-    Mongoid::Geospatial.with_georuby!
-
-
-Defaults (change if you know what you're doing)
+```ruby
+Mongoid::Geospatial.with_georuby!
+```
 
-    Mongoid::Geospatial.lng_symbol = :x
-    Mongoid::Geospatial.lat_symbol = :y
-    Mongoid::Geospatial.earth_radius = EARTH_RADIUS
+By default the convention of this library is LngLat, configure it for LatLng as follows.
 
+```ruby
+Mongoid::Geospatial.configure do |config|
+  config.point.x = Mongoid::Geospatial.lat_symbols
+  config.point.y = Mongoid::Geospatial.lng_symbols
+end
+```
 
+You will need to manually migrate any existing `Point` data if you change configuration in an existing system.
 
-This Fork
----------
+## This Fork
 
 This fork is not backwards compatible with 'mongoid_spacial'.
 This fork delegates calculations to external libs.
 
 Change in your models:
 
-    include Mongoid::Spacial::Document
+```ruby
+include Mongoid::Spacial::Document
+```
 
 to
 
-    include Mongoid::Geospatial
-
+```ruby
+include Mongoid::Geospatial
+```
 
 And for the fields:
 
-
-    field :source,  type: Array,    spacial: true
+```ruby
+field :source,  type: Array,    spacial: true
+```
 
 to
 
-    field :source,  type: Point,    spatial: true # or sphere: true
-
+```ruby
+field :source,  type: Point,    spatial: true # or sphere: true
+```
 
 Beware the 't' and 'c' issue. It's spaTial.
 
-
-
-Troubleshooting
----------------
+## Troubleshooting
 
 **Mongo::OperationFailure: can't find special index: 2d**
 
 Indexes need to be created. Execute command:
 
-    rake db:mongoid:create_indexes
+```
+rake db:mongoid:create_indexes
+```
 
 Programatically
 
-    Model.create_indexes
+```
+Model.create_indexes
+```
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md).
 
+## License
 
-Contributing
-------------
+Copyright (c) 2009-2017 Mongoid Geospatial Authors
 
-* Have mongod running
-* Install dev gems with `bundle install`
-* Run `rake spec`, `spec spec` or `guard`
+MIT License, see [MIT-LICENSE](MIT-LICENSE).

data/RELEASING.md

@@ -0,0 +1,62 @@
+Releasing Mongoid::Geospatial
+=============================
+
+There're no particular rules about when to release mongoid-geospatial. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+bundle exec rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/mongoid/mongoid-geospatial) for all supported platforms.
+
+Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+
+```
+### 0.4.0 (2014-01-27)
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/mongoid/geospatial/version.rb
+git commit -m "Preparing for release, 0.4.0."
+git push origin master
+```
+
+Release.
+
+```
+$ rake release
+
+mongoid-geospatial 0.4.0 built to pkg/mongoid-geospatial-0.4.0.gem.
+Tagged v0.4.0.
+Pushed git commits and tags.
+Pushed mongoid-geospatial 0.4.0 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+### 0.4.1 (Next)
+
+* Your contribution here.
+```
+
+Increment the minor version, modify [lib/mongoid/geospatial/version.rb](lib/mongoid/geospatial/version.rb).
+
+Commit your changes.
+
+```
+git add CHANGELOG.md lib/mongoid/geospatial/version.rb
+git commit -m "Preparing for next developer iteration, 0.4.1."
+git push origin master
+```

data/Rakefile

@@ -12,6 +12,9 @@ RSpec::Core::RakeTask.new(:rcov) do |spec|
   spec.rcov = true
 end
 
-task default: :spec
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new(:rubocop)
+
+task default: %i[rubocop spec]
 
 require 'yard'

data/lib/mongoid/geospatial/config/point.rb

@@ -0,0 +1,19 @@
+module Mongoid
+  module Geospatial
+    module Config
+      module Point
+        extend self
+
+        attr_accessor :x
+        attr_accessor :y
+
+        def reset!
+          self.x = Mongoid::Geospatial.lng_symbols
+          self.y = Mongoid::Geospatial.lat_symbols
+        end
+
+        reset!
+      end
+    end
+  end
+end