ashikawa-core 0.5.1 → 0.6.0

data/lib/ashikawa-core/connection.rb

@@ -1,17 +1,21 @@
 require "rest-client"
 require "json"
 require "uri"
+require "ashikawa-core/exceptions/index_not_found"
+require "ashikawa-core/exceptions/document_not_found"
+require "ashikawa-core/exceptions/collection_not_found"
+require "ashikawa-core/exceptions/unknown_path"
 
 module Ashikawa
   module Core
-    # Represents a Connection via HTTP to a certain host
+    # A Connection via HTTP to a certain host
     class Connection
       # The host part of the connection
       #
       # @return [String]
       # @api public
       # @example Get the host part of the connection
-      #   connection = Connection.new "http://localhost:8529"
+      #   connection = Connection.new("http://localhost:8529")
       #   connection.host # => "localhost"
       attr_reader :host
 
@@ -20,7 +24,7 @@ module Ashikawa
       # @return [String]
       # @api public
       # @example Get the scheme of the connection
-      #   connection = Connection.new "http://localhost:8529"
+      #   connection = Connection.new("http://localhost:8529")
       #   connection.scheme # => "http"
       attr_reader :scheme
 
@@ -29,52 +33,84 @@ module Ashikawa
       # @return [Fixnum]
       # @api public
       # @example Get the port of the connection
-      #   connection = Connection.new "http://localhost:8529"
+      #   connection = Connection.new("http://localhost:8529")
       #   connection.port # => 8529
       attr_reader :port
 
-      # Username and password of the connection
+      # Username of the connection if using authentication
+      # @note you can set these properties with the `authenticate_with` method
       #
-      # Needed if the database is running with HTTP base authentication
-      # enabled. Username and password are sent with every request to
-      # authenticate against the database.
-      #
-      # You can set these properties with the `authenticate_with` method
+      # @return String
+      # @api public
+      # @example Get the username of the connection
+      #   connection = Connection.new("http://localhost:8529")
+      #   connection.authenticate_with(:username => 'james', :password => 'bond')
+      #   connection.username # => 'james'
+      attr_reader :username
+
+      # Password of the connection if using authentication
+      # @note you can set these properties with the `authenticate_with` method
       #
+      # @return String
       # @api public
-      attr_reader :username, :password
+      # @example Get the password of the connection
+      #   connection = Connection.new("http://localhost:8529")
+      #   connection.authenticate_with(:username => 'james', :password => 'bond')
+      #   connection.password # => 'bond'
+      attr_reader :password
 
       # Initialize a Connection with a given API String
       #
       # @param [String] api_string scheme, hostname and port as a String
       # @api public
       # @example Create a new Connection
-      #  connection = Connection.new "http://localhost:8529"
+      #  connection = Connection.new("http://localhost:8529")
       def initialize(api_string = "http://localhost:8529")
-        uri     = URI api_string
+        uri     = URI(api_string)
         @host   = uri.host
         @port   = uri.port
         @scheme = uri.scheme
       end
 
       # Sends a request to a given path returning the parsed result
-      # (Prepends the api_string automatically)
+      # @note prepends the api_string automatically
       #
-      # @example get request
-      #   connection.send_request('/collection/new_collection')
-      # @example post request
-      #   connection.send_request('/collection/new_collection', :post => { :name => 'new_collection' })
       # @param [String] path the path you wish to send a request to.
       # @option params [Hash] :post POST data in case you want to send a POST request.
       # @return [Hash] parsed JSON response from the server
       # @api public
+      # @example get request
+      #   connection.send_request('/collection/new_collection')
+      # @example post request
+      #   connection.send_request('/collection/new_collection', :post => { :name => 'new_collection' })
       def send_request(path, params = {})
-        raw = raw_result_for path, params
-        JSON.parse raw
+        begin
+          raw = raw_result_for(path, params)
+        rescue RestClient::ResourceNotFound
+          resource_not_found_for(path)
+        end
+        JSON.parse(raw)
+      end
+
+      # Raise the fitting ResourceNotFoundException
+      #
+      # @raise [DocumentNotFoundException, CollectionNotFoundException, IndexNotFoundException]
+      # @return nil
+      # @api private
+      def resource_not_found_for(path)
+        path = path.split("/").delete_if { |part| part == "" }
+        resource = path.first
+
+        raise case resource
+          when "document" then DocumentNotFoundException
+          when "collection" then CollectionNotFoundException
+          when "index" then IndexNotFoundException
+          else UnknownPath
+        end
       end
 
       # Sends a request to a given path returning the raw result
