gapic-generator 0.1.1 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53e29f5e9a5cd2e6c4cf68d8e28fe095b5a0f5155f7c892f0b9b5429914b5dfb
-  data.tar.gz: 5ea2ad00f9c340675f2bd4f1b16d02dbb5d2e2b7444b450d326993de263a1cc0
+  metadata.gz: 7758f2d15a52b89f57555f192cf9d477cbfdbd9788578ba30b5e04d9c468ed85
+  data.tar.gz: ef2c5bd9924646eea488db7060dc654dc0cc2ff2ad1d5736e4f04cad217e0fe4
 SHA512:
-  metadata.gz: 8f975242f0242375263e065351763fb67594ba65fc571f882bb54ce1877a5e14ad1419ecaf75e5c58ea0c29c81f5e8becdef635f1013111b624acd3e06248e92
-  data.tar.gz: 10abc98e678f667815d6e325cb27d582d4cbe27f4037edc66cde40ae8eb76b0d7b6fc884258d8ec5473612d327059baffbea94f3e9edf1ba83ae29f2d988e655
+  metadata.gz: 6d28f3903643f3b86770f83538dcaa669668bcd9f89e85592bbc6680c95c13fc043b323cf406fa0fa37b0ad0ad21ed30bb56ed42c7a2be0b423cbfc4c0b7c423
+  data.tar.gz: a98b3d1af7be74a680e0b738b4d0753130f90c51ef71fb181a94189d1806b947338558826cd3e4f5b8c3315897546d2e36a1ce5d99d58dd501fd5aa5e8c3a76d

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Release History for gapic-generator
 
+### 0.1.7 / 2020-03-18
+
+* Path modules extend self so helpers can be invoked on them directly
+* Trigger IAM dependency for IAM V1 files other than iam_policy.proto
+
+### 0.1.6 / 2020-03-17
+
+* Generated libraries now depend on gapic-common 0.2
+* Convert cross-reference syntax in proto docs to YARD cross-reference links.
+* Preserve call options in LROs
+* Fix implicit kwarg warnings under Ruby 2.7
+
+### 0.1.5 / 2020-03-13
+
+* More improvements to escaping of curly braces.
+
+### 0.1.4 / 2020-03-12
+
+* Fixed over-escaping of curly braces in preformatted blocks in the yardocs.
+* Fixed typo in authentication document.
+
+### 0.1.3 / 2020-03-11
+
+* Generated numeric constants are formatted with underscores if necessary.
+
+### 0.1.2 / 2020-03-09
+
+* Support multiple grpc service config files
+
 ### 0.1.1 / 2020-03-09
 
 * Relax rake dependency.

