{"id":13878788,"url":"https://github.com/square/rbs_protobuf","last_synced_at":"2025-06-13T01:39:38.207Z","repository":{"id":41872646,"uuid":"291923848","full_name":"square/rbs_protobuf","owner":"square","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-16T20:18:52.000Z","size":255,"stargazers_count":37,"open_issues_count":11,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-17T06:09:37.046Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/square.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-09-01T07:09:45.000Z","updated_at":"2024-02-01T23:43:54.000Z","dependencies_parsed_at":"2024-02-09T04:30:42.591Z","dependency_job_id":null,"html_url":"https://github.com/square/rbs_protobuf","commit_stats":{"total_commits":118,"total_committers":2,"mean_commits":59.0,"dds":"0.48305084745762716","last_synced_commit":"e8341ed74f40806a605dd826bd0aab47efc9f733"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Frbs_protobuf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Frbs_protobuf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Frbs_protobuf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/square%2Frbs_protobuf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/square","download_url":"https://codeload.github.com/square/rbs_protobuf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226138849,"owners_count":17579496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-06T08:02:00.044Z","updated_at":"2024-11-24T07:31:18.787Z","avatar_url":"https://github.com/square.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# rbs_protobuf\n\nrbs_protobuf is a [RBS](https://github.com/ruby/rbs) generator for Protocol Buffer messages. It parses `.proto` files and generates RBS type signature.\n\nIt works as a `protoc` plugin and generates RBSs for `protobuf` gem. (We plan to support `google-protobuf` gem too.)\n\n## Example\n\nThis is an example .proto file.\n\n```proto\nsyntax = \"proto2\";\n\npackage protobuf.example;\n\nmessage SearchRequest {\n  required string query = 1;\n  optional int32 page_number = 2;\n  optional int32 result_per_page = 3;\n}\n```\n\nrbs_protobuf will generate the following RBS file including method definitions for each attribute with correct types.\n\n```rbs\nmodule Protobuf\n  module Example\n    class SearchRequest \u003c ::Protobuf::Message\n      attr_reader query(): ::String\n\n      attr_writer query(): ::String?\n\n      attr_reader page_number(): ::Integer\n\n      attr_writer page_number(): ::Integer?\n\n      attr_reader result_per_page(): ::Integer\n\n      attr_writer result_per_page(): ::Integer?\n\n      def initialize: (?query: ::String?, ?page_number: ::Integer?, ?result_per_page: ::Integer?) -\u003e void\n\n      def []: (:query) -\u003e ::String\n            | (:page_number) -\u003e ::Integer\n            | (:result_per_page) -\u003e ::Integer\n            | (::Symbol) -\u003e untyped\n\n      def []=: (:query, ::String?) -\u003e ::String?\n             | (:page_number, ::Integer?) -\u003e ::Integer?\n             | (:result_per_page, ::Integer?) -\u003e ::Integer?\n             | (::Symbol, untyped) -\u003e untyped\n    end\n  end\nend\n```\n\nAnd you can type check your Ruby program using the classes with RBS above. 💪\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngroup :development do\n  gem 'rbs_protobuf', require: false\nend\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install rbs_protobuf\n\n## Usage\n\nRun `protoc` with `--rbs_out` option.\n\n    $ RBS_PROTOBUF_BACKEND=protobuf protoc --rbs_out=sig/protos protos/a.proto\n\nYou may need `bundle exec protoc ...` to let bundler set up PATH.\n\n### Options\n\n* `RBS_PROTOBUF_BACKEND` specifies the Ruby code generator gem. Supported value is `protobuf`. (We will add `google-protobuf` for `google-protobuf` gem.)\n* `PB_UPCASE_ENUMS` is for `protobuf` gem support. Specify the environment variable to make enum value constants upper case.\n* `RBS_PROTOBUF_NO_NESTED_NAMESPACE` is to make the RBS declarations flat.\n* `RBS_PROTOBUF_EXTENSION` specifies what to do for extensions.\n* `RBS_PROTOBUF_ACCEPT_NIL_ATTR_WRITER` is to allow passing `nil` to required fields.\n* `RBS_PROTOBUF_FILTERS` contains filter Ruby script paths separated by `File::PATH_SEPARATOR`\n* `RBS_PROTOBUF_CONCAT_LEVEL` contains the number of dir levels that groups generated RBS files to concat\n\n## Type checking\n\nTo type check the output, make sure your type checker configuration loads type definitions of `protobuf` gem.\n\n```ruby\n# Declare in Gemfile and load it with rbs-collection\ngem 'protobuf'\n```\n\nWe assume that you don't type check the generated `.pb.rb` code.\nIf you want to type check them, you need the definition of `Google::Protobuf`, which can be generated from [`descriptor.proto`](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/descriptor.proto).\n\n## Supported features\n\n| Protocol Buffer Feature | Support for `protobuf` gem |\n|-------------------------|----------------------------|\n| Messages                | ✓                          |\n| Enums                   | ✓                          |\n| Packages                | ✓                          |\n| Nested messages         | ✓                          |\n| Maps                    | ✓                          |\n| Extensions              | Read next section          |\n| Services                | Only generates classes     |\n| Oneof                   | No support in `protobuf` gem |\n\n## Extensions\n\nAdding extensions may cause problems if the name of new attribute conflicts.\n\n```proto\nextend SearchRequest {\n  // This extension defines an attribute.\n  optional string option = 100;\n}\n\nextend SearchRequest {\n  // Another extension defines another attribute with same name.\n  optional string option = 101;\n}\n```\n\nIn this case, defining two `option` attributes in RBS causes an error.\nSo, rbs_protobuf allows ignoring extensions for this case.\n\nYou can control the behavior with `RBS_PROTOBUF_EXTENSION` environment variable.\n\n* `false`: Ignores extensions.\n* `print`: Prints RBS for extensions instead of writing them to files. You can copy or modify the printed RBS, and put them in some RBS files.\n* Any value else: Generates RBS for extensions.\n* undefined: Ignores extensions but print messages to ask you to specify a value.\n\n## Filters\n\nYou can apply filters that modifies generated RBS files.\n\nA filter is a proc object with type of `^(String rbs_name, String rbs_content, untyped proto_file) -\u003e [String, String]`:\nIt receives the file name of RBS file, the content of RBS file, the source protobuf object, and returns a pair of RBS file name and content.\n\n```ruby\n# example_fitler.rb: It adds a warning comment at the top of the RBS content.\n-\u003e(rbs_name, rbs_content, _proto_file) {\n  [\n    rbs_name,\n    \"# Don't modify this file. This is generated with rbs_protobuf.\\n\\n\" + rbs_content\n  ]\n}\n```\n\nYou can apply filters by setting `RBS_PROTOBUF_FILTERS` environment variable.\n\n    $ RBS_PROTOBUF_BACKEND=protobuf RBS_PROTOBUF_FILTERS=example_filter.rb protoc ...\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test example:typecheck` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nThe gem works as a plugin of `protoc` command, so `protoc` command should be available for development.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/square/rbs_protobuf.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquare%2Frbs_protobuf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquare%2Frbs_protobuf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquare%2Frbs_protobuf/lists"}