Syntax

Types

_type_ ::= _class-name_ _type-arguments_                 (Class instance type)
         | _interface-name_ _type-arguments_             (Interface type)
         | _alias-name_ _type-arguments_                 (Alias type)
         | `singleton(` _class-name_ `)`                 (Class singleton type)
         | _literal_                                     (Literal type)
         | _type_ `|` _type_                             (Union type)
         | _type_ `&` _type_                             (Intersection type)
         | _type_ `?`                                    (Optional type)
         | `{` _record-name_ `:` _type_ `,` etc. `}`     (Record type)
         | `[]` | `[` _type_ `,` etc. `]`                (Tuples)
         | _type-variable_                               (Type variables)
         | `self`
         | `instance`
         | `class`
         | `bool`
         | `untyped`
         | `nil`
         | `top`
         | `bot`
         | `void`
         | _proc_                                        (Proc type)

_class-name_ ::= _namespace_ /[A-Z]\w*/
_interface-name_ ::= _namespace_ /_[A-Z]\w*/
_alias-name_ ::= _namespace_ /[a-z]\w*/

_type-variable_ ::= /[A-Z]\w*/

_namespace_ ::=                                         (Empty namespace)
              | `::`                                    (Root)
              | _namespace_ /[A-Z]\w*/ `::`             (Namespace)

_type-arguments_ ::=                                    (No type arguments)
                   | `[` _type_ `,` etc. `]`            (Type arguments)

_literal_ ::= _string-literal_
            | _symbol-literal_
            | _integer-literal_
            | `true`
            | `false`

_proc_ ::= _parameters?_ _self-type-binding?_ _block?_ `->` _type_

Class instance type

Class instance type denotes an instance of a class.

Integer                      # Instance of Integer class
::Integer                    # Instance of ::Integer class
Hash[Symbol, String]         # Instance of Hash class with type application of Symbol and String

Interface type

Interface type denotes type of a value which can be a subtype of the interface.

_ToS                          # _ToS interface
::MyApp::_Each[String]        # Interface name with namespace and type application

Alias type

Alias type denotes an alias declared with alias declaration.

The name of type aliases starts with lowercase [a-z].

name
::JSON::t                    # Alias name with namespace
list[Integer]                # Type alias can be generic

Class singleton type

Class singleton type denotes the type of a singleton object of a class.

singleton(String)
singleton(::Hash)            # Class singleton type cannot be parametrized.

Literal type

Literal type denotes a type with only one value of the literal.

123                         # Integer
"hello world"               # A string
:to_s                       # A symbol
true                        # true or false

Union type

Union type denotes a type of one of the given types.

Integer | String           # Integer or String
Array[Integer | String]    # Array of Integer or String

Intersection type

Intersection type denotes a type of all of the given types.

_Reader & _Writer           # _Reader and _Writer

Note that & has higher precedence than | that A & B | C is (A & B) | C.

Optional type

Optional type denotes a type of value or nil.

Integer?
Array[Integer?]

Record type

Records are Hash objects, fixed set of keys, and heterogeneous.

{ id: Integer, name: String }     # Hash object like `{ id: 31, name: String }`

Tuple type

Tuples are Array objects, fixed size and heterogeneous.

[ ]                               # Empty like `[]`
[String]                          # Single string like `["hi"]`
[Integer, Integer]                # Pair of integers like `[1, 2]`
[Symbol, Integer, Integer]        # Tuple of Symbol, Integer, and Integer like `[:pair, 30, 22]`

Empty tuple or 1-tuple sound strange, but RBS allows these types.

Type variable

U
T
S
Elem

Type variables cannot be distinguished from class instance types. They are scoped in class/module/interface/alias declaration or generic method types.

class Ref[T]              # Object is scoped in the class declaration.
  @value: T               # Type variable `T`
  def map: [X] { (T) -> X } -> Ref[X]   # X is a type variable scoped in the method type.
end

Base types

self denotes the type of receiver. The type is used to model the open recursion via self.

instance denotes the type of instance of the class. class is the singleton of the class.

bool is an alias of true | false.

untyped is for a type without type checking. It is ? in gradual typing, dynamic in some languages like C#, and any in TypeScript. It is both subtype and supertype of all of the types. (The type was any but renamed to untyped.)

nil is for nil.

top is a supertype of all of the types. bot is a subtype of all of the types.

void is a supertype of all of the types.

nil or NilClass?

We recommend using nil.

bool or boolish

We have a builtin type alias called boolish. It is an alias of top type, and you can use boolish if we want to allow any object of any type.

We can see an example at the definition of Enumerable#find:

module Enumerable[Elem, Return]
  def find: () { (Elem) -> boolish } -> Elem?
