Release Note 3.0

RBS 3.0 is a pre-release version. You can install the development version for testing.

Some of the highlights in RBS 3.0 are:

• Add class/module alias syntax (#1219)
• Add use syntax (#1224)
• RBS collection skips loading require: false gems (#1222)
• The bundled core RBS signatures are upgraded to Ruby 3.2 (TBD)

You can install it with $ gem install rbs --pre or using Bundler.

gem 'rbs', '~> 3.0.0.dev'

See the CHANGELOG for the details.

There are breaking changes in APIs from RBS 2.8. Read the upgrade guide below if you develop with RBS library.

Add class/module alias syntax

The spec: https://hackmd.io/@soutaro/HkgF2HHco

The class/module alias syntax allows defining alias of classes and modules.

class HashWithIndifferentAccess = ActiveSupport::HashWithIndifferentAccess

The sample code above defines ::HashWithIndifferentAccess that is another name of ::ActiveSupport::HashWithIndifferentAccess.

The difference between type alias syntax is that it is a class/module. So you can inherit from the alias class or mixin the alias modules.

class MyHash < HashWithIndifferentAccess
end

The type definition corresponds to the following Ruby code that defines a constant.

HashWithIndifferentAccess = ActiveSupport::HashWithIndifferentAccess

Add use syntax

The spec: https://hackmd.io/@soutaro/rJ6CqDQss

The use syntax also defines alias names of type names, but unlike the class alias syntax, no constant is defined and it works for per-file basis.

use RBS::TypeName
use RBS::Namespace as NS
use RBS::AST::Declarations::*

With the directives, you can use TypeName for ::RBS::TypeName, NS for ::RBS::Namespace, and all types names under ::RBS::AST::Declarations with unqualified names.

This is an RBS specific feature that has no corresponding Ruby code. This helps keeping type signatures compact/clean/streamlined.

RBS collection skips loading require: false gems

Both libraries and applications are bundled with Bundler -- libraries are loaded in your application, but apps are not. Apps are executed in different process, and your Ruby code doesn't depends the classes/modules of the app dependencies.

RBS collection now skips loading RBS files of app dependencies, if the dependency is declared with require: false in Gemfile.

gem 'steep', require: false        # Steep is a type checker and usually apps don't need its type definition

You may have written rbs_collection.yaml entry to skip loading RBS of a gem.

gems:
  - name: steep
    ignore: true
  - name: rbs
    ignore: true

You can delete the lines, and just add require: false in your Gemfile instead.

To upgrade to the latest setup, edit the Gemfile and rbs_collection.yaml, run $ rbs collection update, and commit the updated rbs_collection.lock.yaml.

Upgrade guide 💪

RBS 3.0 has several breaking changes. This section explains the overview of the incompatibilities to help you making your Ruby code work with 3.0.

AST changes

For class/module alias

• RBS::AST::Declarations::Alias is now renamed to TypeAlias
• RBS::AST::Declarations::ClassAlias and RBS::AST::Declarations::ModuleAlias are added
• RBS::AST::Declarations::t now has ClassAlias and ModuleAlias

For use syntax

• RBS::AST::Directives is added for use directive

For per-method-overload annotations

• RBS::AST::Members::MethodDefinition::Overload is added
• RBS::AST::Members::MethodDefinition#method_types is renamed to #overloads
• RBS::AST::Members::MethodDefinition#overload? is renamed to #overloading?

Parser method type

• The deprecated overloadings with line: and column: keywords of RBS::Parser.parse_method_type and RBS::Parser.parse_type are deleted
• RBS::Parser.parse_signature now returns a triple of RBS::Buffer, Array[RBS::AST::Directives::t], and Array[RBS::AST::Declarations::t]
• RBS::EnvironmentLoader#each_signature is added, and #each_decl is deleted

RBS::Environment utilities

• RBS::Environment::ModuleEntry and RBS::Environment::ClassEntry are added, replacing usages of MultiEntry[T]
• RBS::Environment::ModuleAliasEntry, RBS::Environment::ClassAliasEntry, RBS::Environment::InterfaceEntry, RBS::Environment::ConstantEntry, and RBS::Environment::GlobalEntry are added, replacing usage of SingleEntry[N, T]
• RBS::Environment#add_signature is introduced to support use directives, you can use the method instead of #<<
• Many utility methods are added, like module_name?, constant_entry, ... Use those methods instead of directly accessing the internal data structures like #class_decls and #type_alias_decls (renamed from #alias_decls)