data/lib/gapic/formatting_utils.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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 "bigdecimal"
+
+module Gapic
+  ##
+  # Various string formatting utils
+  #
+  module FormattingUtils
+    @brace_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*[^`\\])?\{(?<inside>[^\s][^}]*)\}(?<post>.*)\z/m
+    @xref_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*)?\[(?<text>[\w\.]+)\]\[(?<addr>[\w\.]+)\](?<post>.*)\z/m
+    @list_element_detector = /\A\s*(\*|\+|-|[0-9a-zA-Z]+\.)\s/
+
+    class << self
+      ##
+      # Given an enumerable of lines, performs yardoc formatting, including:
+      # * Interpreting cross-references identified as described in AIP 192
+      # * Escaping literal braces that look like yardoc type links
+      #
+      # Tries to be smart about exempting preformatted text blocks.
+      #
+      # @param lines [Enumerable<String>]
+      # @return [Enumerable<String>]
+      #
+      def format_doc_lines api, lines
+        # To detect preformatted blocks, this tracks the "expected" base indent
+        # according to Markdown. Specifically, this is the effective indent of
+        # previous block, which is normally 0 except if we're in a list item.
+        # Then, if a block is indented at least 4 spaces past that expected
+        # indent (and as long as it remains so), those lines are considered
+        # preformatted.
+        in_block = nil
+        base_indent = 0
+        lines.map do |line|
+          indent = line_indent line
+          if indent.nil?
+            in_block = nil
+          else
+            in_block, base_indent = update_indent_state in_block, base_indent, line, indent
+            if in_block == false
+              line = escape_line_braces line
+              line = format_line_xrefs api, line
+            end
+          end
+          line
+        end
+      end
+
+      ##
+      # Given a number, format it in such a way that Rubocop will be happy.
+      # Specifically, we add underscores if the magnitude is at least 10_000.
+      # This works for both integers and floats.
+      #
+      # @param value [Numeric]
+      # @return [String]
+      #
+      def format_number value
+        return value.to_s if value.abs < 10_000
+        str = value.is_a?(Integer) ? value.to_s : BigDecimal(value.to_f.to_s).to_s("F")
+        re = /^(-?\d+)(\d\d\d)([_\.][_\.\d]+)?$/
+        while (m = re.match str)
+          str = "#{m[1]}_#{m[2]}#{m[3]}"
+        end
+        str
+      end
+
+      private
+
+      def update_indent_state in_block, base_indent, line, indent
+        if in_block != true && @list_element_detector =~ line
+          in_block = false
+          indent = base_indent if indent > base_indent
+          base_indent = (indent + 7) / 4 * 4
+        else
+          in_block = indent >= base_indent + 4 unless in_block == false
+          base_indent = indent / 4 * 4 if in_block == false && indent < base_indent
+        end
+        [in_block, base_indent]
+      end
+
+      def line_indent line
+        m = /^( *)\S/.match line
+        m.nil? ? nil : m[1].length
+      end
+
+      def escape_line_braces line
+        while (m = @brace_detector.match line)
+          line = "#{m[:pre]}\\\\{#{m[:inside]}}#{m[:post]}"
+        end
+        line
+      end
+
+      def format_line_xrefs api, line
+        while (m = @xref_detector.match line)
+          entity = api.lookup m[:addr]
+          return line if entity.nil?
+          yard_link = yard_link_for_entity entity, m[:text]
+          return line if yard_link.nil?
+          line = "#{m[:pre]}#{yard_link}#{m[:post]}"
+        end
+        line
+      end
+
+      ##
+      # Generate a YARD-style cross-reference for the given entity.
+      #
+      # @param entity [Gapic::Schema::Proto] the entity to link to
+      # @param text [String] the text for the link
+      # @return [String] YARD cross-reference syntax
+      #
+      def yard_link_for_entity entity, text
+        # As a special case, omit the service "google.longrunning.Operations"
+        # and its methods. This is because the generator creates
+        # service-specific copies of the operations client, rather than a
+        # Google::Longrunning::Operations::Client class, and there is in
+        # general no way to tell what the actual service-specific namespace is.
+        return text if entity.address[0, 3] == ["google", "longrunning", "Operations"]
+
+        case entity
+        when Gapic::Schema::Service
+          "{#{convert_address_to_ruby entity}::Client #{text}}"
+        when Gapic::Schema::Method
+          "{#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
+        when Gapic::Schema::Message, Gapic::Schema::Enum, Gapic::Schema::EnumValue
+          "{#{convert_address_to_ruby entity} #{text}}"
+        when Gapic::Schema::Field
+          "{#{convert_address_to_ruby entity.parent}##{entity.name} #{text}}"
+        end
+      end
+
+      def convert_address_to_ruby entity
+        file = entity.containing_file
+        api = file.containing_api
+        address = entity.address
+        address = address.join "." if address.is_a? Array
+        address = address.sub file.package, file.ruby_package if file.ruby_package&.present?
+        address.split(".").reject(&:empty?).map(&:camelize).map { |node| api.fix_namespace node }.join("::")
+      end
+    end
+  end
+end

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.1.1"
+    VERSION = "0.1.7"
   end
 end

data/lib/gapic/schema/api.rb

@@ -53,6 +53,14 @@ module Gapic
         @files.each { |f| f.parent = self }
       end
 
+      def containing_api
+        self
+      end
+
+      def containing_file
+        nil
+      end
+
       def lookup address
         address = address.join "." if address.is_a? Array
         @files.each do |f|
@@ -200,16 +208,14 @@ module Gapic
         end
       end
 
-      # Raw parsed json of the grpc service config if provided
-      # or an empty hash if config was not provided
+      # Raw parsed json of the combined grpc service config files if provided
+      # or an empty hash if no config was provided
       def grpc_service_config_raw
         @grpc_service_config_raw ||= begin
-          grpc_service_config_filename = protoc_options["grpc_service_config"]
-          if grpc_service_config_filename
-            file = ::File.read grpc_service_config_filename
-            JSON.parse file
-          else
-            {}
+          filenames = protoc_options["grpc_service_config"].to_s.split ";"
+          filenames.inject({}) do |running_hash, filename|
+            file_hash = JSON.parse ::File.read filename
+            deep_merge running_hash, file_hash
           end
         end
       end
@@ -252,6 +258,8 @@ module Gapic
         left.merge right do |_k, lt, rt|
           if lt.is_a?(Hash) && rt.is_a?(Hash)
             deep_merge lt, rt
+          elsif lt.is_a?(Array) && rt.is_a?(Array)
+            lt + rt
           else
             rt
           end

data/lib/gapic/schema/wrappers.rb

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/formatting_utils"
+
 module Gapic
   module Schema
     # Base class for all generic proto types including: enums, messages,
@@ -93,18 +95,27 @@ module Gapic
         @docs = docs
       end
 
+      # Returns the "root" of this schema.
+      # @return [Gapic::Schema::Api]
+      def containing_api
+        parent&.containing_api
+      end
+
+      # Returns the file containing this proto entity
+      # @return [Gapic::Schema::File]
+      def containing_file
+        parent&.containing_file
+      end
+
       # Gets the cleaned up leading comments documentation
       def docs_leading_comments
         return nil if @docs.nil?
         return nil if @docs.leading_comments.empty?
 
-        @docs
-          .leading_comments
-          .each_line
-          .map { |line| line.start_with?(" ") ? line[1..-1] : line }
-          .join
-          .split("{").join("\\\\\\{") # The only safe way to replace with \ characters...
-          .split("}").join("\\}")
+        lines = @docs.leading_comments.each_line.to_a
+        lines.map! { |line| line.start_with?(" ") ? line[1..-1] : line }
+        lines = FormattingUtils.format_doc_lines containing_api, lines
+        lines.join
       end
 
       # @!method path
@@ -377,6 +388,10 @@ module Gapic
         @services.each { |m| m.parent = self }
       end
 
+      def containing_file
+        self
+      end
+
       def lookup address
         address = address.split(".").reject(&:empty?).join(".")
         @registry[address]

data/templates/default/gem/gemspec.erb

@@ -23,7 +23,7 @@ Gem::Specification.new do |gem|
 
   gem.required_ruby_version = ">= 2.4"
 
-  gem.add_dependency "gapic-common", "~> 0.1.0"
+  gem.add_dependency "gapic-common", "~> 0.2"
   <%- if gem.iam_dependency? -%>
   gem.add_dependency "grpc-google-iam-v1", "~> 0.6.9"
   <%- end -%>

data/templates/default/gem/gitignore.erb

@@ -16,3 +16,5 @@ pkg/*
 # Ignore files commonly present in certain dev environments
 .vagrant
 .DS_STORE
+.idea
+*.iml

data/templates/default/gem/rubocop.erb

@@ -57,3 +57,5 @@ Style/CaseEquality:
     - "lib/<%= service.client_file_path.sub "client.rb", "*.rb" %>"
     <%- end -%>
     <%- end -%>
+Style/ModuleFunction:
+  Enabled: false

data/templates/default/helpers/default_helper.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 require "active_support/inflector"
+require "gapic/formatting_utils"
 
 module DefaultHelper
   def prepend_with input, prepend
@@ -39,6 +40,10 @@ module DefaultHelper
     input.lines[0] + indent(input.lines[1..-1].join, spacing)
   end
 
+  def format_number value
+    Gapic::FormattingUtils.format_number value
+  end
+
   def assert_locals *locals
     locals.each { |local| raise "missing local in template" if local.nil? }
   end

data/templates/default/helpers/presenters/gem_presenter.rb

@@ -114,7 +114,7 @@ class GemPresenter
   end
 
   def iam_dependency?
-    @api.files.map(&:name).include? "google/iam/v1/iam_policy.proto"
+    @api.files.map(&:name).any? { |f| f.start_with? "google/iam/v1/" }
   end
 
   private

data/templates/default/service/client/_paths.erb

@@ -5,4 +5,5 @@ module Paths
 <%= indent render(partial: "service/client/resource", locals: { resource: resource }), 2 %>
 
 <%- end %>
+  extend self
 end

data/templates/default/service/client/_self_configure_defaults.erb

@@ -3,7 +3,7 @@
 <%- if service.grpc_service_config && !service.grpc_service_config.empty? -%>
 
   <%- if service.grpc_service_config.timeout_seconds -%>
-    default_config.timeout = <%= service.grpc_service_config.timeout_seconds %>
+    default_config.timeout = <%= format_number service.grpc_service_config.timeout_seconds %>
   <%- end -%>
   <%- if service.grpc_service_config.retry_policy -%>
     default_config.retry_policy = <%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: service.grpc_service_config.retry_policy }), 2 %>
@@ -13,7 +13,7 @@
   <%- if method.grpc_service_config && !method.grpc_service_config.empty? -%>
 
     <%- if method.grpc_service_config.timeout_seconds -%>
-      default_config.rpcs.<%= method.name %>.timeout = <%= method.grpc_service_config.timeout_seconds %>
+      default_config.rpcs.<%= method.name %>.timeout = <%= format_number method.grpc_service_config.timeout_seconds %>
     <%- end -%>
     <%- if method.grpc_service_config.retry_policy -%>
       default_config.rpcs.<%= method.name %>.retry_policy =<%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: method.grpc_service_config.retry_policy }), 2 %>

data/templates/default/service/client/_self_configure_retry_policy.erb

@@ -1,13 +1,13 @@
 <%- assert_locals retry_policy -%>
 {
   <%- if retry_policy.initial_delay_seconds -%>
-  initial_delay: <%= retry_policy.initial_delay_seconds %>,
+  initial_delay: <%= format_number retry_policy.initial_delay_seconds %>,
   <%- end -%>
   <%- if retry_policy.max_delay_seconds -%>
-  max_delay: <%= retry_policy.max_delay_seconds %>,
+  max_delay: <%= format_number retry_policy.max_delay_seconds %>,
   <%- end -%>
   <%- if retry_policy.multiplier -%>
-  multiplier: <%= retry_policy.multiplier %>,
+  multiplier: <%= format_number retry_policy.multiplier %>,
   <%- end-%>
   <%- if retry_policy.status_codes -%>
   retry_codes: <%= retry_policy.status_codes %>

data/templates/default/service/client/method/def/_options_defaults.erb

@@ -1,6 +1,6 @@
 <%- assert_locals method -%>
 # Converts hash and nil to an options object
-options = Gapic::CallOptions.new options.to_h if options.respond_to? :to_h
+options = Gapic::CallOptions.new(**options.to_h) if options.respond_to? :to_h
 
 # Customize the options with defaults
 metadata = @config.rpcs.<%= method.name %>.metadata.to_h

data/templates/default/service/client/method/def/_response_normal.erb

@@ -1,7 +1,7 @@
 <%- assert_locals method -%>
 @<%= method.service.stub_name %>.call_rpc :<%= method.name %>, request, options: options do |response, operation|
   <%- if method.lro? -%>
-  response = Gapic::Operation.new response, <%= method.service.lro_client_ivar %>
+  response = Gapic::Operation.new response, <%= method.service.lro_client_ivar %>, options: options
   <%- end -%>
   yield response, operation if block_given?
   return response

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gapic-generator
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.7
 platform: ruby
 authors:
 - Ernest Landrito
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-09 00:00:00.000000000 Z
+date: 2020-03-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -204,6 +204,7 @@ files:
 - gem_templates/test_helper.erb
 - gem_templates/version.erb
 - lib/gapic/file_formatter.rb
+- lib/gapic/formatting_utils.rb
 - lib/gapic/gem_builder.rb
 - lib/gapic/generator.rb
 - lib/gapic/generator/version.rb