gapic-generator 0.10.1 → 0.45.1

data/lib/gapic/package_snippets.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Copyright 2022 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 "google/protobuf/compiler/plugin_pb"
+require "google/cloud/tools/snippetgen/snippetindex/v1/snippet_index_pb"
+require "json"
+
+module Gapic
+  # An object that collects snippets for a package and generates the metadata
+  # content.
+  class PackageSnippets
+    # @private
+    SnippetIndex = ::Google::Cloud::Tools::SnippetGen::SnippetIndex::V1
+
+    ##
+    # Start collecting snippets for a package
+    #
+    # @param proto_package [String] Fully qualified proto package name including
+    #     API version, e.g. `google.cloud.translate.v3`. Required.
+    # @param gem_name [String] Name of the gem being generated, e.g.
+    #     `google-cloud-translate-v3`. Required.
+    # @param snippet_dir [String] Directory where snippets are generated.
+    #     Optional. Defaults to `snippets`.
+    #
+    def initialize proto_package:, gem_name:, snippet_dir: "snippets"
+      api = SnippetIndex::Api.new(
+        id: proto_package,
+        version: proto_package.split(".").last
+      )
+      client_library_object = SnippetIndex::ClientLibrary.new(
+        name: gem_name,
+        version: "",
+        language: "RUBY",
+        apis: [api]
+      )
+      @index_object = SnippetIndex::Index.new(
+        client_library: client_library_object
+      )
+      @metadata_filename = "#{snippet_dir}/snippet_metadata_#{proto_package}.json"
+      @snippet_files = []
+    end
+
+    ##
+    # Add a snippet to the collection
+    #
+    # @param method_presenter [Gapic::Presenters::MethodPresenter]
+    # @param snippet_presenter [Gapic::Presenters::SnippetPresenter]
+    # @param snippet_file [Google::Protobuf::Compiler::CodeGeneratorResponse::File]
+    # @return [self]
+    #
+    def add method_presenter:, snippet_presenter:, snippet_file:
+      service_presenter = method_presenter.service
+      snippet_lines = [""] + snippet_file.content.split("\n")
+      @index_object.snippets <<
+        build_snippet_object(snippet_presenter, method_presenter, service_presenter, snippet_lines)
+      @snippet_files << snippet_file
+      self
+    end
+
+    ##
+    # Return a list of files to render for this package. This includes all the
+    # snippet files themselves, and the metadata file.
+    #
+    # @return [Array<Google::Protobuf::Compiler::CodeGeneratorResponse::File>]
+    #
+    def files
+      metadata_content = JSON.pretty_generate json_value_for @index_object
+      metadata_file = Google::Protobuf::Compiler::CodeGeneratorResponse::File.new(
+        name: @metadata_filename,
+        content: metadata_content
+      )
+      @snippet_files + [metadata_file]
+    end
+
+    private
+
+    def build_snippet_object snippet_presenter, method_presenter, service_presenter, snippet_lines
+      service_presenter = service_presenter.rest if snippet_presenter.transport == :rest
+      SnippetIndex::Snippet.new(
+        region_tag: snippet_presenter.region_tag,
+        title: snippet_presenter.snippet_name,
+        description: snippet_presenter.description,
+        file: snippet_presenter.snippet_file_path,
+        language: "RUBY",
+        client_method: build_client_method_object(method_presenter, service_presenter),
+        canonical: true,
+        origin: "API_DEFINITION",
+        segments: build_segments_array(snippet_lines, snippet_presenter.region_tag)
+      )
+    end
+
+    def build_client_method_object method_presenter, service_presenter
+      parameter = SnippetIndex::ClientMethod::Parameter.new(
+        type: method_presenter.request_type,
+        name: "request"
+      )
+      client = SnippetIndex::ServiceClient.new(
+        short_name: service_presenter.client_suffix_for_default_transport,
+        full_name: service_presenter.client_name_full
+      )
+      SnippetIndex::ClientMethod.new(
+        short_name: method_presenter.name,
+        full_name: "#{service_presenter.client_name_full}##{method_presenter.name}",
+        async: false,
+        parameters: [parameter],
+        result_type: method_presenter.return_type,
+        client: client,
+        method: build_method_object(method_presenter, service_presenter)
+      )
+    end
+
+    def build_method_object method_presenter, service_presenter
+      service = SnippetIndex::Service.new(
+        short_name: service_presenter.name,
+        full_name: service_presenter.grpc_full_name
+      )
+      SnippetIndex::Method.new(
+        short_name: method_presenter.grpc_name,
+        full_name: method_presenter.grpc_full_name,
+        service: service
+      )
+    end
+
+    # Currently this builds only the FULL segment. We can fill out additional
+    # segment types once requirements have been clarified.
+    def build_segments_array snippet_lines, region_tag
+      start_tag_line = snippet_lines.index { |line| line.include? "[START #{region_tag}]" }
+      end_tag_line = snippet_lines.index { |line| line.include? "[END #{region_tag}]" }
+      result = []
+      if start_tag_line && end_tag_line
+        result << SnippetIndex::Snippet::Segment.new(
+          start: start_tag_line + 1,
+          end: end_tag_line - 1,
+          type: "FULL"
+        )
+      end
+      result
+    end
+
+    def json_value_for value
+      json = value.class.encode_json value, preserve_proto_fieldnames: true,
+                                            emit_defaults: true
+      JSON.parse json
+    end
+  end
+end