end

We want to write something like:

array.find {|x| x && x.some_test? }               # The block will return (bool | nil)

We recommend using boolish for method arguments and block return values, if you only use the values for conditions. You can write bool if you strictly want true | false.

void, boolish, or top?

They are all equivalent for the type system; they are all top type.

void tells developers a hint that the value should not be used. boolish implies the value is used as a truth value. top is anything else.

Proc type

Proc type denotes type of procedures, Proc instances.

^(Integer) -> String                  # A procedure with an {Integer} parameter and returns {String}
^(?String, size: Integer) -> bool     # A procedure with {String} optional parameter, `size` keyword of {Integer}, and returns `bool`

See the next section for details.

Method Types and Proc Types

_method-type_ ::= _parameters?_ _block?_ `->` _type_                # Method type

_proc_ ::= `^` _parameters?_ _self-type-binding?_ _block?_ `->` _type_  # Proc type

_parameters?_ ::=                   (Empty)
                | _parameters_      (Parameters)

_parameters_ ::= `(` _required-positionals_ _optional-positionals_ _rest-positional_ _trailing-positionals_ _keywords_ `)`

_parameter_ ::= _type_ _var-name_                                  # Parameter with var name
              | _type_                                             # Parameter without var name
_required-positionals_ ::= _parameter_ `,` etc.
_optional-positionals_ ::= `?` _parameter_ `,` etc.
_rest-positional_ ::=                                              # Empty
                    | `*` _parameter_
_trailing-positionals_ ::= _parameter_ `,` etc.
_keywords_ ::=                                                     # Empty
             | `**` _parameter_                                    # Rest keyword
             | _keyword_ `:` _parameter_ `,` _keywords_            # Required keyword
             | `?` _keyword_ `:` _parameter_ `,` _keywords_        # Optional keyword

_var-name_ ::= /[a-z]\w*/

_self-type-binding?_ =                              (Empty)
                     | `[` `self` `:` _type_ `]`    (Self type binding)

_block?_ =                                                           (No block)
         | `{` _parameters_ _self-type-binding?_ `->` _type_ `}`      (Block)
         | `?` `{` _parameters_ _self-type-binding?_ `->` _type_ `}`  (Optional block)

Parameters

A parameter can be a type or a pair of type and variable name. Variable name can be used for documentation.

Examples

# Two required positional {Integer} parameters, and returns {String}
(Integer, Integer) -> String

# Two optional parameters `size` and `name`.
# `name` is a optional parameter with optional type so that developer can omit, pass a string, or pass `nil`.
(?Integer size, ?String? name) -> String

# Method type with a rest parameter
(*Integer, Integer) -> void

# `size` is a required keyword, with variable name of `sz`.
# `name` is a optional keyword.
# `created_at` is a optional keyword, and the value can be `nil`.
(size: Integer sz, ?name: String, ?created_at: Time?) -> void

Self type binding

Self type binding represents the type of methods that uses #instance_eval, which replaces the value of self inside blocks.

123.instance_eval do
  self + 1        # self is `123` here
end

Proc types and blocks can have self type bindings.

^(Integer) [self: String] -> void                                     # Proc type with self type binding
^(Integer) [self: String] { (Symbol) [self: bool] -> void } -> void   # Proc type with self type binding of {String} and a block with self type binding of `bool`

Method type can have blocks with self type bindings.

() { (Integer) [self: String] -> void } -> void     # A method type with block with self type binding

Members

_member_ ::= _ivar-member_                # Ivar definition
           | _method-member_              # Method definition
           | _attribute-member_           # Attribute definition
           | _include-member_             # Mixin (include)
           | _extend-member_              # Mixin (extend)
           | _prepend-member_             # Mixin (prepend)
           | _alias-member_               # Alias
           | _visibility-member_          # Visibility member

_ivar-member_ ::= _ivar-name_ `:` _type_

_method-member_ ::= _visibility_ `def` _method-name_ `:` _method-types_            # Instance method
                  | _visibility_ `def self.` _method-name_ `:` _method-types_      # Singleton method
                  | `def self?.` _method-name_ `:` _method-types_     # Singleton and instance method

_method-types_ ::= _method-type-parameters_ _method-type_                       # Single method type
                 | _method-type-parameters_ _method-type_ `|` _method-types_    # Overloading types
                 | `...`                                                        # Overloading for duplicate definitions

_method-type-parameters_ ::=                                                    # Empty
                           | `[` _type-variable_ `,` ... `]`

_attribute-member_ ::= _visibility_ _attribute-type_ _method-name_ `:` _type_                     # Attribute
                     | _visibility_ _attribute-type_ _method-name_ `(` _ivar-name_ `) :` _type_   # Attribute with variable name specification
                     | _visibility_ _attribute-type_ _method-name_ `() :` _type_                  # Attribute without variable