-      # (Prepends the api_string automatically)
+      # @note prepends the api_string automatically
       #
       # @example get request
       #   connection.raw_result_for('/collection/new_collection')
@@ -85,15 +121,15 @@ module Ashikawa
       # @return [String] raw response from the server
       # @api public
       def raw_result_for(path, params = {})
-        path   = full_path path
+        path   = full_path(path)
         method = [:post, :put, :delete].find { |method_name|
-          params.has_key? method_name
+          params.has_key?(method_name)
         } || :get
 
-        if [:post, :put].include? method
-          RestClient.send method, path, params[method].to_json
+        if [:post, :put].include?(method)
+          RestClient.send(method, path, params[method].to_json)
         else
-          RestClient.send method, path
+          RestClient.send(method, path)
         end
       end
 
@@ -101,6 +137,11 @@ module Ashikawa
       #
       # @return [Boolean]
       # @api public
+      # @example Is authentication activated for this connection?
+      #   connection = Connection.new("http://localhost:8529")
+      #   connection.authentication? #=> false
+      #   connection.authenticate_with(:username => 'james', :password => 'bond')
+      #   connection.authentication? #=> true
       def authentication?
         !!@username
       end
@@ -112,6 +153,9 @@ module Ashikawa
       # @return [self]
       # @raise [ArgumentError] if username or password are missing
       # @api public
+      # @example Authenticate with the database for all future requests
+      #   connection = Connection.new("http://localhost:8529")
+      #   connection.authenticate_with(:username => 'james', :password => 'bond')
       def authenticate_with(options = {})
         if options.key? :username and options.key? :password
           @username = options[:username]
@@ -128,6 +172,10 @@ module Ashikawa
       # @param [String] path The API path
       # @return [String] Full path
       # @api public
+      # @example Get the full path
+      #   connection = Connection.new("http://localhost:8529")
+      #   connection.full_path('documents') #=> "http://localhost:8529/_api/documents"
+      #   connection.full_path('/documents') #=> "http://localhost:8529/_api/documents"
       def full_path(path)
         prefix = if authentication?
           "#{@scheme}://#{@username}:#{@password}@#{@host}:#{@port}"

data/lib/ashikawa-core/cursor.rb

@@ -2,7 +2,7 @@ require 'ashikawa-core/document'
 
 module Ashikawa
   module Core
-    # Represents a Cursor on a certain Database.
+    # A Cursor on a certain Database.
     # It is an enumerable.
     class Cursor
       include Enumerable
@@ -10,11 +10,17 @@ module Ashikawa
       # The ID of the cursor
       # @return [Int]
       # @api public
+      # @example Get the id of the cursor
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
+      #   cursor.id #=> 1337
       attr_reader :id
 
       # The number of documents
       # @return [Int]
       # @api public
+      # @example Get the number of documents
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
+      #   cursor.length #=> 23
       attr_reader :length
 
       # Initialize a Cursor with the database and raw data
@@ -22,39 +28,54 @@ module Ashikawa
       # @param [Database] database
       # @param [Hash] raw_cursor
       # @api public
+      # @example Create a new Cursor from the raw representation
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
       def initialize(database, raw_cursor)
         @database = database
-        parse_raw_cursor raw_cursor
+        parse_raw_cursor(raw_cursor)
       end
 
       # Iterate over the documents found by the cursor
       #
       # @yield [document]
+      # @return nil
       # @api public
-      def each(&block)
+      # @example Print all documents
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
+      #   cursor.each do |document|
+      #     p document
+      #   end
+      def each
         begin
           @current.each do |raw_document|
-            block.call Document.new(@database, raw_document)
+            yield Document.new(@database, raw_document)
           end
         end while next_batch
+        nil
       end
 
       # Delete the cursor
+      # @return [Hash] parsed JSON response from the server
       # @api public
+      # @example Delete the cursor
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
+      #   cursor.delete
       def delete
