gcloud 0.5.0 → 0.6.0

data/lib/gcloud/pubsub/subscription.rb

@@ -199,18 +199,16 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:immediate]</code>::
+      # +immediate+::
       #   When +true+ the system will respond immediately even if it is not able
       #   to return messages. When +false+ the system is allowed to wait until
       #   it can return least one message. No messages are returned when a
       #   request times out. The default value is +true+. (+Boolean+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   The maximum number of messages to return for this request. The Pub/Sub
       #   system may return fewer than the number specified. The default value
       #   is +100+, the maximum value is +1000+. (+Integer+)
-      # <code>options[:autoack]</code>::
+      # +autoack+::
       #   Automatically acknowledge the message as it is pulled. The default
       #   value is +false+. (+Boolean+)
       #
@@ -250,14 +248,15 @@ module Gcloud
       #   msgs = sub.pull immediate: false
       #   msgs.each { |msg| msg.acknowledge! }
       #
-      def pull options = {}
+      def pull immediate: true, max: 100, autoack: false
         ensure_connection!
+        options = { immediate: immediate, max: max }
         resp = connection.pull name, options
         if resp.success?
           messages = Array(resp.data["receivedMessages"]).map do |gapi|
             ReceivedMessage.from_gapi gapi, self
           end
-          acknowledge messages if options[:autoack]
+          acknowledge messages if autoack
           messages
         else
           fail ApiError.from_response(resp)
@@ -274,13 +273,11 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   The maximum number of messages to return for this request. The Pub/Sub
       #   system may return fewer than the number specified. The default value
       #   is +100+, the maximum value is +1000+. (+Integer+)
-      # <code>options[:autoack]</code>::
+      # +autoack+::
       #   Automatically acknowledge the message as it is pulled. The default
       #   value is +false+. (+Boolean+)
       #
@@ -299,8 +296,8 @@ module Gcloud
       #   msgs = sub.wait_for_messages
       #   msgs.each { |msg| msg.acknowledge! }
       #
-      def wait_for_messages options = {}
-        pull options.merge(immediate: false)
+      def wait_for_messages max: 100, autoack: false
+        pull immediate: false, max: max, autoack: autoack
       end
 
       ##
@@ -309,16 +306,14 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   The maximum number of messages to return for this request. The Pub/Sub
       #   system may return fewer than the number specified. The default value
       #   is +100+, the maximum value is +1000+. (+Integer+)
-      # <code>options[:autoack]</code>::
+      # +autoack+::
       #   Automatically acknowledge the message as it is pulled. The default
       #   value is +false+. (+Boolean+)
-      # <code>options[:delay]</code>::
+      # +delay+::
       #   The number of seconds to pause between requests when the Google Cloud
       #   service has no messages to return. The default value is +1+.
       #   (+Number+)
@@ -361,10 +356,9 @@ module Gcloud
       #     # process msg
       #   end
       #
-      def listen options = {}
-        delay = options.fetch(:delay, 1)
+      def listen max: 100, autoack: false, delay: 1
         loop do
-          msgs = wait_for_messages options
+          msgs = wait_for_messages max: max, autoack: autoack
           if msgs.any?
             msgs.each { |msg| yield msg }
           else
@@ -456,9 +450,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:force]</code>::
+      # +force+::
       #   Force the latest policy to be retrieved from the Pub/Sub service when
       #   +true. Otherwise the policy will be memoized to reduce the number of
       #   API calls made to the Pub/Sub service. The default is +false+.
@@ -501,8 +493,8 @@ module Gcloud
       #   subscription = pubsub.subscription "my-subscription"
       #   policy = subscription.policy force: true
       #
-      def policy options = {}
-        @policy = nil if options[:force]
+      def policy force: nil
+        @policy = nil if force
         @policy ||= begin
           ensure_connection!
           resp = connection.get_subscription_policy name

data/lib/gcloud/pubsub/topic.rb

@@ -108,12 +108,10 @@ module Gcloud
       #   periods (.), tildes (~), plus (+) or percent signs (%). It must be
       #   between 3 and 255 characters in length, and it must not start with
       #   "goog". (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:deadline]</code>::