data/lib/gapic/path_pattern/parser.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "active_support/inflector"
 require "gapic/path_pattern/segment"
 require "gapic/path_pattern/pattern"
 
@@ -39,7 +40,7 @@ module Gapic
           segments << segment
         end
 
-        Pattern.new path_pattern, segments
+        Pattern.new format_pattern(path_pattern), segments
       end
 
       # @private
@@ -117,7 +118,7 @@ module Gapic
         match = simple_resource_id_regex.match url_pattern
         segment_pattern = match[:segment_pattern]
 
-        resource_name = match[:resource_name]
+        resource_name = ActiveSupport::Inflector.underscore match[:resource_name]
         resource_pattern = match[:resource_pattern] if match.names.include? "resource_pattern"
         resource_patterns = resource_pattern.nil? ? [] : [resource_pattern]
 
@@ -141,6 +142,14 @@ module Gapic
         remainder = match.post_match
         [segment, remainder]
       end
+
+      # Formats variables within a path pattern.
+      # @private
+      def self.format_pattern pattern
+        pattern.gsub(/\{([a-zA-Z0-9_]+)\}/) do
+          "{#{ActiveSupport::Inflector.underscore ::Regexp.last_match(1)}}"
+        end
+      end
     end
   end
 end

data/lib/gapic/path_pattern/pattern.rb

@@ -38,12 +38,66 @@ module Gapic
       end
 
       ##
-      # All argument names from this pattern
+      # All argument from this pattern, including ids for positional arguments
       # @return [Array<String>]
       def arguments
         @segments.select(&:provides_arguments?).map(&:arguments).flatten
       end
 
+      ##
+      # Whether this is a basic single-star ("*") pattern
+      # @return [Boolean]
+      def star_pattern?
+        @segments.length == 1 && @segments[0].pattern == "*"
+      end
+
+      ##
+      # Whether this is a basic double-star ("**") pattern
+      # @return [Boolean]
+      def double_star_pattern?
+        @segments.length == 1 && @segments[0].pattern == "**"
+      end
+
+      ##
+      # Whether this pattern ends with a double-star ("**")
+      # @return [Boolean]
+      def ends_with_double_star_pattern?
+        segments.last.pattern.end_with? "**"
+      end
+
+      ##
+      # Converts the PathPattern into a regex string
+      # @return [String]
+      def to_regex_str
+        regex_str = segments.first.to_regex_str
+
+        # for double wildcards the leading `/`` is optional
+        # e.g. `foo/**` should match `foo`
+        # this is why segments 'bring' the leading separator
+        # with them as they build the pattern
+        segments.drop(1).each_with_index do |segment, _index|
+          is_double_wildcard = segment.pattern == "**"
+
+          regex_str = if is_double_wildcard
+                        "#{regex_str}(?:/.*)?"
+                      else
+                        "#{regex_str}/#{segment.to_regex_str}"
+                      end
+        end
+
+        regex_str
+      end
+
+      ##
+      # Converts the PathPattern into a regex string that matches a whole field
+      # - adds markers for the beginning and end of the string
+      # - adds handling of an optional tail `/` if needed
+      # @return [String]
+      def to_field_regex_str
+        tail_slash_accept = ends_with_double_star_pattern? ? "" : "/?"
+        "^#{to_regex_str}#{tail_slash_accept}$"
+      end
+
       ##
       # Whether pattern contains a positional segment
       # @return [Boolean]
