mongo 0.18.2 → 0.18.3

data/lib/mongo/{errors.rb → exceptions.rb}

@@ -1,18 +1,18 @@
-# Copyright 2009 10gen, Inc.
+# --
+# Copyright (C) 2008-2009 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
+#     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.
-
-# Exceptions raised by the MongoDB driver.
+# ++
 
 module Mongo
   # Generic Mongo Ruby Driver exception class.
@@ -39,7 +39,8 @@ module Mongo
   # Raised on failures in connection to the database server.
   class ConnectionTimeoutError < MongoRubyError; end
 
-  # Raised when trying to insert a document that exceeds the 4MB limit.
+  # Raised when trying to insert a document that exceeds the 4MB limit or
+  # when the document contains objects that can't be serialized as BSON.
   class InvalidDocument < MongoDBError; end
 
   # Raised when a database operation fails.

data/lib/mongo/gridfs.rb

@@ -14,3 +14,9 @@
 # limitations under the License.
 # ++
 require 'mongo/gridfs/grid_store'
+
+# GridFS is a specification for storing large binary objects in MongoDB.
+# See the documentation for GridFS::GridStore
+# @see GridFS::GridStore
+module GridFS
+end

data/lib/mongo/gridfs/grid_store.rb

@@ -20,25 +20,32 @@ require 'mongo/gridfs/chunk'
 
 module GridFS
 
-  # GridStore is an IO-like object that provides input and output for
-  # streams of data to Mongo. See Mongo's documentation about GridFS for
-  # storage implementation details.
+  # GridStore is an IO-like class that provides input and output for
+  # streams of data to MongoDB.
   #
-  # Example code:
+  # @example
   #
-  #   require 'mongo/gridfs'
-  #   GridStore.open(database, 'filename', 'w') { |f|
-  #     f.puts "Hello, world!"
-  #   }
-  #   GridStore.open(database, 'filename, 'r') { |f|
-  #     puts f.read         # => Hello, world!\n
-  #   }
-  #   GridStore.open(database, 'filename', 'w+') { |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
-  #   }
+  #  include GridFS
+  #
+  #  #Store the text "Hello, world!" in the grid store.
+  #  GridStore.open(database, 'filename', 'w') do |f|
+  #    f.puts "Hello, world!"
+  #  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!"
+  #  end
+  #
+  #  # Retrieve everything, outputting  "Hello, world!\nBut wait, there's more!\n"
+  #  GridStore.open(database, 'filename', 'r') do |f|
+  #    puts f.read
+  #  end
   class GridStore
 
     DEFAULT_ROOT_COLLECTION = 'fs'
@@ -70,80 +77,128 @@ module GridFS
 
     attr_reader :md5
 
-    class << self
-
-      def exist?(db, name, root_collection=DEFAULT_ROOT_COLLECTION)
-        db.collection("#{root_collection}.files").find({'filename' => name}).next_document != nil
-      end
+    # Determine whether a given file exists in the GridStore.
+    #
+    # @param [Mongo::DB] a MongoDB database.
+    # @param [String] name the filename.
+    # @param [String] root_collection the name of the gridfs root collection.
+    #
+    # @return [Boolean]
+    def self.exist?(db, name, root_collection=DEFAULT_ROOT_COLLECTION)
+      db.collection("#{root_collection}.files").find({'filename' => name}).next_document != nil
+    end
 
-      def open(db, name, mode, options={})
-        gs = self.new(db, name, mode, options)
-        result = nil
-        begin
-          result = yield gs if block_given?
-        ensure
-          gs.close
-        end
-        result
+    # Open a GridFS file for reading, writing, or appending. Note that
+    # this method must be used with a block.
+    #
+    # @param [Mongo::DB] a MongoDB database.
+    # @param [String] name the filename.
+    # @param [String] mode one of 'r', 'w', or 'w+' for reading, writing, 
+    #   and appending, respectively.
+    # @param [Hash] options any of the options available on 
+    #   GridStore initialization.
+    #
+    # @see GridStore#initialize.
+    # @see The various GridStore class methods, e.g., GridStore.open, GridStore.read etc.
+    def self.open(db, name, mode, options={})
+      gs = self.new(db, name, mode, options)
+      result = nil
+      begin
+        result = yield gs if block_given?
+      ensure
+        gs.close
       end
+      result
+    end
 
-      def read(db, name, length=nil, offset=nil)
-        GridStore.open(db, name, 'r') { |gs|
-          gs.seek(offset) if offset
-          gs.read(length)
-        }
+    # Read a file stored in GridFS.
+    #
+    # @param [Mongo::DB] db a MongoDB database.
+    # @param [String] name the name of the file.
+    # @param [Integer] length the number of bytes to read.
+    # @param [Integer] offset the number of bytes beyond the 
+    #   beginning of the file to start reading.
+    #
+    # @return [String] the file data
+    def self.read(db, name, length=nil, offset=nil)
+      GridStore.open(db, name, 'r') do |gs|
+        gs.seek(offset) if offset
+        gs.read(length)
       end
