gcloud 0.5.0 → 0.6.0

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

@@ -0,0 +1,85 @@
+#--
+# 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 Document
+      ##
+      # Document::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 Document::List with an array of Document instances.
+        def initialize arr = []
+          super arr
+        end
+
+        ##
+        # Whether there a next page of documents.
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of documents.
+        def next
+          return nil unless next?
+          ensure_index!
+          @index.documents token: token
+        end
+
+        ##
+        # Retrieves all documents by repeatedly loading pages until #next?
+        # returns false. Returns the list instance for method chaining.
+        def all
+          while next?
+            next_documents = self.next
+            push(*next_documents)
+            self.token = next_documents.token
+          end
+          self
+        end
+
+        ##
+        # New Documents::List from a response object.
+        def self.from_response resp, index #:nodoc:
+          data = JSON.parse resp.body
+          documents = new(Array(data["documents"]).map do |doc_hash|
+            Document.from_hash doc_hash
+          end)
+          documents.instance_eval do
+            @token = data["nextPageToken"]
+            @index = index
+          end
+          documents
+        rescue JSON::ParserError
+          raise ApiError.from_response(resp)
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active connection is available.
+        def ensure_index!
+          fail "Must have active connection" unless @index
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/search/errors.rb

@@ -0,0 +1,67 @@
+#--
+# 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/errors"
+
+module Gcloud
+  module Search
+    ##
+    # Base Search exception class.
+    class Error < Gcloud::Error
+    end
+
+    ##
+    # Raised when an API call is not successful.
+    class ApiError < Error
+      ##
+      # The code of the error.
+      attr_reader :code
+
+      ##
+      # The errors encountered.
+      attr_reader :errors
+
+      def initialize message, code, errors = [] #:nodoc:
+        super message
+        @code   = code
+        @errors = errors
+      end
+
+      def self.from_response resp #:nodoc:
+        data = JSON.parse resp.body
+        if data["error"]
+          from_response_data data["error"]
+        else
+          from_response_status resp
+        end
+      rescue JSON::ParserError
+        from_response_status resp
+      end
+
+      def self.from_response_data error #:nodoc:
+        new error["message"], error["code"], error["errors"]
+      end
+
+      def self.from_response_status resp #:nodoc:
+        if resp.status == 404
+          new "#{resp.body}: #{resp.request.uri.request_uri}",
+              resp.status
+        else
+          new resp.body, resp.status
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/search/field_value.rb

