proto_plugin 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c7fb4f38a0f6f9a22f62228fbd39ac9995319b83b05667f83b510cd3e3407fb
-  data.tar.gz: d6f39e7a5a77c5f541ee2c52f12d114c8fb6795d8e27617542927008911a23dc
+  metadata.gz: d119edf1d041fd9838fe8e63e00be22d1e7592dccc95033e094eb65b282913e3
+  data.tar.gz: cf6966a0c8afebfc1c573ee75151e3c494cfd8400d873d374cfecc0d45e1c8bd
 SHA512:
-  metadata.gz: a1a877e5ee1ed9e55c882cbe312abaa83c1fc29bacad7ba4c35db5c668f40cefd19182263fadfe974e458e937fa30df30d8c30257afe682a98e5ad1d071f0412
-  data.tar.gz: 8fc91b1050f5661b616ebd209a116bb8e1edb2e13a2b66b6a20b7be517c78f0fd8b4ee8317af121cc313055e5adc9414855985f70ea754d9494bcc2598a372b8
+  metadata.gz: 3dabe171b0c94f545334b1741b3eb7512a3351888f4079b4ccde46a55be9f7ed4123d6c189252f65d41f80ef695523d098870df3aa0b48c6568bca87956e7dd1
+  data.tar.gz: 2716675a6bfc4afccbe8eb743b3158338cb74e3177a5d1a053cd5e31473524c8a943508dc57a9a8839fc043f7dbea2763f9005052cf0ff66a0c51b04fecd7075

data/README.md

@@ -24,7 +24,7 @@ require "proto_plugin"
 class MyCoolPlugin < ProtoPlugin::Base
   def run
     request.file_to_generate.each do |f|
-      name = File.basename(f, ".proto")
+      name = File.basename(f.name, ".proto")
 
       add_file(name: "#{name}.txt", content: <<~TXT)
         This file was generated from #{name}.proto!

data/exe/protoc-gen-proto-plugin-demo

@@ -5,12 +5,12 @@ require "proto_plugin"
 
 class Demo < ProtoPlugin::Base
   def run
-    request.file_to_generate.each do |f|
-      name = File.basename(f, ".proto")
+    files_to_generate.each do |f|
+      name = File.basename(f.name, ".proto")
       add_file(path: "#{name}.txt", content: <<~TXT)
         Parameters: #{parameters}
 
-        This file was generated from #{name}.proto!
+        This file was generated from #{f.name}!
       TXT
     end
   end

data/lib/proto_plugin/base.rb

@@ -48,6 +48,10 @@ module ProtoPlugin
     # @return [Google::Protobuf::Compiler::CodeGeneratorRequest]
     attr_reader :request
 
+    # The context for the current invocation of the plugin.
+    # @return [Context]
+    attr_reader :context
+
     # The response message to be sent back to `protoc`.
     # @return [Google::Protobuf::Compiler::CodeGeneratorResponse]
     attr_reader :response
@@ -56,6 +60,7 @@ module ProtoPlugin
     # `Google::Protobuf::Compiler::CodeGeneratorRequest`.
     def initialize(request:)
       @request = request
+      @context = Context.new(request: request)
       @response = Google::Protobuf::Compiler::CodeGeneratorResponse.new(
         supported_features: supported_features.reduce(&:|),
       )
@@ -74,6 +79,30 @@ module ProtoPlugin
       end
     end
 
+    # Returns an array of `ProtoPlugin::FileDescriptor` representing the files that
+    # were passed to `protoc` to be generated.
+    #
+    # @example `protoc --myplugin_out=. input_one.proto input_two.proto`
+    #   [
+    #     <ProtoPlugin::FileDescriptor: name: "input_one.proto">,
+    #     <ProtoPlugin::FileDescriptor: name: "input_two.proto">
+    #   ]
+    #
+    # @return [Array<FileDescriptor>]
+    def files_to_generate
+      @files_to_generate ||= request.file_to_generate.filter_map do |filename|
+        lookup_file(name: filename)
+      end
+    end
+
+    # Finds an imported file descriptor with the given `name` attribute.
+    #
+    # @return [ProtoPlugin::FileDescriptor]
+    # @return [nil] if the file was not found
+    def lookup_file(name:)
+      context.file_by_filename(name)
+    end
+
     # Returns the list of supported `CodeGeneratorResponse::Feature` values by the plugin. The returned
     # values are bitwise or-ed together and set on `response`.
     #

