RBS::Inline

RBS::Inline allows embedding RBS type declarations into Ruby code as comments. You can declare types, write the implementation, and verifies they are consistent without leaving the editor opening the Ruby code.

[!IMPORTANT] The syntax is experimental. We are still seeking the best syntax with your feedbacks.

[!IMPORTANT] This gem is a prototype for testing. We plan to merge this feature to rbs-gem and deprecate rbs-inline gem after that.

[!NOTE] Use Steep >= 1.8.0.dev to avoid the conflicts on #: syntax.

Here is a quick example of embedded declarations.

# rbs_inline: enabled

class Person
  attr_reader :name #: String

  attr_reader :addresses #: Array[String]

  # @rbs name: String
  # @rbs addresses: Array[String]
  # @rbs return: void
  def initialize(name:, addresses:)
    @name = name
    @addresses = addresses
  end

  def to_s #: String
    "Person(name = #{name}, addresses = #{addresses.join(", ")})"
  end

  # @rbs &block: (String) -> void
  def each_address(&block) #:: void
    addresses.each(&block)
  end
end

This is equivalent to the following RBS type definition.

class Person
  attr_reader name: String

  attr_reader addresses: Array[String]

  def initialize: (name: String, addresses: Array[String]) -> void

  def to_s: () -> String

  def each_address: () { (String) -> void } -> void
end

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add rbs-inline --require=false

Note that the --require=false is important to avoid having type definition dependencies to this gem, which is usually unnecessary.

You can of course add a gem call in your Gemfile yourself.

gem 'rbs-inline', require: false

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install rbs-inline

Usage

The gem works as a transpiler from annotated Ruby code to RBS files. Run rbs-inline command to generate RBS files, and use the generated files with Steep, or any tools which supports RBS type definitions.

# Print generated RBS files
$ bundle exec rbs-inline lib

# Save generated RBS files under sig/generated
$ bundle exec rbs-inline --output lib

You may want to use fswatch or likes to automatically generate RBS files when you edit the Ruby code.

$ fswatch -0 lib | xargs -0 -n1 bundle exec rbs-inline --output

More materials

Our wiki has some materials to read.

Syntax guide explains more details of the syntax and annotations.
Roadmap explains some of the missing features and our plans.
Snippets helps setting up your editors.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To 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 the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/soutaro/rbs-inline. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Rbs::Inline project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

soutaro / rbs-inline

readme