-        @database.send_request "/cursor/#{@id}", delete: {}
+        @database.send_request("/cursor/#{@id}", :delete => {})
       end
 
       private
 
       # Pull the raw data from the cursor into this object
       #
+      # @return self
       # @api private
       def parse_raw_cursor(raw_cursor)
-        @id       = raw_cursor['id'].to_i if raw_cursor.has_key? 'id'
+        @id       = raw_cursor['id'].to_i if raw_cursor.has_key?('id')
         @has_more = raw_cursor['hasMore']
-        @length   = raw_cursor['count'].to_i if raw_cursor.has_key? 'count'
+        @length   = raw_cursor['count'].to_i if raw_cursor.has_key?('count')
         @current  = raw_cursor['result']
+        self
       end
 
       # Get a new batch from the server
@@ -63,8 +84,8 @@ module Ashikawa
       # @api private
       def next_batch
         return false unless @has_more
-        raw_cursor = @database.send_request "/cursor/#{@id}", put: {}
-        parse_raw_cursor raw_cursor
+        raw_cursor = @database.send_request("/cursor/#{@id}", :put => {})
+        parse_raw_cursor(raw_cursor)
       end
     end
   end

data/lib/ashikawa-core/database.rb

@@ -1,3 +1,4 @@
+require "ashikawa-core/exceptions/collection_not_found"
 require "ashikawa-core/collection"
 require "ashikawa-core/connection"
 require "ashikawa-core/cursor"
@@ -5,29 +6,29 @@ require "forwardable"
 
 module Ashikawa
   module Core
-    # Represents an ArangoDB database in Ruby
+    # An ArangoDB database
     class Database
       extend Forwardable
 
       # Delegate sending requests to the connection
-      delegate send_request: :@connection
-      delegate host: :@connection
-      delegate port: :@connection
-      delegate scheme: :@connection
-      delegate authenticate_with: :@connection
+      def_delegator :@connection, :send_request
+      def_delegator :@connection, :host
+      def_delegator :@connection, :port
+      def_delegator :@connection, :scheme
+      def_delegator :@connection, :authenticate_with
 
       # Initializes the connection to the database
       #
       # @param [Connection, String] connection A Connection object or a String to create a Connection object.
       # @api public
       # @example Access a Database by providing the URL
-      #  database = Ashikawa::Core::Database.new "http://localhost:8529"
+      #  database = Ashikawa::Core::Database.new("http://localhost:8529")
       # @example Access a Database by providing a Connection
-      #  connection = Connection.new "http://localhost:8529"
+      #  connection = Connection.new("http://localhost:8529")
       #  database = Ashikawa::Core::Database.new connection
       def initialize(connection)
         if connection.class == String
-          @connection = Ashikawa::Core::Connection.new connection
+          @connection = Ashikawa::Core::Connection.new(connection)
         else
           @connection = connection
         end
@@ -38,13 +39,13 @@ module Ashikawa
       # @return [Array<Collection>]
       # @api public
       # @example Get an Array containing the Collections in the database
-      #   database = Ashikawa::Core::Database.new "http://localhost:8529"
+      #   database = Ashikawa::Core::Database.new("http://localhost:8529")
       #   database["a"]
       #   database["b"]
       #   database.collections # => [ #<Collection name="a">, #<Collection name="b">]
       def collections
-        server_response = send_request "/collection"
-        server_response["collections"].map { |collection| Ashikawa::Core::Collection.new self, collection }
+        server_response = send_request("/collection")
+        server_response["collections"].map { |collection| Ashikawa::Core::Collection.new(self, collection) }
       end
 
       # Get or create a Collection based on name or ID
@@ -53,27 +54,30 @@ module Ashikawa
       # @return [Collection]
       # @api public
       # @example Get a Collection from the database by name
-      #   database = Ashikawa::Core::Database.new "http://localhost:8529"
+      #   database = Ashikawa::Core::Database.new("http://localhost:8529")
       #   database["a"] # => #<Collection name="a">
       # @example Get a Collection from the database by ID
-      #   database = Ashikawa::Core::Database.new "http://localhost:8529"
+      #   database = Ashikawa::Core::Database.new("http://localhost:8529")
       #   database["7254820"] # => #<Collection id=7254820>
       def [](collection_identifier)
         begin
