mongo 0.19.1 → 0.19.2

data/lib/bson/types/code.rb

@@ -0,0 +1,36 @@
+# --
+# Copyright (C) 2008-2010 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+
+module BSON
+
+  # JavaScript code to be evaluated by MongoDB.
+  class Code < String
+
+    # Hash mapping identifiers to their values
+    attr_accessor :scope
+
+    # Wrap code to be evaluated by MongoDB.
+    #
+    # @param [String] code the JavaScript code.
+    # @param [Hash] a document mapping identifiers to values, which
+    #   represent the scope in which the code is to be executed.
+    def initialize(code, scope={})
+      super(code)
+      @scope = scope
+    end
+
+  end
+end

data/lib/bson/types/dbref.rb

@@ -0,0 +1,40 @@
+# --
+# Copyright (C) 2008-2010 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+
+module BSON
+
+  # A reference to another object in a MongoDB database.
+  class DBRef
+
+    attr_reader :namespace, :object_id
+
+    # Create a DBRef. Use this class in conjunction with DB#dereference.
+    #
+    # @param [String] a collection name
+    # @param [ObjectID] an object id
+    #
+    # @core dbrefs constructor_details
+    def initialize(namespace, object_id)
+      @namespace = namespace
+      @object_id = object_id
+    end
+
+    def to_s
+      "ns: #{namespace}, id: #{object_id}"
+    end
+
+  end
+end

data/lib/bson/types/min_max_keys.rb

@@ -0,0 +1,58 @@
+# --
+# Copyright (C) 2008-2010 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+
+module BSON
+
+  # A class representing the BSON MaxKey type. MaxKey will always compare greater than
+  # all other BSON types and values.
+  #
+  # @example Sorting (assume @numbers is a collection):
+  #
+  #   >> @numbers.save({"n" => Mongo::MaxKey.new})
+  #   >> @numbers.save({"n" => 0})
+  #   >> @numbers.save({"n" => 5_000_000})
+  #   >> @numbers.find.sort("n").to_a
+  #   => [{"_id"=>4b5a050c238d3bace2000004, "n"=>0},
+  #       {"_id"=>4b5a04e6238d3bace2000002, "n"=>5_000_000},
+  #       {"_id"=>4b5a04ea238d3bace2000003, "n"=>#<Mongo::MaxKey:0x1014ef410>},
+  #      ]
+  class MaxKey
+
+    def ==(obj)
+      obj.class == MaxKey
+    end
+  end
+
+  # A class representing the BSON MinKey type. MinKey will always compare less than
+  # all other BSON types and values.
+  #
+  # @example Sorting (assume @numbers is a collection):
+  #
+  #   >> @numbers.save({"n" => Mongo::MinKey.new})
+  #   >> @numbers.save({"n" => -1_000_000})
+  #   >> @numbers.save({"n" => 1_000_000})
+  #   >> @numbers.find.sort("n").to_a
+  #   => [{"_id"=>4b5a050c238d3bace2000004, "n"=>#<Mongo::MinKey:0x1014ef410>},
+  #       {"_id"=>4b5a04e6238d3bace2000002, "n"=>-1_000_000},
+  #       {"_id"=>4b5a04ea238d3bace2000003, "n"=>1_000_000},
+  #      ]
+  class MinKey
+
+    def ==(obj)
+      obj.class == MinKey
+    end
+  end
+end

data/lib/bson/types/objectid.rb