data/lib/proto_plugin/context.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ProtoPlugin
+  # An object that is responsible for organizing the graph of imported descriptors for
+  # a given invocation of a plugin.
+  #
+  # It provides many helpers for looking up a file, message, or other descriptor.
+  class Context
+    # Initializes a context from a given `Google::Protobuf::Compiler::CodeGeneratorRequest`.
+    def initialize(request:)
+      index_files_by_filename(request.proto_file)
+      index_types_by_proto_name
+    end
+
+    # Finds an imported file descriptor with the given `name` attribute.
+    #
+    # @return [ProtoPlugin::FileDescriptor]
+    # @return [nil] if the file was not found
+    def file_by_filename(name)
+      @files_by_filename[name]
+    end
+
+    def type_by_proto_name(name)
+      @types_by_proto_name[name]
+    end
+
+    private
+
+    def index_files_by_filename(files)
+      @files_by_filename = files.each_with_object({}) do |fd, hash|
+        hash[fd.name] = FileDescriptor.new(self, fd)
+      end
+    end
+
+    def index_types_by_proto_name
+      @types_by_proto_name = @files_by_filename.values.each_with_object({}) do |fd, hash|
+        package = fd.package || ""
+        package = ".#{package}" unless package.empty?
+        index_enums_by_name(fd.enums, hash, prefix: package)
+        index_messages_by_name(fd.messages, hash, prefix: package)
+      end
+    end
+
+    def index_enums_by_name(enums, hash, prefix:)
+      enums.each do |e|
+        hash["#{prefix}.#{e.name}"] = e
+      end
+    end
+
+    def index_messages_by_name(msgs, hash, prefix:)
+      msgs.each do |m|
+        path = "#{prefix}.#{m.name}"
+        index_enums_by_name(m.enums, hash, prefix: path)
+        index_messages_by_name(m.messages, hash, prefix: path)
+        hash[path] = m
+      end
+    end
+  end
+end

data/lib/proto_plugin/enum_descriptor.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ProtoPlugin
+  # A wrapper class around `Google::Protobuf::EnumDescriptorProto`
+  # which provides helpers and more idiomatic Ruby access patterns.
+  #
+  # Any method not defined directly is delegated to the descriptor the wrapper was initialized with.
+  #
+  # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L336
+  class EnumDescriptor < SimpleDelegator
+    # @return [Google::Protobuf::EnumDescriptorProto]
+    attr_reader :descriptor
+
+    # The file or message descriptor this enum was defined within.
+    #
+    # @return [FileDescriptor] if defined as a root enum
+    # @return [MessageDescriptor] if defined as a nested enum (inverse of `enum_type`)
+    attr_reader :parent
+
+    # @param descriptor [Google::Protobuf::EnumDescriptorProto]
+    # @param parent [FileDescriptorFileDescriptorProto, MessageDescriptor]
+    #   The file or message descriptor this enum was defined within.
+    def initialize(descriptor, parent)
+      super(descriptor)
+      @descriptor = descriptor
+      @parent = parent
+    end
+
+    # The full name of the enum, including parent namespace.
+    #
+    # @example
+    #   "My::Ruby::Package::EnumName"
+    #
+    # @return [String]
+    def full_name
+      @full_name ||= begin
+        prefix = case parent
+        when MessageDescriptor
+          parent.full_name
+        when FileDescriptor
+          parent.namespace
+        end
+        "#{prefix}::#{name}"
+      end
+    end
+  end
+end

