ashikawa-core 0.4.1 → 0.5.1

data/.gitignore

@@ -6,3 +6,5 @@ doc
 Gemfile.lock
 pkg/*
 report/*
+coverage
+.rbx

data/.travis.yml

@@ -1,4 +1,6 @@
 language: ruby
+before_script:
+  - ./spec/setup/arangodb.sh
 rvm:
   - 1.9.2
   - 1.9.3

data/CONTRIBUTING.md

@@ -3,10 +3,11 @@
 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.
-5. Check with `rake` that everything is fine and send the Pull Request :)
+2. Fork your feature branch from the `development` branch (not the `master` branch)
+3. Write an acceptance test: Describe what you want to do (our integration tests touch the database)
+4. Implement it: Write a unit test, check that it fails, make the test pass – repeat (our unit tests don't touch the database)
+5. Write documentation for it.
+6. Check with `rake` that everything is fine and send the pull request to the `development` branch :)
 
 ## How to get started developing
 
@@ -38,7 +39,3 @@ Guard is a tool for comfortable development. If you want to use it for developme
 * 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). Therefore it is important that you run the integration tests on your local machine before sending the pull requests.

data/Guardfile

@@ -11,7 +11,7 @@ guard 'rspec', :spec_paths => "spec/unit" do
   watch(%r{spec/.+\.rb})
 end
 
-guard 'rspec', :spec_paths => "spec/integration" do
+guard 'rspec', :spec_paths => "spec/acceptance" do
   watch(%r{lib/.+\.rb})
   watch(%r{spec/.+\.rb})
 end

data/README.md

@@ -6,6 +6,16 @@
 
 Ashikawa Core is a Wrapper around the ArangoDB Rest API. It provides low level access and will be used in different ArangoDB ODMs.
 
+All tests run on Travis CI for the following versions of Ruby:
+
+* MRI 1.9.2 and 1.9.3
+* Rubinius 1.9 mode
+* JRuby 1.9 mode
+
+We also run on JRuby and MRI Head. MRI-head is currently not passing, because some dependencies are not compatible.
+
+Please note that the `master` branch is always the stable version released on Ruby Gems (*This is actually a lie, but we are currently converting to this model ;) The next release will implement this*). If you want the most recent version, please refer to the `development` branch.
+
 ## How to use it
 
 For a detailed description of Ashikawa::Core please refer to the [documentation](http://rdoc.info/github/triAGENS/ashikawa-core/master/frames). An example:
@@ -18,6 +28,10 @@ database["my_collection"].name = "new_name"
 database["new_name"].delete
 ```
 
+# Issues or Questions
+
+If you find a bug in this gem, please report it on [our tracker](https://github.com/triAGENS/ashikawa-core/issues). If you have a question, just contact us via the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/ashikawa) – we are happy to help you :)
+
 # Contributing
 
-If you want to contribute to the project, see CONTRIBUTING.md for details.
+If you want to contribute to the project, see CONTRIBUTING.md for details. It contains information on our process and how to set up everything.

data/Rakefile

@@ -2,21 +2,28 @@
 require "bundler/gem_tasks"
 require "rspec"
 require "rspec/core/rake_task"
+require "roodi"
+require "roodi_task"
 # require 'yardstick/rake/measurement'
 # require 'yardstick/rake/verify'
 
 
 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"
+  desc "Run the acceptance tests. Requires ArangoDB to be running."
+  RSpec::Core::RakeTask.new(:acceptance_with_running_arangodb) do |spec|
+    spec.pattern = "spec/acceptance/*_spec.rb"
   end
 
-  desc "Run the authentication integration tests. Requires ArangoDB."
-  RSpec::Core::RakeTask.new(:integration_auth) do |spec|
-    spec.rspec_opts = "--require integration_auth/arango_helper.rb"
-    spec.pattern = "spec/integration_auth/*_spec.rb"
+  desc "Run the acceptance tests. Requires ArangoDB."
+  RSpec::Core::RakeTask.new(:acceptance) do |spec|
+    spec.rspec_opts = "--require acceptance/arango_helper.rb"
+    spec.pattern = "spec/acceptance/*_spec.rb"
+  end
+
+  desc "Run the authentication acceptance tests. Requires ArangoDB."
+  RSpec::Core::RakeTask.new(:acceptance_auth) do |spec|
+    spec.rspec_opts = "--require acceptance_auth/arango_helper.rb"
+    spec.pattern = "spec/acceptance_auth/*_spec.rb"
   end
 
   desc "Run the unit tests"
@@ -25,7 +32,7 @@ namespace :spec do
   end
 
   desc "Run all tests. Requires ArangoDB"
-  task :all => [:integration, :unit]
+  task :all => [:acceptance, :unit]
 end
 
 desc "check if gems are up to date"
@@ -64,10 +71,36 @@ namespace :yard do
   end
 end
 
-desc "Run Unit Tests and verify documentation - no ArangoDB required"
+namespace :metrics do
+  metric_tasks = []
+
+  begin
+    require 'cane/rake_task'
+
+    desc "Run cane to check quality metrics"
+    Cane::RakeTask.new(:cane) do |cane|
+      cane.abc_max = 10
+      cane.style_measure = 140
+      cane.style_glob = "{app,lib}/**/*.rb"
+    end
+
+    metric_tasks << :cane
+  rescue LoadError
+    warn "cane not available, quality task not provided."
+  end
+
+  RoodiTask.new do |roodi|
+    roodi.patterns = %w(lib/**/*.rb spec/**/*.rb)
+  end
+  metric_tasks << :roodi
+
+  task :all => metric_tasks
+end
+
+desc "Run Unit Tests - no ArangoDB required"
 # task :ci => ["spec:unit", "yard:verify"]
