mongo 0.18.2 → 0.18.3

data/README.rdoc

@@ -2,7 +2,7 @@
 
 This is the 10gen-supported Ruby driver for MongoDB[http://www.mongodb.org].
 
-Here is a quick code sample. See the MongoDB Ruby Tutorial
+Here's a quick code sample. See the MongoDB Ruby Tutorial
 (http://www.mongodb.org/display/DOCS/Ruby+Tutorial) for much more.
 
   require 'rubygems'
@@ -56,7 +56,7 @@ That's all there is to it!
 For extensive examples, see the MongoDB Ruby Tutorial
 (http://www.mongodb.org/display/DOCS/Ruby+Tutorial).
 
-Bundled with the dirver are many examples in the "examples" subdirectory. Samples include using
+Bundled with the driver are many examples, located in the "examples" subdirectory. Samples include using
 the driver and using the GridFS class GridStore. MongoDB must be running for
 these examples to work, of course.
 
@@ -82,25 +82,34 @@ Note that the GridStore class is not automatically required when you require
 
 Example code:
 
-  GridStore.open(database, 'filename', 'w') { |f|
+  include GridFS
+
+  # Store the text "Hello, world!" in the grid store.
+  GridStore.open(database, 'filename', 'w') do |f|
     f.puts "Hello, world!"
-  }
-  GridStore.open(database, 'filename, 'r') { |f|
-    puts f.read         # => Hello, world!\n
-  }
-  GridStore.open(database, 'filename', 'w+') { |f|
+  end
+
+  # Output "Hello, world!"
+  GridStore.open(database, 'filename', 'r') do |f|
+    puts f.read
+  end
+
+  # Add text to the grid store.
+  GridStore.open(database, 'filename', 'w+') do |f|
     f.puts "But wait, there's more!"
-  }
-  GridStore.open(database, 'filename, 'r') { |f|
-    puts f.read         # => Hello, world!\nBut wait, there's more!\n
-  }
+  end
+
+  # Retrieve everything, outputting  "Hello, world!\nBut wait, there's more!\n"
+  GridStore.open(database, 'filename', 'r') do |f|
+    puts f.read
+  end
 
 
 = Notes
 
 == Thread Safety
 
-The driver is thread safe.
+The driver is thread-safe.
 
 == Connection Pooling
 
@@ -119,7 +128,7 @@ A pooled connection to a paired instance would look like this:
                     :right => ["db2.example.com", 27017]}, nil,
                     :pool_size => 20, :timeout => 5)
 
-Though the pooling architecure will undoubtedly evolve, it owes much credit
+Though the pooling architecture will undoubtedly evolve, it currently owes much credit
 to the connection pooling implementations in ActiveRecord and PyMongo.
 
 == Using with Phusion Passenger
@@ -139,7 +148,7 @@ or handle reconnecting when passenger forks a new process:
     end
   end
 
-The above code should be put in _environment.rb_ or an initialization
+The above code should be put in _environment.rb_ or in an initialization
 script.
 
 See this thread[http://groups.google.com/group/mongodb-user/browse_thread/thread/f31e2d23de38136a]
@@ -156,7 +165,7 @@ 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
+UTF-8. If the string is not ASCII, it may not be a well-formed UTF-8
 string.
 
 == Primary Keys
@@ -173,17 +182,18 @@ generate _id values. If you want to control _id values or even their types,
 using a PK factory lets you do so.
 
 You can tell the Ruby Mongo driver how to create primary keys by passing in
-the :pk option to the Connection#db method.
+the :pk_factory option to the Connection#db method.
 
-  include Mongo
-  db = Connection.new.db('dbname', :pk => MyPKFactory.new)
+  db = Mongo::Connection.new.db('dbname', :pk_factory => MyPKFactory.new)
 
 A primary key factory object must respond to :create_pk, which should take a
 hash and return a hash which merges the original hash with any primary key
-fields the factory wishes to inject. NOTE: if the object already has a primary
-key, the factory should not inject a new key; this means that the object is
-being used in a repsert but it already exists. The idea here is that whenever
-a record is inserted, the :pk object's +create_pk+ method will be called and
+fields the factory wishes to inject. 
+
+NOTE: if the object already has a primary key, the factory should not inject
+a new key; this means that the object may already exist in the database.
+The idea here is that whenever a record is inserted,
+the :pk_factory object's +create_pk+ method will be called and
 the new hash returned will be inserted.
 
 Here is a sample primary key factory, taken from the tests:
@@ -251,11 +261,10 @@ Random cursor fun facts:
 - Cursors have a to_a method.
 
 
-
 = Testing
 
 If you have the source code, you can run the tests. There's a separate rake task for testing with
-the mongo_ext c extension enabled.
+the mongo_ext C extension enabled.
 
   $ rake test:c
 
@@ -268,7 +277,7 @@ These will run both unit and functional tests. To run these tests alone:
   $ rake test:unit
   $ rake test:functional
 
-To run any individual rake tasks with the C extenson enabled, just pass C_EXT=true to the task:
+To run any individual rake tasks with the C extension enabled, just pass C_EXT=true to the task:
 
   $ rake test:unit C_EXT=true
 
@@ -318,9 +327,9 @@ validator script.
 This documentation is available online at http://api.mongodb.org/ruby. You can
 generate the documentation if you have the source by typing
 
-  $ rake rdoc
+  $ rake ydoc
 
-Then open the file html/index.html.
+Then open the file +ydoc/index.html+.
 
 
 = Release Notes

data/Rakefile

@@ -28,6 +28,7 @@ namespace :test do
     Rake::Task['test:unit'].invoke
     Rake::Task['test:functional'].invoke
     Rake::Task['test:pooled_threading'].invoke
+    Rake::Task['test:drop_databases'].invoke
     ENV['C_EXT'] = nil
   end
 
@@ -37,6 +38,7 @@ namespace :test do
     Rake::Task['test:unit'].invoke
     Rake::Task['test:functional'].invoke
     Rake::Task['test:pooled_threading'].invoke
+    Rake::Task['test:drop_databases'].invoke
   end
 
   Rake::TestTask.new(:unit) do |t|
@@ -73,6 +75,15 @@ namespace :test do
     t.test_files = FileList['test/replica/query_test.rb']
     t.verbose    = true
   end
+
+  task :drop_databases do |t|
+    puts "Dropping test database..."
+    require File.join(File.dirname(__FILE__), 'lib', 'mongo')
+    include Mongo
+    con = Connection.new(ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost',
+      ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT)
+    con.drop_database('ruby-mongo-test')
+  end
 end
 
 desc "Generate documentation"
@@ -83,6 +94,14 @@ task :rdoc do
   system "rdoc --main README.rdoc --op #{out} --inline-source --quiet README.rdoc `find lib -name '*.rb'`"
 end
 
+desc "Generate YARD documentation"
+task :ydoc do
+  version = eval(File.read("mongo-ruby-driver.gemspec")).version
+  out = File.join('ydoc', version.to_s)
+  FileUtils.rm_rf('ydoc')
+  system "yardoc lib/**/*.rb lib/mongo/**/*.rb -o #{out} --title MongoRuby-#{version}"
+end
+
 desc "Publish documentation to mongo.rubyforge.org"
 task :publish => [:rdoc] do
   # Assumes docs are in ./html

data/bin/objectid_benchmark.rb

@@ -0,0 +1,23 @@
+require 'rubygems'
+require 'mongo'
+require 'benchmark'
+
+TRIALS = 500000
+
+include Mongo
+
+Benchmark.bm do |x|
+
+  x.report('original') do
+    TRIALS.times do
+      ObjectID.new(nil, true)
+    end
+  end
+
+  x.report('new') do
+    TRIALS.times do
+      ObjectID.new(nil, false)
+    end
+  end
+
+end

data/examples/admin.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 require 'pp'
 
@@ -8,16 +9,16 @@ host = ENV['MONGO_RUBY_DRIVER_HOST'] || 'localhost'
 port = ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
 
 puts "Connecting to #{host}:#{port}"
-db = Connection.new(host, port).db('ruby-mongo-examples')
+db = Mongo::Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.create_collection('test')
 
 # Erase all records from collection, if any
-coll.clear
+coll.remove
 
 admin = db.admin
 
 # Profiling level set/get
-p admin.profiling_level
+puts "Profiling level: #{admin.profiling_level}"
 
 # Start profiling everything
 admin.profiling_level = :all
@@ -31,8 +32,8 @@ admin.profiling_level = :off
 # Print all profiling info
 pp admin.profiling_info
 
-# Validate returns a hash if all is well or raises an exception if there is a
-# problem.
+# Validate returns a hash if all is well and
+# raises an exception if there is a problem.
 info = admin.validate_collection(coll.name)
 puts "valid = #{info['ok']}"
 puts info['result']

data/examples/capped.rb

@@ -1,4 +1,4 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'mongo'
 
 include Mongo
@@ -10,9 +10,8 @@ puts "Connecting to #{host}:#{port}"
 db = Connection.new(host, port).db('ruby-mongo-examples')
 db.drop_collection('test')
 
-# A capped collection has a max size and optionally a max number of records.
-# Old records get pushed out by new ones once the size or max num records is
-# reached.
+# A capped collection has a max size and, optionally, a max number of records.
+# Old records get pushed out by new ones once the size or max num records is reached.
 coll = db.create_collection('test', :capped => true, :size => 1024, :max => 12)
 
 100.times { |i| coll.insert('a' => i+1) }

data/examples/cursor.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 require 'pp'
 
@@ -12,7 +13,7 @@ db = Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.collection('test')
 
 # Erase all records from collection, if any
-coll.clear
+coll.remove
 
 # Insert 3 records
 3.times { |i| coll.insert({'a' => i+1}) }
@@ -23,7 +24,7 @@ coll.clear
 # Find returns a Cursor, which is Enumerable. You can iterate:
 coll.find().each { |row| pp row }
 
-# You can turn it into an array
+# You can turn it into an array:
 array = coll.find().to_a
 
 # You can iterate after turning it into an array (the cursor will iterate over

data/examples/gridfs.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 require 'mongo/gridfs'
 
@@ -19,7 +20,7 @@ end
 GridStore.open(db, 'foobar', 'w') { |f| f.write("hello, world!") }
 
 # Read it and print out the contents
-dump(db, 'foobar')                 # defined above
+dump(db, 'foobar')
 
 # Append more data
 GridStore.open(db, 'foobar', 'w+') { |f| f.write("\n"); f.puts "line two" }

data/examples/index_test.rb

@@ -1,10 +1,5 @@
-class Exception
-  def errmsg
-    "%s: %s\n%s" % [self.class, message, (backtrace || []).join("\n") << "\n"]
-  end
-end
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
 require 'mongo'
 
 include Mongo
@@ -15,6 +10,12 @@ port = ENV['MONGO_RUBY_DRIVER_PORT'] || Connection::DEFAULT_PORT
 puts ">> Connecting to #{host}:#{port}"
 db = Connection.new(host, port).db('ruby-mongo-index_test')
 
+class Exception
+  def errmsg
+    "%s: %s\n%s" % [self.class, message, (backtrace || []).join("\n") << "\n"]
+  end
+end
+
 puts ">> Dropping collection test"
 begin
   res = db.drop_collection('test')
@@ -43,8 +44,8 @@ coll.insert(arr)
 puts "inserted"
 
 puts ">> Creating index"
-res = coll.create_index "all", :_id => 1, :number => 1, :rndm => 1, :msg => 1
-# res = coll.create_index "all", '_id' => 1, 'number' => 1, 'rndm' => 1, 'msg' => 1
+#res = coll.create_index "all", :_id => 1, :number => 1, :rndm => 1, :msg => 1
+res = coll.create_index [[:number, 1], [:rndm, 1], [:msg, 1]]
 puts "created index: #{res.inspect}"
 # ============================ Mongo Log ============================
 # Fri Dec  5 14:45:02 Adding all existing records for ruby-mongo-console.test to new index
@@ -76,7 +77,7 @@ end
 
 puts ">> Dropping index"
 begin
-  res = coll.drop_index "all_1"
+  res = coll.drop_index "number_1_rndm_1_msg_1"
   puts "dropped : #{res.inspect}"
 rescue => e
   puts "Error: #{e.errmsg}"

data/examples/info.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 
 include Mongo
@@ -11,7 +12,7 @@ db = Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.collection('test')
 
 # Erase all records from collection, if any
-coll.clear
+coll.remove
 
 # Insert 3 records
 3.times { |i| coll.insert({'a' => i+1}) }

data/examples/queries.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 require 'pp'
 
@@ -12,7 +13,7 @@ db = Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.collection('test')
 
 # Remove all records, if any
-coll.clear
+coll.remove
 
 # Insert three records
 coll.insert('a' => 1)

data/examples/simple.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 
 include Mongo
@@ -11,7 +12,7 @@ db = Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.collection('test')
 
 # Erase all records from collection, if any
-coll.clear
+coll.remove
 
 # Insert 3 records
 3.times { |i| coll.insert({'a' => i+1}) }

data/examples/strict.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 
 include Mongo

data/examples/types.rb

@@ -1,4 +1,5 @@
-$LOAD_PATH[0,0] = File.join(File.dirname(__FILE__), '..', 'lib')
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'mongo'
 require 'pp'
 
@@ -12,7 +13,7 @@ db = Connection.new(host, port).db('ruby-mongo-examples')
 coll = db.collection('test')
 
 # Remove all records, if any
-coll.clear
+coll.remove
 
 # Insert record with all sorts of values
 coll.insert('array' => [1, 2, 3],
@@ -32,4 +33,4 @@ coll.insert('array' => [1, 2, 3],
 
 pp coll.find().next_document
 
-coll.clear
+coll.remove

data/lib/mongo.rb

@@ -1,10 +1,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  ASCENDING = 1
-  DESCENDING = -1
-
-  VERSION = "0.18.2"
+  VERSION = "0.18.3"
 end
 
 begin
@@ -13,32 +10,52 @@ begin
     require 'mongo_ext/cbson'
     raise LoadError unless defined?(CBson::VERSION) && CBson::VERSION == Mongo::VERSION
     require 'mongo/util/bson_c'
-    BSON            = BSON_C
+    BSON = BSON_C
   rescue LoadError
     require 'mongo/util/bson_ruby'
-    BSON            = BSON_RUBY
+    BSON = BSON_RUBY
     warn "\n**Notice: C extension not loaded. This is required for optimum MongoDB Ruby driver performance."
     warn "  You can install the extension as follows:\n  gem install mongo_ext\n"
     warn "  If you continue to receive this message after installing, make sure that the"
     warn "  mongo_ext gem is in your load path and that the mongo_ext and mongo gems are of the same version.\n"
 end
 
+module Mongo
+  ASCENDING = 1
+  DESCENDING = -1
+
+  module Constants
+    OP_REPLY        = 1
+    OP_MSG          = 1000
+    OP_UPDATE       = 2001
+    OP_INSERT       = 2002
+    OP_QUERY        = 2004
+    OP_GET_MORE     = 2005
+    OP_DELETE       = 2006
+    OP_KILL_CURSORS = 2007
+
+    OP_QUERY_SLAVE_OK          = 4
+    OP_QUERY_NO_CURSOR_TIMEOUT = 16
+  end
+
+end
+
 require 'mongo/types/binary'
 require 'mongo/types/code'
 require 'mongo/types/dbref'
 require 'mongo/types/objectid'
 require 'mongo/types/regexp_of_holding'
+require 'mongo/types/min_max_keys'
 
 require 'mongo/util/support'
 require 'mongo/util/conversions'
 require 'mongo/util/server_version'
 require 'mongo/util/bson_ruby'
 
-require 'mongo/errors'
-require 'mongo/constants'
+require 'mongo/admin'
+require 'mongo/collection'
 require 'mongo/connection'
-require 'mongo/db'
 require 'mongo/cursor'
-require 'mongo/collection'
-require 'mongo/admin'
-
+require 'mongo/db'
+require 'mongo/exceptions'
+require 'mongo/gridfs'