+    end
 
-      # List the contents of all GridFS files stored in the given db and
-      # root collection.
-      #
-      # :db :: the database to use
-      #
-      # :root_collection :: the root collection to use. If not specified, will use default root collection.
-      def list(db, root_collection=DEFAULT_ROOT_COLLECTION)
-        db.collection("#{root_collection}.files").find().map { |f|
-          f['filename']
-        }
+    # List the contents of all GridFS files stored in the given db and
+    # root collection.
+    #
+    # @param [Mongo::DB] db a MongoDB database.
+    # @param [String] root_collection the name of the root collection.
+    #
+    # @return [Array]
+    def self.list(db, root_collection=DEFAULT_ROOT_COLLECTION)
+      db.collection("#{root_collection}.files").find().map do |f|
+        f['filename']
       end
+    end
 
-      def readlines(db, name, separator=$/)
-        GridStore.open(db, name, 'r') { |gs|
-          gs.readlines(separator)
-        }
+    # Get each line of data from the specified file 
+    # as an array of strings.
+    #
+    # @param [Mongo::DB] db a MongoDB database.
+    # @param [String] name the filename.
+    # @param [String, Reg] separator
+    #
+    # @return [Array]
+    def self.readlines(db, name, separator=$/)
+      GridStore.open(db, name, 'r') do |gs|
+        gs.readlines(separator)
       end
+    end
 
-      def unlink(db, *names)
-        names.each { |name|
-          gs = GridStore.new(db, name)
-          gs.send(:delete_chunks)
-          gs.collection.remove('_id' => gs.files_id)
-        }
+    # Remove one for more files from the given db.
+    #
+    # @param [Mongo::Database] db a MongoDB database.
+    # @param [Array<String>] names the filenames to remove
+    #
+    # @return [True]
+    def self.unlink(db, *names)
+      names.each do |name|
+        gs = GridStore.new(db, name)
+        gs.send(:delete_chunks)
+        gs.collection.remove('_id' => gs.files_id)
       end
+    end
+    class << self
       alias_method :delete, :unlink
-
     end
 
-    #---
-    # ================================================================
-    #+++
+    # Rename a file in this collection. Note that this method uses
+    # Collection#update, which means that you will not be notified 
+    #
+    # @param [Mongo::DB] a MongoDB database.
+    # @param [String] src the name of the source file.
+    # @param [String] dest the name of the destination file.
+    # @param [String] root_collection the name of the default root collection.
+    def self.mv(db, src, dest, root_collection=DEFAULT_ROOT_COLLECTION)
+      db.collection("#{root_collection}.files").update({ :filename => src }, { '$set' => { :filename => dest } })
+    end
 
-    # Mode may only be 'r', 'w', or 'w+'.
+    # Initialize a GridStore instance for reading, writing, or modifying a given file.
+    # Note that it's often easier to work with the various GridStore class methods (open, read, etc.).
     #
-    # Options. Descriptions start with a list of the modes for which that
-    # option is legitimate.
+    # @param [Mongo::DB] db a MongoDB database.
+    # @param [String] name a filename.
+    # @param [String] mode either 'r', 'w', or 'w+' for reading, writing, or appending, respectively.
     #
-    # :root :: (r, w, w+) Name of root collection to use, instead of
-    #          DEFAULT_ROOT_COLLECTION.
+    # @option options [String] :root DEFAULT_ROOT_COLLECTION ('r', 'w', 'w+') the name of the root collection to use.
     #
-    # :metadata:: (w, w+) A hash containing any data you want persisted as
-    #                     this file's metadata. See also metadata=
+    # @option options [String] :metadata ({}) (w, w+) A hash containing any data you want persisted as
+    #   this file's metadata.
     #
-    # :chunk_size :: (w) Sets chunk size for files opened for writing
-    #                See also chunk_size= which may only be called before
-    #                any data is written.
+    # @option options [Integer] :chunk_size (Chunk::DEFAULT_CHUNK_SIZE) (w) Sets chunk size for files opened for writing.
+    #   See also GridStore#chunk_size=.
     #
-    # :content_type :: (w) Default value is DEFAULT_CONTENT_TYPE. See
-    #                  also #content_type=
+    # @option options [String] :content_type ('text/plain') Set the content type stored as the 
+    #   file's metadata. See also GridStore#content_type=.
     def initialize(db, name, mode='r', options={})
       @db, @filename, @mode = db, name, mode
       @root = options[:root] || DEFAULT_ROOT_COLLECTION
