moped 1.0.0.beta → 1.0.0.rc

data/lib/moped/connection.rb

@@ -1,48 +1,60 @@
 require "timeout"
 
 module Moped
-  class Connection
-
-    class TCPSocket < ::TCPSocket
-      def self.connect(host, port, timeout)
-        Timeout::timeout(timeout) do
-          new(host, port).tap do |sock|
-            sock.set_encoding 'binary'
-          end
-        end
-      end
-
-      def alive?
-        if Kernel::select([self], nil, nil, 0)
-          !eof? rescue false
-        else
-          true
-        end
-      end
 
-      def write(*args)
-        raise Errors::ConnectionFailure, "Socket connection was closed by remote host" unless alive?
-        super
-      end
-    end
+  # This class contains behaviour of database socket connections.
+  #
+  # @api private
+  class Connection
 
-    def initialize
-      @sock = nil
-      @request_id = 0
+    # Is the connection alive?
+    #
+    # @example Is the connection alive?
+    #   connection.alive?
+    #
+    # @return [ true, false ] If the connection is alive.
+    #
+    # @since 1.0.0
+    def alive?
+      connected? ? @sock.alive? : false
     end
 
+    # Connect to the server.
+    #
+    # @example Connect to the server.
+    #   connection.connect("127.0.0.1", 27017, 30)
+    #
+    # @param [ String ] host The host to connect to.
+    # @param [ Integer ] post The server port.
+    # @param [ Integer ] timeout The connection timeout.
+    #
+    # @return [ TCPSocket ] The socket.
+    #
+    # @since 1.0.0
     def connect(host, port, timeout)
       @sock = TCPSocket.connect host, port, timeout
     end
 
-    def alive?
-      connected? ? @sock.alive? : false
-    end
-
+    # Is the connection connected?
+    #
+    # @example Is the connection connected?
+    #   connection.connected?
+    #
+    # @return [ true, false ] If the connection is connected.
+    #
+    # @since 1.0.0
     def connected?
       !!@sock
     end
 
+    # Disconnect from the server.
+    #
+    # @example Disconnect from the server.
+    #   connection.disconnect
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
     def disconnect
       @sock.close
     rescue
@@ -50,26 +62,27 @@ module Moped
       @sock = nil
     end
 
-    def write(operations)
-      buf = ""
-
-      operations.each do |operation|
-        operation.request_id = (@request_id += 1)
-        operation.serialize(buf)
-      end
-
-      @sock.write buf
-    end
-
-    def receive_replies(operations)
-      operations.map do |operation|
-        read if operation.is_a?(Protocol::Query) || operation.is_a?(Protocol::GetMore)
-      end
+    # Initialize the connection.
+    #
+    # @example Initialize the connection.
+    #   Connection.new
+    #
+    # @since 1.0.0
+    def initialize
+      @sock = nil
+      @request_id = 0
     end
 
+    # Read from the connection.
+    #
+    # @example Read from the connection.
+    #   connection.read
+    #
+    # @return [ Hash ] The returned document.
+    #
+    # @since 1.0.0
     def read
       reply = Protocol::Reply.allocate
-
       reply.length,
         reply.request_id,
         reply.response_to,
@@ -88,8 +101,100 @@ module Moped
           BSON::Document.deserialize(buffer)
         end
       end
-
       reply
     end