-task :ci => ["spec:unit"]
+task :ci => ["spec:unit", "spec:acceptance_with_running_arangodb", "metrics:all"]
 
 desc "Run all tests and verify documentation - ArangoDB required"
 # task :default => ["spec:all", "yard:verify"]
-task :default => ["spec:all"]
+task :default => ["spec:all", "metrics:all"]

data/ashikawa-core.gemspec

@@ -31,19 +31,26 @@ Gem::Specification.new do |gem|
   else
     # RedCarpet is not compatible with JRuby
     # It is only needed to generate the YARD Documentation
-    gem.add_development_dependency "redcarpet", "~> 2.2.1"
+    gem.add_development_dependency "redcarpet", "~> 2.2.2"
   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.3"
-  gem.add_development_dependency "webmock", "~> 1.8.9"
+  gem.add_development_dependency "webmock", "~> 1.9.0"
   # gem.add_development_dependency "yardstick", "~> 0.6.0"
+  gem.add_development_dependency "simplecov", "~> 0.7.1"
+  gem.add_development_dependency "cane", "~> 2.4.0"
+  gem.add_development_dependency "roodi1.9", "~> 2.0.1"
 
-  gem.add_development_dependency "guard", "~> 1.4.0"
-  gem.add_development_dependency "guard-rspec", "~> 2.1.0"
+  # Do not update to version 3, it is currently not compatible with roodi1.9
+  # see grsmv/roodi1.9#1
+  gem.add_development_dependency "ruby_parser", "~> 2.3.1"
+
+  gem.add_development_dependency "guard", "~> 1.5.3"
+  gem.add_development_dependency "guard-rspec", "~> 2.1.1"
   gem.add_development_dependency "guard-bundler", "~> 1.0.0"
-  gem.add_development_dependency "guard-yard", "~> 2.0.0"
-  gem.add_development_dependency "rb-fsevent", "~> 0.9.1"
+  gem.add_development_dependency "guard-yard", "~> 2.0.1"
+  gem.add_development_dependency "rb-fsevent", "~> 0.9.2"
 end

data/lib/ashikawa-core/collection.rb

@@ -1,6 +1,8 @@
 require "ashikawa-core/document"
 require "ashikawa-core/index"
 require "ashikawa-core/cursor"
+require "ashikawa-core/query"
+require "restclient/exceptions"
 require "forwardable"
 
 module Ashikawa
@@ -47,6 +49,12 @@ module Ashikawa
       #   collection.id #=> 4588
       attr_reader :id
 
+      # The database the collection belongs to
+      #
+      # @return [Database]
+      # @api public
+      attr_reader :database
+
       # Sending requests is delegated to the database
       delegate send_request: :@database
 
@@ -367,143 +375,6 @@ module Ashikawa
         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