@@ -191,18 +246,26 @@ module GridFS
       @pushback_byte = nil
     end
 
+    # Get the files collection referenced by this GridStore instance.
+    #
+    # @return [Mongo::Collection]
     def collection
       @db.collection("#{@root}.files")
     end
 
-    # Returns collection used for storing chunks. Depends on value of
-    # @root.
+    # Get the chunk collection referenced by this GridStore.
+    #
+    # @return [Mongo::Collection]
     def chunk_collection
       @db.collection("#{@root}.chunks")
     end
 
-    # Change chunk size. Can only change if the file is opened for write
+    # Change the chunk size. This is permitted only when the file is opened for write
     # and no data has yet been written.
+    #
+    # @param [Integer] size the new chunk size, in bytes.
+    #
+    # @return [Integer] the new chunk size.
     def chunk_size=(size)
       unless @mode[0] == ?w && @position == 0 && @upload_date == nil
         raise "error: can only change chunk size if open for write and no data written."
@@ -210,9 +273,7 @@ module GridFS
       @chunk_size = size
     end
 
-    #---
     # ================ reading ================
-    #+++
 
     def getc
       if @pushback_byte
@@ -245,17 +306,6 @@ module GridFS
       str
     end
 
-    def old_read(len=nil, buf=nil)
-      buf ||= ''
-      byte = self.getc
-      while byte != nil && (len == nil || len > 0)
-        buf << byte.chr
-        len -= 1 if len
-        byte = self.getc if (len == nil || len > 0)
-      end
-      buf
-    end
-
     def read(len=nil, buf=nil)
       if len
         read_partial(len, buf)
@@ -302,9 +352,7 @@ module GridFS
       @position -= 1
     end
 
-    #---
     # ================ writing ================
-    #+++
 
     def putc(byte)
       if @curr_chunk.pos == @chunk_size
@@ -344,6 +392,10 @@ module GridFS
 
     def write(string)
       raise "#@filename not opened for write" unless @mode[0] == ?w
+      # Since Ruby 1.9.1 doesn't necessarily store one character per byte.
+      if string.respond_to?(:force_encoding)
+        string.force_encoding("binary")
+      end
       to_write = string.length
       while (to_write > 0) do
         if @curr_chunk && @curr_chunk.data.position == @chunk_size
@@ -363,9 +415,7 @@ module GridFS
     def flush
     end
 
-    #---
     # ================ status ================
-    #+++
 
     def eof
       raise IOError.new("stream not open for reading") unless @mode[0] == ?r
@@ -373,9 +423,7 @@ module GridFS
     end
     alias_method :eof?, :eof
 
-    #---
     # ================ positioning ================
-    #+++
 
     def rewind
       if @curr_chunk.chunk_number != 0

data/lib/mongo/types/binary.rb

@@ -18,7 +18,10 @@ require 'mongo/util/byte_buffer'
 
 module Mongo
 
-  # An array of binary bytes with a Mongo subtype value.
+  # An array of binary bytes with a MongoDB subtype. See the subtype
+  # constants for reference.
+  #
+  # Use this class when storing binary data in documents.
   class Binary < ByteBuffer
 
     SUBTYPE_BYTES = 0x02
@@ -29,6 +32,13 @@ module Mongo
     # One of the SUBTYPE_* constants. Default is SUBTYPE_BYTES.
     attr_accessor :subtype
 
+    # Create a buffer for storing binary data in MongoDB.
+    #
+    # @param [Array] initia_data
+    # @param [Fixnum] one of four values specifying a BSON binary subtype. Possible values are
+    #   SUBTYPE_BYTES, SUBTYPE_UUID, SUBTYPE_MD5, and SUBTYPE_USER_DEFINED.
+    #
+    # @see http://www.mongodb.org/display/DOCS/BSON#BSON-noteondatabinary BSON binary subtypes.
     def initialize(initial_data=[], subtype=SUBTYPE_BYTES)
       super(initial_data)
       @subtype = subtype

data/lib/mongo/types/code.rb

@@ -16,12 +16,17 @@
 
 module Mongo
 
-  # JavaScript code to be evaluated by MongoDB
+  # 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

data/lib/mongo/types/dbref.rb

@@ -16,13 +16,18 @@
 
 module Mongo
 
+  # 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
     def initialize(namespace, object_id)
-      @namespace, @object_id =
-        namespace, object_id
+      @namespace = namespace
+      @object_id = object_id
     end
 
     def to_s

data/lib/mongo/types/min_max_keys.rb

@@ -0,0 +1,58 @@
+# --
+# Copyright (C) 2008-2009 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 Mongo
+
+  # 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