_visibility_ ::= `public` | `private`

_attribute-type_ ::= `attr_reader` | `attr_writer` | `attr_accessor`

_include-member_ ::= `include` _class-name_ _type-arguments_
                   | `include` _interface-name_ _type-arguments_
_extend-member_ ::= `extend` _class-name_ _type-arguments_
                  | `extend` _interface-name_ _type-arguments_
_prepend-member_ ::= `prepend` _class-name_ _type-arguments_

_alias-member_ ::= `alias` _method-name_ _method-name_
                 | `alias self.` _method-name_ `self.` _method-name_

_visibility-member_ ::= _visibility_

_ivar-name_ ::= /@\w+/
_method-name_ ::= ...
                | /`[^`]+`/

Ivar definition

An instance variable definition consists of the name of an instance variable and its type.

@name: String
@value: Hash[Symbol, Key]

Method definition

Method definition has several syntax variations.

You can write self. or self?. before the name of the method to specify the kind of method: instance, singleton, or module function.

def to_s: () -> String                        # Defines a instance method
def self.new: () -> AnObject                  # Defines singleton method
def self?.sqrt: (Numeric) -> Numeric          # self? is for `module_function`s

self? method definition adds two methods: a public singleton method and a private instance method, which is equivalent to module_function in Ruby.

The method type can be connected with |s to define an overloaded method.

def +: (Float) -> Float
     | (Integer) -> Integer
     | (Numeric) -> Numeric

Overloaded method can have ... to overload an existing method. It is useful for monkey-patching.

def +: (Float) -> Float
def +: (BigDecimal) -> BigDecimal
     | ...

You need extra parentheses on return type to avoid ambiguity.

def +: (Float | Integer) -> (Float | Integer)
     | (Numeric) -> Numeric

Adding public and private modifier changes the visibility of the method.

private def puts: (*untyped) -> void       # Defines private instance method

public def self.puts: (*untyped) -> void   # Defines public singleton method

public def self?.puts: (*untyped) -> void  # 🚨🚨🚨 Error: `?.` has own visibility semantics (== `module_function`) 🚨🚨🚨

Attribute definition

Attribute definitions help to define methods and instance variables based on the convention of attr_reader, attr_writer and attr_accessor methods in Ruby.

You can specify the name of instance variable using (@some_name) syntax and also omit the instance variable definition by specifying ().

# Defines `id` method and `@id` instance variable.
attr_reader id: Integer
# @id: Integer
# def id: () -> Integer

# Defines `name=` method and `@raw_name` instance variable.
attr_writer name (@raw_name) : String
# @raw_name: String
# def name=: (String) -> String

# Defines `people` and `people=` methods, but no instance variable.
attr_accessor people (): Array[Person]
# def people: () -> Array[Person]
# def people=: (Array[Person]) -> Array[Person]

Attribute definitions can have the public and private modifiers like method definitions:

private attr_accessor id: Integer

private attr_reader self.name: String

Mixin (include), Mixin (extend), Mixin (prepend)

You can define mixins between class and modules.

include Kernel
include Enumerable[String, void]
extend ActiveSupport::Concern

You can also include or extend an interface.

include _Hashing
extend _LikeString

This allows importing defs from the interface to help developer implementing a set of methods.

Alias

You can define an alias between methods.

def map: [X] () { (String) -> X } -> Array[X]
alias collect map                                   # `#collect` has the same type with `map`

Visibility member

Visibility member allows specifying the default visibility of instance methods and instance attributes.

public

def foo: () -> void          # public instance method

attr_reader name: String     # public instance attribute

private

def bar: () -> void          # private instance method

attr_reader email: String    # private instance attribute

The visibility modifiers overwrite the default visibility per member bases.

The visibility member requires a new line \n after the token.

private alias foo bar       # Syntax error

Declarations

_decl_ ::= _class-decl_                         # Class declaration
         | _module-decl_                        # Module declaration
         | _interface-decl_                     # Interface declaration
         | _type-alias-decl_                    # Type alias declaration
         | _const-decl_                         # Constant declaration
         | _global-decl_                        # Global declaration

_class-decl_ ::= `class` _class-name_ _module-type-parameters_ _members_ `end`
               | `class` _class-name_ _module-type-parameters_ `<` _class-name_ _type-arguments_ _members_ `end`

_module-decl_ ::= `module` _module-name_ _module-type-parameters_ _members_ `end`
                | `module` _module-name_ _module-type-parameters_ `:` _module-self-types_ _members_ `end`