data/lib/proto_plugin/file_descriptor.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ProtoPlugin
+  # A wrapper class around `Google::Protobuf::FileDescriptorProto`
+  # which provides helpers and more idiomatic Ruby access patterns.
+  #
+  # Any method not defined directly is delegated to the descriptor the wrapper was initialized with.
+  #
+  # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L97
+  #   Google::Protobuf::FileDescriptorProto
+  class FileDescriptor < SimpleDelegator
+    # @return [Google::Protobuf::FileDescriptorProto]
+    attr_reader :descriptor
+
+    # @param context [Context]
+    # @param descriptor [Google::Protobuf::FileDescriptorProto]
+    def initialize(context, descriptor)
+      super(descriptor)
+      @context = context
+      @descriptor = descriptor
+    end
+
+    # The enums defined as children of this file.
+    #
+    # @return [Array<EnumDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L111
+    #   Google::Protobuf::DescriptorProto#enum_type
+    def enums
+      @enums ||= @descriptor.enum_type.map do |e|
+        EnumDescriptor.new(e, self)
+      end
+    end
+
+    # The messages defined as children of this file.
+    #
+    # @return [Array<MessageDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L110
+    #   Google::Protobuf::DescriptorProto#message_type
+    def messages
+      @messages ||= @descriptor.message_type.map do |m|
+        MessageDescriptor.new(m, self)
+      end
+    end
+
+    # Returns the Ruby namespace (module) for the file.
+    #
+    # If the `ruby_package` option was specified, then that value
+    # is returned directly. Otherwise, the `package` value is
+    # transformed to Ruby module notation.
+    #
+    # @example Using `package my.protobuf.package;`
+    #   file.namespace #=> "My::Protobuf::Package"
+    # @example Using `option ruby_package = "My::Ruby::Package";`
+    #   file.namespace #=> "My::Ruby::Package"
+    #
+    # @param split [Boolean] Returns the namespace as an array of module names.
+    #
+    # @return [String] The namespace for the file.
+    # @return [Array<String>] If `split: true`, the namespace as an array of module names.
+    def namespace(split: false)
+      @namespace ||= begin
+        namespace = @descriptor.options&.ruby_package
+        if !namespace || namespace.empty?
+          namespace = @descriptor.package.split(".")
+            .map { |token| Utils.camelize(token) }
+            .join("::")
+        end
+        namespace
+      end
+      split ? @namespace.split("::") : @namespace
+    end
+
+    # The services defined in this file.
+    #
+    # @return [Array<ServiceDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L112
+    #   Google::Protobuf::DescriptorProto#service
+    def services
+      @services ||= @descriptor.service.map do |s|
+        ServiceDescriptor.new(s, self, @context)
+      end
+    end
+  end
+end

data/lib/proto_plugin/message_descriptor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ProtoPlugin
+  # A wrapper class around `Google::Protobuf::DescriptorProto`
+  # which provides helpers and more idiomatic Ruby access patterns.
+  #
+  # Any method not defined directly is delegated to the descriptor the wrapper was initialized with.
+  #
+  # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L134
+  #   Google::Protobuf::DescriptorProto
+  class MessageDescriptor < SimpleDelegator
+    # @return [Google::Protobuf::DescriptorProto]
+    attr_reader :descriptor
+
+    # The file or message descriptor this message was defined within.
+    #
+    # @return [FileDescriptor] if defined as a root message
+    # @return [MessageDescriptor] if defined as a nested message (inverse of `nested_type`)
+    attr_reader :parent
+
+    # @param descriptor [Google::Protobuf::DescriptorProto]
+    # @param parent [FileDescriptorFileDescriptorProto, MessageDescriptor]
+    #   The file or message descriptor this message was defined within.
+    def initialize(descriptor, parent)
+      super(descriptor)
+      @descriptor = descriptor
+      @parent = parent
+    end
+
+    # The enums defined as children of this message.
+    #
+    # @return [Array<EnumDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L141
+    #   Google::Protobuf::DescriptorProto#enum_type
+    def enums
+      @enums ||= @descriptor.enum_type.map do |e|
+        EnumDescriptor.new(e, self)
+      end
+    end
+
+    # The messages defined as children of this message.
+    #
+    # @return [Array<MessageDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L140
+    #   Google::Protobuf::DescriptorProto#nested_type
+    def messages
+      @nested_messages ||= @descriptor.nested_type.map do |m|
+        MessageDescriptor.new(m, self)
+      end
+    end
+
+    # The full name of the message, including parent namespace.
+    #
+    # @example
+    #   "My::Ruby::Package::MessageName"
+    #
+    # @return [String]
+    def full_name
+      @full_name ||= begin
+        prefix = case parent
+        when MessageDescriptor
+          parent.full_name
+        when FileDescriptor
+          parent.namespace
+        end
+        "#{prefix}::#{name}"
+      end
+    end
+  end
+end

