From 7648bf10e7779141e848bd4857004c78ebf9170c Mon Sep 17 00:00:00 2001
From: Kristian Mandrup <kmandrup@gmail.com>
Date: Tue, 14 Jun 2011 19:54:18 +0200
Subject: [PATCH] README added usage example - aimed for API

---
 README.textile                                | 53 +++++++++++++++++++
 .../extensions/inflections/within_box_spec.rb | 24 ++++-----
 .../inflections/within_center_spec.rb         | 12 ++---
 3 files changed, 71 insertions(+), 18 deletions(-)

diff --git a/README.textile b/README.textile
index 54ea1cf..905b4f5 100644
--- a/README.textile
+++ b/README.textile
@@ -21,6 +21,59 @@ Specs are currently being reworked to align with the new simplified design.
 - Creation of Mpongo query hashes for Twin- and NestedOperators have been extracted into Query classes (see mongoid/geo/queries folder)
 - #geo_near now uses configuration from Mongoid::Geo::Config, such as the #distance_calculator (if Mongo server doesn't support this) and the #radians_multiplier etc.
 
+h2. Example Usage 1.0.beta (goal)
+
+<pre>
+class Address
+  field :location, :type => Array, :geo => true
+end
+
+my_home = Address.new :location => {:lat => 10, :lng => 12}.to_lng_lat
+my_job = Address.new :location => [10.2, "12.1"].to_lng_lat
+my_club = Address.new :location => [10.2, 12.1]
+my_club.location_lat == 12.1 # true
+my_club.location_lng == 10.2 # true
+
+nearest_locations = Address.geo_near my_club
+nearest_locations.first.
+
+# find near point, max distance
+Address.where :location.near_max => [{:latitude => 10, :longitude => 12 }, 5] # 5 km?
+Address.where :location.near_max => [my_club, 5]
+
+Address.where(:location.within_box => [my_job, my_club])
+Address.where(:location.within_center(:sphere) => [my_home, 5])
+
+# geo_point integration (using GeoPoint class)
+
+Mongoid::Geo::Config.enable_extension! :geo_point
+
+p1 = "58 38 38N, 003 04 12W".geo_point # DMS format support!
+my_home = Address.new :location => p1.to_lng_lat
+
+# a GeoPoint includes some nice geo calculation methods, that are calculated relative to itself !
+p1.bearing_to my_club.geo_point # => 60 deg ?
+p1.distance_to my_home.geo_point # => 2341 kms ?
+
+# geo_vectors integration
+
+Mongoid::Geo::Config.enable_extension! :geo_vectors
+
+my_home = Address.new :location => p1.to_lng_lat
+my_home.add [2, 4].vector # add lng/lat vector
+my_home.add [20, 4.km].vector # add vector of 4km at 20 degrees
+
+</pre>
+
+h2. Example Usage 1.0 (goal)
+
+# Here I would like some kind of location repository key/value storage and allow use/integration of unit distances (see gem 'geo_magic' fx)
+
+<pre>
+Address.where(:location.within_box => [:my_job, :my_club]) # each point should be looked up in the repo using the symbol as key  
+Address.where :location.near_max => [:my_home, 5000.meters] # use geo_magic distance here!
+</pre>
+
 h2. Intro
 
 This is a Geo extension for Mongoid 2.
diff --git a/spec/mongoid/extensions/inflections/within_box_spec.rb b/spec/mongoid/extensions/inflections/within_box_spec.rb
index 756c61a..cefb85e 100644
--- a/spec/mongoid/extensions/inflections/within_box_spec.rb
+++ b/spec/mongoid/extensions/inflections/within_box_spec.rb
@@ -1,12 +1,12 @@
 require "mongoid/spec_helper"
 
 describe Mongoid::Extensions::Symbol::Inflections do
-  describe "#withinBox" do  
+  describe "#within_box" do  
     let(:point_a) { [ 72, -44 ] }
     let(:point_b) { [ 71, -45 ] }      
     
     let(:criteria) do
-      base.where(:location.withinBox => [point_a, point_b])
+      base.where(:location.within_box => [point_a, point_b])
     end
   
     it "adds the $near and $maxDistance modifiers to the selector" do
@@ -15,14 +15,14 @@
     end
   end  
 
