protoc-gen-twirp_ruby 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30f68aaf9f4bab30eb440d98f94cb4840712d18ce8dd44b846b1ba2b8c95878f
-  data.tar.gz: c6ca8284ee938254b60383cf3c38bb801940f758e460c0fd63cdf61468d0f9e1
+  metadata.gz: dae48985eff8d4e3133f64234bf45aa141297f9b8f5e0d516f6ff6c7f9e88d11
+  data.tar.gz: 8feef99527f54ccae5a134e69a5d8f175afa638666fd7664b468ad65a8162347
 SHA512:
-  metadata.gz: 55d98147c37865e774a5e5b68206b53fad68c25b7ac61a9a69a92bf09d0adb569a7e8175aae8dd281be1b94099b699a7830f18c7c256e78db00799b5cddb092b
-  data.tar.gz: b32badee47a22d048aef598801a4412e8cd85b5cc69d6f1665f88cb58fd0d3d7a0adca19145713a258529e480bef58cc5f98d14792f1b9c4e42d36c3c6d280b5
+  metadata.gz: 7b20a7052a82e3fe2ea18bc7d524fb340e0ea275f6330243ded7d987acef6e26c596e069df7288fe76ec48091cc0eefcd18c16430ff4513748d2af2a73eb2273
+  data.tar.gz: 199c42f3b6f8a3952f8f3c6f9d4be6bfbba3944d9349efefb748afd6e00491fa4cb13a3ac19b54f0049b28167e8f975d217b382ceaa88d0d959a3d98f3b55bba

data/CHANGELOG.md

@@ -1,6 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## [Unreleased]
 