-      # @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 [Cursor]
-      # @api public
-      # @example Get an array with all documents
-      #   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.all # => #<Cursor id=33>
-      def all(options={})
-        send_simple_query "/simple/all", options, [:limit, :skip]
-      end
-
-      # Looks for documents in the collection which match the given criteria
-      #
-      # @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 [Cursor]
-      # @api public
-      # @example Find all documents in the collection that are 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.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
-      #
-      # @option options [Integer] :latitude Latitude location for your search.
-      # @option options [Integer] :longitude Longitude location for your search.
-      # @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
-      #   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.near latitude: 37.331693, longitude: -122.030468
-      def near(options={})
-        send_simple_query "/simple/near", options, [:latitude, :longitude, :distance, :skip, :limit, :geo]
-      end
-
-      # Looks for documents in the collection within a certain radius
-      #
-      # @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.
-      # @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"
-      #   raw_collection = {
-      #     "name" => "example_1",
-      #     "waitForSync" => true,
-      #     "id" => 4588,
-      #     "status" => 3,
-      #     "error" => false,
-      #     "code" => 200
-      #   }
-      #   collection = Ashikawa::Core::Collection.new database, raw_collection
-      #   collection.within latitude: 37.331693, longitude: -122.030468, radius: 100
-      def within(options={})
-        send_simple_query "/simple/within", options, [:latitude, :longitude, :radius, :distance, :skip, :limit, :geo]
-      end
-
-
-      # 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
@@ -522,7 +393,7 @@ module Ashikawa
         Document.new @database, server_response
       end
 
-      # Replace a certain document by its ID
+      # Replace a 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
@@ -531,7 +402,7 @@ module Ashikawa
         send_request "/document/#{@id}/#{document_id}", put: raw_document
       end
 
-      # Create a document with given raw data
+      # Create a new document from raw data
       #
       # @param [Hash] raw_document
       # @return DocumentHash
@@ -547,10 +418,13 @@ module Ashikawa
 
       # Add an index to the collection
       #
-      # @param [Symbol] type What kind of index?
-      # @option opts [Array<Symbol>] on On which fields?
+      # @param [Symbol] type specify the type of the index, for example `:hash`
+      # @option opts [Array<Symbol>] on fields on which to apply the index
       # @return Index
       # @api public
