ashikawa-core 0.1 → 0.2

data/Guardfile

@@ -0,0 +1,18 @@
+guard 'bundler' do
+  watch(/^.+\.gemspec/)
+end
+
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+end
+
+guard 'rspec', :version => 2, :spec_paths => "spec/unit" do
+  watch(%r{lib/.+\.rb})
+  watch(%r{spec/.+\.rb})
+end
+
+guard 'rspec', :version => 2, :spec_paths => "spec/integration" do
+  watch(%r{lib/.+\.rb})
+  watch(%r{spec/.+\.rb})
+end
+

data/README.md

@@ -1,6 +1,7 @@
 # Ashikawa Core
 
 [![Build Status](https://secure.travis-ci.org/triAGENS/ashikawa-core.png?branch=master)](http://travis-ci.org/triAGENS/ashikawa-core)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/triAGENS/ashikawa-core)
 
 Ashikawa Core is a Wrapper around the ArangoDB Rest API. It provides low level access and will be used in different ArangoDB ODMs.
 
@@ -39,6 +40,14 @@ Now you can run `rake` to see all tests passing (hopefully). Happy coding!
 
 You can also start up yard for documentation: `rake yard:server`
 
+### Guard
+
+Guard is a tool for comfortable development. If you want to use it for development, you have to first start an instance of ArangoDB and then start guard with `guard`. This will:
+
+* Run a documentation server on `http://localhost:8808`
+* Run `bundle` whenever you change the dependencies
+* Run the integration and unit tests whenever you change a file in the lib or spec directory
+
 ### Continuous Integration
 
 Our tests are run on Travis CI, the build status is displayed above. **Please note** that it only runs the unit tests and not the integration tests, because that would require ArangoDB to be installed on the Travis CI boxes. *Therefore green doesn't neccessarily mean green* (which is unfortunate).
@@ -50,14 +59,5 @@ When you want to write code for the project, please follow these guidelines:
 1. Claim the ticket: Tell us that you want to work on a certain ticket, we will assign it to you (We don't want two people to work on the same thing ;) )
 2. Write an Integration Test: Describe what you want to do (our integration tests touch the database)
 3. Implement it: Write a unit test, check that it fails, make the test pass – repeat (our unit tests don't touch the database)
-4. Write Documentation for it: Check the compatibility with our rules via *yardstick*
+4. Write Documentation for it.
 5. Check with `rake` that everything is fine and send the Pull Request :)
-
-## Documentation
-
-We want `Ashikawa::Core` to be a solid foundation for all Ruby Libraries connecting to ArangoDB. Therefore we want an excellent documentation. We created two rake tasks:
-
-* `rake yard:report`: Measure docs in lib/**/*.rb with yardstick
-* `rake yard:verify`: Verify that yardstick coverage is 100%
-
-The Yardstick coverage will be checked by our CI. Please make sure that the coverage is always at 100%.

data/Rakefile

@@ -9,6 +9,7 @@ require "rspec/core/rake_task"
 namespace :spec do
   desc "Run the integration tests. Requires ArangoDB."
   RSpec::Core::RakeTask.new(:integration) do |spec|
+    spec.rspec_opts = "--require integration/arango_helper.rb"
     spec.pattern = "spec/integration/*_spec.rb"
   end
   
@@ -58,9 +59,9 @@ namespace :yard do
 end
 
 desc "Run Unit Tests and verify documentation - no ArangoDB required"
-# task :ci => ["spec:unit", "yard:verify", "dependencies"]
-task :ci => ["spec:unit", "dependencies"]
+# task :ci => ["spec:unit", "yard:verify"]
+task :ci => ["spec:unit"]
 
 desc "Run all tests and verify documentation - ArangoDB required"
-# task :default => ["spec:all", "yard:verify", "dependencies"]
-task :default => ["spec:all", "dependencies"]
+# task :default => ["spec:all", "yard:verify"]
+task :default => ["spec:all"]

data/ashikawa-core.gemspec

@@ -7,13 +7,13 @@ Gem::Specification.new do |gem|
   gem.version     = Ashikawa::Core::VERSION
   gem.authors     = ["moonglum", "EinLama"]
   gem.email       = ["me@moonglum.net", "tobias.eilert@me.com"]
-  gem.homepage    = ""
+  gem.homepage    = "https://github.com/triAGENS/ashikawa-core"
   gem.summary     = "Ashikawa Core is a Wrapper around the ArangoDB Rest API"
   gem.description = "Ashikawa Core is a Wrapper around the ArangoDB Rest API. It provides low level access and will be used in different ArangoDB ODMs."
-  
+
   gem.required_ruby_version = '>= 1.9.2'
   gem.requirements << "ArangoDB"
-  
+
   gem.rubyforge_project = "ashikawa-core"
 
   gem.files         = `git ls-files`.split("\n")
@@ -23,18 +23,26 @@ Gem::Specification.new do |gem|
 
   # Runtime Dependencies
   gem.add_dependency "rest-client", "~> 1.6.7"
-  
+
   # Runtime Dependencies (JRuby only)
   if defined? PLATFORM and PLATFORM == 'java'
     gem.add_dependency "json", "~> 1.6.6"
     gem.add_dependency "jruby-openssl", "~> 0.7.6.1"
+  else
+    # RedCarpet is not compatible with JRuby
+    # It is only needed to generate the YARD Documentation
+    gem.add_development_dependency "redcarpet", "~> 2.1.1"
   end
-  
+
   # Development Dependencies
   gem.add_development_dependency "rake", "~> 0.9.2.2"
   gem.add_development_dependency "rspec", "~> 2.11.0"
   gem.add_development_dependency "yard", "~> 0.8.2.1"
   gem.add_development_dependency "webmock", "~> 1.8.9"
   # gem.add_development_dependency "yardstick", "~> 0.6.0"
-  gem.add_development_dependency "redcarpet", "~> 2.1.1"
+
+  gem.add_development_dependency "guard", "~> 1.3.2"
+  gem.add_development_dependency "guard-rspec", "~> 1.2.1"
+  gem.add_development_dependency "guard-bundler", "~> 1.0.0"
+  gem.add_development_dependency "guard-yard", "~> 2.0.0"
 end

data/lib/ashikawa-core.rb

@@ -3,6 +3,7 @@ require "ashikawa-core/connection"
 require "ashikawa-core/database"
 require "ashikawa-core/document"
 require "ashikawa-core/version"
+require "ashikawa-core/exceptions/document_not_found"
 
 # Ashikawa is a project dedicated to connect Ruby and ArangoDB
 module Ashikawa

data/lib/ashikawa-core/collection.rb

@@ -1,11 +1,16 @@
 require "ashikawa-core/document"
+require "ashikawa-core/index"
+require "ashikawa-core/cursor"
+require "forwardable"
 
 module Ashikawa
   module Core
     # Represents a certain Collection within the Database
     class Collection
+      extend Forwardable
+
       # The name of the collection, must be unique
-      # 
+      #
       # @return [String]
       # @api public
       # @example Change the name of a collection
@@ -23,9 +28,9 @@ module Ashikawa
       #   collection.name = "example_2"
       #   collection.name # => "example_2"
       attr_reader :name
-      
+
       # The ID of the collection. Is set by the database and unique
-      # 
+      #
       # @return [Fixnum]
       # @api public
       # @example Get the id of the collection
@@ -41,9 +46,12 @@ module Ashikawa
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
       #   collection.id #=> 4588
       attr_reader :id
-      
+
+      # Sending requests is delegated to the database
+      delegate send_request: :@database
+
       # Create a new Collection object with a name and an optional ID
-      # 
+      #
       # @param [Database] database The database the connection belongs to
       # @param [Hash] raw_collection The raw collection returned from the server
       # @api public
@@ -64,9 +72,9 @@ module Ashikawa
         @id  = raw_collection['id'].to_i if raw_collection.has_key? 'id'
         @status = raw_collection['status'].to_i if raw_collection.has_key? 'status'
       end
-      
+
       # Change the name of the collection
-      # 
+      #
       # @param [String] new_name New Name
       # @return [String] New Name
       # @api public
@@ -88,9 +96,9 @@ module Ashikawa
         send_request_for_this_collection "/rename", put: { "name" => new_name }
         @name = new_name
       end
-      
+
       # Checks if the collection is new born
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Is the collection new born?
@@ -108,9 +116,9 @@ module Ashikawa
       def new_born?
         @status == 1
       end
-      
+
       # Checks if the collection is unloaded
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Is the collection unloaded?
@@ -128,9 +136,9 @@ module Ashikawa
       def unloaded?
         @status == 2
       end
-      
+
       # Checks if the collection is loaded
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Is the collection loaded?
@@ -148,9 +156,9 @@ module Ashikawa
       def loaded?
         @status == 3
       end
-      
+
       # Checks if the collection is in the process of being unloaded
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Is the collection unloaded?
@@ -168,9 +176,9 @@ module Ashikawa
       def being_unloaded?
         @status == 4
       end
-      
+
       # Checks if the collection is corrupted
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Is the collection corrupted?
@@ -188,9 +196,9 @@ module Ashikawa
       def corrupted?
         @status > 5
       end
-      
+
       # Does the document wait until the data has been synchronised to disk?
-      # 
+      #
       # @return [Boolean]
       # @api public
       # @example Does the collection wait for file synchronization?
@@ -209,9 +217,9 @@ module Ashikawa
         server_response = send_request_for_this_collection "/properties"
         server_response["waitForSync"]
       end
-      
+
       # Change if the document will wait until the data has been synchronised to disk
-      # 
+      #
       # @return [String] Response from the server
       # @api public
       # @example Tell the collection to wait for file synchronization
@@ -227,11 +235,11 @@ module Ashikawa
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
       #   collection.wait_for_sync = true
       def wait_for_sync=(new_value)
-        server_response = send_request_for_this_collection "/properties", put: { "waitForSync" => new_value }
+        send_request_for_this_collection "/properties", put: { "waitForSync" => new_value }
       end
-      
+
       # Returns the number of documents in the collection
-      # 
+      #
       # @return [Fixnum] Number of documents
       # @api public
       # @example How many documents are in the collection?
@@ -250,9 +258,9 @@ module Ashikawa
         server_response = send_request_for_this_collection "/count"
         server_response["count"]
       end
-      
+
       # Return a figure for the collection
-      # 
+      #
       # @param [Symbol] figure_type The figure you want to know:
       #     * :datafiles_count - the number of active datafiles
       #     * :alive_size - the total size in bytes used by all living documents
@@ -275,13 +283,12 @@ module Ashikawa
       #   collection.figure :datafiles_count #=> 0
       def figure(figure_type)
         server_response = send_request_for_this_collection "/figures"
-        
         figure_area, figure_name = figure_type.to_s.split "_"
         server_response["figures"][figure_area][figure_name]
       end
-      
+
       # Deletes the collection
-      # 
+      #
       # @return [String] Response from the server
       # @api public
       # @example Delete a collection
@@ -299,9 +306,9 @@ module Ashikawa
       def delete
         send_request_for_this_collection "", delete: {}
       end
-      
+
       # Load the collection into memory
-      # 
+      #
       # @return [String] Response from the server
       # @api public
       # @example Load a collection into memory
@@ -319,9 +326,9 @@ module Ashikawa
       def load
         send_request_for_this_collection "/load", put: {}
       end
-      
+
       # Load the collection into memory
-      # 
+      #
       # @return [String] Response from the server
       # @api public
       # @example Unload a collection into memory
@@ -339,9 +346,9 @@ module Ashikawa
       def unload
         send_request_for_this_collection "/unload", put: {}
       end
-      
+
       # Delete all documents from the collection
-      # 
+      #
       # @return [String] Response from the server
       # @api public
       # @example Remove all documents from a collection
@@ -359,14 +366,13 @@ module Ashikawa
       def truncate!
         send_request_for_this_collection "/truncate", put: {}
       end
-      
+
       # Retrieves all documents for this collection
-      # 
+      #
       # @note It is advised to NOT use this method due to possible HUGE data amounts requested
-      # @param [Hash] options Additional options for this query.
       # @option options [Integer] :limit limit the maximum number of queried and returned elements.
       # @option options [Integer] :skip skip the first <n> documents of the query.
-      # @return [Array<Document>]
+      # @return [Cursor]
       # @api public
       # @example Get an array with all documents
       #   database = Ashikawa::Core::Database.new "http://localhost:8529"
@@ -379,25 +385,17 @@ module Ashikawa
       #     "code" => 200
       #   }
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
-      #   collection.all # => [#<Document id=43>]
+      #   collection.all # => #<Cursor id=33>
       def all(options={})
-        request_data = { "collection" => @name }
-        
-        request_data["limit"] = options[:limit] if options.has_key? :limit
-        request_data["skip"] = options[:skip] if options.has_key? :skip
-        
-        server_response = @database.send_request "/simple/all", :put => request_data
-        
-        documents_from_response(server_response)
+        send_simple_query "/simple/all", options, [:limit, :skip]
       end
-      
+
       # Looks for documents in the collection which match the given criteria
-      # 
-      # @param [Hash] reference_data a Hash with data similar to the documents you are looking for.
-      # @param [Hash] options Additional options for this query.
+      #
+      # @option options [Hash] :example a Hash with data matching the documents you are looking for.
       # @option options [Integer] :limit limit the maximum number of queried and returned elements.
       # @option options [Integer] :skip skip the first <n> documents of the query.
-      # @return [Array<Document>]
+      # @return [Cursor]
       # @api public
       # @example Find all documents in the collection that are red
       #   database = Ashikawa::Core::Database.new "http://localhost:8529"
@@ -410,26 +408,45 @@ module Ashikawa
       #     "code" => 200
       #   }
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
-      #   collection.by_example { "color" => "red"} # => [#<Document id=2444 color="red">]
-      def by_example(reference_data, options={})
-        request_data = { "collection" => @name, "example" => reference_data }
-        
-        request_data["limit"] = options[:limit] if options.has_key? :limit
-        request_data["skip"] = options[:skip] if options.has_key? :skip
-        
-        server_response = @database.send_request "/simple/by-example", :put => request_data
-        
-        documents_from_response(server_response)
+      #   collection.by_example example: { "color" => "red"} # => #<Cursor id=2444>
+      def by_example(options={})
+        send_simple_query "/simple/by-example", options, [:limit, :skip, :example]
       end
-      
+
+      # Looks for one document in the collection which matches the given criteria
+      #
+      # @param [Hash] example a Hash with data matching the document you are looking for.
+      # @return [Document]
+      # @api public
+      # @example Find one document in the collection that is red
+      #   database = Ashikawa::Core::Database.new "http://localhost:8529"
+      #   raw_collection = {
+      #     "name" => "example_1",
+      #     "waitForSync" => true,
+      #     "id" => 4588,
+      #     "status" => 3,
+      #     "error" => false,
+      #     "code" => 200
+      #   }
+      #   collection = Ashikawa::Core::Collection.new database, raw_collection
+      #   collection.first_example { "color" => "red"} # => #<Document id=2444 color="red">
+      def first_example(example)
+        server_response = send_request "/simple/first-example",
+          put: { "collection" => @name, "example" => example }
+        Document.new @database, server_response
+      end
+
       # Looks for documents in the collection based on location
       #
-      # @param [Hash] options Options for this search.
       # @option options [Integer] :latitude Latitude location for your search.
       # @option options [Integer] :longitude Longitude location for your search.
-      # @return [Array<Document>]
+      # @option options [Integer] :skip The documents to skip in the query.
+      # @option options [Integer] :distance If given, the attribute key used to store the distance.
+      # @option options [Integer] :limit The maximal amount of documents to return (default: 100).
+      # @option options [Integer] :geo If given, the identifier of the geo-index to use.
+      # @return [Cursor]
       # @api public
-      # @example Find all documents at Infinite Loop 
+      # @example Find all documents at Infinite Loop
       #   database = Ashikawa::Core::Database.new "http://localhost:8529"
       #   raw_collection = {
       #     "name" => "example_1",
@@ -442,23 +459,19 @@ module Ashikawa
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
       #   collection.near latitude: 37.331693, longitude: -122.030468
       def near(options={})
-        request_data = { "collection" => @name }
-
-        request_data["latitude"] = options[:latitude] if options.has_key? :latitude
-        request_data["longitude"] = options[:longitude] if options.has_key? :longitude
-
-        server_response = @database.send_request "/simple/near", :put => request_data
-
-        documents_from_response(server_response)
+        send_simple_query "/simple/near", options, [:latitude, :longitude, :distance, :skip, :limit, :geo]
       end
 
       # Looks for documents in the collection within a certain radius
       #
-      # @param [Hash] options Options for this search.
       # @option options [Integer] :latitude Latitude location for your search.
       # @option options [Integer] :longitude Longitude location for your search.
       # @option options [Integer] :radius Radius around the given location you want to search in.
-      # @return [Array<Document>]
+      # @option options [Integer] :skip The documents to skip in the query.
+      # @option options [Integer] :distance If given, the attribute key used to store the distance.
+      # @option options [Integer] :limit The maximal amount of documents to return (default: 100).
+      # @option options [Integer] :geo If given, the identifier of the geo-index to use.
+      # @return [Cursor]
       # @api public
       # @example Find all documents within a radius of 100 to Infinite Loop
       #   database = Ashikawa::Core::Database.new "http://localhost:8529"
@@ -473,26 +486,101 @@ module Ashikawa
       #   collection = Ashikawa::Core::Collection.new database, raw_collection
       #   collection.within latitude: 37.331693, longitude: -122.030468, radius: 100
       def within(options={})
-        request_data = { "collection" => @name }
-
-        request_data["latitude"] = options[:latitude] if options.has_key? :latitude
-        request_data["longitude"] = options[:longitude] if options.has_key? :longitude
-        request_data["radius"] = options[:radius] if options.has_key? :radius
+        send_simple_query "/simple/within", options, [:latitude, :longitude, :radius, :distance, :skip, :limit, :geo]
+      end
 
-        server_response = @database.send_request "/simple/within", :put => request_data
 
-        documents_from_response(server_response)
+      # Looks for documents in the collection with an attribute between two values
+      #
+      # @option options [Integer] :attribute The attribute path to check.
+      # @option options [Integer] :left The lower bound
+      # @option options [Integer] :right The upper bound
+      # @option options [Integer] :closed If true, use intervall including left and right, otherwise exclude right, but include left.
+      # @option options [Integer] :skip The documents to skip in the query (optional).
+      # @option options [Integer] :limit The maximal amount of documents to return (optional).
+      # @return [Cursor]
+      # @api public
+      def in_range(options={})
+        send_simple_query "/simple/range", options, [:attribute, :left, :right, :closed, :limit, :skip]
       end
 
       # Fetch a certain document by its ID
-      # 
+      #
       # @param [Integer] document_id the id of the document
+      # @raise [DocumentNotFoundException] If the requested document was not found
       # @return Document
       # @api public
       # @example Fetch a document with the ID 12345
       #   document = collection[12345]
       def [](document_id)
-        Ashikawa::Core::Document.new "#{@id}/#{document_id}"
+        begin
+          server_response = send_request "/document/#{@id}/#{document_id}"
+        rescue RestClient::ResourceNotFound
+          raise DocumentNotFoundException
+        end
+
+        Document.new @database, server_response
+      end
+
+      # Replace a certain document by its ID
+      #
+      # @param [Integer] document_id the id of the document
+      # @param [Hash] raw_document the data you want to replace it with
+      # @api public
+      def []=(document_id, raw_document)
+        send_request "/document/#{@id}/#{document_id}", put: raw_document
+      end
+
+      # Create a document with given raw data
+      #
+      # @param [Hash] raw_document
+      # @return DocumentHash
+      # @api public
+      def create(raw_document)
+        server_response = send_request "/document?collection=#{@id}",
+          post: raw_document
+
+        Document.new @database, server_response
+      end
+
+      alias :<< :create
+
+      # Add an index to the collection
+      #
+      # @param [Symbol] type What kind of index?
+      # @option opts [Array<Symbol>] on On which fields?
+      # @return Index
+      # @api public
+      def add_index(type, opts)
+        server_response = send_request "/index?collection=#{@id}", post: {
+          "type" => type.to_s,
+          "fields" => opts[:on].map { |field| field.to_s }
+        }
+
+        Index.new self, server_response
+      end
+
+      # Get an index by ID
+      #
+      # @param [Int] id
+      # @return Index
+      # @api public
+      def index(id)
+        server_response = send_request "/index/#{@id}/#{id}"
+
+        Index.new self, server_response
+      end
+
+      # Get all indices
+      #
+      # @return [Array<Index>]
+      # @api public
+      def indices
+        server_response = send_request "/index?collection=#{@id}"
+
+        server_response["indexes"].map do |raw_index|
+          Index.new self, raw_index
+        end
       end
 
       private
@@ -502,22 +590,25 @@ module Ashikawa
       # @return [String] Response from the server
       # @api private
       def send_request_for_this_collection(path, method={})
-        if method == {}
-          @database.send_request "/collection/#{id}#{path}"
-        else
-          @database.send_request "/collection/#{id}#{path}", method
-        end
+        send_request "/collection/#{id}#{path}", method
       end
 
-      # Takes JSON returned by the database and collects Documents from the data
-      # 
-      # @param [Array<Hash>] parsed_server_response parsed JSON response from the server. Should contain document-hashes.
-      # @return [Array<Document>]
+      # Send a simple query to the server
+      #
+      # @param [String] path The path for the request
+      # @param [Hash] options The options given to the method
+      # @param [Array<Symbol>] keys The required keys
+      # @return [Hash] The parsed hash for the request
       # @api private
-      def documents_from_response(parsed_server_response)
-        parsed_server_response.collect do |document|
-          Ashikawa::Core::Document.new(document["_id"], document["_rev"])
+      def send_simple_query(path, options, keys)
+        request_data = { "collection" => @name }
+
+        keys.each do |key|
+          request_data[key.to_s] = options[key] if options.has_key? key
         end
+
+        server_response = send_request path, :put => request_data
+        Cursor.new @database, server_response
       end
     end
   end