github-migration
/
mongo-ruby-driver
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc cleanup and initial move to YARD

This commit is contained in:
Kyle Banker 2010-01-05 17:42:52 -05:00
parent 870892e04f
commit 2310a878ea
5 changed files with 203 additions and 156 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
lib/mongo.rb
View File

@ -41,4 +41,4 @@ require 'mongo/db'
require 'mongo/cursor' require 'mongo/cursor'
require 'mongo/collection' require 'mongo/collection'
require 'mongo/admin' require 'mongo/admin'
require 'mongo/gridfs'

329
lib/mongo/collection.rb
View File

@ -16,11 +16,23 @@
module Mongo module Mongo
# A named collection of records in a database. # A named collection of documents in a database.
class Collection class Collection
attr_reader :db, :name, :pk_factory, :hint attr_reader :db, :name, :pk_factory, :hint
# Initialize a collection object.
#
# @param [DB] db a MongoDB database instance.
# @param [String, Symbol] name the name of the collection.
#
# @raise [InvalidName]
# if collection name is empty, contains '$', or starts or ends with '.'
#
# @raise [TypeError]
# if collection name is not a string or symbol
#
# @return [Collection]
def initialize(db, name, pk_factory=nil) def initialize(db, name, pk_factory=nil)
case name case name
when Symbol, String when Symbol, String
@ -46,21 +58,30 @@ module Mongo
@hint = nil @hint = nil
end end
# Get a sub-collection of this collection by name. # Return a sub-collection of this collection by name. If 'users' is a collection, then
# 'users.comments' is a sub-collection of users.
# #
# Raises InvalidName if an invalid collection name is used. # @param [String] name
# the collection to return
# #
# :name :: the name of the collection to get # @raise [InvalidName]
# if passed an invalid collection name
#
# @return [Collection]
# the specified sub-collection
def [](name) def [](name)
name = "#{self.name}.#{name}" name = "#{self.name}.#{name}"
return Collection.new(db, name) if !db.strict? || db.collection_names.include?(name) return Collection.new(db, name) if !db.strict? || db.collection_names.include?(name)
raise "Collection #{name} doesn't exist. Currently in strict mode." raise "Collection #{name} doesn't exist. Currently in strict mode."
end end
# Set hint fields to use and return +self+. hint may be a single field # Set a hint field for query optimizer. Hint may be a single field
# name, array of field names, or a hash (preferably an OrderedHash). # name, array of field names, or a hash (preferably an [OrderedHash]).
# May be +nil+. # If using MongoDB > 1.1, you probably don't ever need to set a hint.
def hint=(hint) #
# @param [String, Array, OrderedHash] hint a single field, an array of
# fields, or a hash specifying fields
def hint=(hint=nil)
@hint = normalize_hint_fields(hint) @hint = normalize_hint_fields(hint)
self self
end end
@ -80,51 +101,49 @@ module Mongo
# evaluated cursors will be closed. If given no block +find+ returns a # evaluated cursors will be closed. If given no block +find+ returns a
# cursor. # cursor.
# #
# :selector :: A document (hash) specifying elements which must be # @param [Hash] selector
# present for a document to be included in the result set. # a document specifying elements which must be present for a
# document to be included in the result set.
# #
# Options: # @option opts [Array] :fields field names that should be returned in the result
# :fields :: Array of field names that should be returned in the result # set ("_id" will always be included). By limiting results to a certain subset of fields,
# set ("_id" will always be included). By limiting results # you can cut down on network traffic and decoding time.
# to a certain subset of fields you can cut down on network # @option opts [Integer] :skip number of documents to skip from the beginning of the result set
# traffic and decoding time. # @option opts [Integer] :limit maximum number of documents to return
# :skip :: Number of documents to omit (from the start of the result set) # @option opts [Array] :sort an array of [key, direction] pairs to sort by. Direction should
# when returning the results # be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
# :limit :: Maximum number of records to return # @option opts [String, Array, OrderedHash] :hint hint for query optimizer, usually not necessary if using MongoDB > 1.1
# :sort :: An array of [key, direction] pairs to sort by. Direction should # @option opts [Boolean] :snapshot ('false') if true, snapshot mode will be used for this query.
# be specified as Mongo::ASCENDING (or :ascending / :asc) or # Snapshot mode assures no duplicates are returned, or objects missed, which were preset at both the start and
# Mongo::DESCENDING (or :descending / :desc) # end of the query's execution. For details see http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database
# :hint :: See #hint. This option overrides the collection-wide value. # @option opts [Boolean] :timeout ('true') when +true+, the returned cursor will be subject to
# :snapshot :: If true, snapshot mode will be used for this query. # the normal cursor timeout behavior of the mongod process. When +false+, the returned cursor will never timeout. Note
# Snapshot mode assures no duplicates are returned, or # that disabling timeout will only work when #find is invoked with a block. This is to prevent any inadvertant failure to
# objects missed, which were preset at both the start and # close the cursor, as the cursor is explicitly closed when block code finishes.
# end of the query's execution. For details see #
# http://www.mongodb.org/display/DOCS/How+to+do+Snapshotting+in+the+Mongo+Database # @raise [ArgumentError]
# :timeout :: When +true+ (default), the returned cursor will be subject to # if timeout is set to false and find is not invoked in a block
# the normal cursor timeout behavior of the mongod process. #
# When +false+, the returned cursor will never timeout. Note # @raise [RuntimeError]
# that disabling timeout will only work when #find is invoked # if given unknown options
# with a block. This is to prevent any inadvertant failure to def find(selector={}, opts={})
# close the cursor, as the cursor is explicitly closed when fields = opts.delete(:fields)
# block code finishes.
def find(selector={}, options={})
fields = options.delete(:fields)
fields = ["_id"] if fields && fields.empty? fields = ["_id"] if fields && fields.empty?
skip = options.delete(:skip) || skip || 0 skip = opts.delete(:skip) || skip || 0
limit = options.delete(:limit) || 0 limit = opts.delete(:limit) || 0
sort = options.delete(:sort) sort = opts.delete(:sort)
hint = options.delete(:hint) hint = opts.delete(:hint)
snapshot = options.delete(:snapshot) snapshot = opts.delete(:snapshot)
if options[:timeout] == false && !block_given? if opts[:timeout] == false && !block_given?
raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block." raise ArgumentError, "Timeout can be set to false only when #find is invoked with a block."
end end
timeout = block_given? ? (options.delete(:timeout) || true) : true timeout = block_given? ? (opts.delete(:timeout) || true) : true
if hint if hint
hint = normalize_hint_fields(hint) hint = normalize_hint_fields(hint)
else else
hint = @hint # assumed to be normalized already hint = @hint # assumed to be normalized already
end end
raise RuntimeError, "Unknown options [#{options.inspect}]" unless options.empty? raise RuntimeError, "Unknown options [#{opts.inspect}]" unless opts.empty?
cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit, cursor = Cursor.new(self, :selector => selector, :fields => fields, :skip => skip, :limit => limit,
:order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout) :order => sort, :hint => hint, :snapshot => snapshot, :timeout => timeout)
@ -137,17 +156,22 @@ module Mongo
end end
end end
# Get a single object from the database. # Return a single object from the database.
# #
# Raises TypeError if the argument is of an improper type. Returns a # @return [OrderedHash, Nil]
# single document (hash), or nil if no result is found. # a single document or nil if no result is found.
# #
# :spec_or_object_id :: a hash specifying elements which must be # @param [Hash, ObjectID, Nil] spec_or_object_id a hash specifying elements
# present for a document to be included in the result set OR an # which must be present for a document to be included in the result set or an
# instance of ObjectID to be used as the value for an _id query. # instance of ObjectID to be used as the value for an _id query.
# if nil an empty spec, {}, will be used. # If nil, an empty selector, {}, will be used.
# :options :: options, as passed to Collection#find #
def find_one(spec_or_object_id=nil, options={}) # @option opts [Hash]
# any valid options that can be send to Collection#find
#
# @raise [TypeError]
# if the argument is of an improper type.
def find_one(spec_or_object_id=nil, opts={})
spec = case spec_or_object_id spec = case spec_or_object_id
when nil when nil
{} {}
@ -158,45 +182,45 @@ module Mongo
else else
raise TypeError, "spec_or_object_id must be an instance of ObjectID or Hash, or nil" raise TypeError, "spec_or_object_id must be an instance of ObjectID or Hash, or nil"
end end
find(spec, options.merge(:limit => -1)).next_document find(spec, opts.merge(:limit => -1)).next_document
end end
# Save a document in this collection. # Save a document to this collection.
# #
# If +to_save+ already has an '_id' then an update (upsert) operation # @param [Hash] doc
# is performed and any existing document with that _id is overwritten. # the document to be saved. If the document already has an '_id' key,
# Otherwise an insert operation is performed. Returns the _id of the # then an update (upsert) operation will be performed, and any existing
# saved document. # document with that _id is overwritten. Otherwise an insert operation is performed.
# #
# :to_save :: the document (a hash) to be saved # @return [ObjectID] the _id of the saved document.
# #
# Options: # @option opts [Boolean] :safe (+false+)
# :safe :: if true, check that the save succeeded. OperationFailure # If true, check that the save succeeded. OperationFailure
# will be raised on an error. Checking for safety requires an extra # will be raised on an error. Note that a safe check requires an extra
# round-trip to the database # round-trip to the database.
def save(to_save, options={}) def save(doc, options={})
if to_save.has_key?(:_id) || to_save.has_key?('_id') if doc.has_key?(:_id) || doc.has_key?('_id')
id = to_save[:_id] || to_save['_id'] id = doc[:_id] || doc['_id']
update({:_id => id}, to_save, :upsert => true, :safe => options.delete(:safe)) update({:_id => id}, doc, :upsert => true, :safe => options.delete(:safe))
id id
else else
insert(to_save, :safe => options.delete(:safe)) insert(doc, :safe => options.delete(:safe))
end end
end end
# Insert a document(s) into this collection. # Insert one or more documents into the collection.
# #
# "<<" is aliased to this method. Returns the _id of the inserted # @param [Hash, Array] doc_or_docs
# document or a list of _ids of the inserted documents. The object(s) # a document (as a hash) or array of documents to be inserted.
# may have been modified by the database's PK factory, if it has one.
# #
# :doc_or_docs :: a document (as a hash) or Array of documents to be # @return [ObjectID, Array]
# inserted # the _id of the inserted document or a list of _ids of all inserted documents.
# Note: the object may have been modified by the database's PK factory, if it has one.
# #
# Options: # @option opts [Boolean] :safe (+false+)
# :safe :: if true, check that the insert succeeded. OperationFailure # If true, check that the save succeeded. OperationFailure
# will be raised on an error. Checking for safety requires an extra # will be raised on an error. Note that a safe check requires an extra
# round-trip to the database # round-trip to the database.
def insert(doc_or_docs, options={}) def insert(doc_or_docs, options={})
doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array) doc_or_docs = [doc_or_docs] unless doc_or_docs.is_a?(Array)
doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) } doc_or_docs.collect! { |doc| @pk_factory.create_pk(doc) }
@ -205,15 +229,18 @@ module Mongo
end end
alias_method :<<, :insert alias_method :<<, :insert
# Remove all records from this collection. # Remove all documents from this collection.
# If +selector+ is specified, only matching documents will be removed.
# #
# Remove all records from the collection: # @param [Hash] selector
# @collection.remove # If specified, only matching documents will be removed.
# @collection.remove({})
# #
# Remove only records that have expired: # Examples
# @collection.remove({:expire => {'$lte' => Time.now}}) # @example: remove all documents from the 'users':
# @users.remove
# @users.remove({})
#
# @example: remove only documents that have expired:
# @users.remove({:expire => {'$lte' => Time.now}})
def remove(selector={}) def remove(selector={})
message = ByteBuffer.new message = ByteBuffer.new
message.put_int(0) message.put_int(0)
@ -226,21 +253,22 @@ module Mongo
# Update a single document in this collection. # Update a single document in this collection.
# #
# :selector :: a hash specifying elements which must be present for a document to be updated. Note: # @param [Hash] selector
# a hash specifying elements which must be present for a document to be updated. Note:
# the update command currently updates only the first document matching the # the update command currently updates only the first document matching the
# given selector. If you want all matching documents to be updated, be sure # given selector. If you want all matching documents to be updated, be sure
# to specify :multi => true. # to specify :multi => true.
# :document :: a hash specifying the fields to be changed in the # @param [Hash] document
# selected document, or (in the case of an upsert) the document to # a hash specifying the fields to be changed in the selected document,
# be inserted # or (in the case of an upsert) the document to be inserted
# #
# Options: # @option [Boolean] :upsert (+false+) if true, performs an upsert (update or insert)
# :upsert :: if true, perform an upsert operation # @option [Boolean] :multi (+false+) update all documents matching the selector, as opposed to
# :multi :: update all documents matching the selector, as opposed to # just the first matching document. Note: only works in MongoDB 1.1.3 or later.
# just the first matching document. Note: only works in 1.1.3 or later. # @option opts [Boolean] :safe (+false+)
# :safe :: if true, check that the update succeeded. OperationFailure # If true, check that the save succeeded. OperationFailure
# will be raised on an error. Checking for safety requires an extra # will be raised on an error. Note that a safe check requires an extra
# round-trip to the database # round-trip to the database.
def update(selector, document, options={}) def update(selector, document, options={})
message = ByteBuffer.new message = ByteBuffer.new
message.put_int(0) message.put_int(0)
@ -260,12 +288,13 @@ module Mongo
end end
end end
# Create a new index. +field_or_spec+ # Create a new index.
# should be either a single field name or a Array of [field name, #
# direction] pairs. Directions should be specified as # @param [String, Array] field_or_spec
# Mongo::ASCENDING or Mongo::DESCENDING. # should be either a single field name or an array of
# +unique+ is an optional boolean indicating whether this index # [field name, direction] pairs. Directions should be specified as Mongo::ASCENDING or Mongo::DESCENDING.
# should enforce a uniqueness constraint. #
# @param [Boolean] unique if true, this index will enforce a uniqueness constraint.
def create_index(field_or_spec, unique=false) def create_index(field_or_spec, unique=false)
field_h = OrderedHash.new field_h = OrderedHash.new
if field_or_spec.is_a?(String) || field_or_spec.is_a?(Symbol) if field_or_spec.is_a?(String) || field_or_spec.is_a?(Symbol)
@ -283,15 +312,19 @@ module Mongo
name name
end end
# Drop index +name+. # Drop a specified index.
#
# @param [String] name
def drop_index(name) def drop_index(name)
@db.drop_index(@name, name) @db.drop_index(@name, name)
end end
# Drop all indexes. # Drop all indexes.
def drop_indexes def drop_indexes
# just need to call drop indexes with no args; will drop them all
# Note: calling drop_indexes with no args will drop them all.
@db.drop_index(@name, '*') @db.drop_index(@name, '*')
end end
# Drop the entire collection. USE WITH CAUTION. # Drop the entire collection. USE WITH CAUTION.
@ -299,26 +332,26 @@ module Mongo
@db.drop_collection(@name) @db.drop_collection(@name)
end end
# Performs a map/reduce operation on the current collection. Returns a new # Perform a map/reduce operation on the current collection.
# collection containing the results of the operation.
# #
# Required: # @param [String, Code] map a map function, written in JavaScript.
# +map+ :: a map function, written in javascript. # @param [String, Code] reduce a reduce function, written in JavaScript.
# +reduce+ :: a reduce function, written in javascript.
# #
# Optional: # @option opts [Hash] :query ({}) a query selector document, like what's passed to #find, to limit
# :query :: a query selector document, like what's passed to #find, to limit
# the operation to a subset of the collection. # the operation to a subset of the collection.
# :sort :: sort parameters passed to the query. # @option opts [Array] :sort ([]) an array of [key, direction] pairs to sort by. Direction should
# :limit :: number of objects to return from the collection. # be specified as Mongo::ASCENDING (or :ascending / :asc) or Mongo::DESCENDING (or :descending / :desc)
# :finalize :: a javascript function to apply to the result set after the # @option opts [Integer] :limit (nil) if passing a query, number of objects to return from the collection.
# @option opts [String, Code] :finalize (nil) a javascript function to apply to the result set after the
# map/reduce operation has finished. # map/reduce operation has finished.
# :out :: the name of the output collection. if specified, the collection will not be treated as temporary. # @option opts [String] :out (nil) the name of the output collection. If specified, the collection will not be treated as temporary.
# :keeptemp :: if true, the generated collection will be persisted. default is false. # @option opts [Boolean] :keeptemp (false) if true, the generated collection will be persisted. default is false.
# :verbose :: if true, provides statistics on job execution time. # @option opts [Boolean ] :verbose (false) if true, provides statistics on job execution time.
# #
# For more information on using map/reduce, see http://www.mongodb.org/display/DOCS/MapReduce # @return [Collection] a collection containing the results of the operation.
def map_reduce(map, reduce, options={}) #
# @see http://www.mongodb.org/display/DOCS/MapReduce Offical MongoDB map/reduce documentation.
def map_reduce(map, reduce, opts={})
map = Code.new(map) unless map.is_a?(Code) map = Code.new(map) unless map.is_a?(Code)
reduce = Code.new(reduce) unless reduce.is_a?(Code) reduce = Code.new(reduce) unless reduce.is_a?(Code)
@ -326,7 +359,7 @@ module Mongo
hash['mapreduce'] = self.name hash['mapreduce'] = self.name
hash['map'] = map hash['map'] = map
hash['reduce'] = reduce hash['reduce'] = reduce
hash.merge! options hash.merge! opts
result = @db.command(hash) result = @db.command(hash)
unless result["ok"] == 1 unless result["ok"] == 1
@ -336,20 +369,20 @@ module Mongo
end end
alias :mapreduce :map_reduce alias :mapreduce :map_reduce
# Performs a group query, similar to the 'SQL GROUP BY' operation. # Perform a group aggregation.
# Returns an array of grouped items.
# #
# :key :: either 1) an array of fields to group by, 2) a javascript function to generate # @param [Array, String, Code, Nil] :key either 1) an array of fields to group by,
# the key object, or 3) nil. # 2) a javascript function to generate the key object, or 3) nil.
# :condition :: an optional document specifying a query to limit the documents over which group is run. # @param [Hash] condition an optional document specifying a query to limit the documents over which group is run.
# :initial :: initial value of the aggregation counter object # @param [Hash] initial initial value of the aggregation counter object
# :reduce :: aggregation function as a JavaScript string # @param [String, Code] reduce aggregation function, in JavaScript
# :finalize :: optional. a JavaScript function that receives and modifies # @param [String, Code] finalize :: optional. a JavaScript function that receives and modifies
# each of the resultant grouped objects. Available only when group is run # each of the resultant grouped objects. Available only when group is run
# with command set to true. # with command set to true.
# :command :: if true, run the group as a command instead of in an # @param [Boolean] command if true, run the group as a command instead of in an
# eval - it is likely that this option will eventually be # eval. Note: Running group as eval has been DEPRECATED.
# deprecated and all groups will be run as commands #
# @return [Array] the grouped items.
def group(key, condition, initial, reduce, command=false, finalize=nil) def group(key, condition, initial, reduce, command=false, finalize=nil)
if command if command
@ -443,9 +476,14 @@ EOS
end end
end end
# Returns a list of distinct values for +key+ across all # Return a list of distinct values for +key+ across all
# documents in the collection. The key may use dot notation # documents in the collection. The key may use dot notation
# to reach into an embedded object. # to reach into an embedded object.
#
# @param [String, Symbol, OrderedHash] key or hash to group by.
# @param [Hash] query a selector for limiting the result set over which to group.
#
# @example Saving zip codes and ages and returning distinct results.
# @collection.save({:zip => 10010, :name => {:age => 27}}) # @collection.save({:zip => 10010, :name => {:age => 27}})
# @collection.save({:zip => 94108, :name => {:age => 24}}) # @collection.save({:zip => 94108, :name => {:age => 24}})
# @collection.save({:zip => 10010, :name => {:age => 27}}) # @collection.save({:zip => 10010, :name => {:age => 27}})
@ -461,6 +499,8 @@ EOS
# to limit the documents over which distinct is run: # to limit the documents over which distinct is run:
# @collection.distinct("name.age", {"name.age" => {"$gt" => 24}}) # @collection.distinct("name.age", {"name.age" => {"$gt" => 24}})
# [27] # [27]
#
# @return [Array] an array of distinct values.
def distinct(key, query=nil) def distinct(key, query=nil)
raise MongoArgumentError unless [String, Symbol].include?(key.class) raise MongoArgumentError unless [String, Symbol].include?(key.class)
command = OrderedHash.new command = OrderedHash.new
@ -473,11 +513,12 @@ EOS
# Rename this collection. # Rename this collection.
# #
# If operating in auth mode, client must be authorized as an admin to # Note: If operating in auth mode, the client must be authorized as an admin to
# perform this operation. Raises +InvalidName+ if +new_name+ is an invalid # perform this operation.
# collection name.
# #
# :new_name :: new name for this collection # @param [String ] new_name the new name for this collection
#
# @raise [InvalidName] if +new_name+ is an invalid collection name.
def rename(new_name) def rename(new_name)
case new_name case new_name
when Symbol, String when Symbol, String
@ -500,23 +541,25 @@ EOS
@db.rename_collection(@name, new_name) @db.rename_collection(@name, new_name)
end end
# Get information on the indexes for the collection +collection_name+. # Get information on the indexes for this collection.
# Returns a hash where the keys are index names (as returned by #
# Collection#create_index and the values are lists of [key, direction] # @return [Hash] a hash where the keys are index names.
# pairs specifying the index (as passed to Collection#create_index).
def index_information def index_information
@db.index_information(@name) @db.index_information(@name)
end end
# Return a hash containing options that apply to this collection. # Return a hash containing options that apply to this collection.
# 'create' will be the collection name. For the other possible keys # For all possible keys and values, see DB#create_collection.
# and values, see DB#create_collection. #
# @return [Hash] options that apply to this collection.
def options def options
@db.collections_info(@name).next_document['options'] @db.collections_info(@name).next_document['options']
end end
# Get the number of documents in this collection. # Get the number of documents in this collection.
def count() #
# @return [Integer]
def count
find().count() find().count()
end end