@@ -0,0 +1,164 @@
+#--
+# 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
+    ##
+    # = FieldValue
+    #
+    # FieldValue is used to represent a value that belongs to a field. (See
+    # Fields and FieldValues)
+    #
+    # A field value must have a type. A value that is a Numeric will default to
+    # `:number`, while a DateTime will default to `:datetime`. If a type is not
+    # provided it will be determined by looking at the value.
+    #
+    # String values (text, html, atom) can also specify a lang value, which is
+    # an {ISO 639-1
+    # code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   search = gcloud.search
+    #   index = search.index "products"
+    #
+    #   document = index.document "product-sku-000001"
+    #   puts "The document description is:"
+    #   document["description"].each do |value|
+    #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+    #   end
+    #
+    # For more information see {Documents and
+    # fields}[https://cloud.google.com/search/documents_indexes].
+    #
+    class FieldValue < DelegateClass(::Object)
+      attr_reader :type, :lang, :name
+
+      # rubocop:disable Metrics/LineLength
+      # Disabled because there are links in the docs that are long.
+
+      ##
+      # Create a new FieldValue object.
+      #
+      # === Parameters
+      #
+      # +value+::
+      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
+      # +type+::
+      #   The type of the field value. A field can have multiple values with
+      #   same or different types; however, it cannot have multiple Timestamp or
+      #   number values. (+Symbol+)
+      #
+      #   The following values are supported:
+      #   * +:text+ - The value is a string with maximum length 1024**2
+      #     characters.
+      #   * +:html+ - The value is an HTML-formatted string with maximum length
+      #     1024**2 characters.
+      #   * +:atom+ - The value is a string with maximum length 500 characters.
+      #   * +:geo+ - The value is a point on earth described by latitude and
+      #     longitude coordinates, represented in string with any of the listed
+      #     {ways of writing
+      #     coordinates}[http://en.wikipedia.org/wiki/Geographic_coordinate_conversion].
+      #   * +:datetime+ - The value is a +DateTime+.
+      #   * +:number+ - The value is a +Numeric+ between -2,147,483,647 and
+      #     2,147,483,647. The value will be stored as a double precision
+      #     floating point value in Cloud Search.
+      # +lang+::
+      #   The language of a string value. Must be a valid {ISO 639-1
+      #   code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+      #   (+String+)
+      # +name+::
+      #   The name of the field. New values will be configured with this name.
+      #   (+String+)
+      #
+      def initialize value, type: nil, lang: nil, name: nil #:nodoc:
+        super value
+        if type
+          @type = type.to_s.downcase.to_sym
+        else
+          @type = infer_type
+        end
+        @lang = lang if string_type?
+        @name = name
+      end
+
+      # rubocop:enable Metrics/LineLength
+
+      ##
+      # Determines if the value a string type. The value is text or html or atom
+      # (or default).
+      def string_type?
+        [:atom, :default, :html, :text].include? type
+      end
+
+      ##
+      # Get the original value object.
+      def value #:nodoc:
+        __getobj__
+      end
+
+      ##
+      # Create a new FieldValue instance from a value Hash.
+      def self.from_raw field_value, name = nil #:nodoc:
+        value = field_value["stringValue"]
+        type = field_value["stringFormat"]
+        if field_value["timestampValue"]
+          value = DateTime.parse(field_value["timestampValue"])
+          type = :datetime
+        elsif field_value["geoValue"]
+          value = field_value["geoValue"]
+          type = :geo
+        elsif field_value["numberValue"]
+          value = Float(field_value["numberValue"])
+          type = :number
+        end
+        fail "No value found in #{raw_field.inspect}" if value.nil?
+        new value, type: type, lang: field_value["lang"], name: name
+      end
+
+      ##
+      # Create a raw Hash object containing the field value.
+      def to_raw #:nodoc:
+        case type
+        when :atom, :default, :html, :text
+          {
+            "stringFormat" => type.to_s.upcase,
+            "lang" => lang,
+            "stringValue" => to_s
+          }.delete_if { |_, v| v.nil? }
+        when :geo
+          { "geoValue" => to_s }
+        when :number
+          { "numberValue" => to_f }
+        when :datetime
+          { "timestampValue" => rfc3339 }
+        end
+      end
+
+      protected
+
+      def infer_type #:nodoc:
+        if respond_to? :rfc3339
+          :datetime
+        elsif value.is_a? Numeric # must call on original object...
+          :number
+        else
+          :default
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/search/field_values.rb