-- Nothing (yet)
+- No notable changes since last release
+
+## [1.2.0] - 2024-05-29
+
+- Streamline gem release with rake task - [#41](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/41)
+- Make `skip-empty` the default behavior; remove recognizing the option flag - [#40](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/40) 
+- Update GitHub action to run specs on all supported Ruby versions - [#37](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/37)
+
+## [1.1.1] - 2024-05-22
+
+- Remove unnecessary `racc` runtime dependency - [#33](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/33)
 
 ## [1.1.0] - 2024-05-21
 

data/README.md

@@ -1,14 +1,22 @@
 [![Gem Version](https://img.shields.io/gem/v/protoc-gen-twirp_ruby.svg)](https://rubygems.org/gems/protoc-gen-twirp_ruby)
-[![Build](https://github.com/collectiveidea/protoc-gen-twirp_ruby/actions/workflows/main.yml/badge.svg)](https://github.com/collectiveidea/protoc-gen-twirp_ruby/actions/workflows/main.yml)
+[![Specs](https://github.com/collectiveidea/protoc-gen-twirp_ruby/actions/workflows/rspec.yml/badge.svg)](https://github.com/collectiveidea/protoc-gen-twirp_ruby/actions/workflows/rspec.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/a0020a73103eedbe760c/test_coverage)](https://codeclimate.com/github/collectiveidea/protoc-gen-twirp_ruby/test_coverage)
 
-# protoc-gen-twirp_ruby
+# protoc-gen-twirp_ruby - A `protoc` plugin for Twirp-Ruby.
 
-This gem provides a `protoc` plugin that generates [Twirp-Ruby](https://github.com/arthurnn/twirp-ruby) services and clients.
+This gem is a `protoc` plugin that generates [Twirp-Ruby](https://github.com/arthurnn/twirp-ruby) services and clients.
 
-**NOTE:** Twirp-Ruby [already has a protoc plugin available](https://github.com/arthurnn/twirp-ruby/tree/main/protoc-gen-twirp_ruby)
-released as a `go` module. This project creates an alternative plugin written in Ruby and distributed as a gem that
-produces comparable output while being both more familiar and accessible to Ruby developers.
+## Why use this? 
+
+Twirp-Ruby [already does this](https://github.com/arthurnn/twirp-ruby/tree/main/protoc-gen-twirp_ruby)
+via a `go` module. So why use this version? 
+
+* Easier install (just add the gem).
+* You already know and love Ruby.
+* We're committed to keeping it up to date.
+
+The Go version works fine (we used it for years) but it was missing features that we wanted. Building in Ruby allows us to iterate quicker and makes it easier for others to contribute.
 
 ## Installation
 
@@ -25,70 +33,69 @@ the `--ruby_out` option). It does not generate Twirp services and clients; that
 
 ### Install the `protoc-gen-twirp_ruby` plugin
  
-Install the gem by adding it to your Gemfile:
+Run `gem install protoc-gen-twirp_ruby` or add it to your Gemfile:
 
 ```ruby
-group :development, :test do
-  "protoc-gen-twirp_ruby"
-end
-````
-
-Alternatively, install the gem on your system:
-
-```bash
-gem install protoc-gen-twirp_ruby
+gem "protoc-gen-twirp_ruby", group: :development
 ```
 
-## Migration from the `protoc-gen-twirp_ruby` go module
+If you previously used the Go version, see our [Migration Instructions](#migrating-from-the-go-module).
 
-If you have previously installed the `go` version of the plugin via the [Twirp-Ruby Code Generation wiki page](https://github.com/arthurnn/twirp-ruby/wiki/Code-Generation)
-instructions, then you'll want to uninstall it before invoking the `protoc` command.
+## Usage
+
+Pass `--twirp_ruby_out` to `protoc` to generate Twirp-Ruby code:
 
 ```bash
-rm `go env GOPATH`/bin/protoc-gen-twirp_ruby
+protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./path/to/service.proto
 ```
 
-### Notable plugin differences
+### Options
 
-This gem generates nearly identical Twirp-Ruby output as the go version plugin. Some notable differences
-that might affect migration include:
+You can configure the code generation. Pass options by specifying `--twirp_ruby_opt=<option>` on the `protoc` command line.
 
- * Generated output code is in [standardrb style](https://github.com/standardrb/standard).
- * Generated service and client class names are improved for well-named protobuf services. See [#6](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/6).
- * Supports various protoc command line [configuration options](https://github.com/collectiveidea/protoc-gen-twirp_ruby?tab=readme-ov-file#options).
+ * `generate=<service|client|both>`: Customize generated output to include generated services, clients, or both. Optional,
+    defaults to both to preserve backwards compatibility.
+   * `generate=service` - only generate `::Twirp::Service`s.
+   * `generate=client` - only generate `::Twirp::Client`s.
+   * `generate=both` - default; generate both services and clients. 
 
-## Usage
+Example : 
+
+```bash
+protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. --twirp_ruby_opt=generate=client ./path/to/service.proto
+```
 
-Once `protoc` and the `protoc-gen-twirp_ruby` gem is installed, pass `--twirp_ruby_out` to generate Twirp-Ruby code:
+## Migrating from the Go module
+
+If you previously installed the `protoc-gen-twirp_ruby` Go module via the [Twirp-Ruby's Code Generation wiki page](https://github.com/arthurnn/twirp-ruby/wiki/Code-Generation)
+instructions, then you'll want to uninstall it before invoking the `protoc` command.
 
 ```bash
-protoc --proto_path=. --ruby_out=. --twirp_ruby_out=. ./path/to/service.proto
+rm `go env GOPATH`/bin/protoc-gen-twirp_ruby
 ```
 
-### Options
+### Differences from the Go module
 
-The plugin supports the following options to configure code generation. Pass options by
-specifying `--twirp_ruby_opt=<option>` on the `protoc` command line.
+This gem generates nearly identical Twirp-Ruby output as the Go version. Some notable differences
+that might affect migration include:
 
- * `skip-empty`: Avoid generating a `_twirp.rb` for a `.proto` with no service definitions. By default, a `_twirp.rb`
-   file is generated for every proto file listed on the command line, even if the file is empty scaffolding. 
- * `generate=<service|client|both>`: Customize generated output to include generated services, clients, or both.
-   * `generate=service` - only generate `::Twirp::Service` subclass(es).
-   * `generate=client` - only generate `::Twirp::Client` subclass(es).
-   * `generate=both` - generate both services and clients. This is the default option to preserve
-     backwards compatibility.
+ * Generated output code is in [standardrb style](https://github.com/standardrb/standard).
+ * Generated service and client class names are improved for well-named protobuf services. See [#6](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/6).
+ * Supports `ruby_package` in `.proto` files
+ * Supports protoc command line [configuration options](#options).
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-For continued development purposes, we can route `protoc` to the local repo code for the plugin and generate against the example via:
+To experiment with development changes, route `protoc` to the local plugin when generating code
+via the `--plugin=protoc-gen-twirp_ruby=./exe/protoc-gen-twirp_ruby` option. For example:
 
 ```bash
 protoc --plugin=protoc-gen-twirp_ruby=./exe/protoc-gen-twirp_ruby --ruby_out=. --twirp_ruby_out=. ./example/hello_world.proto
 ```
 
-The local code for the gem can also be installed via `bundle exec rake install` to omit the `--plugin=protoc-gen-twirp_ruby=` option from `protoc`:
+Alternatively, install the local gem before invoking `protoc`:
 
 ```bash
 bundle exec rake install
@@ -97,7 +104,16 @@ protoc --ruby_out=. --twirp_ruby_out=. ./example/hello_world.proto
 
 ## Releasing
 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Install the [GitHub CLI](https://cli.github.com): `brew install gh` or [follow the instructions](https://github.com/cli/cli#installation).
+
+To release a new version:
+
+ * Submit a PR with the following changes (see e.g. [#30](https://github.com/collectiveidea/protoc-gen-twirp_ruby/pull/30)):
+   * Update the version number in `version.rb`
+   * Update the CHANGELOG.md
+     * Create a section for the new version and move the unreleased version there
+   * Re-generate the example: `bundle exec rake example`
+ * Once merged and `main` is up-to-date, run `bundle exec rake release`.
 
 ## Contributing
 

data/lib/twirp/protoc_plugin/code_generator.rb

@@ -10,9 +10,7 @@ module Twirp
     class CodeGenerator
       # @param proto_file [Google::Protobuf::FileDescriptorProto]
       # @param relative_ruby_protobuf [String] e.g. "example_rb.pb"
-      # @param options [Hash{Symbol => Boolean, Symbol}]
-      #   * :skip_empty [Boolean] indicating whether generation should skip creating a twirp file
-      #       for proto files that contain no services.
+      # @param options [Hash{Symbol => Symbol}]
       #   * :generate [Symbol] one of: :service, :client, or :both.
       def initialize(proto_file, relative_ruby_protobuf, options)
         @proto_file = proto_file
@@ -42,10 +40,6 @@ module Twirp
           indent_level += 1
         end
 
-        unless @proto_file.has_service?
-          output << line("# No services found; To skip generating this file, specify `--twirp_ruby_opt=skip-empty`.", indent_level)
-        end
-
         @proto_file.service.each_with_index do |service, index| # service: <Google::Protobuf::ServiceDescriptorProto>
           # Add newline between definitions when multiple are generated
           output << "\n" if index > 0

data/lib/twirp/protoc_plugin/core_ext/string/to_anchor.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class String
+  # Converts the string to an acceptable URL anchor.
+  #
+  # Thw rules for GitHub markdown links are:
+  #   - force lowercase
+  #   - strip punctuation
+  #   - replace spaces with dashes
+  # @return [String] the string converted to an acceptable URL anchor
+  def to_anchor
+    downcase.gsub(/[^a-z0-9_ -]/, "").tr(" ", "-")
+  end
+end

data/lib/twirp/protoc_plugin/process.rb

@@ -25,7 +25,7 @@ module Twirp
 
         request.proto_file.each do |proto_file| # proto_file: <Google::Protobuf::FileDescriptorProto>
           next unless request.file_to_generate.include?(proto_file.name)
-          next if options[:skip_empty] && !proto_file.has_service?
+          next unless proto_file.has_service? # do not generate when no services defined
 
           file = Google::Protobuf::Compiler::CodeGeneratorResponse::File.new
           file.name = proto_file.twirp_output_filename
@@ -39,19 +39,19 @@ module Twirp
 
       private
 
-      # @param params [String] the parameters from protoc command line in comma-separated stringified
-      #   array format, e.g. "some-flag,key1=value1".
+      # @param params [String] the parameters from `protoc` command line in comma-separated stringified
+      #   array format, e.g. "some-flag,key1=value1". For repeated command line options, `protoc` will
+      #   add the option multiple times, e.g. "some-flag,key1=value1,key1=twice,key2=value2".
       #
-      #   The only valid parameter is currently the optional "skip-empty" flag.
-      # @return [Hash{Symbol => Boolean, Symbol}]
-      #   * :skip_empty [Boolean] indicating whether generation should skip creating a twirp file
-      #       for proto files that contain no services. Default false.
+      #   The only valid parameter is currently the optional "generate" parameter.
+      #
+      # @return Hash{Symbol => Symbol} the extracted options, a Hash that contains:
       #   * :generate [Symbol] one of: :service, :client, or :both. Default :both.
+      #
       # @raise [ArgumentError] when a required parameter is missing, a parameter value is invalid, or
       #   an unrecognized parameter is present on the command line
       def extract_options(params)
         opts = {
-          skip_empty: false,
           generate: :both
         }
 
@@ -60,12 +60,7 @@ module Twirp
           # In the event value contains an =, we want to leave that intact.
           # Limit the split to just separate the key out.
           key, value = param.split("=", 2)
-          if key == "skip-empty"
-            unless value.nil? || value.empty?
-              raise ArgumentError, "Unexpected value passed to skip-empty flag: #{value}"
-            end
-            opts[:skip_empty] = true
-          elsif key == "generate"
+          if key == "generate"
             if value.nil? || value.empty?
               raise ArgumentError, "Unexpected missing value for generate option. Please supply one of: service, client, both."
             end

data/lib/twirp/protoc_plugin/version.rb

@@ -2,6 +2,6 @@
 
 module Twirp
   module ProtocPlugin
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protoc-gen-twirp_ruby
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Darron Schall
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-05-21 00:00:00.000000000 Z
+date: 2024-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-protobuf
@@ -27,13 +27,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: racc
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -41,7 +41,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -55,7 +55,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rspec-file_fixtures
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -69,7 +69,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec-file_fixtures
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -96,7 +96,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A Ruby protoc plugin generator for Twirp-Ruby.
+description: A protoc plugin that generates Twirp-Ruby services and clients. A pure
+  Ruby alternative to the Go version that ships with Twirp-Ruby.
 email: info@collectiveidea.com
 executables:
 - protoc-gen-twirp_ruby
@@ -116,6 +117,7 @@ files:
 - lib/twirp/protoc_plugin/core_ext/string/camel_case.rb
 - lib/twirp/protoc_plugin/core_ext/string/capitalize_first.rb
 - lib/twirp/protoc_plugin/core_ext/string/snake_case.rb
+- lib/twirp/protoc_plugin/core_ext/string/to_anchor.rb
 - lib/twirp/protoc_plugin/descriptor_ext/file_descriptor_proto_ext.rb
 - lib/twirp/protoc_plugin/descriptor_ext/service_descriptor_proto_ext.rb
 - lib/twirp/protoc_plugin/process.rb
@@ -147,5 +149,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key: 
 specification_version: 4
-summary: A Ruby protoc plugin generator for Twirp-Ruby.
+summary: A protoc plugin for generating Twirp-Ruby clients and/or services
 test_files: []