@@ -76,6 +130,15 @@ module Gapic
         parent_pattern_segments = last_segment.provides_arguments? ? segments[0...-2] : segments[0...-1]
         parent_pattern_segments.map(&:pattern_template).join("/")
       end
+
+      ##
+      # The pattern with the resource names stripped
+      # from the ResourceId segments
+      # (e.g. `collections/{resource_id=foo/*}` => `collections/foo/*`)
+      #
+      def simplified_pattern
+        @segments.map(&:simplified_pattern).join("/")
+      end
     end
   end
 end

data/lib/gapic/path_pattern/segment.rb

@@ -97,11 +97,37 @@ module Gapic
         pattern
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        false
+      end
+
+      ##
+      # The difference between `simplified_pattern` and `pattern`
+      # does not exist for the Positional segments
+      # @return [String]
+      def simplified_pattern
+        pattern
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        if pattern == "**"
+          ".*"
+        else
+          "[^/]+"
+        end
+      end
+
       # @private
       def == other
         return false unless other.is_a? self.class
 
-        (pattern == other.pattern && position == other.position)
+        pattern == other.pattern && position == other.position
       end
     end
 
@@ -129,6 +155,12 @@ module Gapic
         @type              = type
         @pattern           = pattern
         @resource_names    = resource_names
+
+        # For the segments specified like `{foo}`, the implied resource pattern is `*`
+        # `{foo}` === `{foo=*}`
+        if resource_patterns.empty?
+          resource_patterns = ["*"]
+        end
         @resource_patterns = resource_patterns
       end
 
@@ -139,15 +171,9 @@ module Gapic
         false
       end
 
-      ##
-      # Whether the segment provides a resource pattern
-      # @return [Boolean]
-      def resource_pattern?
-        resource_patterns.any?
-      end
-
       ##
       # Whether the segment provides a nontrivial resource pattern
+      # (not `*` or `**`)
       # @return [Boolean]
       def nontrivial_resource_pattern?
         resource_patterns.any? { |res_pattern| !res_pattern.match?(/^\*+$/) }
@@ -168,8 +194,8 @@ module Gapic
       end
 
       ##
-      # Returns a segment's pattern filled with dummy values
-      #   names of the values are generated starting from the index provided
+      # Returns a segment's pattern filled with dummy values.
+      # Names of the values are generated starting from the index provided.
       # @param start_index [Integer] a starting index for dummy value generation
       # @return [String] a pattern filled with dummy values
       def expected_path_for_dummy_values start_index
@@ -184,7 +210,13 @@ module Gapic
       # Path string for this segment
       # @return [String]
       def path_string
-        type == :simple_resource_id ? "\#{#{resource_names[0]}}" : pattern.gsub("{", "\#{")
+        if type == :simple_resource_id
+          name = resource_names[0]
+          name = "binding.local_variable_get :#{name}" if Gapic::RubyInfo.keywords.include? name
+          "\#{#{name}}"
+        else
+          pattern.gsub "{", "\#{"
+        end
       end
 
       ##
