moped 1.0.0.beta → 1.0.0.rc

data/lib/moped/protocol/delete.rb

@@ -76,6 +76,7 @@ module Moped
         @flags                = options[:flags]
       end
 
+      undef op_code
       # @return [Number] OP_DELETE operation code (2006)
       def op_code
         2006

data/lib/moped/protocol/get_more.rb

@@ -43,6 +43,7 @@ module Moped
       # @return [Number] the id of the cursor to get more documents from
       int64    :cursor_id
 
+      undef op_code
       # @return [Number] OP_GETMORE operation code (2005)
       def op_code
         2005

data/lib/moped/protocol/insert.rb

@@ -46,6 +46,7 @@ module Moped
       # @return [Array<Hash>] the documents to insert
       document :documents, type: :array
 
+      undef op_code
       # @return [Number] OP_INSERT operation code (2002)
       def op_code
         2002

data/lib/moped/protocol/kill_cursors.rb

@@ -35,6 +35,7 @@ module Moped
       # @return [Array] the cursor ids to kill
       int64    :cursor_ids, type: :array
 
+      undef op_code
       # @return [Number] OP_KILL_CURSORS operation code (2007)
       def op_code
         2007

data/lib/moped/protocol/message.rb

@@ -152,8 +152,6 @@ module Moped
         # @param [String] name the name of this field
         # @param [Hash{Symbol => Number}] flags the flags for this flag field
         def flags(name, flag_map = {})
-          attr_writer name
-
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def #{name}
               @#{name} ||= []

data/lib/moped/protocol/query.rb

@@ -64,6 +64,7 @@ module Moped
       # @return [Hash, nil] the fields to include in the reply
       document :fields, :optional => true
 
+      undef op_code
       # @return [Number] OP_QUERY operation code (2004)
       def op_code
         2004

data/lib/moped/protocol/update.rb

@@ -56,6 +56,7 @@ module Moped
       # @return [Hash] the updates to apply
       document :update
 
+      undef op_code
       # @return [Number] OP_UPDATE operation code (2001)
       def op_code
         2001

data/lib/moped/query.rb

@@ -19,56 +19,65 @@ module Moped
   class Query
     include Enumerable
 
-    # @return [Collection] the query's collection
-    attr_reader :collection
+    # @attribute [r] collection The collection to execute the query on.
+    # @attribute [r] operation The query operation.
+    # @attribute [r] selector The query selector.
+    attr_reader :collection, :operation, :selector
 