+      # @example Add a hash-index to the fields :name and :profession of a collection
+      #   people = database['people']
+      #   people.add_index :hash, :on => [:name, :profession]
       def add_index(type, opts)
         server_response = send_request "/index?collection=#{@id}", post: {
           "type" => type.to_s,
@@ -562,7 +436,7 @@ module Ashikawa
 
       # Get an index by ID
       #
-      # @param [Int] id
+      # @param [Integer] id
       # @return Index
       # @api public
       def index(id)
@@ -583,6 +457,14 @@ module Ashikawa
         end
       end
 
+      # Return a Query initialized with this collection
+      #
+      # @return [Query]
+      # @api public
+      def query
+        Query.new self
+      end
+
       private
 
       # Send a request to the server with the name of the collection prepended
@@ -592,24 +474,6 @@ module Ashikawa
       def send_request_for_this_collection(path, method={})
         send_request "/collection/#{id}#{path}", method
       end
-
-      # 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 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
 end

data/lib/ashikawa-core/connection.rb

@@ -1,5 +1,6 @@
 require "rest-client"
 require "json"
+require "uri"
 
 module Ashikawa
   module Core
@@ -49,68 +50,93 @@ module Ashikawa
       # @api public
       # @example Create a new Connection
       #  connection = Connection.new "http://localhost:8529"
-      def initialize(api_string="http://localhost:8529")
-        @api_string = api_string
-
-        require 'uri'
-        uri = URI(@api_string)
-        @host = uri.host
-        @port = uri.port
+      def initialize(api_string = "http://localhost:8529")
+        uri     = URI api_string
+        @host   = uri.host
+        @port   = uri.port
         @scheme = uri.scheme
       end
 
-      def authenticate_with(options={})
-        if options.key? :username and options.key? :password
-          @username = options[:username]
-          @password = options[:password]
-        else
-          raise ArgumentError, 'missing username or password'
-        end
-
-        self
-      end
-
-      # Sends a request to a given path (Prepends the api_string automatically)
+      # Sends a request to a given path returning the parsed result
+      # (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.
-      # @param [Hash] method_params additional parameters for your request. Only needed if you want to send something other than a GET request.
-      # @option method_params [Hash] :post POST data in case you want to send a POST request.
+      # @option params [Hash] :post POST data in case you want to send a POST request.
       # @return [Hash] parsed JSON response from the server
-      # @api semipublic
-      def send_request(path, method_params = {})
-        path = "#{url}/_api/#{path.gsub(/^\//, '')}"
+      # @api public
+      def send_request(path, params = {})
+        raw = raw_result_for path, params
+        JSON.parse raw
+      end
+
+      # Sends a request to a given path returning the raw result
+      # (Prepends the api_string automatically)
+      #
+      # @example get request
+      #   connection.raw_result_for('/collection/new_collection')
+      # @example post request
+      #   connection.raw_result_for('/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 [String] raw response from the server
+      # @api public
+      def raw_result_for(path, params = {})
+        path   = full_path path
+        method = [:post, :put, :delete].find { |method_name|
+          params.has_key? method_name
+        } || :get
 
-        answer = if method_params.has_key? :post
-          RestClient.post path, method_params[:post].to_json
-        elsif method_params.has_key? :put
-          RestClient.put path, method_params[:put].to_json
-        elsif method_params.has_key? :delete
-          RestClient.delete path
+        if [:post, :put].include? method
+          RestClient.send method, path, params[method].to_json
         else
-          RestClient.get path
+          RestClient.send method, path
         end
-
-        JSON.parse answer
       end
 
+      # Checks if authentication for this Connection is active or not
+      #
+      # @return [Boolean]
+      # @api public
       def authentication?
         !!@username
       end
 
-      private
+      # Authenticate with given username and password
+      #
+      # @option [String] username
+      # @option [String] password
+      # @return [self]
+      # @raise [ArgumentError] if username or password are missing
+      # @api public
+      def authenticate_with(options = {})
+        if options.key? :username and options.key? :password
+          @username = options[:username]
+          @password = options[:password]
+        else
+          raise ArgumentError, 'missing username or password'
+        end
+
+        self
+      end
 
-      def url
-        if authentication?
+      # Return the full path for a given API path
+      #
+      # @param [String] path The API path
+      # @return [String] Full path
+      # @api public
+      def full_path(path)
+        prefix = if authentication?
           "#{@scheme}://#{@username}:#{@password}@#{@host}:#{@port}"
         else
-          @api_string
+          "#{@scheme}://#{@host}:#{@port}"
         end
-      end
 
+        "#{prefix}/_api/#{path.gsub(/^\//, '')}"
+      end
     end
   end
 end

data/lib/ashikawa-core/cursor.rb

@@ -24,10 +24,7 @@ module Ashikawa
       # @api public
       def initialize(database, raw_cursor)
         @database = database
-        @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'
-        @current  = raw_cursor['result']
+        parse_raw_cursor raw_cursor
       end
 
       # Iterate over the documents found by the cursor
@@ -43,22 +40,31 @@ module Ashikawa
       end
 
       # Delete the cursor
+      # @api public
       def delete
         @database.send_request "/cursor/#{@id}", delete: {}
       end
 
       private
 
+      # Pull the raw data from the cursor into this object
+      #
+      # @api private
+      def parse_raw_cursor(raw_cursor)
+        @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'
+        @current  = raw_cursor['result']
+      end
+
       # Get a new batch from the server
       #
       # @return [Boolean] Is there a next batch?
+      # @api private
       def next_batch
-        return @false unless @has_more
+        return false unless @has_more
         raw_cursor = @database.send_request "/cursor/#{@id}", put: {}
-        @id       = raw_cursor['id']
-        @has_more = raw_cursor['hasMore']
-        @length   = raw_cursor['count']
-        @current  = raw_cursor['result']
+        parse_raw_cursor raw_cursor
       end
     end
   end

data/lib/ashikawa-core/database.rb

@@ -68,19 +68,12 @@ module Ashikawa
         Ashikawa::Core::Collection.new self, server_response
       end
 
-      # Send a query to the database
+      # Return a Query initialized with this database
       #
-      # @param [String] query
-      # @option opts [Integer] :count Should the number of results be counted?
-      # @option opts [Integer] :batch_size Set the number of results returned at once
-      def query(query, opts = {})
-        parameter = { query: query }
-
-        parameter[:count] = opts[:count] if opts.has_key? :count
-        parameter[:batchSize] = opts[:batch_size] if opts.has_key? :batch_size
-
-        server_response = send_request "/cursor", post: parameter
-        Cursor.new self, server_response
+      # @return [Query]
+      # @api public
+      def query
+        Query.new self
       end
     end
   end