gcloud 0.5.0 → 0.6.0

data/lib/gcloud/search/index/list.rb

@@ -0,0 +1,90 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Gcloud
+  module Search
+    class Index
+      ##
+      # Index::List is a special case Array with additional values.
+      class List < DelegateClass(::Array)
+        ##
+        # If not empty, indicates that there are more records that match
+        # the request and this value should be passed to continue.
+        attr_accessor :token
+
+        ##
+        # Create a new Index::List with an array of Index instances.
+        def initialize arr = []
+          super arr
+        end
+
+        ##
+        # Whether there a next page of indexes.
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of indexes.
+        def next
+          return nil unless next?
+          ensure_connection!
+          resp = @connection.list_indexes token: token
+          if resp.success?
+            Index::List.from_response resp, @connection
+          else
+            fail ApiError.from_response(resp)
+          end
+        end
+
+        ##
+        # Retrieves all indexes by repeatedly loading pages until #next?
+        # returns false. Returns the list instance for method chaining.
+        def all
+          while next?
+            next_indexes = self.next
+            push(*next_indexes)
+            self.token = next_indexes.token
+          end
+          self
+        end
+
+        ##
+        # New Indexs::List from a response object.
+        def self.from_response resp, conn #:nodoc:
+          data = JSON.parse resp.body
+          indexes = new(Array(data["indexes"]).map do |raw_index|
+            Index.from_raw raw_index, conn
+          end)
+          indexes.instance_eval do
+            @token = data["nextPageToken"]
+            @connection = conn
+          end
+          indexes
+        rescue JSON::ParserError
+          raise ApiError.from_response(resp)
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active connection is available.
+        def ensure_connection!
+          fail "Must have active connection" unless @connection
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/search/project.rb

@@ -0,0 +1,197 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gcloud/gce"
+require "gcloud/search/connection"
+require "gcloud/search/credentials"
+require "gcloud/search/index"
+require "gcloud/search/errors"
+
+module Gcloud
+  module Search
+    ##
+    # = Project
+    #
+    # Projects are top-level containers in Google Cloud Platform. They store
+    # information about billing and authorized users, and they control access to
+    # Google Cloud Search resources. Each project has a friendly name and a
+    # unique ID. Projects can be created only in the {Google Developers
+    # Console}[https://console.developers.google.com].
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   search = gcloud.search
+    #   index = search.index "books"
+    #
+    # See Gcloud#search
+    class Project
+      ##
+      # The Connection object.
+      attr_accessor :connection #:nodoc:
+
+      ##
+      # Creates a new Connection instance.
+      #
+      # See Gcloud.search
+      def initialize project, credentials #:nodoc:
+        project = project.to_s # Always cast to a string
+        fail ArgumentError, "project is missing" if project.empty?
+        @connection = Connection.new project, credentials
+      end
+
+      ##
+      # The ID of the current project.
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new "my-project", "/path/to/keyfile.json"
+      #   search = gcloud.search
+      #
+      #   search.project #=> "my-project"
+      #
+      def project
+        connection.project
+      end
+
+      ##
+      # Default project.
+      def self.default_project #:nodoc:
+        ENV["SEARCH_PROJECT"] ||
+          ENV["GCLOUD_PROJECT"] ||
+          ENV["GOOGLE_CLOUD_PROJECT"] ||
+          Gcloud::GCE.project_id
+      end
+
+      ##
+      # Retrieves an existing index by ID.
+      #
+      # === Parameters
+      #
+      # +index_id+::
+      #   The ID of an index. (+String+)
+      # +skip_lookup+::
+      #   Optionally create an Index object without verifying the index resource
+      #   exists on the Search service. Documents saved on this object will
+      #   create the index resource if the resource does not yet exist. Default
+      #   is +false+. (+Boolean+)
+      #
+      # === Returns
+      #
+      # Gcloud::Search::Index or nil if the index does not exist
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #
+      #   index = search.index "books"
+      #   index.index_id #=> "books"
+      #
+      # A new index can be created by providing the desired +index_id+ and the
+      # +skip_lookup+ option:
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #
+      #   index = search.index "more-books"
+      #   index #=> nil
+      #   index = search.index "more-books", skip_lookup: true
+      #   index.index_id #=> "more-books"
+      #
+      def index index_id, skip_lookup: false
+        if skip_lookup
+          index_hash = { "indexId" => index_id, "projectId" => project }
+          return Gcloud::Search::Index.from_raw index_hash, connection
+        end
+        indexes(prefix: index_id).all.detect do |ix|
+          ix.index_id == index_id
+        end
+      end
+
+      ##
+      # Retrieves the list of indexes belonging to the project.
+      #
+      # === Parameters
+      #
+      # +prefix+::
+      #   The prefix of the index name. It is used to list all indexes with
+      #   names that have this prefix. (+String+)
+      # +token+::
+      #   A previously-returned page token representing part of the larger set
+      #   of results to view. (+String+)
+      # +max+::
+      #   Maximum number of indexes to return. The default is +100+. (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Search::Index (See Gcloud::Search::Index::List)
+      #
+      # === Examples
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #
+      #   indexes = search.indexes
+      #   indexes.each do |index|
+      #     puts index.index_id
+      #   end
+      #
+      # If you have a significant number of indexes, you may need to paginate
+      # through them: (See Gcloud::Search::Index::List)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #
+      #   indexes = search.indexes
+      #   loop do
+      #     indexes.each do |index|
+      #       puts index.index_id
+      #     end
+      #     break unless indexes.next?
+      #     indexes = indexes.next
+      #   end
+      #
+      def indexes prefix: nil, token: nil, max: nil
+        ensure_connection!
+        options = { prefix: prefix, token: token, max: max }
+        resp = connection.list_indexes options
+        if resp.success?
+          Index::List.from_response resp, connection
+        else
+          fail ApiError.from_response(resp)
+        end
+      end
+
+      protected
+
+      ##
+      # Raise an error unless an active connection is available.
+      def ensure_connection!
+        fail "Must have active connection" unless connection
+      end
+    end
+  end
+end