+
+    # Get the replies to the database operation.
+    #
+    # @example Get the replies.
+    #   connection.receive_replies(operations)
+    #
+    # @param [ Array<Message> ] operations The query or get more ops.
+    #
+    # @return [ Array<Hash> ] The returned deserialized documents.
+    #
+    # @since 1.0.0
+    def receive_replies(operations)
+      operations.map do |operation|
+        read if operation.is_a?(Protocol::Query) || operation.is_a?(Protocol::GetMore)
+      end
+    end
+
+    # Write to the connection.
+    #
+    # @example Write to the connection.
+    #   connection.write(data)
+    #
+    # @param [ Array<Message> ] operations The database operations.
+    #
+    # @return [ Integer ] The number of bytes written.
+    #
+    # @since 1.0.0
+    def write(operations)
+      buf = ""
+      operations.each do |operation|
+        operation.request_id = (@request_id += 1)
+        operation.serialize(buf)
+      end
+      @sock.write(buf)
+    end
+
+    # This is a wrapper around a tcp socket.
+    class TCPSocket < ::TCPSocket
+
+      # Is the socket connection alive?
+      #
+      # @example Is the socket alive?
+      #   socket.alive?
+      #
+      # @return [ true, false ] If the socket is alive.
+      #
+      # @since 1.0.0
+      def alive?
+        if Kernel::select([ self ], nil, nil, 0)
+          !eof? rescue false
+        else
+          true
+        end
+      end
+
+      # Write to the socket.
+      #
+      # @example Write to the socket.
+      #   socket.write(data)
+      #
+      # @param [ Object ] args The data to write.
+      #
+      # @return [ Integer ] The number of bytes written.
+      #
+      # @since 1.0.0
+      def write(*args)
+        raise Errors::ConnectionFailure, "Socket connection was closed by remote host" unless alive?
+        super
+      end
+
+      class << self
+
+        # Connect to the tcp server.
+        #
+        # @example Connect to the server.
+        #   TCPSocket.connect("127.0.0.1", 27017, 30)
+        #
+        # @param [ String ] host The host to connect to.
+        # @param [ Integer ] post The server port.
+        # @param [ Integer ] timeout The connection timeout.
+        #
+        # @return [ TCPSocket ] The socket.
+        #
+        # @since 1.0.0
+        def connect(host, port, timeout)
+          Timeout::timeout(timeout) do
+            new(host, port).tap do |sock|
+              sock.set_encoding('binary')
+            end
+          end
+        end
+      end
+    end
   end
 end

data/lib/moped/cursor.rb

@@ -1,13 +1,61 @@
 module Moped
 
+  # Contains logic for cursor behaviour.
+  #
   # @api private
   class Cursor
-    attr_reader :session
 
-    attr_reader :query_op
-    attr_reader :get_more_op
-    attr_reader :kill_cursor_op
+    # @attribute [r] get_more_op The get more message.
+    # @attribute [r] kill_cursor_op The kill cursor message.
+    # @attribute [r] query_op The query message.
+    # @attribute [r] session The session.
+    attr_reader :get_more_op, :kill_cursor_op, :query_op, :session
+
+    # Iterate over the results of the query.
+    #
+    # @example Iterate over the results.
+    #   cursor.each do |doc|
+    #     #...
+    #   end
+    #
+    # @return [ Enumerator ] The cursor enum.
+    #
+    # @since 1.0.0
+    def each
+      documents = load_docs
+      documents.each { |doc| yield doc }
+      while more?
+        return kill if limited? && @limit <= 0
+        documents = get_more
+        documents.each { |doc| yield doc }
+      end
+    end
 
+    # Get more documents from the database for the cursor. Executes a get more
+    # command.
+    #
+    # @example Get more docs.
+    #   cursor.get_more
+    #
+    # @return [ Array<Hash> ] The next batch of documents.
+    #
+    # @since 1.0.0
+    def get_more
+      reply = @node.get_more @database, @collection, @cursor_id, @limit
+      @limit -= reply.count if limited?
+      @cursor_id = reply.cursor_id
+      reply.documents
+    end
+
+    # Initialize the new cursor.
+    #
+    # @example Create the new cursor.
+    #   Cursor.new(session, message)
+    #
+    # @param [ Session ] session The session.
+    # @param [ Message ] query_operation The query message.
+    #
+    # @since 1.0.0
     def initialize(session, query_operation)
       @session = session
 
@@ -28,52 +76,61 @@ module Moped
       }
     end
 
-    def each
-      documents = load
-      documents.each { |doc| yield doc }
-
-      while more?
-        return kill if limited? && @limit <= 0
+    # Kill the cursor.
+    #
+    # @example Kill the cursor.
+    #   cursor.kill
+    #
+    # @return [ Object ] The result of the kill cursors command.
+    #
+    # @since 1.0.0
+    def kill
+      @node.kill_cursors([ @cursor_id ])
+    end
 