+      # +deadline+::
       #   The maximum number of seconds after a subscriber receives a message
       #   before the subscriber should acknowledge the message. (+Integer+)
-      # <code>options[:endpoint]</code>::
+      # +endpoint+::
       #   A URL locating the endpoint to which messages should be pushed.
       #   e.g. "https://example.com/push" (+String+)
       #
@@ -156,8 +154,9 @@ module Gcloud
       #                         deadline: 120,
       #                         endpoint: "https://example.com/push"
       #
-      def subscribe subscription_name, options = {}
+      def subscribe subscription_name, deadline: nil, endpoint: nil
         ensure_connection!
+        options = { deadline: deadline, endpoint: endpoint }
         resp = connection.create_subscription name, subscription_name, options
         if resp.success?
           Subscription.from_gapi resp.data, connection
@@ -175,9 +174,7 @@ module Gcloud
       #
       # +subscription_name+::
       #   Name of a subscription. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:skip_lookup]</code>::
+      # +skip_lookup+::
       #   Optionally create a Subscription object without verifying the
       #   subscription resource exists on the Pub/Sub service. Calls made on
       #   this object will raise errors if the service resource does not exist.
@@ -210,10 +207,10 @@ module Gcloud
       #   subscription = pubsub.subscription "my-sub", skip_lookup: true
       #   puts subscription.name
       #
-      def subscription subscription_name, options = {}
+      def subscription subscription_name, skip_lookup: nil
         ensure_connection!
-        if options[:skip_lookup]
-          return Subscription.new_lazy(subscription_name, connection, options)
+        if skip_lookup
+          return Subscription.new_lazy(subscription_name, connection)
         end
         resp = connection.get_subscription subscription_name
         return Subscription.from_gapi(resp.data, connection) if resp.success?
@@ -228,13 +225,11 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:token]</code>::
+      # +token+::
       #   The +token+ value returned by the last call to +subscriptions+;
       #   indicates that this is a continuation of a call, and that the system
       #   should return the next page of data. (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of subscriptions to return. (+Integer+)
       #
       # === Returns
@@ -275,8 +270,9 @@ module Gcloud
       #     tmp_subs = topic.subscriptions token: tmp_subs.token
       #   end
       #
-      def subscriptions options = {}
+      def subscriptions token: nil, max: nil
         ensure_connection!
+        options = { token: token, max: max }
         resp = connection.list_topics_subscriptions name, options
         if resp.success?
           Subscription::List.from_response resp, connection
@@ -351,9 +347,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:force]</code>::
+      # +force+::
       #   Force the latest policy to be retrieved from the Pub/Sub service when
       #   +true. Otherwise the policy will be memoized to reduce the number of
       #   API calls made to the Pub/Sub service. The default is +false+.
@@ -396,8 +390,8 @@ module Gcloud
       #   topic = pubsub.topic "my-topic"
       #   policy = topic.policy force: true
       #
-      def policy options = {}
-        @policy = nil if options[:force]
+      def policy force: nil
+        @policy = nil if force
         @policy ||= begin
           ensure_connection!
           resp = connection.get_topic_policy name
@@ -612,11 +606,7 @@ module Gcloud
         ##
         # Make the hash look like it was returned from the Cloud API.
         def jsonify_hash hash
-          if hash.respond_to? :to_h
-            hash = hash.to_h
-          else
-            hash = Hash.try_convert(hash) || {}
-          end
+          hash = (hash || {}).to_h
           return hash if hash.empty?
           JSON.parse(JSON.dump(hash))
         end

data/lib/gcloud/resource_manager.rb

@@ -27,9 +27,7 @@ module Gcloud
   # +keyfile+::
   #   Keyfile downloaded from Google Cloud. If file path the file must be
   #   readable. (+String+ or +Hash+)
-  # +options+::
-  #   An optional Hash for controlling additional behavior. (+Hash+)
-  # <code>options[:scope]</code>::
+  # +scope+::
   #   The OAuth 2.0 scopes controlling the set of resources and operations that
   #   the connection can access. See {Using OAuth 2.0 to Access Google
   #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