data/lib/gcloud/search/result.rb

@@ -0,0 +1,169 @@
+#--
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gcloud/search/result/list"
+require "gcloud/search/fields"
+
+module Gcloud
+  module Search
+    ##
+    # = Result
+    #
+    # See Gcloud#search
+    class Result
+      ##
+      # Creates a new Result instance.
+      def initialize #:nodoc:
+        @fields = Fields.new
+        @raw = {}
+      end
+
+      ##
+      # The unique identifier of the document referenced in the search result.
+      def doc_id
+        @raw["docId"]
+      end
+
+      ##
+      # The token for the next page of results.
+      def token
+        @raw["nextPageToken"]
+      end
+
+      ##
+      # Retrieve the field values associated to a field name.
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. New values will be configured with this name.
+      #   (+String+)
+      #
+      # === Returns
+      #
+      # FieldValue
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   documents = index.search "best T-shirt ever"
+      #   document = documents.first
+      #   puts "The best match for your search is:"
+      #   document["description"].each do |value|
+      #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+      #   end
+      #
+      def [] name
+        @fields[name]
+      end
+
+      # rubocop:disable Style/TrivialAccessors
+      # Disable rubocop because we want .fields to be listed with the other
+      # methods on the class.
+
+      ##
+      # The fields in the search result. Each field has a name (String) and a
+      # list of values (FieldValues). (See Fields)
+      def fields
+        @fields
+      end
+
+      # rubocop:enable Style/TrivialAccessors
+
+      ##
+      # Calls block once for each field, passing the field name and values pair
+      # as parameters. If no block is given an enumerator is returned instead.
+      # (See Fields#each)
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   documents = index.search "best T-shirt ever"
+      #   document = documents.first
+      #   puts "The best match for your search is:"
+      #   document.each do |name, values|
+      #     puts "* #{name}:"
+      #     values.each do |value|
+      #       puts "  * #{value} (#{value.type})"
+      #     end
+      #   end
+      #
+      def each &block
+        @fields.each(&block)
+      end
+
+      ##
+      # Returns a new array populated with all the field names.
+      # (See Fields#names)
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   documents = index.search "best T-shirt ever"
+      #   document = documents.first
+      #   puts "The best match has the following fields:"
+      #   document.names.each do |name|
+      #     puts "* #{name}:"
+      #   end
+      #
+      def names
+        @fields.names
+      end
+
+      ##
+      # Override to keep working in interactive shells manageable.
+      def inspect #:nodoc:
+        insp_token = ""
+        if token
+          trunc_token = "#{token[0, 8]}...#{token[-5..-1]}"
+          trunc_token = token if token.length < 20
+          insp_token = ", token: #{trunc_token.inspect}"
+        end
+        insp_fields = ", fields: (#{fields.names.map(&:inspect).join ', '})"
+        "#{self.class}(doc_id: #{doc_id.inspect}#{insp_token}#{insp_fields})"
+      end
+
+      ##
+      # New Result from a raw data object.
+      def self.from_hash hash #:nodoc:
+        result = new
+        result.instance_variable_set "@raw", hash
+        result.instance_variable_set "@fields", Fields.from_raw(hash["fields"])
+        result
+      end
+
+      ##
+      # Returns the Result data as a hash
+      def to_hash #:nodoc:
+        hash = @raw.dup
+        hash["fields"] = @fields.to_raw
+        hash
+      end
+    end
+  end
+end