Repository files navigation

RBS is a language to describe the structure of Ruby programs.You can write down the definition of a class or module: methods defined in the class, instance variables and their types, and inheritance/mix-in relations.It also allows declaring constants and global variables.

The following is a small example of RBS for a chat app.

moduleChatApp  VERSION: StringclassUserattr_reader login: Stringattr_reader email: Stringdef initialize: (login: String, email: String) ->voidendclassBotattr_reader name: Stringattr_reader email: Stringattr_reader owner: Userdef initialize: (name: String, owner: User) ->voidendclassMessageattr_reader id: Stringattr_reader string: Stringattr_reader from: User | Bot# `|` means union types: `#from` can be `User` or `Bot`attr_reader reply_to: Message?# `?` means optional type: `#reply_to` can be `nil`def initialize: (from: User | Bot, string: String) ->voiddef reply: (from: User | Bot, string: String) -> MessageendclassChannelattr_reader name: Stringattr_reader messages: Array[Message]attr_reader users: Array[User]attr_reader bots: Array[Bot]def initialize: (name: String) ->voiddef each_member: () { (User | Bot) ->void } ->void# `{` and `}` means block.                   | () -> Enumerator[User | Bot,void]# Method can be overloaded.endend

• The standard library signatures targets the latest release of Ruby. (3.2 as of 2023.)
• The library code targets non-EOL versions of Ruby. (>= 3.0 as of 2023.)

Install therbs gem.$ gem install rbs from the command line, or add a line in yourGemfile.

gem"rbs"

The gem ships with therbs command line tool to demonstrate what it can do and help develop RBS.

$rbs version$rbs list$rbs ancestors ::Object$rbs methods ::Object$rbs method Objectthen

An end user ofrbs will probably findrbs prototype the most useful. This command generates boilerplate signature declarations for ruby files. For example, say you have written the below ruby script.

# person.rbclassPersonattr_reader:nameattr_reader:contactsdefinitialize(name:)@name=name@contacts=[]enddefspeak"I'm#{@name} and I love Ruby!"endend

Running prototype on the above will automatically generate

$rbs prototype rb person.rbclass Person  @name: untyped  @contacts: untyped  attr_reader name: untyped  attr_reader contacts: untyped  def initialize: (name: untyped) -> void  def speak: () -> ::Stringend

It prints signatures for all methods, classes, instance variables, and constants.This is only a starting point, and you should edit the output to match your signature more accurately.

rbs prototype offers three options.

• rb generates from just the available Ruby code
• rbi generates from Sorbet RBI
• runtime generates from runtime API

There are two important concepts,environment anddefinition.

Anenvironment is a dictionary that keeps track of all declarations. What is the declaration associated withString class? Anenvironment will give you the answer.

Adefinition gives you the detail of the class. What is the type of the return value ofgsub method of theString class? Thedefinition forString class knows the list of methods it provides and their types.

The following is a small code to retrieve the definition of theString#gsub method.

require"rbs"loader=RBS::EnvironmentLoader.new()# loader.add(path: Pathname("sig"))   # Load .rbs files from `sig` directory# loader.add(library: "pathname")     # Load pathname libraryenvironment=RBS::Environment.from_loader(loader).resolve_type_names# ::Stringstring=RBS::TypeName.new(name::String,namespace:RBS::Namespace.root)# Class declaration for ::Stringdecl=environment.class_decls[string]# Builder provides the translation from `declaration` to `definition`builder=RBS::DefinitionBuilder.new(env:environment)# Definition of instance of Stringinstance=builder.build_instance(string)# Print the types of `gsub` method:putsinstance.methods[:gsub].method_types.join("\n")# Outputs =>#  (::Regexp | ::string pattern, ::string replacement) -> ::String#  (::Regexp | ::string pattern, ::Hash[::String, ::String] hash) -> ::String#  (::Regexp | ::string pattern) { (::String match) -> ::_ToS } -> ::String#  (::Regexp | ::string pattern) -> ::Enumerator[::String, self]# Definition of singleton of Stringsingleton=builder.build_singleton(string)# No `gsub` method for String singletonputssingleton.methods[:gsub]

• Architecture
• Core and standard library signature contribution guide
• Writing signatures guide
• Stdlib signatures guide
• Syntax
• RBS by Example
• RBS collection
• UsingData andStruct
• Releasing a gem with RBS

Here is a list of some places you can talk with active maintainers.

• Ruby Discord Server (invite link) -- We haverbs channel in Ruby Discord server.
• ruby-jp Slack Workspace (in Japanese) -- We havetypes channel in ruby-jp slack workspace.
• gem_rbs_collection -- We have a repository of third-party RBS type definitions, for the case your dependency doesn't ship with RBS files.

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

To install this gem onto your local machine, runbundle exec rake install. To release a new version, update the version number inversion.rb, and then runbundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the.gem file torubygems.org.

This project usesclang-format to enforce consistent formatting of C code with a.clang-format configuration in the root directory.

First, install clang-format:

# macOSbrew install clang-format# Ubuntu/Debiansudo apt-get install clang-format# Windowschoco install llvm

Format all C source files:

rake format:c

Check formatting without making changes:

rake format:c_check

For VS Code users, install the "clangd" extension which will automatically use the project's.clang-format file.

Bug reports and pull requests are welcome on GitHub athttps://github.com/ruby/rbs.