@@ -0,0 +1,263 @@
+#--
+# 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/field_value"
+
+module Gcloud
+  module Search
+    ##
+    # = FieldValues
+    #
+    # The list of values for a field.
+    #
+    # Each field has a name (String) and a list of values. Each field name
+    # consists of only ASCII characters, must be unique within the document and
+    # is case sensitive. A field name must start with a letter and can contain
+    # letters, digits, or underscore, with a maximum of 500 characters.
+    #
+    # Each field on a document can have multiple values. FieldValues is the
+    # object that manages the multiple values. Values can be the same or
+    # different types; however, it cannot have multiple datetime (DateTime) or
+    # number (Float) values. (See FieldValue)
+    #
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   search = gcloud.search
+    #   index = search.index "products"
+    #
+    #   document = index.document "product-sku-000001"
+    #   puts "The document description is:"
+    #   document["description"].each do |value|
+    #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+    #   end
+    #
+    # For more information see {Documents and
+    # fields}[https://cloud.google.com/search/documents_indexes].
+    #
+    class FieldValues
+      include Enumerable
+
+      ##
+      # Create a new FieldValues object.
+      #
+      # === Parameters
+      #
+      # +name+::
+      #   The name of the field. New values will be configured with this name.
+      #   (+String+)
+      # +values+::
+      #   A list of values to add to the field. (+Array+ of +FieldValue+
+      #   objects)
+      #
+      def initialize name, values = [] # :nodoc:
+        @name = name
+        @values = values
+      end
+
+      ##
+      # Returns the element at index, or returns a subarray starting at the
+      # start index and continuing for length elements, or returns a subarray
+      # specified by range of indices.
+      #
+      # Negative indices count backward from the end of the array (-1 is the
+      # last element). For start and range cases the starting index is just
+      # before an element. Additionally, an empty array is returned when the
+      # starting index for an element range is at the end of the array.
+      #
+      # Returns nil if the index (or starting index) are out of range.
+      def [] index
+        @values[index]
+      end
+
+      # rubocop:disable Metrics/LineLength
+      # Disabled because there are links in the docs that are long.
+
+      ##
+      # Add a new value. The field name will be added to the value object. If
+      # the field value is a DateTime or Numeric, or the type is set to
+      # +:datetime+ or +:number+, then the added value will replace any existing
+      # values of the same type (since there can be only one).
+      #
+      # === Parameters
+      #
+      # +value+::
+      #   The value to add to the field. (+String+ or +Datetime+ or +Float+)
+      # +type+::
+      #   The type of the field value. An attempt is made to set the correct
+      #   type when this option is missing, although it must be provided for
+      #   +:geo+ values. A field can have multiple values with same or different
+      #   types; however, it cannot have multiple +:datetime+ or +:number+
+      #   values. (+Symbol+)
+      #
+      #   The following values are supported:
+      #   * +:default+ - The value is a string. The format will be automatically
+      #     detected. This is the default value for strings.
+      #   * +:text+ - The value is a string with maximum length 1024**2
+      #     characters.
+      #   * +:html+ - The value is an HTML-formatted string with maximum length
+      #     1024**2 characters.
+      #   * +:atom+ - The value is a string with maximum length 500 characters.
+      #   * +:geo+ - The value is a point on earth described by latitude and
+      #     longitude coordinates, represented in string with any of the listed
+      #     {ways of writing
+      #     coordinates}[http://en.wikipedia.org/wiki/Geographic_coordinate_conversion].
+      #   * +:datetime+ - The value is a +DateTime+.
+      #   * +:number+ - The value is a +Numeric+ between -2,147,483,647 and
+      #     2,147,483,647. The value will be stored as a double precision
+      #     floating point value in Cloud Search.
+      # +lang+::
+      #   The language of a string value. Must be a valid {ISO 639-1
+      #   code}[https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes].
+      #   (+String+)
+      #
+      # === Returns
+      #
+      # FieldValue
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document["sku"].add "product-sku-000001", type: :atom
+      #   document["description"].add "The best T-shirt ever.",
+      #                               type: :text, lang: "en"
+      #   document["description"].add "<p>The best T-shirt ever.</p>",
+      #                               type: :html, lang: "en"
+      #   document["price"].add 24.95
+      #
+      def add value, type: nil, lang: nil
+        new_field = FieldValue.new value, type: type, lang: lang, name: @name
+        if [:datetime, :number].include? new_field.type
+          @values.delete_if { |v| v.type == new_field.type }
+        end
+        @values << new_field
+      end
+
+      # rubocop:enable Metrics/LineLength
+
+      ##
+      # Deletes all values that are equal to value.
+      #
+      # === Parameters
+      #
+      # +value+::
+      #   The value to remove from the list of values.
+      #
+      # === Returns
+      #
+      # The last deleted +FieldValue+, or +nil+ if no matching value is found.
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document["description"].count #=> 2
+      #   document["description"].delete "The best T-shirt ever."
+      #   document["description"].count #=> 1
+      #
+      def delete value, &block
+        fv = @values.detect { |v| v == value }
+        @values.delete fv, &block
+      end
+
+      ##
+      # Deletes the value at the specified index, returning that FieldValue, or
+      # +nil+ if the index is out of range.
+      ##
+      # Deletes all values that are equal to value.
+      #
+      # === Parameters
+      #
+      # +index+::
+      #   The index of the value to be removed from the list of values.
+      #
+      # === Returns
+      #
+      # The deleted +FieldValue+ found at the specified index, or # +nil+ if the
+      # index is out of range.
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   document["description"].count #=> 2
+      #   document["description"].delete_at 0
+      #   document["description"].count #=> 1
+      #
+      def delete_at index
+        @values.delete_at index
+      end
+
+      ##
+      # Calls the given block once for each field value, passing the field value
+      # as a parameter.
+      #
+      # An Enumerator is returned if no block is given.
+      #
+      # === Example
+      #
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   search = gcloud.search
+      #   index = search.index "products"
+      #
+      #   document = index.document "product-sku-000001"
+      #   puts "The document description is:"
+      #   document["description"].each do |value|
+      #     puts "* #{value} (#{value.type}) [#{value.lang}]"
+      #   end
+      #
+      def each &block
+        @values.each(&block)
+      end
+
+      ##
+      # Returns +true+ if there are no values.
+      def empty?
+        @values.empty?
+      end
+
+      ##
+      # Create a new FieldValues instance from a name and values Hash.
+      def self.from_raw name, values #:nodoc:
+        field_values = values.map { |value| FieldValue.from_raw value, name }
+        FieldValues.new name, field_values
+      end
+
+      ##
+      # Create a raw Hash object containing all the field values.
+      def to_raw #:nodoc:
+        { "values" => @values.map(&:to_raw) }
+      end
+    end
+  end
+end