@@ -0,0 +1,180 @@
+# --
+# Copyright (C) 2008-2010 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+
+require 'thread'
+require 'socket'
+require 'digest/md5'
+
+module BSON
+
+  # Generates MongoDB object ids.
+  #
+  # @core objectids
+  class ObjectID
+    @@lock  = Mutex.new
+    @@index = 0
+
+    # Create a new object id. If no parameter is given, an id corresponding
+    # to the ObjectID BSON data type will be created. This is a 12-byte value
+    # consisting of a 4-byte timestamp, a 3-byte machine id, a 2-byte process id,
+    # and a 3-byte counter.
+    #
+    # @param [Array] data should be an array of bytes. If you want
+    #   to generate a standard MongoDB object id, leave this argument blank.
+    def initialize(data=nil)
+      @data = data || generate
+    end
+
+    # Determine if the supplied string is legal. Legal strings will
+    # consist of 24 hexadecimal characters.
+    #
+    # @param [String] str
+    #
+    # @return [Boolean]
+    def self.legal?(str)
+      len = 24
+      str =~ /([0-9a-f]+)/i
+      match = $1
+      str && str.length == len && match == str
+    end
+
+    # Create an object id from the given time. This is useful for doing range
+    # queries; it works because MongoDB's object ids begin
+    # with a timestamp.
+    #
+    # @param [Time] time a utc time to encode as an object id.
+    #
+    # @return [Mongo::ObjectID]
+    #
+    # @example Return all document created before Jan 1, 2010.
+    #   time = Time.utc(2010, 1, 1)
+    #   time_id = ObjectID.from_time(time)
+    #   collection.find({'_id' => {'$lt' => time_id}})
+    def self.from_time(time)
+      self.new([time.to_i,0,0].pack("NNN").unpack("C12"))
+    end
+
+    # Adds a primary key to the given document if needed.
+    #
+    # @param [Hash] doc a document requiring an _id.
+    #
+    # @return [Mongo::ObjectID, Object] returns a newly-created or 
+    #   current _id for the given document.
+    def self.create_pk(doc)
+      doc.has_key?(:_id) || doc.has_key?('_id') ? doc : doc.merge!(:_id => self.new)
+    end
+
+    # Check equality of this object id with another.
+    #
+    # @param [Mongo::ObjectID] object_id
+    def eql?(object_id)
+      @data == object_id.instance_variable_get("@data")
+    end
+    alias_method :==, :eql?
+
+    # Get a unique hashcode for this object.
+    # This is required since we've defined an #eql? method.
+    #
+    # @return [Integer]
+    def hash
+      @data.hash
+    end
+
+    # Get an array representation of the object id.
+    #
+    # @return [Array]
+    def to_a
+      @data.dup
+    end
+
+    # Given a string representation of an ObjectID, return a new ObjectID
+    # with that value.
+    #
+    # @param [String] str
+    #
+    # @return [Mongo::ObjectID]
+    def self.from_string(str)
+      raise InvalidObjectID, "illegal ObjectID format" unless legal?(str)
+      data = []
+      12.times do |i|
+        data[i] = str[i * 2, 2].to_i(16)
+      end
+      self.new(data)
+    end
+
+    # Get a string representation of this object id.
+    #
+    # @return [String]
+    def to_s
+      str = ' ' * 24
+      12.times do |i|
+        str[i * 2, 2] = '%02x' % @data[i]
+      end
+      str
+    end
+
+    def inspect
+      "ObjectID('#{to_s}')"
+    end
+
+    # Convert to MongoDB extended JSON format. Since JSON includes type information,
+    # but lacks an ObjectID type, this JSON format encodes the type using an $id key.
+    #
+    # @return [String] the object id represented as MongoDB extended JSON.
+    def to_json(escaped=false)
+      "{\"$oid\": \"#{to_s}\"}"
+    end
+
+    # Return the UTC time at which this ObjectID was generated. This may
+    # be used in lieu of a created_at timestamp since this information
+    # is always encoded in the object id.
+    #
+    # @return [Time] the time at which this object was created.
+    def generation_time
+      Time.at(@data.pack("C4").unpack("N")[0]).utc
+    end
+
+    private
+
+    # We need to define this method only if CBson isn't loaded.
+    unless defined? CBson
+      def generate
+        oid = ''
+
+        # 4 bytes current time
+        time = Time.new.to_i
+        oid += [time].pack("N")
+
+        # 3 bytes machine
+        oid += Digest::MD5.digest(Socket.gethostname)[0, 3]
+
+        # 2 bytes pid
+        oid += [Process.pid % 0xFFFF].pack("n")
+
+        # 3 bytes inc
+        oid += [get_inc].pack("N")[1, 3]
+
+        oid.unpack("C12")
+      end
+    end
+
+    def get_inc
+      @@lock.synchronize do
+        @@index = (@@index + 1) % 0xFFFFFF
+      end
+    end
+  end
+end