-    # @return [Hash] the query's selector
-    attr_reader :selector
-
-    # @api private
-    attr_reader :operation
-
-    # @param [Collection] collection the query's collection
-    # @param [Hash] selector the query's selector
-    def initialize(collection, selector)
-      @collection = collection
-      @selector = selector
-
-      @operation = Protocol::Query.new(
-        collection.database.name,
-        collection.name,
-        selector
+    # Get the count of matching documents in the query.
+    #
+    # @example Get the count.
+    #   db[:people].find.count
+    #
+    # @return [ Integer ] The number of documents that match the selector.
+    #
+    # @since 1.0.0
+    def count
+      result = collection.database.command(
+        count: collection.name,
+        query: selector
       )
+      result["n"].to_i
     end
 
-    # Set the query's limit.
+    # Get the distinct values in the collection for the provided key.
     #
-    # @param [Numeric] limit
-    # @return [Query] self
-    def limit(limit)
-      operation.limit = limit
-      self
-    end
-
-    # Set the number of documents to skip.
+    # @example Get the distinct values.
+    #   db[:people].find.distinct(:name)
     #
-    # @param [Numeric] skip
-    # @return [Query] self
-    def skip(skip)
-      operation.skip = skip
-      self
+    # @param [ Symbol, String ] key The name of the field.
+    #
+    # @return [ Array<Object ] The distinct values.
+    #
+    # @since 1.0.0
+    def distinct(key)
+      result = collection.database.command(
+        distinct: collection.name,
+        key: key.to_s,
+        query: selector
+      )
+      result["values"]
     end
 
-    # Set the sort order for the query.
+    # Iterate through documents matching the query's selector.
     #
-    # @example
-    #   db[:people].find.sort(name: 1, age: -1).one
+    # @example Iterate over the matching documents.
+    #   db[:people].find.each do |doc|
+    #     #...
+    #   end
     #
-    # @param [Hash] sort
-    # @return [Query] self
-    def sort(sort)
-      operation.selector = { "$query" => selector, "$orderby" => sort }
-      self
+    # @return [ Enumerator ] The enumerator.
+    #
+    # @since 1.0.0
+    #
+    # @yieldparam [ Hash ] document each matching document
+    def each
+      cursor = Cursor.new(session, operation)
+      cursor.to_enum.tap do |enum|
+        enum.each do |document|
+          yield document
+        end if block_given?
+      end
     end
 
     # Explain the current query.
@@ -77,6 +86,8 @@ module Moped
     #   db[:people].find.explain
     #
     # @return [ Hash ] The explain document.
+    #
+    # @since 1.0.0
     def explain
       operation.selector = {
         "$query" => selector,
@@ -85,19 +96,14 @@ module Moped
       } and first
     end
 
-    # Set the fields to return from the query.
+    # Get the first matching document.
     #
-    # @example
-    #   db[:people].find.select(name: 1).one # => { name: "John" }
+    # @example Get the first matching document.
+    #   db[:people].find.first
     #
-    # @param [Hash] select
-    # @return [Query] self
-    def select(select)
-      operation.fields = select
-      self
-    end
-
-    # @return [Hash] the first document that matches the selector.
+    # @return [ Hash ] The first document that matches the selector.
+    #
+    # @since 1.0.0
     def first
       reply = session.context.query(
         operation.database,
@@ -110,113 +116,177 @@ module Moped
       )
       reply.documents.first
     end
-    alias one first
+    alias :one :first
 
-    # Iterate through documents matching the query's selector.
+    # Initialize the query.
     #
-    # @yieldparam [Hash] document each matching document
-    def each
-      cursor = Cursor.new(session, operation)
-      cursor.to_enum.tap do |enum|
-        enum.each do |document|
-          yield document
-        end if block_given?
+    # @example Initialize the query.
+    #   Query.new(collection, selector)
+    #
+    # @param [ Collection ] collection The query's collection.
+    # @param [ Hash ] selector The query's selector.
+    #
+    # @since 1.0.0
+    def initialize(collection, selector)
+      @collection, @selector = collection, selector
+      @operation = Protocol::Query.new(
+        collection.database.name,
+        collection.name,
+        selector
+      )
+    end
+
+    # Set the query's limit.
+    #
+    # @example Set the limit.
+    #   db[:people].find.limit(20)
+    #
+    # @param [ Integer ] limit The number of documents to limit.
+    #
+    # @return [ Query ] self
+    #
+    # @since 1.0.0
+    def limit(limit)
+      operation.limit = limit
+      self
+    end
+
+    # Remove a single document matching the query's selector.
+    #
+    # @example Remove a single document.
+    #   db[:people].find(name: "John").remove
+    #
+    # @return [ Hash, nil ] If in safe mode the last error result.
+    #
+    # @since 1.0.0
+    def remove
+      session.with(consistency: :strong) do |session|
+        session.context.remove(
+          operation.database,
+          operation.collection,
+          operation.selector,
+          flags: [ :remove_first ]
+        )
       end
     end
 
-    # Get the distinct values in the collection for the provided key.
+    # Remove multiple documents matching the query's selector.
     #
-    # @example Get the distinct values.
-    #   query.distinct(:name)
+    # @example Remove all matching documents.
+    #   db[:people].find(name: "John").remove_all
     #
-    # @param [ Symbol, String ] key The name of the field.
+    # @return [ Hash, nil ] If in safe mode the last error result.
     #
-    # @return [ Array<Object ] The distinct values.
-    def distinct(key)
-      result = collection.database.command(
-        distinct: collection.name,
-        key: key.to_s,
-        query: selector
-      )
+    # @since 1.0.0
+    def remove_all
+      session.with(consistency: :strong) do |session|
+        session.context.remove(
+          operation.database,
+          operation.collection,
+          operation.selector
+        )
+      end
+    end
 
-      result["values"]
+    # Set the fields to include or exclude from the query.
+    #
+    # @example Select the fields to include or exclude.
+    #   db[:people].find.select(name: 1).one # => { name: "John" }
+    #
+    # @param [ Hash ] select The inclusions or exclusions.
+    #
+    # @return [ Query ] self
+    #
+    # @since 1.0.0
+    def select(select)
+      operation.fields = select
+      self
     end
 
-    # @return [Numeric] the number of documents that match the selector.
-    def count
-      result = collection.database.command(
-        count: collection.name,
-        query: selector
-      )
+    # Set the number of documents to skip.
+    #
+    # @example Set the number to skip.
+    #   db[:people].find.skip(20)
+    #
+    # @param [ Integer ] skip The number of documents to skip.
+    #
+    # @return [ Query ] self
+    #
+    # @since 1.0.0
+    def skip(skip)
+      operation.skip = skip
+      self
+    end
 
-      result["n"]
+    # Set the sort order for the query.
+    #
+    # @example Set the sort order.
+    #   db[:people].find.sort(name: 1, age: -1).one
+    #
+    # @param [ Hash ] sort The order as key/(1/-1) pairs.
+    #
+    # @return [ Query ] self
+    #
+    # @since 1.0.0
+    def sort(sort)
+      operation.selector = { "$query" => selector, "$orderby" => sort }
+      self
     end
 
     # Update a single document matching the query's selector.
     #
-    # @example
+    # @example Update the first matching document.
     #   db[:people].find(_id: 1).update(name: "John")
     #
-    # @param [Hash] change the changes to make to the document
-    # @param [Array] flags an array of operation flags. Valid values are:
+    # @param [ Hash ] change The changes to make to the document
+    # @param [ Array ] flags An array of operation flags. Valid values are:
     #   +:multi+ and +:upsert+
+    #
+    # @return [ Hash, nil ] If in safe mode the last error result.
+    #
+    # @since 1.0.0
     def update(change, flags = nil)
       session.with(consistency: :strong) do |session|
-        session.context.update operation.database,
+        session.context.update(
+          operation.database,
           operation.collection,
           operation.selector,
           change,
           flags: flags
+        )
       end
     end
 
     # Update multiple documents matching the query's selector.
     #
-    # @example
+    # @example Update multiple documents.
     #   db[:people].find(name: "John").update_all(name: "Mary")
     #
-    # @param [Hash] change the changes to make to the documents
+    # @param [ Hash ] change The changes to make to the documents
+    #
+    # @return [ Hash, nil ] If in safe mode the last error result.
+    #
+    # @since 1.0.0
     def update_all(change)
-      update change, [:multi]
+      update(change, [ :multi ])
     end
 
     # Update an existing document with +change+, otherwise create one.
     #
-    # @example
+    # @example Upsert the changes.
     #   db[:people].find.entries # => { name: "John" }
     #   db[:people].find(name: "John").upsert(name: "James")
     #   db[:people].find.entries # => { name: "James" }
     #   db[:people].find(name: "John").upsert(name: "Mary")
     #   db[:people].find.entries # => [{ name: "James" }, { name: "Mary" }]
     #
-    # @param [Hash] change the changes to make to the the document
-    def upsert(change)
-      update change, [:upsert]
-    end
-
-    # Remove a single document matching the query's selector.
+    # @param [ Hash ] change The changes to make to the the document.
     #
-    # @example
-    #   db[:people].find(name: "John").remove
-    def remove
-      session.with(consistency: :strong) do |session|
-        session.context.remove operation.database,
-          operation.collection,
-          operation.selector,
-          flags: [:remove_first]
-      end
-    end
-
-    # Remove multiple documents matching the query's selector.
+    # @return [ Hash, nil ] If in safe mode the last error result.
     #
-    # @example
-    #   db[:people].find(name: "John").remove_all
-    def remove_all
-      session.with(consistency: :strong) do |session|
-        session.context.remove operation.database,
-          operation.collection,
-          operation.selector
-      end
+    # @since 1.0.0
+    def upsert(change)
+      update(change, [ :upsert ])
     end
 
     private

data/lib/moped/session.rb

@@ -30,54 +30,81 @@ module Moped
   class Session
     extend Forwardable
 
-    # @return [Hash] this session's options
-    attr_reader :options
-
-    # @private
-    # @return [Cluster] this session's cluster
-    attr_reader :cluster
-
-    # @private
-    # @return [Context] this session's context
-    attr_reader :context
-
-    # @param [Array] seeds an of host:port pairs
-    # @param [Hash] options
-    # @option options [Boolean] :safe (false) ensure writes are persisted
-    # @option options [Hash] :safe ensure writes are persisted with the
-    #   specified safety level e.g., "fsync: true", or "w: 2, wtimeout: 5"
-    # @option options [Symbol, String] :database the database to use
-    # @option options [:strong, :eventual] :consistency (:eventual)
-    def initialize(seeds, options = {})
-      @cluster = Cluster.new(seeds, {})
-      @context = Context.new(self)
-      @options = options
-      @options[:consistency] ||= :eventual
-    end
+    # @attribute [r] cluster The session cluster.
+    # @attribute [r] context The session context.
+    # @attribute [r] options The session options.
+    attr_reader :cluster, :context, :options
 
-    # @return [Boolean] whether the current session requires safe operations.
-    def safe?
-      !!safety
-    end
+    # @method [](collection)
+    # Return +collection+ from the current database.
+    #
+    # @param (see Moped::Database#[])
+    # @return (see Moped::Database#[])
+    delegate :"[]" => :current_database
+
+    # @method command(command)
+    # Run +command+ on the current database.
+    #
+    # @param (see Moped::Database#command)
+    # @return (see Moped::Database#command)
+    delegate :command => :current_database
 
-    # @return [:strong, :eventual] the session's consistency
+    # @method drop
+    # Drop the current database.
+    #
+    # @param (see Moped::Database#drop)
+    # @return (see Moped::Database#drop)
+    delegate :drop => :current_database
+
+    # @method login(username, password)
+    # Log in with +username+ and +password+ on the current database.
+    #
+    # @param (see Moped::Database#login)
+    # @raise (see Moped::Database#login)
+    delegate :login => :current_database
+
+    # @method logout
+    # Log out from the current database.
+    #
+    # @param (see Moped::Database#logout)
+    # @raise (see Moped::Database#login)
+    delegate :logout => :current_database
+
+    # Get the session's consistency.
+    #
+    # @example Get the session consistency.
+    #   session.consistency
+    #
+    # @return [ :strong, :eventual ] The session's consistency.
+    #
+    # @since 1.0.0
     def consistency
       options[:consistency]
     end
 
-    # Switch the session's current database.
+    # Initialize a new database session.
     #
-    # @example
-    #   session.use :moped
-    #   session[:people].find.one # => { :name => "John" }
+    # @example Initialize a new session.
+    #   Session.new([ "localhost:27017" ])
     #
-    # @param [String] database the database to use
-    def use(database)
-      options[:database] = database
-      set_current_database database
+    # @param [ Array ] seeds an of host:port pairs
+    # @param [ Hash ] options
+    #
+    # @option options [ Boolean ] :safe (false) Ensure writes are persisted.
+    # @option options [ Hash ] :safe Ensure writes are persisted with the
+    #   specified safety level e.g., "fsync: true", or "w: 2, wtimeout: 5".
+    # @option options [ Symbol, String ] :database The database to use.
+    # @option options [ :strong, :eventual ] :consistency (:eventual).
+    #
+    # @since 1.0.0
+    def initialize(seeds, options = {})
+      @cluster = Cluster.new(seeds, {})
+      @context = Context.new(self)
+      @options = options
+      @options[:consistency] ||= :eventual
     end
 
-    # Create a new session with +options+ reusing existing connections.
+    # Create a new session with +options+ and use new socket connections.
     #
     # @example Change safe mode
     #   session.with(safe: { w: 2 })[:people].insert(name: "Joe")
@@ -100,29 +127,18 @@ module Moped
     #     end
     #   end
     #
-    # @yieldparam [Moped::Session] session the new session
-    # @return [Moped::Session, Object] the new session, or the value returned
-    #   by the block if provided.
-    def with(options = {})
-      session = dup
-      session.options.update options
-
-      if block_given?
-        yield session
-      else
-        session
-      end
-    end
-
-    # Create a new session with +options+ and use new socket connections.
+    # @param [ Hash ] options The options.
+    #
+    # @return [ Session ] The new session.
     #
     # @see #with
-    # @yieldparam [Moped::Session] session the new session
-    # @return [Moped::Session] the new session
+    #
+    # @since 1.0.0
+    #
+    # @yieldparam [ Session ] session The new session.
     def new(options = {})
       session = with(options)
       session.instance_variable_set(:@cluster, cluster.dup)
-
       if block_given?
         yield session
       else
@@ -130,52 +146,88 @@ module Moped
       end
     end
 
-    # @method [](collection)
-    # Return +collection+ from the current database.
+    # Is the session operating in safe mode?
     #
-    # @param (see Moped::Database#[])
-    # @return (see Moped::Database#[])
-    delegate :"[]" => :current_database
-
-    # @method command(command)
-    # Run +command+ on the current database.
+    # @example Is the session operating in safe mode?
+    #   session.safe?
     #
-    # @param (see Moped::Database#command)
-    # @return (see Moped::Database#command)
-    delegate :command => :current_database
-
-    # @method drop
-    # Drop the current database.
+    # @return [ true, false ] Whether the current session requires safe
+    #   operations.
     #
-    # @param (see Moped::Database#drop)
-    # @return (see Moped::Database#drop)
-    delegate :drop => :current_database
+    # @since 1.0.0
+    def safe?
+      !!safety
+    end
 
-    # @method login(username, password)
-    # Log in with +username+ and +password+ on the current database.
+    # Get the safety level for the session.
     #
-    # @param (see Moped::Database#login)
-    # @raise (see Moped::Database#login)
-    delegate :login => :current_database
-
-    # @method logout
-    # Log out from the current database.
+    # @example Get the safety level.
+    #   session.safety
     #
-    # @param (see Moped::Database#logout)
-    # @raise (see Moped::Database#login)
-    delegate :logout => :current_database
-
-    # @return [Boolean, Hash] the safety level for this session
+    # @return [ Boolean, Hash ] The safety level for this session.
+    #
+    # @since 1.0.0
     def safety
       safe = options[:safe]
-
       case safe
-      when false
-        false
-      when true
-        { safe: true }
+      when false then false
+      when true then { safe: true }
+      else safe
+      end
+    end
+
+    # Switch the session's current database.
+    #
+    # @example Switch the current database.
+    #   session.use :moped
+    #   session[:people].find.one # => { :name => "John" }
+    #
+    # @param [ String, Symbol ] database The database to use.
+    #
+    # @since 1.0.0
+    def use(database)
+      options[:database] = database
+      set_current_database database
+    end
+
+    # Create a new session with +options+ reusing existing connections.
+    #
+    # @example Change safe mode
+    #   session.with(safe: { w: 2 })[:people].insert(name: "Joe")
+    #
+    # @example Change safe mode with block
+    #   session.with(safe: { w: 2 }) do |session|
+    #     session[:people].insert(name: "Joe")
+    #   end
+    #
+    # @example Temporarily change database
+    #   session.with(database: "admin") do |admin|
+    #     admin.command ismaster: 1
+    #   end
+    #
+    # @example Copy between databases
+    #   session.use "moped"
+    #   session.with(database: "backup") do |backup|
+    #     session[:people].each do |person|
+    #       backup[:people].insert person
+    #     end
+    #   end
+    #
+    # @param [ Hash ] options The session options.
+    #
+    # @return [ Session, Object ] The new session, or the value returned
+    #   by the block if provided.
+    #
+    # @since 1.0.0
+    #
+    # @yieldparam [ Session ] session The new session.
+    def with(options = {})
+      session = dup
+      session.options.update(options)
+      if block_given?
+        yield session
       else
-        safe
+        session
       end
     end
 
@@ -191,10 +243,6 @@ module Moped
       end
     end
 
-    def set_current_database(database)
-      @current_database = Database.new(self, database)
-    end
-
     def initialize_copy(_)
       @context = Context.new(self)
       @options = @options.dup
@@ -203,5 +251,9 @@ module Moped
         remove_instance_variable :@current_database
       end
     end
+
+    def set_current_database(database)
+      @current_database = Database.new(self, database)
+    end
   end
 end