groonga-client 0.0.2 → 0.0.3

data/.yardopts

@@ -1,4 +1,5 @@
 --output-dir doc/reference/en
+--markup markdown
 lib/**/*.rb
 -
 doc/text/**/*

data/README.md

@@ -57,6 +57,7 @@ TODO: use commands with parameters for examples
 ## Authors
 
 * Haruka Yoshihara \<yoshihara@clear-code.com\>
+* Kouhei Sutou \<kou@clear-code.com\>
 
 ## License
 

data/doc/text/news.md

@@ -1,12 +1,25 @@
 # NEWS
 
+## 0.0.3 - 2013-09-18
+
+### Improvements
+
+  * Supported "table_create" command.
+  * {Groonga::Client.open} returns block value.
+  * Supported {Groonga::Client#close}.
+  * select: Supported auto time value conversion.
+  * select: Renamed to {Groonga::Client::Response::Select#n_hits}
+    from #n_records. It is a backward incompatible change.
+  * Added {Groonga::Client::Connection::Error} as an abstracted error.
+  * Required groonga-command 1.0.4 or later.
+
 ## 0.0.2 - 2013-07-08
 
 ### Improvements
 
-* Supported "select" command.
-* Supported Enumerable type interface in
-  Response::TableList and Response::ColumnList
+  * Supported "select" command.
+  * Supported Enumerable type interface in
+    Response::TableList and Response::ColumnList
 
 ## 0.0.1 - 2013-06-27
 

data/groonga-client.gemspec

@@ -47,7 +47,7 @@ Gem::Specification.new do |spec|
   # end
 
   spec.add_runtime_dependency("gqtp", ">= 1.0.4")
-  spec.add_runtime_dependency("groonga-command", ">= 1.0.2")
+  spec.add_runtime_dependency("groonga-command", ">= 1.0.4")
 
   spec.add_development_dependency("bundler")
   spec.add_development_dependency("rake")

data/lib/groonga/client.rb

@@ -18,17 +18,41 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
 require "groonga/client/command"
-require "groonga/client/protocol/gqtp"
-require "groonga/client/protocol/http"
+require "groonga/client/connection/gqtp"
+require "groonga/client/connection/http"
 
 module Groonga
   class Client
     class << self
+      # @!macro [new] initialize_options
+      #   @param [Hash] options The options.
+      #   @option options [:gqtp or :http] :protocol The protocol that is
+      #     used by the client.
+      #
+      # @overload open(options={})
+      #   Opens a new client connection.
+      #
+      #   @macro initialize_options
+      #   @return [Client] The opened client.
+      #
+      # @overload open(options={}) {|client| }
+      #   Opens a new client connection while the block is evaluated.
+      #   The block is finished the opened client is closed.
+      #
+      #   @macro initialize_options
+      #   @yield [client] Gives a opened client to the block. The opened
+      #     client is closed automatically when the block is finished.
+      #   @yieldparam client [Client] The opened client.
+      #   @yieldreturn [Object] Any object.
+      #   @return [Object] Any object that is returned by the block.
       def open(options={}, &block)
         client = new(options)
         if block_given?
-          yield(client)
-          client.close
+          begin
+            yield(client)
+          ensure
+            client.close
+          end
         else
           client
         end
@@ -38,18 +62,55 @@ module Groonga
     attr_reader :protocol
     attr_reader :connection
 
+    # @macro initialize_options
     def initialize(options)
       @protocol = options.delete(:protocol) || :gqtp
 
       @connection = nil
       if @protocol == :gqtp
-        @connection = Groonga::Client::Protocol::GQTP.new(options)
+        @connection = Groonga::Client::Connection::GQTP.new(options)
       else
-        @connection = Groonga::Client::Protocol::HTTP.new(options)
+        @connection = Groonga::Client::Connection::HTTP.new(options)
       end
     end
 
-    def close
+    # Closes the opened client connection if the current connection is
+    # still opened. You can't send a new command after you call this
+    # method.
+    #
+    # @overload close
+    #   Closes synchronously.
+    #
+    #   @return [Boolean] true when the opened connection is closed.
+    #      false when there is no connection.
+    #
+    # @overload close {}
+    #   Closes asynchronously.
+    #
+    #   @yield [] Calls the block when the opened connection is closed.
+    #   @return [#wait] The request object. If you want to wait until
+    #      the request is processed. You can send #wait message to the
+    #      request.
+    def close(&block)
+      sync = !block_given?
+      if @connection
+        close_request = @connection.close do
+          yield unless sync
+          @connection = nil
+        end
+        if sync
+          close_request.wait
+          true
+        else
+          close_request
+        end
+      else
+        if sync
+          false
+        else
+          Connection::EmptryReqest.new
+        end
+      end
     end
 
     def cache_limit(parameters)
@@ -128,6 +189,7 @@ module Groonga
     end
 
     def table_create(parameters)
+      execute_command("table_create", parameters)
     end
 
     def table_list(parameters={})

data/lib/groonga/client/command.rb

@@ -46,8 +46,7 @@ module Groonga
 
       private
       def parse_raw_response(raw_response)
-        response_class = Groonga::Client::Response.find(@command.name)
-        response_class.parse(raw_response, @command.output_type)
+        Groonga::Client::Response.parse(@command, raw_response)
       end
     end
   end

data/lib/groonga/client/connection/error.rb

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Kouhei Sutou <kou@clear-code.com>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+module Groonga
+  class Client
+    module Connection
+      class Error < StandardError
+        attr_reader :raw_error
+        def initialize(raw_error)
+          @raw_error = raw_error
+          super(raw_error.message)
+        end
+      end
+    end
+  end
+end

data/lib/groonga/client/{protocol → connection}/gqtp.rb

@@ -22,9 +22,11 @@ require "erb"
 require "gqtp"
 require "json"
 
+require "groonga/client/connection/request"
+
 module Groonga
   class Client
-    module Protocol
+    module Connection
       class GQTP
         def initialize(options)
           @client = ::GQTP::Client.new(options)
@@ -41,6 +43,44 @@ module Groonga
           end
         end
 
+        # @return [Boolean] true if the current connection is opened,
+        #   false otherwise.
+        def connected?
+          not @client.nil?
+        end
+
+        # Closes the opened connection if the current connection is
+        # still opened. You can't send a new command after you call
+        # this method.
+        #
+        # @overload close
+        #   Closes synchronously.
+        #
+        #   @return [Boolean] true when the opened connection is closed.
+        #      false when there is no connection.
+        #
+        # @overload close {}
+        #   Closes asynchronously.
+        #
+        #   @yield [] Calls the block when the opened connection is closed.
+        #   @return [#wait] The request object. If you want to wait until
+        #      the request is processed. You can send #wait message to the
+        #      request.
+        def close(&block)
+          sync = !block_given?
+          if connected?
+            return_value = @client.close(&block)
+            @client = nil
+            return_value
+          else
+            if sync
+              false
+            else
+              EmptyRequest.new
+            end
+          end
+        end
+
         class RawResponse
           include ERB::Util
 

data/lib/groonga/client/connection/http.rb

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
+# Copyright (C) 2013  Kouhei Sutou <kou@clear-code.com>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+require "open-uri"
+
+require "groonga/client/connection/request"
+require "groonga/client/connection/error"
+
+module Groonga
+  class Client
+    module Connection
+      class HTTP
+        def initialize(options)
+          @host = options[:host] || "127.0.0.1"
+          @port = options[:port] || 10041
+        end
+
+        def send(command)
+          url = "http://#{@host}:#{@port}#{command.to_uri_format}"
+          thread = Thread.new do
+            begin
+              open(url) do |response|
+                body = response.read
+                yield(body)
+              end
+            rescue OpenURI::HTTPError
+              raise Error.new($!)
+            end
+          end
+          ThreadRequest.new(thread)
+        end
+
+        # @return [false] Always returns false because the current
+        #   implementation doesn't support keep-alive.
+        def connected?
+          false
+        end
+
+        # Does nothing because the current implementation doesn't
+        # support keep-alive. If the implementation supports
+        # keep-alive, it close the opend connection.
+        #
+        # @overload close
+        #   Closes synchronously.
+        #
+        #   @return [false] It always returns false because there is always
+        #      no connectin.
+        #
+        # @overload close {}
+        #   Closes asynchronously.
+        #
+        #   @yield [] Calls the block when the opened connection is closed.
+        #   @return [#wait] The request object. If you want to wait until
+        #      the request is processed. You can send #wait message to the
+        #      request.
+        def close(&block)
+          sync = !block_given?
+          if sync
+            false
+          else
+            EmptyRequest.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/groonga/client/{protocol/http.rb → connection/request.rb}

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
 # Copyright (C) 2013  Kouhei Sutou <kou@clear-code.com>
 #
 # This library is free software; you can redistribute it and/or
@@ -17,12 +16,10 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 
-require "open-uri"
-
 module Groonga
   class Client
-    module Protocol
-      class Request
+    module Connection
+      class ThreadRequest
         def initialize(thread)
           @thread = thread
         end
@@ -32,21 +29,11 @@ module Groonga
         end
       end
 
-      class HTTP
-        def initialize(options)
-          @host = options[:host] || "127.0.0.1"
-          @port = options[:port] || 10041
+      class EmptyRequest
+        def initialize
         end
 
-        def send(command)
-          url = "http://#{@host}:#{@port}#{command.to_uri_format}"
-          thread = Thread.new do
-            open(url) do |response|
-              body = response.read
-              yield(body)
-            end
-          end
-          Request.new(thread)
+        def wait
         end
       end
     end

data/lib/groonga/client/response/base.rb

@@ -33,12 +33,24 @@ module Groonga
         def find(name)
           @@registered_commands[name] || Base
         end
+
+        # Parses the response for the request of the command and returns
+        # response object.
+        #
+        # @param [Groonga::Command::Base] The command of the request.
+        # @param [String] The raw (not parsed) response returned by groonga
+        #   server.
+        # @return [Base]
+        def parse(command, raw_response)
+          klass = find(command.name)
+          klass.parse(command, raw_response)
+        end
       end
 
       class Base
         class << self
-          def parse(raw_response, type)
-            case type
+          def parse(command, raw_response)
+            case command.output_type
             when :json
               header, body = JSON.parse(raw_response)
             when :xml
@@ -47,7 +59,7 @@ module Groonga
               header = nil
               body = raw_response
             end
-            response = new(header, body)
+            response = new(command, header, body)
             response.raw = raw_response
             response
           end
@@ -100,13 +112,31 @@ module Groonga
           end
         end
 
-        attr_accessor :header, :body
+        # @return [Groonga::Command] The command for the request.
+        attr_accessor :command
+        # @return [::Array<Integer, Float, Float>] The header of response.
+        #   It consists of `[return_code, start_time, elapsed_time_in_seconds]`
+        #   for success case.
+        #   It consists of
+        #   `[return_code, start_time, elapsed_time_in_seconds, error_message, error_location]`
+        #   for error case.
+        # @see http://groonga.org/docs/reference/command/output_format.html#header
+        #   Defails for header format.
+        attr_accessor :header
+        # @return [::Hash] The body of response. Its content is depends on
+        #   command.
+        # @see http://groonga.org/docs/reference/command.html
+        #   The list of built-in commands.
+        attr_accessor :body
+        # @return [String] The unparsed response. It may be JSON, XML or
+        #   groonga command format.
         attr_accessor :raw
 
-        def initialize(header, body)
-          @header = header
-          @body = body
-          @raw = nil
+        def initialize(command, header, body)
+          self.command = command
+          self.header = header
+          self.body = body
+          self.raw = nil
         end
       end
     end