proto_plugin 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96f4f3743b30d3c4f264e7756c603da53e14566c2e414b45cf2da7918635a103
-  data.tar.gz: 66cc63cd84cc91c179f0b25e9401d9f23e5d1d7cb678387dd604275abe09e240
+  metadata.gz: 3c7fb4f38a0f6f9a22f62228fbd39ac9995319b83b05667f83b510cd3e3407fb
+  data.tar.gz: d6f39e7a5a77c5f541ee2c52f12d114c8fb6795d8e27617542927008911a23dc
 SHA512:
-  metadata.gz: d6830929a04b8e7464797a2d5c4129d6840246f09b4ace2e77c7cebc5ce63d49b1a4d016e66c85f8dd0d9acf86c5ae675ed99f22a882d85f8c4feb697ea5124d
-  data.tar.gz: c2c9786adcf0530eec151fd445877788d2786b22fb0c9a3c23b8a9080a7ca27277f2b756a6deaead8a1c700e86ce66ccfb87672a1d7d4431798c9ad48880f5aa
+  metadata.gz: a1a877e5ee1ed9e55c882cbe312abaa83c1fc29bacad7ba4c35db5c668f40cefd19182263fadfe974e458e937fa30df30d8c30257afe682a98e5ad1d071f0412
+  data.tar.gz: 8fc91b1050f5661b616ebd209a116bb8e1edb2e13a2b66b6a20b7be517c78f0fd8b4ee8317af121cc313055e5adc9414855985f70ea754d9494bcc2598a372b8

data/README.md

@@ -10,7 +10,7 @@
 gem install proto_plugin
 ```
 
-## Usage
+## Getting Started
 
 Creating a `protoc` plugin is as simple as creating a new executable script.
 
@@ -36,6 +36,11 @@ end
 MyCoolPlugin.run!
 ```
 
+> [!TIP]
+> For more details on the available API, see the docs: https://cocoahero.github.io/proto_plugin
+
+### Usage
+
 To invoke the plugin, first make sure you have `protoc` [installed](https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation). Then in a terminal, run:
 
 ```bash

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

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

data/lib/proto_plugin/base.rb

@@ -4,8 +4,31 @@ require "google/protobuf"
 require "google/protobuf/plugin_pb"
 
 module ProtoPlugin
+  # The primary base class to inherit from when implementing a plugin.
+  #
+  # ```ruby
+  # require 'proto_plugin'
+  #
+  # class MyCoolPlugin < ProtoPlugin::Base
+  #   def run
+  #     # override to provide your implementation
+  #   end
+  # end
+  #
+  # MyCoolPlugin.run!
+  # ````
+  # @abstract
   class Base
     class << self
+      ##
+      # The preferred way of invoking a plugin.
+      #
+      # Decodes a `Google::Protobuf::Compiler::CodeGeneratorRequest` message
+      # from `input:`, invokes the plugin by calling `#run`, and then encodes
+      # `response` to the stream specified by `output:`.
+      #
+      # @param input [IO] The stream that the request is decoded from.
+      # @param output [IO] The stream that the response is encoded to.
       def run!(input: $stdin, output: $stdout)
         plugin = new(
           request: Google::Protobuf::Compiler::CodeGeneratorRequest.decode(
@@ -21,10 +44,16 @@ module ProtoPlugin
       end
     end
 
+    # The request message the plugin was initialized with.
+    # @return [Google::Protobuf::Compiler::CodeGeneratorRequest]
     attr_reader :request
 
+    # The response message to be sent back to `protoc`.
+    # @return [Google::Protobuf::Compiler::CodeGeneratorResponse]
     attr_reader :response
 
+    # Initializes a new instance of the plugin with a given
+    # `Google::Protobuf::Compiler::CodeGeneratorRequest`.
     def initialize(request:)
       @request = request
       @response = Google::Protobuf::Compiler::CodeGeneratorResponse.new(
@@ -32,16 +61,42 @@ module ProtoPlugin
       )
     end
 
+    # Convenience method for accessing the parameters passed to the plugin.
+    #
+    # @example `protoc --myplugin_opt=key=value --myplugin_opt=bare`
+    #  {"key" => "value", "bare" => nil}
+    #
+    # @return [Hash]
+    def parameters
+      @parameters ||= request.parameter&.split(",")&.each_with_object({}) do |param, hash|
+        key, value = param.split("=")
+        hash[key] = value
+      end
+    end
+
+    # Returns the list of supported `CodeGeneratorResponse::Feature` values by the plugin. The returned
+    # values are bitwise or-ed together and set on `response`.
+    #
+    # Defaults to `CodeGeneratorResponse::Feature::FEATURE_NONE`.
     def supported_features
       [Google::Protobuf::Compiler::CodeGeneratorResponse::Feature::FEATURE_NONE]
     end
 
-    def add_file(name:, content:)
+    # Convenience method for appending a `CodeGeneratorResponse::File` message to `response`.
+    #
+    # The path is relative to the directory specified when invoking `protoc`. For example,
+    # specifiying `--myplugin_out=gen` will result in `gen/:path`.
+    #
+    # @param path [String] The relative path to write the file's content.
+    # @param content [String] The content which will be written to the file.
+    def add_file(path:, content:)
       @response.file << Google::Protobuf::Compiler::CodeGeneratorResponse::File.new(
-        name: name, content: content,
+        name: path, content: content,
       )
     end
 
+    # The primary entrypoint. Override to provide your plugin's implementation.
+    # @abstract
     def run
     end
   end

data/lib/proto_plugin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ProtoPlugin
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proto_plugin
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jonathan Baker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-09-21 00:00:00.000000000 Z
+date: 2024-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -44,7 +44,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/cocoahero/proto_plugin
   source_code_uri: https://github.com/cocoahero/proto_plugin
+  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:
@@ -63,5 +65,5 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key: 
 specification_version: 4
-summary: Easily build `protoc` plugins in Ruby.
+summary: Easily build protobuf compiler plugins in Ruby.
 test_files: []