proto_plugin 0.1.0.pre.alpha.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1f639a6d10b3b1453fe175009232fc1e1b548c4b93b7075e336b548c9a71bf
-  data.tar.gz: '008f968744cc7f74d42df472d1b191a71752973ad9ebba255673d4db4c594f28'
+  metadata.gz: 3c7fb4f38a0f6f9a22f62228fbd39ac9995319b83b05667f83b510cd3e3407fb
+  data.tar.gz: d6f39e7a5a77c5f541ee2c52f12d114c8fb6795d8e27617542927008911a23dc
 SHA512:
-  metadata.gz: 97fc2b8b9e3d1687d987696a95b479c816937ab0ff92d20e929974dc9884e9d60ff869392fa29eec69285531965a73da35146a88f62e07bcf320efbda85000be
-  data.tar.gz: 82546a40d21f5c5f893fcd89df670667743f0b15cc133134cfbe68ee997cf157a9544ee46bb97ea3f180115f89d5e98ae7671c38cdd44fd6f1b7905fa6021d1f
+  metadata.gz: a1a877e5ee1ed9e55c882cbe312abaa83c1fc29bacad7ba4c35db5c668f40cefd19182263fadfe974e458e937fa30df30d8c30257afe682a98e5ad1d071f0412
+  data.tar.gz: 8fc91b1050f5661b616ebd209a116bb8e1edb2e13a2b66b6a20b7be517c78f0fd8b4ee8317af121cc313055e5adc9414855985f70ea754d9494bcc2598a372b8

data/README.md

@@ -1,5 +1,7 @@
-# Proto::Plugin
+# ProtoPlugin
 
+[![Lint](https://github.com/cocoahero/proto_plugin/actions/workflows/lint.yml/badge.svg)](https://github.com/cocoahero/proto_plugin/actions/workflows/lint.yml)
+[![Test](https://github.com/cocoahero/proto_plugin/actions/workflows/test.yml/badge.svg)](https://github.com/cocoahero/proto_plugin/actions/workflows/test.yml)
 [![Gem Version](https://badge.fury.io/rb/proto_plugin.svg)](https://badge.fury.io/rb/proto_plugin)
 
 ## Installation
@@ -8,6 +10,55 @@
 gem install proto_plugin
 ```
 
+## Getting Started
+
+Creating a `protoc` plugin is as simple as creating a new executable script.
+
+The name of the file must follow the format `protoc-gen-[plugin-name]`. As an example, the below file could be named `protoc-gen-mycoolplugin`.
+
+```ruby
+#! /usr/bin/env ruby
+
+require "proto_plugin"
+
+class MyCoolPlugin < ProtoPlugin::Base
+  def run
+    request.file_to_generate.each do |f|
+      name = File.basename(f, ".proto")
+
+      add_file(name: "#{name}.txt", content: <<~TXT)
+        This file was generated from #{name}.proto!
+      TXT
+    end
+  end
+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
+protoc --plugin=path/to/protoc-gen-mycoolplugin --mycoolplugin_out=. input.proto
+```
+
+If the executable script is in your `$PATH`, for example installed via a gem, you can omit the `--plugin` argument.
+
+```bash
+protoc --mycoolplugin_out=. input.proto
+```
+
+See [`exe/protoc-gen-proto-plugin-demo`](./exe/protoc-gen-proto-plugin-demo) in this repo as another example of a plugin. Since it should be in your `$PATH` (you did install this gem right?) you can invoke it with:
+
+```bash
+protoc --proto-plugin-demo_out=. input.proto
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/rake` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

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

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+require "proto_plugin"
+
+class Demo < ProtoPlugin::Base
+  def run
+    request.file_to_generate.each do |f|
+      name = File.basename(f, ".proto")
+      add_file(path: "#{name}.txt", content: <<~TXT)
+        Parameters: #{parameters}
+
+        This file was generated from #{name}.proto!
+      TXT
+    end
+  end
+end
+
+Demo.run!

data/lib/proto_plugin/base.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+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(
+            input.read,
+          ),
+        )
+
+        plugin.run
+
+        result = plugin.response
+        output.write(result.to_proto)
+        result
+      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(
+        supported_features: supported_features.reduce(&:|),
+      )
+    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
+
+    # 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: path, content: content,
+      )
+    end
+
+    # The primary entrypoint. Override to provide your plugin's implementation.
+    # @abstract
+    def run
+    end
+  end
+end

data/lib/proto_plugin/version.rb

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

data/lib/proto_plugin.rb

@@ -4,3 +4,4 @@ module ProtoPlugin
 end
 
 require_relative "proto_plugin/version"
+require_relative "proto_plugin/base"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: proto_plugin
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.2
+  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
@@ -27,13 +27,16 @@ dependencies:
 description: 
 email:
 - jonathan@jmb.dev
-executables: []
+executables:
+- protoc-gen-proto-plugin-demo
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- exe/protoc-gen-proto-plugin-demo
 - lib/proto_plugin.rb
+- lib/proto_plugin/base.rb
 - lib/proto_plugin/version.rb
 homepage: https://github.com/cocoahero/proto_plugin
 licenses:
@@ -41,16 +44,18 @@ 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:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -60,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: []