@@ -52,11 +50,12 @@ module Gcloud
   #     puts projects.project_id
   #   end
   #
-  def self.resource_manager keyfile = nil, options = {}
+  def self.resource_manager keyfile = nil, scope: nil
     if keyfile.nil?
-      credentials = Gcloud::ResourceManager::Credentials.default options
+      credentials = Gcloud::ResourceManager::Credentials.default scope: scope
     else
-      credentials = Gcloud::ResourceManager::Credentials.new keyfile, options
+      credentials = Gcloud::ResourceManager::Credentials.new keyfile,
+                                                             scope: scope
     end
     Gcloud::ResourceManager::Manager.new credentials
   end

data/lib/gcloud/resource_manager/connection.rb

@@ -36,10 +36,10 @@ module Gcloud
         @res_man = @client.discovered_api "cloudresourcemanager", API_VERSION
       end
 
-      def list_project options = {}
-        params = { filter: options.delete(:filter),
-                   pageToken: options.delete(:token),
-                   maxResults: options.delete(:max)
+      def list_project filter: nil, token: nil, max: nil
+        params = { filter: filter,
+                   pageToken: token,
+                   maxResults: max
                  }.delete_if { |_, v| v.nil? }
 
         @client.execute(

data/lib/gcloud/resource_manager/manager.rb

@@ -54,9 +54,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:filter]</code>::
+      # +filter+::
       #   An expression for filtering the results of the request. Filter rules
       #   are case insensitive. (+String+)
       #
@@ -74,10 +72,10 @@ module Gcloud
       #   * +labels.color:red+ - The project's label color has the value red.
       #   * <code>labels.color:red labels.size:big</code> - The project's label
       #     color has the value red and its label size has the value big.
-      # <code>options[:token]</code>::
+      # +token+::
       #   A previously-returned page token representing part of the larger set
       #   of results to view. (+String+)
-      # <code>options[:max]</code>::
+      # +max+::
       #   Maximum number of projects to return. (+Integer+)
       #
       # === Returns
@@ -119,8 +117,8 @@ module Gcloud
       #     puts project.project_id
       #   end
       #
-      def projects options = {}
-        resp = connection.list_project options
+      def projects filter: nil, token: nil, max: nil
+        resp = connection.list_project filter: filter, token: token, max: max
         if resp.success?
           Project::List.from_response resp, self
         else
@@ -174,16 +172,14 @@ module Gcloud
       #   The unique, user-assigned ID of the project. It must be 6 to 30
       #   lowercase letters, digits, or hyphens. It must start with a letter.
       #   Trailing hyphens are prohibited. (+String+)
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:name]</code>::
+      # +name+::
       #   The user-assigned name of the project. This field is optional and can
       #   remain unset.
       #
       #   Allowed characters are: lowercase and uppercase letters, numbers,
       #   hyphen, single-quote, double-quote, space, and exclamation point.
       #   (+String+)
-      # <code>options[:labels]</code>::
+      # +labels+::
       #   The labels associated with this project.
       #
       #   Label keys must be between 1 and 63 characters long and must conform
@@ -218,10 +214,10 @@ module Gcloud
       #                                             name: "Todos Development",
       #                                             labels: {env: :development}
       #
-      def create_project project_id, options = {}
+      def create_project project_id, name: nil, labels: nil
         resp = connection.create_project project_id,
-                                         options[:name],
-                                         options[:labels]
+                                         name,
+                                         labels
         if resp.success?
           Project.from_gapi resp.data, connection
         else

data/lib/gcloud/resource_manager/project.rb

@@ -366,9 +366,7 @@ module Gcloud
       #
       # === Parameters
       #
-      # +options+::
-      #   An optional Hash for controlling additional behavior. (+Hash+)
-      # <code>options[:force]</code>::
+      # +force+::
       #   Force load the latest policy when +true+. Otherwise the policy will be
       #   memoized to reduce the number of API calls made. The default is
       #   +false+. (+Boolean+)
@@ -411,8 +409,8 @@ module Gcloud
       #   project = resource_manager.project "tokyo-rain-123"
       #   policy = project.policy force: true
       #