data/lib/bson/types/regexp_of_holding.rb

@@ -0,0 +1,45 @@
+# --
+# Copyright (C) 2008-2010 10gen Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ++
+
+module BSON
+
+  # 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.
+  # 
+  # @deprecated
+  class RegexpOfHolding < Regexp
+
+    attr_accessor :extra_options_str
+
+    # @deprecated we're no longer supporting this.
+    # +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)
+      warn "RegexpOfHolding is deprecated; the modifiers i, m, and x will be stored automatically as BSON." +
+        "If you're only storing the options i, m, and x, you can safely ignore this message."
+      super(str, options)
+      @extra_options_str = extra_options_str
+    end
+  end
+
+end

data/lib/mongo.rb

@@ -1,7 +1,7 @@
 $:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 
 module Mongo
-  VERSION = "0.19.1"
+  VERSION = "0.19.2"
 end
 
 begin
@@ -21,8 +21,9 @@ begin
 end
 
 module Mongo
-  ASCENDING = 1
+  ASCENDING  =  1
   DESCENDING = -1
+  GEO2D      = '2d'
 
   module Constants
     OP_REPLY        = 1
@@ -48,6 +49,7 @@ require 'mongo/types/regexp_of_holding'
 require 'mongo/types/min_max_keys'
 
 require 'mongo/util/support'
+require 'mongo/util/core_ext'
 require 'mongo/util/conversions'
 require 'mongo/util/server_version'
 require 'mongo/util/bson_ruby'

data/lib/mongo/collection.rb

@@ -265,13 +265,13 @@ module Mongo
 
       if opts[:safe]
         @connection.send_message_with_safe_check(Mongo::Constants::OP_DELETE, message, @db.name,
-          "db.#{@db.name}.remove(#{selector.inspect})")
+          "#{@db.name}['#{@name}'].remove(#{selector.inspect})")
         # the return value of send_message_with_safe_check isn't actually meaningful --
         # only the fact that it didn't raise an error is -- so just return true
         true
       else
         @connection.send_message(Mongo::Constants::OP_DELETE, message,
-          "db.#{@db.name}.remove(#{selector.inspect})")
+          "#{@db.name}['#{@name}'].remove(#{selector.inspect})")
       end
     end
 
@@ -307,41 +307,82 @@ module Mongo
       message.put_array(BSON.serialize(document, false, true).to_a)
       if options[:safe]
         @connection.send_message_with_safe_check(Mongo::Constants::OP_UPDATE, message, @db.name,
-          "db.#{@name}.update(#{selector.inspect}, #{document.inspect})")
+          "#{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})")
       else
         @connection.send_message(Mongo::Constants::OP_UPDATE, message,
-          "db.#{@name}.update(#{selector.inspect}, #{document.inspect})")
+          "#{@db.name}['#{@name}'].update(#{selector.inspect}, #{document.inspect})")
       end
     end
 
     # Create a new index.
     #
-    # @param [String, Array] field_or_spec
+    # @param [String, Array] spec
     #   should be either a single field name or an array of
-    #   [field name, direction] pairs. Directions should be specified as Mongo::ASCENDING or Mongo::DESCENDING.
+    #   [field name, direction] pairs. Directions should be specified
+    #   as Mongo::ASCENDING, Mongo::DESCENDING, or Mongo::GEO2D.
     #