@@ -194,6 +226,46 @@ module Gapic
         "*"
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        true
+      end
+
+      ##
+      # The pattern with the resource name
+      # (e.g. `foo` in `{foo=bar/*}`) stripped.
+      # So `{foo=bar/*}` -> `bar/*`.
+      #
+      # Not implemented for multivariate segments
+      # (e.g `{foo}~{bar}`).
+      #
+      # @return [String]
+      def simplified_pattern
+        if resource_patterns.count > 1
+          raise "Not implemented for multivariate ResourceId segments"
+        end
+        resource_patterns[0]
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        raise "Not implemented for multivariate ResourceId segments" if resource_patterns.count > 1
+
+        resource_pattern = if resource_patterns[0].nil?
+                             "*"
+                           else
+                             resource_patterns[0]
+                           end
+
+        resource_pattern_regex = Gapic::PathPattern::Parser.parse(resource_pattern).to_regex_str
+
+        "(?<#{resource_names[0]}>#{resource_pattern_regex})"
+      end
+
       ##
       # Initialization helper to create a simple resource without a pattern
       # @param name [String] resource name
@@ -206,9 +278,10 @@ module Gapic
       def == other
         return false unless other.is_a? self.class
 
-        (type == other.type && pattern == other.pattern &&
+        type == other.type &&
+          pattern == other.pattern &&
           resource_names == other.resource_names &&
-          resource_patterns == other.resource_patterns)
+          resource_patterns == other.resource_patterns
       end
     end
 
@@ -272,6 +345,28 @@ module Gapic
         pattern
       end
 
+      ##
+      # Whether the segment is a resource id segment
+      # @return [Boolean]
+      def resource_id_segment?
+        false
+      end
+
+      ##
+      # The difference between `simplified_pattern` and `pattern`
+      # does not exist for the CollectionId segments
+      # @return [String]
+      def simplified_pattern
+        pattern
+      end
+
+      ##
+      # Creates a string with a regex representation of this segment's pattern
+      # @return [String]
+      def to_regex_str
+        pattern
+      end
+
       # @private
       def == other
         return false unless other.is_a? self.class

data/lib/gapic/presenters/enum_presenter.rb

@@ -20,8 +20,15 @@ module Gapic
     # A presenter for proto enums.
     #
     class EnumPresenter
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param enum [Gapic::Schema::Enum]
+      #
       def initialize enum
         @enum = enum
+        @type = "enum"
       end
 
       def name
@@ -35,6 +42,13 @@ module Gapic
       def values
         @values ||= @enum.values.map { |v| EnumValuePresenter.new v }
       end
+
+      ##
+      # @return [Boolean] Whether the enum is marked as deprecated.
+      #
+      def is_deprecated?
+        @enum.is_deprecated?
+      end
     end
   end
 end

data/lib/gapic/presenters/enum_value_presenter.rb

@@ -14,6 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/ruby_info"
+
 module Gapic
   module Presenters
     ##
@@ -24,8 +26,9 @@ module Gapic
         @value = value
       end
 
+      # @return [String] The enum value name without keyword collision.
       def name
-        @value.name
+        Gapic::RubyInfo.keywords.include?(@value.name) ? "#{@value.parent.name}::#{@value.name}" : @value.name
       end
 
       def doc_description

data/lib/gapic/presenters/field_presenter.rb

@@ -25,16 +25,33 @@ module Gapic
     class FieldPresenter
       include Gapic::Helpers::NamespaceHelper
 
+      # @return [String] String representation of this presenter type.
+      attr_reader :type
+
+      ##
+      # @param api [Gapic::Schema::Api]
+      # @param message [Gapic::Schema::Message]
+      # @param field [Gapic::Schema::Field]
+      #
       def initialize api, message, field
         @api = api
         @message = message
         @field = field
+        @type = "field"
       end
 
       def name
         @field.name
       end
 
+      ##
+      # @return [String] The field name to be used as a value without reserved keywords.
+      #
+      def value_name
+        name = @field.name
+        Gapic::RubyInfo.keywords.include?(name) ? "#{name}_param" : name
+      end
+
       def doc_types
         field_doc_types @field, false
       end
@@ -48,8 +65,15 @@ module Gapic
         field_doc_types @field, true
       end
 
