RUBY-443

Adds ability to declare sort ordering via an ordered hash.
If using Ruby < 1.9 BSON::OrderedHash is required.

Author: TylerBrock

lib/mongo/cursor.rb

@@ -199,21 +199,19 @@ def count(skip_and_limit = false)
     # This method overrides any sort order specified in the Collection#find
     # method, and only the last sort applied has an effect.
     #
-    # @param [Symbol, Array] key_or_list either 1) a key to sort by or 2)
-    #   an array of [key, direction] pairs to sort by. Direction should
-    #   be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
+    # @param [Symbol, Array] key_or_list either 1) a key to sort by 2)
+    #   an array of [key, direction] pairs to sort by or 3) a hash of
+    #   field => direction pairs to sort by. Direction should be specified as 
+    #   Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING
+    #   (or :descending / :desc)
     #
     # @raise [InvalidOperation] if this cursor has already been used.
     #
     # @raise [InvalidSortValueError] if the specified order is invalid.
-    def sort(key_or_list, direction=nil)
+    def sort(order, direction=nil)
       check_modifiable
 
-      if !direction.nil?
-        order = [[key_or_list, direction]]
-      else
-        order = key_or_list
-      end
+      order = [[order, direction]] unless direction.nil?
 
       @order = order
       self

lib/mongo/util/conversions.rb

@@ -24,6 +24,29 @@ module Conversions
     ASCENDING_CONVERSION  = ["ascending", "asc", "1"]
     DESCENDING_CONVERSION = ["descending", "desc", "-1"]
 
+    # Allows sort parameters to be defined as a Hash.
+    # Does not allow usage of un-ordered hashes, therefore
+    # Ruby 1.8.x users must use BSON::OrderedHash.
+    #
+    # Example:
+    #
+    # <tt>hash_as_sort_parameters({:field1 => :asc, "field2" => :desc})</tt> =>
+    # <tt>{ "field1" => 1, "field2" => -1}</tt>
+    def hash_as_sort_parameters(value)
+      if RUBY_VERSION < '1.9' && !value.is_a?(BSON::OrderedHash)
+        raise InvalidSortValueError.new(
+          "Hashes used to supply sort order must maintain ordering." +
+          "Use BSON::OrderedHash."
+        )
+      else
+        order_by = value.inject({}) do |memo, (key, direction)|
+          memo[key.to_s] = sort_value(direction.to_s.downcase)
+          memo
+        end
+      end
+      order_by
+    end
+
     # Converts the supplied +Array+ to a +Hash+ to pass to mongo as
     # sorting parameters. The returned +Hash+ will vary depending 
     # on whether the passed +Array+ is one or two dimensional.

lib/mongo/util/support.rb

@@ -69,6 +69,7 @@ def validate_read_preference(value)
 
     def format_order_clause(order)
       case order
+        when Hash, BSON::OrderedHash then hash_as_sort_parameters(order)
         when String, Symbol then string_as_sort_parameters(order)
         when Array then array_as_sort_parameters(order)
         else

test/db_api_test.rb

@@ -183,13 +183,67 @@ def test_find_sorting
     # Sorting using empty array; no order guarantee should not blow up.
     docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => []).to_a
     assert_equal 4, docs.size
+  end
 
+  def test_find_sorting_with_hash
     # Sorting using ordered hash. You can use an unordered one, but then the
     # order of the keys won't be guaranteed thus your sort won't make sense.
+
+    @@coll.remove
+    @@coll.insert('a' => 1, 'b' => 2)
+    @@coll.insert('a' => 2, 'b' => 1)
+    @@coll.insert('a' => 3, 'b' => 2)
+    @@coll.insert('a' => 4, 'b' => 1)
+    
     oh = BSON::OrderedHash.new
     oh['a'] = -1
-    assert_raise InvalidSortValueError do 
-      docs = @@coll.find({'a' => { '$lt' => 10 }}, :sort => oh).to_a
+
+    # Sort as a method
+    docs = @@coll.find.sort(oh).to_a
+    assert_equal 4, docs.size
+    assert_equal 4, docs[0]['a']
+    assert_equal 3, docs[1]['a']
+    assert_equal 2, docs[2]['a']
+    assert_equal 1, docs[3]['a']
+
+    # Sort as an option
+    docs = @@coll.find({}, :sort => oh).to_a
+    assert_equal 4, docs.size
+    assert_equal 4, docs[0]['a']
+    assert_equal 3, docs[1]['a']
+    assert_equal 2, docs[2]['a']
+    assert_equal 1, docs[3]['a']
+
+    if RUBY_VERSION > '1.9'
+      docs = @@coll.find({}, :sort => {:a => -1}).to_a
+      assert_equal 4, docs.size
+      assert_equal 4, docs[0]['a']
+      assert_equal 3, docs[1]['a']
+      assert_equal 2, docs[2]['a']
+      assert_equal 1, docs[3]['a']
+
+      docs = @@coll.find.sort(:a => -1).to_a
+      assert_equal 4, docs.size
+      assert_equal 4, docs[0]['a']
+      assert_equal 3, docs[1]['a']
+      assert_equal 2, docs[2]['a']
+      assert_equal 1, docs[3]['a']
+
+      docs = @@coll.find.sort(:b => -1, :a => 1).to_a
+      assert_equal 4, docs.size
+      assert_equal 1, docs[0]['a']
+      assert_equal 3, docs[1]['a']
+      assert_equal 2, docs[2]['a']
+      assert_equal 4, docs[3]['a']
+    else
+      # Sort as an option
+      assert_raise InvalidSortValueError do
+        @@coll.find({}, :sort => {:a => -1}).to_a
+      end
+      # Sort as a method
+      assert_raise InvalidSortValueError do
+        @@coll.find.sort(:a => -1).to_a
+      end
     end
   end