-        documents = get_more
-        documents.each { |doc| yield doc }
-      end
+    # Does the cursor have a limit provided in the query?
+    #
+    # @example Is the cursor limited?
+    #   cursor.limited?
+    #
+    # @return [ true, false ] If a limit has been provided over zero.
+    #
+    # @since 1.0.0
+    def limited?
+      @limited
     end
 
-    def load
+    # Load the documents from the database.
+    #
+    # @example Load the documents.
+    #   cursor.load_docs
+    #
+    # @return [ Array<Hash> ] The documents.
+    #
+    # @since 1.0.0
+    def load_docs
       consistency = session.consistency
       @options[:flags] |= [:slave_ok] if consistency == :eventual
 
       reply, @node = session.context.with_node do |node|
-        [node.query(@database, @collection, @selector, @options), node]
+        [ node.query(@database, @collection, @selector, @options), node ]
       end
 
       @limit -= reply.count if limited?
       @cursor_id = reply.cursor_id
-
       reply.documents
     end
 
-    def limited?
-      @limited
-    end
-
+    # Are there more documents to be returned from the database?
+    #
+    # @example Are there more documents?
+    #   cursor.more?
+    #
+    # @return [ true, false ] If there are more documents to load.
+    #
+    # @since 1.0.0
     def more?
       @cursor_id != 0
     end
-
-    def get_more
-      reply = @node.get_more @database, @collection, @cursor_id, @limit
-
-      @limit -= reply.count if limited?
-      @cursor_id = reply.cursor_id
-
-      reply.documents
-    end
-
-    def kill
-      @node.kill_cursors [@cursor_id]
-    end
   end
-
 end

data/lib/moped/database.rb

@@ -14,53 +14,85 @@ module Moped
   #   end
   class Database
 
-    # @return [Session] the database's session
-    attr_reader :session
-
-    # @return [String, Symbol] the database's name
-    attr_reader :name
-
-    # @param [Session] session the session
-    # @param [String, Symbol] name the database's name
-    def initialize(session, name)
-      @session = session
-      @name = name
-    end
+    # @attribute [r] name The name of the database.
+    # @attribute [r] session The session.
+    attr_reader :name, :session
 
     # Drop the database.
+    #
+    # @example Drop the database.
+    #   database.drop
+    #
+    # @return [ nil ] nil.
+    #
+    # @since 1.0.0
     def drop
       session.with(consistency: :strong) do |session|
-        session.context.command name, dropDatabase: 1
+        session.context.command(name, dropDatabase: 1)
       end
     end
 
+    # Initialize the database.
+    #
+    # @example Initialize a database object.
+    #   Database.new(session, :artists)
+    #
+    # @param [ Session ] session The session.
+    # @param [ String, Symbol ] name The name of the database.
+    #
+    # @since 1.0.0
+    def initialize(session, name)
+      @session, @name = session, name
+    end
+
     # Log in with +username+ and +password+ on the current database.
     #
-    # @param [String] username the username
-    # @param [String] password the password
+    # @example Authenticate against the database.
+    #   session.login("user", "pass")
+    #
+    # @param [ String ] username The username.
+    # @param [ String ] password The password.
+    #
+    # @since 1.0.0
     def login(username, password)
       session.context.login(name, username, password)
     end
 
     # Log out from the current database.
+    #
+    # @example Logout from the current database.
+    #   session.logout
+    #
+    # @since 1.0.0
     def logout
       session.context.logout(name)
     end
 
     # Run +command+ on the database.
     #
-    # @example
+    # @example Run a command.
     #   db.command(ismaster: 1)
     #   # => { "master" => true, hosts: [] }
     #
-    # @param [Hash] command the command to run
-    # @return [Hash] the result of the command
+    # @param [ Hash ] command The command to run.
+    #
+    # @return [ Hash ] the result of the command.
+    #
+    # @since 1.0.0
     def command(command)
       session.context.command name, command
     end
 
-    # @param [Symbol, String] collection the collection name
-    # @return [Moped::Collection] an instance of +collection+
+    # Get a collection by the provided name.
+    #
+    # @example Get a collection.
+    #   session[:users]
+    #
+    # @param [ Symbol, String ] collection The collection name.
+    #
+    # @return [ Collection ] An instance of the collection.
+    #
+    # @since 1.0.0
     def [](collection)
       Collection.new(self, collection)
     end