-      def doc_description
-        @field.docs_leading_comments
+      ##
+      # The description as it should appear in YARD docs.
+      #
+      # @param transport [:grpc,:rest] Whether xref links should go to REST or
+      #   gRPC client classes. Uses the default transport if not provided.
+      # @return [String]
+      #
+      def doc_description transport: nil
+        @field.docs_leading_comments transport: transport
       end
 
       def default_value
@@ -59,7 +83,7 @@ module Gapic
       end
 
       def as_kwarg value: nil
-        "#{name}: #{value || name}"
+        "#{name}: #{value || value_name}"
       end
 
       # TODO: remove, only used in tests
@@ -126,14 +150,60 @@ module Gapic
       end
 
       ##
-      # Name of this field, camel-cased
+      # Name of this field, camel-cased.
       # @return [String]
+      #
       def camel_name
         camel_name_for name
       end
 
+      ##
+      # @return [Boolean] Whether the field is marked as deprecated.
+      #
+      def is_deprecated?
+        @field.is_deprecated?
+      end
+
       protected
 
+      # @private
+      FIELD_TYPE_MAPPING = {
+        TYPE_DOUBLE: "::Float",
+        TYPE_FLOAT: "::Float",
+        TYPE_INT64: "::Integer",
+        TYPE_UINT64: "::Integer",
+        TYPE_INT32: "::Integer",
+        TYPE_FIXED64: "::Integer",
+        TYPE_FIXED32: "::Integer",
+        TYPE_BOOL: "::Boolean",
+        TYPE_STRING: "::String",
+        TYPE_BYTES: "::String",
+        TYPE_UINT32: "::Integer",
+        TYPE_SFIXED32: "::Integer",
+        TYPE_SFIXED64: "::Integer",
+        TYPE_SINT32: "::Integer",
+        TYPE_SINT64: "::Integer"
+      }.freeze
+
+      # @private
+      FIELD_VALUE_MAPPING = {
+        TYPE_DOUBLE: "3.5",
+        TYPE_FLOAT: "3.5",
+        TYPE_INT64: "42",
+        TYPE_UINT64: "42",
+        TYPE_INT32: "42",
+        TYPE_FIXED64: "42",
+        TYPE_FIXED32: "42",
+        TYPE_BOOL: "true",
+        TYPE_STRING: "\"hello world\"",
+        TYPE_BYTES: "\"hello world\"",
+        TYPE_UINT32: "42",
+        TYPE_SFIXED32: "42",
+        TYPE_SFIXED64: "42",
+        TYPE_SINT32: "42",
+        TYPE_SINT64: "42"
+      }.freeze
+
       def field_doc_types field, output
         return field_map_type field.message, output if field.map?
         base_type =
@@ -144,14 +214,7 @@ module Gapic
             # TODO: handle when arg message is nil and enum is the type
             message_ruby_type field.enum
           else
-            case field.type
-            when 1, 2                              then "::Float"
-            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
-            when 9, 12                             then "::String"
-            when 8                                 then "::Boolean"
-            else
-              "::Object"
-            end
+            FIELD_TYPE_MAPPING[field.type] || "::Object"
           end
         field.repeated? ? "::Array<#{base_type}>" : base_type
       end
@@ -179,14 +242,8 @@ module Gapic
           # TODO: select the first non-0 enum value
           ":#{@field.enum.values.first.name}"
         else
-          case @field.type
-          when 1, 2                              then "3.5"
-          when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "42"
-          when 9, 12                             then "\"hello world\""
-          when 8                                 then "true"
-          else
-            "::Object"
-          end
+          # BUG: This should default to a better value
+          FIELD_VALUE_MAPPING[@field.type] || "::Object"
         end
       end
 
@@ -201,7 +258,7 @@ module Gapic
       def camel_name_for attr_name
         parts = attr_name.split "_"
         first_part = parts[0]
-        other_parts = parts[1..-1]
+        other_parts = parts[1..]
         other_parts_pascal = other_parts.map(&:capitalize).join
         "#{first_part}#{other_parts_pascal}"
       end