docs and tests for fields option with a hash

lib/mongo/collection.rb

@@ -107,9 +107,11 @@ module Mongo
     #   a document specifying elements which must be present for a
     #   document to be included in the result set.
     #
-    # @option opts [Array] :fields field names that should be returned in the result
+    # @option opts [Array, Hash] :fields field names that should be returned in the result
     #   set ("_id" will always be included). By limiting results to a certain subset of fields,
-    #   you can cut down on network traffic and decoding time.
+    #   you can cut down on network traffic and decoding time. If using a Hash, keys should be field
+    #   names and values should be either 1 or 0, depending on whether you want to include or exclude
+    #   the given field.
     # @option opts [Integer] :skip number of documents to skip from the beginning of the result set
     # @option opts [Integer] :limit maximum number of documents to return
     # @option opts [Array]   :sort an array of [key, direction] pairs to sort by. Direction should

test/collection_test.rb

@@ -250,6 +250,25 @@ class TestCollection < Test::Unit::TestCase
     end
   end
 
+  def test_fields_as_hash
+    @@test.save(:a => 1, :b => 1, :c => 1)
+
+    doc = @@test.find_one({:a => 1}, :fields => {:b => 0})
+    assert_nil doc['b']
+    assert doc['a']
+    assert doc['c']
+
+    doc = @@test.find_one({:a => 1}, :fields => {:a => 1, :b => 1})
+    assert_nil doc['c']
+    assert doc['a']
+    assert doc['b']
+
+
+    assert_raise Mongo::OperationFailure do
+      @@test.find_one({:a => 1}, :fields => {:a => 1, :b => 0})
+    end
+  end
+
   def test_find_one
     id = @@test.save("hello" => "world", "foo" => "bar")