mongo 0.0.3 → 0.0.4

data/README.rdoc

@@ -49,6 +49,21 @@ be running, of course.
 See also the test code, especially tests/test_db_api.rb.
 
 
+= Notes
+
+== String Encoding
+
+The BSON ("Binary JSON") format used to communicate with Mongo requires that
+strings be UTF-8 (http://en.wikipedia.org/wiki/UTF-8).
+
+Ruby 1.9 has built-in character encoding support. All strings sent to Mongo
+and received from Mongo are converted to UTF-8 when necessary, and strings
+read from Mongo will have their character encodings set to UTF-8.
+
+When used with Ruby 1.8, the bytes in each string are written to and read from
+Mongo as-is. If the string is ASCII all is well, because ASCII is a subset of
+UTF-8. If the string is not ASCII then it may not be a well-formed UTF-8 string.
+
 = Testing
 
 If you have the source code, you can run the tests.

data/Rakefile

@@ -7,7 +7,7 @@ require 'rake/gempackagetask'
 require 'rake/contrib/rubyforgepublisher'
 
 GEM = "mongo"
-GEM_VERSION = '0.0.3'
+GEM_VERSION = '0.0.4'
 SUMMARY = 'Simple pure-Ruby driver for the 10gen Mongo DB'
 DESCRIPTION = 'This is a simple pure-Ruby driver for the 10gen Mongo DB. For more information about Mongo, see http://www.mongodb.org.'
 AUTHOR = 'Jim Menard'

data/lib/mongo.rb

@@ -1,8 +1,10 @@
+require 'mongo/types/binary'
+require 'mongo/types/dbref'
+require 'mongo/types/objectid'
+require 'mongo/types/regexp_of_holding'
+require 'mongo/types/undefined'
+
 require 'mongo/mongo'
-require 'mongo/objectid'
-require 'mongo/dbref'
-require 'mongo/binary'
-require 'mongo/undefined'
 require 'mongo/message'
 require 'mongo/db'
 require 'mongo/cursor'

data/lib/mongo/admin.rb

@@ -66,7 +66,7 @@ module XGen
         # Return an array contining current profiling information from the
         # database.
         def profiling_info
-          @db.query(DB::SYSTEM_PROFILE_COLLECTION, Query.new({})).to_a
+          @db.query(Collection.new(@db, DB::SYSTEM_PROFILE_COLLECTION), Query.new({})).to_a
         end
 
         # Validate a named collection by raising an exception if there is a

data/lib/mongo/collection.rb

@@ -23,13 +23,22 @@ module XGen
       # A named collection of records in a database.
       class Collection
 
-        attr_reader :db, :name
+        attr_reader :db, :name, :hint_fields
 
         def initialize(db, name)
           @db = db
           @name = name
         end
 
+        # Set hint fields to use and return +self+. hint_fields may be a
+        # single field name or array of field names. May be +nil+. If no hint
+        # fields are specified, the ones in the collection are used if they
+        # exist.
+        def hint(hint_fields)
+          @hint_fileds = hint_fileds
+          self
+        end
+
         # Return records that match a +selector+ hash. See Mongo docs for
         # details.
         #
@@ -47,7 +56,7 @@ module XGen
           limit = options.delete(:limit) || 0
           sort = options.delete(:sort)
           raise RuntimeError, "Unknown options [#{options.inspect}]" unless options.empty?
-          @db.query(@name, Query.new(selector, fields, offset, limit, sort))
+          @db.query(self, Query.new(selector, fields, offset, limit, sort))
         end
 
         # Insert +objects+, which are hashes. "<<" is aliased to this method.

data/lib/mongo/cursor.rb

@@ -29,12 +29,26 @@ module XGen
 
         RESPONSE_HEADER_SIZE = 20
 
-        def initialize(db, collection, num_to_return=0)
-          @db, @collection, @num_to_return = db, collection, num_to_return
+        attr_reader :db, :collection, :query
+
+        def initialize(db, collection, query)
+          @db, @collection, @query = db, collection, query
+          @num_to_return = @query.number_to_return || 0
           @cache = []
           @closed = false
           @can_call_to_a = true
-          read_all
+          @query_run = false
+        end
+
+        def closed?; @closed; end
+
+        # Set hint fields to use and return +self+. hint_fields may be a
+        # single field name or array of field names. May be +nil+. If no hint
+        # fields are specified, the ones in the collection are used if they
+        # exist.
+        def hint(hint_fields)
+          @hint_fields = hint_fields
+          self
         end
 
         # Return +true+ if there are more records to retrieve. We do not check
@@ -100,9 +114,20 @@ module XGen
           @rows
         end
 
+        # Returns an explain plan record.
+        def explain
+          sel = OrderedHash.new
+          sel['query'] = @query.selector
+          sel['$explain'] = true
+          c = Cursor.new(@db, @collection, Query.new(sel))
+          e = c.next_object
+          c.close
+          e
+        end
+
         # Close the cursor.
         def close
-          @db.send_to_db(KillCursorMessage(@cursor_id)) if @cursor_id
+          @db.send_to_db(KillCursorsMessage.new(@cursor_id)) if @cursor_id
           @cache = []
           @cursor_id = 0
           @closed = true
@@ -146,6 +171,7 @@ module XGen
         private
 
         def next_object_on_wire
+          send_query_if_needed
           # if @n_remaining is 0 but we have a non-zero cursor, there are more
           # to fetch, so do a GetMore operation, but don't do it here - do it
           # when someone pulls an object out of the cache and it's empty
@@ -154,8 +180,9 @@ module XGen
         end
 
         def refill_via_get_more
+          send_query_if_needed
           return if @cursor_id == 0
-          @db.send_to_db(GetMoreMessage.new(@db.name, @collection, @cursor_id))
+          @db.send_to_db(GetMoreMessage.new(@db.name, @collection.name, @cursor_id))
           read_all
         end
 
@@ -170,6 +197,27 @@ module XGen
           BSON.new(@db).deserialize(buf)
         end
 
+        def send_query_if_needed
+          # Run query first time we request an object from the wire
+          unless @query_run
+            hints = @hint_fields || @collection.hint_fields
+            hints = [hints] if hints.kind_of?(String)
+            query = if hints
+                      h = {}
+                      hints.each { |field| h[field] = 1 }
+                      sel = OrderedHash.new
+                      sel['query'] = @query.selector
+                      sel['$hint'] = h
+                      Query.new(sel)
+                    else
+                      @query
+                    end
+            @db.send_query_message(QueryMessage.new(@db.name, @collection.name, query))
+            @query_run = true
+            read_all
+          end
+        end
+
         def to_s
           "DBResponse(flags=#@result_flags, cursor_id=#@cursor_id, start=#@starting_from, n_returned=#@n_returned)"
         end
@@ -177,4 +225,3 @@ module XGen
     end
   end
 end
-

data/lib/mongo/db.rb

@@ -49,6 +49,8 @@ module XGen
         # The name of the database.
         attr_reader :name
 
+        attr_reader :host, :port
+
         # The database's socket. For internal use only.
         attr_reader :socket
 
@@ -82,7 +84,7 @@ module XGen
         def collections_info(coll_name=nil)
           selector = {}
           selector[:name] = full_coll_name(coll_name) if coll_name
-          query(SYSTEM_NAMESPACE_COLLECTION, Query.new(selector))
+          query(Collection.new(self, SYSTEM_NAMESPACE_COLLECTION), Query.new(selector))
         end
 
         # Create a collection. If +strict+ is false, will return existing or
@@ -151,6 +153,20 @@ module XGen
           ok?(doc) && is_master.kind_of?(Numeric) && is_master.to_i == 1
         end
 
+        # Returns a string of the form "host:port" that points to the master
+        # database. Works even if this is the master database.
+        def master
+          doc = db_command(:ismaster => 1)
+          is_master = doc['ismaster']
+          raise "Error retrieving master database" unless ok?(doc) && is_master.kind_of?(Numeric)
+          case is_master.to_i
+          when 1
+            "#@host:#@port"
+          else
+            doc['remote']
+          end
+        end
+
         # Close the connection to the database.
         def close
           @socket.close
@@ -161,12 +177,19 @@ module XGen
           send_to_db(MsgMessage.new(msg))
         end
         
-        # Send a Query to +collection_name+ and return a Cursor over the
-        # results.
-        def query(collection_name, query)
+        # Returns a Cursor over the query results.
+        #
+        # Note that the query gets sent lazily; the cursor calls
+        # #send_query_message when needed. If the caller never requests an
+        # object from the cursor, the query never gets sent.
+        def query(collection, query)
+          Cursor.new(self, collection, query)
+        end
+
+        # Used by a Cursor to lazily send the query to the database.
+        def send_query_message(query_message)
           @semaphore.synchronize {
-            send_to_db(QueryMessage.new(@name, collection_name, query))
-            Cursor.new(self, collection_name, query.number_to_return)
+            send_to_db(query_message)
           }
         end
 
@@ -233,7 +256,7 @@ module XGen
         # :ns :: Namespace; same as +collection_name+.
         def index_information(collection_name)
           sel = {:ns => full_coll_name(collection_name)}
-          query(SYSTEM_INDEX_COLLECTION, Query.new(sel)).collect { |row|
+          query(Collection.new(self, SYSTEM_INDEX_COLLECTION), Query.new(sel)).collect { |row|
             h = {:name => row['name']}
             raise "Name of index on return from db was nil. Coll = #{full_coll_name(collection_name)}" unless h[:name]
 
@@ -298,7 +321,7 @@ module XGen
 
           q = Query.new(selector)
           q.number_to_return = 1
-          query(SYSTEM_COMMAND_COLLECTION, q).next_object
+          query(Collection.new(self, SYSTEM_COMMAND_COLLECTION), q).next_object
         end
 
       end

data/lib/mongo/message/query_message.rb

@@ -8,8 +8,11 @@ module XGen
 
       class QueryMessage < Message
 
+        attr_reader :query
+
         def initialize(db_name, collection_name, query)
           super(OP_QUERY)
+          @query = query
           write_int(0)
           write_string("#{db_name}.#{collection_name}")
           write_int(query.number_to_skip)

data/lib/mongo/types/regexp_of_holding.rb

@@ -0,0 +1,44 @@
+# --
+# Copyright (C) 2008-2009 10gen Inc.
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License, version 3, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+# for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+# ++
+
+module XGen
+  module Mongo
+    module Driver
+
+      # A Regexp that can hold on to extra options and ignore them. Mongo
+      # regexes may contain option characters beyond 'i', 'm', and 'x'. (Note
+      # that Mongo only uses those three, but that regexes coming from other
+      # languages may store different option characters.)
+      #
+      # Note that you do not have to use this class at all if you wish to
+      # store regular expressions in Mongo. The Mongo and Ruby regex option
+      # flags are the same. Storing regexes is discouraged, in any case.
+      class RegexpOfHolding < Regexp
+
+        attr_accessor :extra_options_str
+
+        # +str+ and +options+ are the same as Regexp. +extra_options_str+
+        # contains all the other flags that were in Mongo but we do not use or
+        # understand.
+        def initialize(str, options, extra_options_str)
+          super(str, options)
+          @extra_options_str = extra_options_str
+        end
+      end
+
+    end
+  end
+end

data/lib/mongo/util/bson.rb

@@ -17,8 +17,11 @@
 require 'base64'
 require 'mongo/util/byte_buffer'
 require 'mongo/util/ordered_hash'
-require 'mongo/objectid'
-require 'mongo/dbref'
+require 'mongo/types/binary'
+require 'mongo/types/dbref'
+require 'mongo/types/objectid'
+require 'mongo/types/regexp_of_holding'
+require 'mongo/types/undefined'
 
 # A BSON seralizer/deserializer.
 class BSON
@@ -43,8 +46,18 @@ class BSON
   NUMBER_INT = 16
   MAXKEY = 127
 
+  if RUBY_VERSION >= '1.9'
+    def self.to_utf8(str)
+      str.encode("utf-8")
+    end
+  else
+    def self.to_utf8(str)
+      str                       # TODO punt for now
+    end
+  end
+
   def self.serialize_cstr(buf, val)
-    buf.put_array(val.to_s.unpack("C*") + [0])
+    buf.put_array(to_utf8(val.to_s).unpack("C*") + [0])
   end
 
   def initialize(db=nil)
@@ -67,7 +80,7 @@ class BSON
     obj.each {|k, v|
       type = bson_type(v, k)
       case type
-      when STRING, CODE
+      when STRING, CODE, SYMBOL
         serialize_string_element(@buf, k, v, type)
       when NUMBER, NUMBER_INT
         serialize_number_element(@buf, k, v, type)
@@ -87,8 +100,6 @@ class BSON
         serialize_null_element(@buf, k)
       when REF
         serialize_dbref_element(@buf, k, v)
-      when SYMBOL
-        serialize_symbol_element(@buf, k, v)
       when BINARY
         serialize_binary_element(@buf, k, v)
       when UNDEFINED
@@ -118,6 +129,9 @@ class BSON
       when STRING, CODE
         key = deserialize_cstr(@buf)
         doc[key] = deserialize_string_data(@buf)
+      when SYMBOL
+        key = deserialize_cstr(@buf)
+        doc[key] = deserialize_string_data(@buf).intern
       when NUMBER
         key = deserialize_cstr(@buf)
         doc[key] = deserialize_number_data(@buf)
@@ -151,9 +165,6 @@ class BSON
       when REF
         key = deserialize_cstr(@buf)
         doc[key] = deserialize_dbref_data(@buf, key, parent)
-      when SYMBOL
-        key = deserialize_cstr(@buf)
-        doc[key] = deserialize_symbol_data(@buf)
       when BINARY
         key = deserialize_cstr(@buf)
         doc[key] = deserialize_binary_data(@buf)
@@ -170,6 +181,7 @@ class BSON
     doc
   end
 
+  # For debugging.
   def hex_dump
     str = ''
     @buf.to_a.each_with_index { |b,i|
@@ -221,13 +233,18 @@ class BSON
     options |= Regexp::IGNORECASE if options_str.include?('i')
     options |= Regexp::MULTILINE if options_str.include?('m')
     options |= Regexp::EXTENDED if options_str.include?('x')
-    Regexp.new(str, options)
+    options_str.gsub!(/[imx]/, '') # Now remove the three we understand
+    XGen::Mongo::Driver::RegexpOfHolding.new(str, options, options_str)
   end
 
   def deserialize_string_data(buf)
     len = buf.get_int
     bytes = buf.get(len)
-    bytes[0..-2].pack("C*")
+    str = bytes[0..-2].pack("C*")
+    if RUBY_VERSION >= '1.9'
+      str.force_encoding("utf-8")
+    end
+    str
   end
 
   def deserialize_oid_data(buf)
@@ -240,10 +257,6 @@ class BSON
     XGen::Mongo::Driver::DBRef.new(parent, key, @db, ns, oid)
   end
 
-  def deserialize_symbol_data(buf)
-    deserialize_cstr(buf).intern
-  end
-
   def deserialize_binary_data(buf)
     len = buf.get_int
     bytes = buf.get(len)
@@ -268,12 +281,6 @@ class BSON
     buf.put_array(val.object_id.to_a)
   end
 
-  def serialize_symbol_element(buf, key, val)
-    buf.put(SYMBOL)
-    self.class.serialize_cstr(buf, key)
-    self.class.serialize_cstr(buf, val)
-  end
-
   def serialize_binary_element(buf, key, val)
     buf.put(BINARY)
     self.class.serialize_cstr(buf, key)
@@ -342,7 +349,9 @@ class BSON
     options_str << 'i' if ((options & Regexp::IGNORECASE) != 0)
     options_str << 'm' if ((options & Regexp::MULTILINE) != 0)
     options_str << 'x' if ((options & Regexp::EXTENDED) != 0)
-    self.class.serialize_cstr(buf, options_str)
+    options_str << val.extra_options_str if val.respond_to?(:extra_options_str)
+    # Must store option chars in alphabetical order
+    self.class.serialize_cstr(buf, options_str.split(//).sort.uniq.join)
   end
 
   def serialize_oid_element(buf, key, val)
@@ -379,6 +388,9 @@ class BSON
       break if b == 0
       chars << b.chr
     end
+    if RUBY_VERSION >= '1.9'
+      chars.force_encoding("utf-8") # Mongo stores UTF-8
+    end
     chars
   end
 

data/lib/mongo/util/ordered_hash.rb

@@ -15,8 +15,14 @@
 # ++
 
 # A hash in which the order of keys are preserved.
+#
+# Under Ruby 1.9 and greater, this class has no added methods because Ruby's
+# Hash already keeps its keys ordered by order of insertion.
 class OrderedHash < Hash
 
+  # We only need the body of this class if the RUBY_VERSION is before 1.9
+  if RUBY_VERSION < '1.9'
+
   attr_accessor :ordered_keys
 
   def keys
@@ -57,4 +63,6 @@ class OrderedHash < Hash
     str << '}'
   end
 
+  end                           # Ruby before 1.9
+
 end

data/tests/test_bson.rb

@@ -59,7 +59,26 @@ class BSONTest < Test::Unit::TestCase
   def test_regex
     doc = {'doc' => /foobar/i}
     @b.serialize(doc)
-    assert_equal doc, @b.deserialize
+    doc2 = @b.deserialize
+    assert_equal doc, doc2
+
+    r = doc2['doc']
+    assert_kind_of XGen::Mongo::Driver::RegexpOfHolding, r
+    assert_equal '', r.extra_options_str
+
+    r.extra_options_str << 'zywcab'
+    assert_equal 'zywcab', r.extra_options_str
+
+    b = BSON.new
+    doc = {'doc' => r}
+    b.serialize(doc)
+    doc2 = nil
+    doc2 = b.deserialize
+    assert_equal doc, doc2
+
+    r = doc2['doc']
+    assert_kind_of XGen::Mongo::Driver::RegexpOfHolding, r
+    assert_equal 'abcwyz', r.extra_options_str # must be sorted
   end
 
   def test_boolean

data/tests/test_cursor.rb

@@ -0,0 +1,63 @@
+$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+require 'mongo'
+require 'test/unit'
+
+# NOTE: assumes Mongo is running
+class CursorTest < Test::Unit::TestCase
+
+  include XGen::Mongo::Driver
+
+  def setup
+    host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
+    port = ENV['MONGO_RUBY_DRIVER_PORT'] || Mongo::DEFAULT_PORT
+    @db = Mongo.new(host, port).db('ruby-mongo-test')
+    @coll = @db.collection('test')
+    @coll.clear
+    @r1 = @coll.insert('a' => 1) # collection not created until it's used
+    @coll_full_name = 'ruby-mongo-test.test'
+  end
+
+  def teardown
+    @coll.clear unless @coll == nil || @db.socket.closed?
+  end
+
+  def test_explain
+    cursor = @coll.find('a' => 1)
+    explaination = cursor.explain
+    assert_not_nil explaination['cursor']
+    assert_kind_of Numeric, explaination['n']
+    assert_kind_of Numeric, explaination['millis']
+    assert_kind_of Numeric, explaination['nscanned']
+  end
+
+  def test_close_no_query_sent
+    begin
+      cursor = @coll.find('a' => 1)
+      cursor.close
+      assert cursor.closed?
+    rescue => ex
+      fail ex.to_s
+    end
+  end
+
+  def test_close_after_query_sent
+    begin
+      cursor = @coll.find('a' => 1)
+      cursor.next_object
+      cursor.close
+      assert cursor.closed?
+    rescue => ex
+      fail ex.to_s
+    end
+  end
+
+  def test_hint
+    begin
+      cursor = @coll.find('a' => 1).hint('a')
+      assert_equal 1, cursor.to_a.size
+    rescue => ex
+      fail ex.to_s
+    end
+  end
+
+end

data/tests/test_db_api.rb

@@ -354,4 +354,8 @@ class DBAPITest < Test::Unit::TestCase
     assert @db.master?
   end
 
+  def test_master
+    assert_equal "#{@db.host}:#{@db.port}", @db.master
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mongo
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Jim Menard
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-01-12 00:00:00 -05:00
+date: 2009-01-14 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -25,11 +25,9 @@ files:
 - bin/mongo_console
 - bin/validate
 - lib/mongo/admin.rb
-- lib/mongo/binary.rb
 - lib/mongo/collection.rb
 - lib/mongo/cursor.rb
 - lib/mongo/db.rb
-- lib/mongo/dbref.rb
 - lib/mongo/message/get_more_message.rb
 - lib/mongo/message/insert_message.rb
 - lib/mongo/message/kill_cursors_message.rb
@@ -42,9 +40,12 @@ files:
 - lib/mongo/message/update_message.rb
 - lib/mongo/message.rb
 - lib/mongo/mongo.rb
-- lib/mongo/objectid.rb
 - lib/mongo/query.rb
-- lib/mongo/undefined.rb
+- lib/mongo/types/binary.rb
+- lib/mongo/types/dbref.rb
+- lib/mongo/types/objectid.rb
+- lib/mongo/types/regexp_of_holding.rb
+- lib/mongo/types/undefined.rb
 - lib/mongo/util/bson.rb
 - lib/mongo/util/byte_buffer.rb
 - lib/mongo/util/ordered_hash.rb
@@ -53,6 +54,7 @@ files:
 - tests/test_admin.rb
 - tests/test_bson.rb
 - tests/test_byte_buffer.rb
+- tests/test_cursor.rb
 - tests/test_db_api.rb
 - tests/test_db_connection.rb
 - tests/test_message.rb