data/lib/proto_plugin/method_descriptor.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ProtoPlugin
+  # A wrapper class around `Google::Protobuf::MethodDescriptorProto`
+  # which provides helpers and more idiomatic Ruby access patterns.
+  #
+  # Any method not defined directly is delegated to the descriptor the wrapper was initialized with.
+  #
+  # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L381
+  class MethodDescriptor < SimpleDelegator
+    # @return [Google::Protobuf::MethodDescriptorProto]
+    attr_reader :descriptor
+
+    # The service this method was defined in.
+    #
+    # @return [ServiceDescriptor]
+    attr_reader :service
+
+    # @param descriptor [Google::Protobuf::MethodDescriptorProto]
+    # @param service [ServiceDescriptor] The service this method was defined in.
+    # @param context [Context]
+    def initialize(descriptor, service, context)
+      super(descriptor)
+      @descriptor = descriptor
+      @service = service
+      @context = context
+    end
+
+    # Returns the `MessageDescriptor` of the method's input type.
+    #
+    # @return [MessageDescriptor]
+    def input
+      @context.type_by_proto_name(input_type)
+    end
+
+    # Returns the `MessageDescriptor` of the method's output type.
+    #
+    # @return [MessageDescriptor]
+    def output
+      @context.type_by_proto_name(output_type)
+    end
+
+    # Returns true if the client may stream multiple client messages.
+    #
+    # @return [Boolean]
+    def client_streaming?
+      descriptor.client_streaming
+    end
+
+    # Returns true if the server may stream multiple server messages.
+    #
+    # @return [Boolean]
+    def server_streaming?
+      descriptor.server_streaming
+    end
+
+    # Returns true if both the client and server only may send single messages.
+    #
+    # @return [Boolean]
+    def unary?
+      !client_streaming? && !server_streaming?
+    end
+
+    # Returns true if both the client and server may send multiple streamed messages.
+    #
+    # @return [Boolean]
+    def bidirectional_streaming?
+      client_streaming? && server_streaming?
+    end
+  end
+end