-    # @param [Boolean] unique if true, this index will enforce a uniqueness constraint.
+    #   Note that geospatial indexing only works with versions of MongoDB >= 1.3.3+. Keep in mind, too,
+    #   that in order to geo-index a given field, that field must reference either an array or a sub-object
+    #   where the first two values represent x- and y-coordinates. Examples can be seen below.
+    #
+    #   Also note that it is permissible to create compound indexes that include a geospatial index as
+    #   long as the geospatial index comes first.
+    #
+    # @param [Boolean] unique if true, this index will enforce a uniqueness constraint. DEPRECATED. Future
+    #   versions of this driver will specify the uniqueness constraint using a hash param.
+    #
+    # @option opts [Boolean] :unique (false) if true, this index will enforce a uniqueness constraint.
+    # @option opts [Boolean] :background (false) indicate that the index should be built in the background. This
+    #   feature is only available in MongoDB >= 1.3.2.
+    # @option opts [Boolean] :dropDups If creating a unique index on a collection with pre-existing records,
+    #   this option will keep the first document the database indexes and drop all subsequent with duplicate values.
+    # @option opts [Integer] :min specify the minimum longitude and latitude for a geo index.
+    # @option opts [Integer] :max specify the maximum longitude and latitude for a geo index.
+    #
+    # @example Creating a compound index:
+    #   @posts.create_index([['subject', Mongo::ASCENDING], ['created_at', Mongo::DESCENDING]])
+    #
+    # @example Creating a geospatial index:
+    #   @restaurants.create_index([['location', Mongo::GEO2D]])
+    #
+    #   # Note that this will work only if 'location' represents x,y coordinates:
+    #   {'location': [0, 50]}
+    #   {'location': {'x' => 0, 'y' => 50}}
+    #   {'location': {'latitude' => 0, 'longitude' => 50}}
+    #
+    # @example A geospatial index with alternate longitude and latitude:
+    #   @restaurants.create_index([['location', Mongo::GEO2D]], :min => 500, :max => 500)
     #
     # @return [String] the name of the index created.
     #
     # @core indexes create_index-instance_method
-    def create_index(field_or_spec, unique=false)
-      field_h = OrderedHash.new
-      if field_or_spec.is_a?(String) || field_or_spec.is_a?(Symbol)
-        field_h[field_or_spec.to_s] = 1
+    def create_index(spec, opts={})
+      opts.assert_valid_keys(:min, :max, :background, :unique, :dropDups) if opts.is_a?(Hash)
+      field_spec = OrderedHash.new
+      if spec.is_a?(String) || spec.is_a?(Symbol)
+        field_spec[spec.to_s] = 1
+      elsif spec.is_a?(Array) && spec.all? {|field| field.is_a?(Array) }
+        spec.each { |f| field_spec[f[0].to_s] = f[1] }
       else
-        field_or_spec.each { |f| field_h[f[0].to_s] = f[1] }
+        raise MongoArgumentError, "Invalid index specification #{spec.inspect}; " + 
+          "should be either a string, symbol, or an array of arrays."
+      end
+
+      name = generate_index_name(field_spec)
+      if opts == true || opts == false
+        warn "For Collection#create_index, the method for specifying a unique index has changed." +
+          "Please pass :unique => true to the method instead."
       end
-      name = generate_index_names(field_h)
       sel  = {
         :name   => name,
         :ns     => "#{@db.name}.#{@name}",
-        :key    => field_h,
-        :unique => unique }
+        :key    => field_spec,
+        :unique => (opts == true ? true : false) }
+      sel.merge!(opts) if opts.is_a?(Hash)
       begin
-        insert_documents([sel], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
+        response = insert_documents([sel], Mongo::DB::SYSTEM_INDEX_COLLECTION, false, true)
       rescue Mongo::OperationFailure
-        raise Mongo::OperationFailure, "Failed to create index #{sel.inspect}."
+        raise Mongo::OperationFailure, "Failed to create index #{sel.inspect} with the following errors: #{response}"
       end
       name
     end
@@ -593,15 +634,15 @@ module Mongo
       documents.each { |doc| message.put_array(BSON.serialize(doc, check_keys, true).to_a) }
       if safe
         @connection.send_message_with_safe_check(Mongo::Constants::OP_INSERT, message, @db.name,
-          "db.#{collection_name}.insert(#{documents.inspect})")
+          "#{@db.name}['#{collection_name}'].insert(#{documents.inspect})")
       else
         @connection.send_message(Mongo::Constants::OP_INSERT, message,
-          "db.#{collection_name}.insert(#{documents.inspect})")
+          "#{@db.name}['#{collection_name}'].insert(#{documents.inspect})")
       end
       documents.collect { |o| o[:_id] || o['_id'] }
     end
 
-    def generate_index_names(spec)
+    def generate_index_name(spec)
       indexes = []
       spec.each_pair do |field, direction|
         indexes.push("#{field}_#{direction}")