7
lib/mongo/connection.rb
View File

@ -23,8 +23,7 @@ module Mongo
# A connection to MongoDB. # A connection to MongoDB.
class Connection class Connection
# We need to make sure that all connection abort when # Abort connections if a ConnectionError is raised.
# a ConnectionError is raised.
Thread.abort_on_exception = true Thread.abort_on_exception = true
DEFAULT_PORT = 27017 DEFAULT_PORT = 27017
@ -254,7 +253,7 @@ module Mongo
end end
# Creates a new socket and tries to connect to master. # Creates a new socket and tries to connect to master.
# If successful, sets @host and @port to master and returns the socket. # If successful, sets host and port to master and returns the socket.
def connect_to_master def connect_to_master
close close
@host = @port = nil @host = @port = nil
@ -286,7 +285,7 @@ module Mongo
end end
# Are we connected to MongoDB? This is determined by checking whether # Are we connected to MongoDB? This is determined by checking whether
# @host and @port have values, since they're set to nil on calls to #close. # host and port have values, since they're set to nil on calls to #close.
def connected? def connected?
@host && @port @host && @port
end end

3
lib/mongo/gridfs.rb
View File

@ -14,3 +14,6 @@
# limitations under the License. # limitations under the License.
# ++ # ++
require 'mongo/gridfs/grid_store' require 'mongo/gridfs/grid_store'
module GridFS
end

2
lib/mongo/util/support.rb
View File

@ -13,8 +13,10 @@
# See the License for the specific language governing permissions and # See the License for the specific language governing permissions and
# limitations under the License. # limitations under the License.
# ++ # ++
# nodoc
class Object class Object
# nodoc
def returning(value) def returning(value)
yield value yield value
value value