-          server_response = send_request "/collection/#{collection_identifier}"
-        rescue RestClient::ResourceNotFound
-          server_response = send_request "/collection", post: { name: collection_identifier }
+          server_response = send_request("/collection/#{collection_identifier}")
+        rescue CollectionNotFoundException
+          server_response = send_request("/collection", :post => { :name => collection_identifier })
         end
 
-        Ashikawa::Core::Collection.new self, server_response
+        Ashikawa::Core::Collection.new(self, server_response)
       end
 
       # Return a Query initialized with this database
       #
       # @return [Query]
       # @api public
+      # @example Send an AQL query to the database
+      #   database = Ashikawa::Core::Database.new("http://localhost:8529")
+      #   database.query.execute "FOR u IN users LIMIT 2" # => #<Cursor id=33>
       def query
-        Query.new self
+        Query.new(self)
       end
     end
   end

data/lib/ashikawa-core/document.rb

@@ -2,14 +2,14 @@ require 'ashikawa-core/exceptions/document_not_found'
 
 module Ashikawa
   module Core
-    # Represents a certain Document within a certain Collection
+    # A certain Document within a certain Collection
     class Document
       # The ID of the document without the Collection prefix
       #
       # @return [Int]
       # @api public
       # @example Get the ID for a Document
-      #   document = Ashikawa::Core::Document.new database, raw_document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
       #   document.id # => 2345678
       attr_reader :id
 
@@ -18,7 +18,7 @@ module Ashikawa
       # @return [Int]
       # @api public
       # @example Get the Revision for a Document
-      #   document = Ashikawa::Core::Document.new database, raw_document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
       #   document.revision # => 3456789
       attr_reader :revision
 
@@ -27,17 +27,23 @@ module Ashikawa
       # @param [Database] database
       # @param [Hash] raw_document
       # @api public
+      # @example Create a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
       def initialize(database, raw_document)
         @database = database
         @collection_id, @id = raw_document['_id'].split('/').map { |id| id.to_i } unless raw_document['_id'].nil?
         @revision = raw_document['_rev'].to_i unless raw_document['_rev'].nil?
-        @content = raw_document.delete_if { |key, value| key[0] == "_" }
+        @content = raw_document.delete_if { |key, value| key.start_with?("_") }
       end
 
       # Raises an exception if the document is not persisted
       #
       # @raise [DocumentNotFoundException]
-      # @api semi-public
+      # @return nil
+      # @api semipublic
+      # @example Check if the document is persisted
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document.check_if_persisted!
       def check_if_persisted!
         raise DocumentNotFoundException if @id.nil?
       end
@@ -45,25 +51,36 @@ module Ashikawa
       # Get the value of an attribute of the document
       #
       # @param [String] attribute_name
-      # @api public
       # @return [Object] The value of the attribute
+      # @api public
+      # @example Get the name attribute of a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document['name'] #=> 'Lebowski'
       def [](attribute_name)
         @content[attribute_name]
       end
 
       # Remove the document from the database
       #
+      # @return [Hash] parsed JSON response from the server
       # @api public
+      # @example Delete a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document.delete
       def delete
         check_if_persisted!
-        @database.send_request "document/#{@collection_id}/#{@id}", delete: {}
+        @database.send_request("document/#{@collection_id}/#{@id}", :delete => {})
       end
 
       # Update the value of an attribute (Does not write to database)
       #
       # @param [String] attribute_name
       # @param [Object] value
+      # @return [Object] The value
       # @api public
+      # @example Change the name attribute of a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document['name'] = 'The dude'
       def []=(attribute_name, value)
         check_if_persisted!
         @content[attribute_name] = value
@@ -73,16 +90,24 @@ module Ashikawa
       #
       # @return [Hash]
       # @api public
+      # @example Get the hash representation of a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document.to_hash #=> { :name => "Lebowski", :occupation => "Not occupied" }
       def to_hash
         @content
       end
 
       # Save the changes to the database
       #
+      # @return [Hash] parsed JSON response from the server
       # @api public
+      # @example Save changes to a document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document['occupation'] = 'Not occupied'
+      #   document.save
       def save()
         check_if_persisted!
-        @database.send_request "document/#{@collection_id}/#{@id}", put: @content
+        @database.send_request("document/#{@collection_id}/#{@id}", :put => @content)
       end
     end
   end