_module-self-types_ ::= _class-name_ _type-arguments_ `,` _module-self-types_            (Class instance)
                      | _interface-name_ _type-arguments_ `,` _module-self-types_        (Interface)

_interface-decl_ ::= `interface` _interface-name_ _module-type-parameters_ _interface-members_ `end`

_interface-members_ ::= _method-member_              # Method
                      | _include-member_             # Mixin (include)
                      | _alias-member_               # Alias

_type-alias-decl_ ::= `type` _alias-name_ _module-type-parameters_ `=` _type_

_const-decl_ ::= _const-name_ `:` _type_

_global-decl_ ::= _global-name_ `:` _type_

_const-name_ ::= _namespace_ /[A-Z]\w*/
_global-name_ ::= /$[a-zA-Z]\w+/ | ...

_module-type-parameters_ ::=                                                  # Empty
                           | `[` _module-type-parameter_ `,` ... `]`

Class declaration

Class declaration can have type parameters and superclass. When you omit superclass, ::Object is assumed.

Module declaration

Module declaration takes optional self type parameter, which defines a constraint about a class when the module is mixed.

interface _Each[A, B]
  def each: { (A) -> void } -> B
end

module Enumerable[A, B] : _Each[A, B]
  def count: () -> Integer
end

The Enumerable module above requires each method for enumerating objects.

Interface declaration

Interface declaration can have parameters but allows only a few of the members.

interface _Hashing
  def hash: () -> Integer
  def eql?: (untyped) -> bool
end

There are several limitations which are not described in the grammar.

1. Interface cannot include modules
2. Interface cannot have singleton method definitions

interface _Foo
  include Bar                  # Error: cannot include modules
  def self.new: () -> Foo      # Error: cannot include singleton method definitions
end

Type alias declaration

You can declare an alias of types.

type subject = Attendee | Speaker
type JSON::t = Integer | TrueClass | FalseClass | String | Hash[Symbol, t] | Array[t]

Type alias can be generic like class, module, and interface.

type list[out T] = [T, list[T]] | nil

Constant type declaration

You can declare a constant.

Person::DefaultEmailAddress: String

Global type declaration

You can declare a global variable.

$LOAD_PATH: Array[String]

Generics

_module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-variable_ _generics-bound_

_method-type-param_ ::= _type-variable_ _generics-bound_

_generics-bound_ ::=                       (No type bound)
                   | `<` _bound-type_      (The generics parameter is bounded)

_bound-type_ ::= _class-name_ _type-arguments_       (Class instance type)
               | _interface-name_ _type-arguments_   (Interface type)
               | `singleton(` _class-name_ `)`       (Class singleton type)

_generics-variance_ ::=               (Invariant)
                      | `out`         (Covariant)
                      | `in`          (Contravariant)

_generics-unchecked_ ::=              (Empty)
                       | `unchecked`  (Skips variance annotation validation)

RBS allows class/module/interface/type alias definitions and methods to be generic.

# Simple generic class definition
class Stack[T]
  def push: (T) -> void

  def pop: () -> T
end

For classes with type parameters, you may specify if they are "invariant" (default), "covariant" (out) or "contravariant" (in). See this definition of covariance and contravariance.

For example, an Array of String can almost be considered to be an Array of Object, but not the reverse, so we can think of:

# The `T` type parameter is covariant.
class Array[out T]
  # etc.
end

There's a limitation with this for mutable objects (like arrays): a mutation could invalidate this. If an Array of String is passed to a method as an Array of Object, and that method adds an Integer to the Array, the promise is broken.

In those cases, one must use the unchecked keyword:

# Skips the validation of variance of the type parameter `T`.
# The type safety prohibits `out` type parameters to appear at _negative_ position (== method parameter), but we want {Array} to have it.
class Array[unchecked out T]
  def include?: (T) -> bool
end

This is how Array is actually defined in RBS.

Note that RBS doesn't allow specifying variance related annotations to generic method types.

class Foo
  def bar: [out T] () -> T    # Syntax error
end

You can also specify the upper bound of the type parameter.

class PrettyPrint[T < _Output]
  interface _Output
    def <<: (String) -> void
  end

  attr_reader output: T
end

If a type parameter has an upper bound, the type parameter must be instantiated with types that is a subclass of the upper bound.

type str_printer = PrettyPrint[String]    # OK
type int_printer = PrettyPrint[Integer]      # Type error

The upper bound must be one of a class instance type, interface type, or class singleton type.

Comments

You can write single line comments. Comments must be on their own line. Comments can lead with whitespace.

# This if interface Foo
# Usage of Foo is bar
interface _Foo
  # New foo is a method
  # it will return foo.
  def new: () -> Foo
end