-  describe "#withinBox, one hash point" do  
+  describe "#within_box, one hash point" do  
     let(:point_a) do 
       {:lat => 72, :lng => -44 }
     end
     let(:point_b) { [ 71, -45 ] }      
     
     let(:criteria) do
-      base.where(:location.withinBox => [point_a, point_b])
+      base.where(:location.within_box => [point_a, point_b])
     end
   
     it "adds the $near and $maxDistance modifiers to the selector" do
@@ -32,7 +32,7 @@
   end  
 
 
-  describe "#withinBox hash box" do  
+  describe "#within_box hash box" do  
     let(:point_a) { [ 72, -44 ] }
     let(:point_b) { [ 71, -45 ] }      
     let(:box) do
@@ -40,7 +40,7 @@
     end
     
     let(:criteria) do
-      base.where(:location.withinBox => box)
+      base.where(:location.within_box => box)
     end
   
     it "adds the $near and $maxDistance modifiers to the selector" do
@@ -49,7 +49,7 @@
     end
   end  
 
-  describe "#withinBox Struct box" do  
+  describe "#within_box Struct box" do  
     let(:point_a) { [ 72, -44 ] }
     let(:point_b) { [ 71, -45 ] }      
     let(:box) do
@@ -60,7 +60,7 @@
     end
     
     let(:criteria) do
-      base.where(:location.withinBox => box)
+      base.where(:location.within_box => box)
     end
   
     it "adds the $near and $maxDistance modifiers to the selector" do
@@ -69,12 +69,12 @@
     end
   end  
 
-  describe "#withinBox sphere" do  
+  describe "#within_box sphere" do  
     let(:point_a) { [ 72, -44 ] }
     let(:point_b) { [ 71, -45 ] }      
     
     let(:criteria) do
-      base.where(:location.withinBox(:sphere) => [point_a, point_b])
+      base.where(:location.within_box(:sphere) => [point_a, point_b])
     end
   
     it "adds the $near and $maxDistance modifiers to the selector" do
@@ -83,7 +83,7 @@
     end
   end
   
-  describe "#withinBox Struct circle" do  
+  describe "#within_box Struct circle" do  
     let(:center) { [ 71, -45 ] }      
     let(:box) do
       b = (Struct.new :center, :radius).new
@@ -93,7 +93,7 @@
     end
     
     let(:criteria) do
-      base.where(:location.withinCenter => [[ 72, -44 ], 5])
+      base.where(:location.within_center => [[ 72, -44 ], 5])
     end
   
     it "adds the $within and $center modifiers to the selector" do
diff --git a/spec/mongoid/extensions/inflections/within_center_spec.rb b/spec/mongoid/extensions/inflections/within_center_spec.rb
index d81b769..f55a654 100644
--- a/spec/mongoid/extensions/inflections/within_center_spec.rb
+++ b/spec/mongoid/extensions/inflections/within_center_spec.rb
@@ -1,9 +1,9 @@
 require "mongoid/spec_helper"
 
 describe Mongoid::Extensions::Symbol::Inflections do  
-  describe "#withinCenter" do  
+  describe "#within_center" do  
     let(:criteria) do
-      base.where(:location.withinCenter => [[ 72, -44 ], 5])
+      base.where(:location.within_center => [[ 72, -44 ], 5])
     end
   
     it "adds the $within and $center modifiers to the selector" do
@@ -12,14 +12,14 @@
     end
   end  
 
-  describe "#withinCenter hash circle" do  
+  describe "#within_center hash circle" do  
     let(:center) { [ 72, -44 ] }
     let(:circle) do
       {:center => center, :radius => 5}
     end
     
     let(:criteria) do
-      base.where(:location.withinCenter => circle)
+      base.where(:location.within_center => circle)
     end
   
     it "adds the $within and $center modifiers to the selector" do
@@ -28,9 +28,9 @@
     end
   end 
   
-  describe "#withinCenter sphere" do  
+  describe "#within_center sphere" do  
     let(:criteria) do
-      base.where(:location.withinCenter(:sphere) => [[ 72, -44 ], 5])
+      base.where(:location.within_center(:sphere) => [[ 72, -44 ], 5])
     end
   
     it "adds the $within and $center modifiers to the selector" do