-      def policy options = {}
-        @policy = nil if options[:force]
+      def policy force: nil
+        @policy = nil if force
         @policy ||= begin
           ensure_connection!
           resp = connection.get_policy project_id

data/lib/gcloud/search.rb

@@ -0,0 +1,295 @@
+# 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"
+require "gcloud/search/project"
+
+#--
+# Google Cloud Search
+module Gcloud
+  ##
+  # Creates a new +Project+ instance connected to the Search service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Identifier for a Search project. If not present, the default project for
+  #   the credentials is used. (+String+)
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  # +scope::
+  #   The OAuth 2.0 scopes controlling the set of resources and operations that
+  #   the connection can access. See {Using OAuth 2.0 to Access Google
+  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
+  #   or +Array+)
+  #
+  #   The default scopes are:
+  #
+  #   * +https://www.googleapis.com/auth/cloudsearch+
+  #   * +https://www.googleapis.com/auth/userinfo.email+
+  #
+  # === Returns
+  #
+  # Gcloud::Search::Project
+  def self.search project = nil, keyfile = nil, scope: nil
+    project ||= Gcloud::Search::Project.default_project
+    if keyfile.nil?
+      credentials = Gcloud::Search::Credentials.default scope: scope
+    else
+      credentials = Gcloud::Search::Credentials.new keyfile, scope: scope
+    end
+    Gcloud::Search::Project.new project, credentials
+  end
+
+  # rubocop:disable Metrics/LineLength
+  # Disabled because there are links in the docs that are long.
+
+  ##
+  # = Google Cloud Search
+  #
+  # Google Cloud Search allows an application to quickly perform full-text and
+  # geo-spatial searches without having to spin up instances and without the
+  # hassle of managing and maintaining a search service.
+  #
+  # Cloud Search provides a model for indexing documents containing structured
+  # data, with documents and indexes saved to a separate persistent store
+  # optimized for search operations. The API supports full text matching on
+  # string fields and allows indexing any number of documents in any number of
+  # indexes.
+  #
+  # The Cloud Search API is an Alpha release, and might be changed in
+  # backward-incompatible ways. It is not currently recommended for production
+  # use. It is not subject to any SLA or deprecation policy.
+  #
+  # == Accessing the Service
+  #
+  # Currently, the Cloud Search API is available only to white-listed users.
+  # Contact your account manager or a member of the Google Cloud sales team if
+  # you are interested in access.
+  #
+  # == Authentication
+  #
+  # Authentication is handled by Gcloud#search. You can provide the project and
+  # credential information to connect to the Cloud Search service, or if you are
+  # running on Google Compute Engine this configuration is taken care of for
+  # you. You can read more about the options for connecting in the
+  # {Authentication Guide}[link:AUTHENTICATION.md].
+  #
+  # == Managing Indexes
+  #
+  # An Index is a searchable collection of documents that belongs to a Project.
+  #
+  # You can list the indexes in your current project:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #
+  #   indexes = search.indexes  # API call
+  #   indexes.each do |index|
+  #     puts index.index_id
+  #   end
+  #
+  # And you can use the project to create new indexes:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #
+  #   index = search.index "products", skip_lookup: true
+  #
+  # A new index is an unsaved value object. Indexes cannot be created,
+  # updated, or deleted directly in the service: They are derived from the
+  # documents which are created "within" them. A new index will exist in the
+  # service once you save a document that references it.
+  #
+  # == Managing Documents
+  #
+  # Using an index, create a new, unsaved Document instance, providing
+  # your own unique document ID, as shown below, or omitting this argument to
+  # let the service assign the ID.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #
+  #   index = search.index "products"
+  #   document = index.document "product-sku-000001"
+  #   index.find document # API call
+  #   #=> nil
+  #   document.rank #=> nil
+  #
+  # Add one or more fields to the document. (See {Adding document fields}[#module-Gcloud::Search-label-Adding+document+fields], below.)
+  #
+  #   document.add "price", 24.95
+  #
+  # When your document is complete, save it:
+  #
+  #   index.save document # API call
+  #   document.rank # set by the server
+  #   #=> 1443648166
+  #
+  # You can list the documents in an index:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "products"
+  #
+  #   documents = index.documents # API call
+  #   documents.map &:doc_id #=> ["product-sku-000001"]
+  #
+  # And you can delete documents:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "products"
+  #
+  #   document = index.find "product-sku-000001"
+  #
+  #   document.delete  # API call
+  #   index.find document # API call
+  #   #=> nil
+  #
+  # To update a document after manipulating its fields or rank, just re-save it:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "products"
+  #
+  #   document = index.find "product-sku-000001"
+  #
+  #   document.rank = 12345
+  #   document.add "price", 9.95 # replace existing number value
+  #   index.save document # API call
+  #
+  # == Adding document fields
+  #
+  # Fields belong to documents and are the data that actually gets searched.
+  # Each field has a FieldValues collection, which facilitates access to
+  # FieldValue objects. Each FieldValue object will be saved as one of the
+  # {Cloud Search types}[https://cloud.google.com/search/documents_indexes#document_fields_field_names_and_multi-valued_fields].
+  # The type will be inferred from the value when possible, or you can
+  # explicitly specify it by passing a symbol with the +type+ option to
+  # Document#add.
+  #
+  # - String (+:atom+, +:html+, +:text+, or +:default+)
+  # - Number (+:number+)
+  # - Timestamp (+:datetime+)
+  # - Geovalue (+:geo+)
+  #
+  # String values can be tokenized using one of three different types of
+  # tokenization, which can be passed with the +type+ option when the value is
+  # added:
+  #
+  # - +:atom+ means "don't tokenize this string", treat it as one
+  #   thing to compare against
+  #
+  # - +:html+ means "treat this string as HTML", not comparing against the
+  #   tags, and treating the rest of the content like +:text+
+  #
+  # - +:text+ means "treat this string as normal text" and split words
+  #   apart to be compared against
+  #
+  # Again, you can add more than one value to a field, and the values may be of
+  # different types.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #
+  #   index = search.index "products"
+  #   document = index.find "product-sku-000001"
+  #   document.add "description", "The best T-shirt ever.", type: :text, lang: "en"
+  #   document.add "description", "<p>The best T-shirt ever.</p>", type: :html, lang: "en"
+  #   document["description"].size #=> 2
+  #
+  # == Searching
+  #
+  # After populating an index with documents, you can request search results
+  # with a query:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "books"
+  #
+  #   results = index.search "dark stormy"
+  #   results.each do |result|
+  #     puts result.doc_id
+  #   end
+  #
+  # By default, Result objects are sorted by document rank. For more information
+  # see the {REST API documentation for Document.rank}[https://cloud.google.com/search/reference/rest/v1/projects/indexes/documents#resource_representation.google.cloudsearch.v1.Document.rank].
+  #
+  # You can specify how to sort results with the +order+ option:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "books"
+  #
+  #   results = index.search "dark stormy", order: "published, avg_review desc"
+  #   documents = index.search query # API call
+  #
+  # You can add computed fields with the +expressions+ option, and specify the
+  # fields that are returned with the +fields+ option. No document data will be
+  # returned if you omit the +fields+ option, only `doc_id` references to any
+  # matched documents.
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "products"
+  #
+  #   results = index.search "cotton T-shirt",
+  #                          expressions: { total_price: "(price + tax)" },
+  #                          fields: ["name", "total_price", "highlight"]
+  #
+  # Just as in documents, Result data is accessible via Fields methods:
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   search = gcloud.search
+  #   index = search.index "products"
+  #   document = index.find "product-sku-000001"
+  #   results = index.search "cotton T-shirt"
+  #   values = results[0]["description"]
+  #
+  #   values[0] #=> "100% organic cotton ruby gem T-shirt"
+  #   values[0].type #=> :text
+  #   values[0].lang #=> "en"
+  #   values[1] #=> "<p>100% organic cotton ruby gem T-shirt</p>"
+  #   values[1].type #=> :html
+  #   values[1].lang #=> "en"
+  #
+  module Search
+  end
+  # rubocop:enable Metrics/LineLength
+end