data/lib/proto_plugin/service_descriptor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module ProtoPlugin
+  # A wrapper class around `Google::Protobuf::ServiceDescriptorProto`
+  # which provides helpers and more idiomatic Ruby access patterns.
+  #
+  # Any method not defined directly is delegated to the descriptor the wrapper was initialized with.
+  #
+  # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L373
+  class ServiceDescriptor < SimpleDelegator
+    # @return [Google::Protobuf::ServiceDescriptorProto]
+    attr_reader :descriptor
+
+    # The file this service was defined within.
+    #
+    # @return [FileDescriptor]
+    attr_reader :parent
+
+    # @param descriptor [Google::Protobuf::ServiceDescriptorProto]
+    # @param parent [FileDescriptor] The file this service was defined within.
+    # @param context [Context]
+    def initialize(descriptor, parent, context)
+      super(descriptor)
+      @descriptor = descriptor
+      @parent = parent
+      @context = context
+    end
+
+    # The full name of the service, including parent namespace.
+    #
+    # @example
+    #   "My::Ruby::Package::ServiceName"
+    #
+    # @return [String]
+    def full_name
+      @full_name ||= "#{parent.namespace}::#{name}"
+    end
+
+    # The methods defined for the service.
+    #
+    # @note This method is named `rpc_methods` to avoid conflicting with Object#methods.
+    #
+    # @return [Array<MethodDescriptor>]
+    #
+    # @see https://github.com/protocolbuffers/protobuf/blob/v28.2/src/google/protobuf/descriptor.proto#L375
+    #   Google::Protobuf::ServiceDescriptorProto#method
+    def rpc_methods
+      @rpc_methods ||= @descriptor["method"].map do |m|
+        MethodDescriptor.new(m, self, @context)
+      end
+    end
+  end
+end

data/lib/proto_plugin/utils.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ProtoPlugin
+  # A set of utility functions used by the library.
+  module Utils
+    class << self
+      # Converts string to UpperCamelCase.
+      #
+      # @param value [String]
+      #
+      # @return [String]
+      def camelize(value)
+        string = value.to_s
+
+        if string.match?(/\A[a-z\d]*\z/)
+          return string.capitalize
+        else
+          string = string.sub(/^[a-z\d]*/) do |match|
+            match.capitalize! || match
+          end
+        end
+
+        string.gsub!(%r{(?:_|(/))([a-z\d]*)}i) do
+          word = ::Regexp.last_match(2)
+          substituted = word.capitalize! || word
+          ::Regexp.last_match(1) ? "::#{substituted}" : substituted
+        end
+
+        string
+      end
+    end
+  end
+end

data/lib/proto_plugin/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module ProtoPlugin
-  VERSION = "0.2.0"
+  # The version of the ProtoPlugin gem.
+  # @return [String]
+  VERSION = "0.3.0"
 end

data/lib/proto_plugin.rb

@@ -1,7 +1,15 @@
 # frozen_string_literal: true
 
+# Easily build protobuf compiler plugins in Ruby.
 module ProtoPlugin
 end
 
-require_relative "proto_plugin/version"
+require_relative "proto_plugin/utils"
+require_relative "proto_plugin/context"
+require_relative "proto_plugin/file_descriptor"
+require_relative "proto_plugin/enum_descriptor"
+require_relative "proto_plugin/message_descriptor"
+require_relative "proto_plugin/service_descriptor"
+require_relative "proto_plugin/method_descriptor"
 require_relative "proto_plugin/base"
+require_relative "proto_plugin/version"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: proto_plugin
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Jonathan Baker
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-25 00:00:00.000000000 Z
+date: 2025-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -24,7 +23,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.28'
-description: 
 email:
 - jonathan@jmb.dev
 executables:
@@ -37,6 +35,13 @@ files:
 - exe/protoc-gen-proto-plugin-demo
 - lib/proto_plugin.rb
 - lib/proto_plugin/base.rb
+- lib/proto_plugin/context.rb
+- lib/proto_plugin/enum_descriptor.rb
+- lib/proto_plugin/file_descriptor.rb
+- lib/proto_plugin/message_descriptor.rb
+- lib/proto_plugin/method_descriptor.rb
+- lib/proto_plugin/service_descriptor.rb
+- lib/proto_plugin/utils.rb
 - lib/proto_plugin/version.rb
 homepage: https://github.com/cocoahero/proto_plugin
 licenses:
@@ -47,7 +52,6 @@ metadata:
   documentation_uri: https://cocoahero.github.io/proto_plugin
   allowed_push_host: https://rubygems.org
   funding_uri: https://github.com/sponsors/cocoahero
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -55,15 +59,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - "~>"
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Easily build protobuf compiler plugins in Ruby.
 test_files: []