rbs-professional

name	rbs-professional
description	A skill to assist to write RBS (Ruby signature, Ruby Type system) and rbs-inline.

RBS Professional

Introductions

RBS Professional is a skill designed to assist developers in writing RBS (Ruby Signature) and rbs-inline (embedding RBS type declarations into Ruby code as comments) code. RBS is a language for describing the types of Ruby programs, enabling better type checking and documentation.

RBS Syntax

_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_
         | `^` `(` `?` `)` `->` _type_                                   # Proc type with untyped parameter

RBS Examples

Class instance types

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 types

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

Alias types

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 types

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

Literal types

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

Union types

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

Intersection types

_Reader & _Writer           # _Reader and _Writer

rbs-inline Examples

Method comments

# @rbs size: Integer -- The size of the section in px
# @rbs optional: Integer -- Type of the optional parameter
# @rbs title: String -- Title of the section
# @rbs content: String -- Type of the optional keyword parameter
# @rbs *rest: String -- Type of the rest args
# @rbs **kwrest: untyped -- Type of the keyword rest args
# @rbs return: Section? -- Returns the new section or `nil`
def section(size, optional=123, title:, content: "Hello!", *rest, **kwrest)
end

# @rbs &block: (?) -> untyped -- Block is required, but not clear what will be yielded
def foo(&block)
  yield 1
  yield 2, "true"
end

# @rbs &block: ? (?) -> untyped -- Block is optional
def bar(&block)
end

# @rbs &: (String) -> void -- It yields String
def baz
end

# @rbs *: untyped
# @rbs **: String
# @rbs &: ? (String) -> bool
def foo(*, **) = nil

# @rbs yields: String
# @rbs skip: untyped
# @rbs !return: bool
def foo(return:, yields:, skip:) #: void
end

# `# @rbs override` annotation tells the method is overriding the super class definition.

# @rbs override
def foo(x, y)
end

Attributes

class Foo
  attr_reader :name #: String
  attr_reader :size, :count #: Integer
end

Instance Variables

class Foo
  # @rbs @name: String -- Instance variable
  # @rbs self.@all_names: Array[String] -- Instance variable of the class
end

Class Definitions

Define Generic classes

# @rbs generic A -- Type of `a`
# @rbs generic unchecked in B < String -- Type of `b`
class Foo
end

Module Definitions

• Generics is supported with # @rbs generic annotation, like class definition.
• Module self type constraints can be defined with # @rbs module-self annotation.

# @rbs module-self BasicObject
module Kernel
end

Use Generic classes and modules

The constant super class is supported. Generics is also supported by #[ annotation.

class Foo < String
end

class Bar < Array #[String]
end

The #[ syntax allows mixing generic modules.

class Foo
  include Foo

  extend Enumerable #[Integer, void]
end

# @rbs inherits annotation allows specifying super class with RBS syntax, even if the super class syntax in Ruby is something unsupported.

# @rbs inherits Hash[String, Integer]
class Foo < Hash
end

# @rbs inherits Struct[String | Integer]
class Bar < Struct.new(:size, :name, keyword_init: true)
end

Blocks defining classes and modules

For method calls with blocks that defines modules/classes implicitly, we introduce @rbs class and @rbs module syntax.

The @rbs module and @rbs class annotations accepts RBS syntax for opening modules/classes. end is omitted.

module Foo
  extend ActiveSupport::Concern

  # @rbs module ClassMethods
  class_methods do
    # @rbs () -> Integer
    def foo = 123
  end
end

Constant Types

VERSION = "1.2.3"

Foo = [1,2,3].sample #: Integer

Embedding RBS elements directory

We have # @rbs! annotation for something not covered by the annotations.

class Person
  include ActiveModel::Model
  include ActiveModel::Attributes

  attribute :id, :integer, default: 0
  attribute :name, :string, default: ''

  # @rbs!
  #   attr_accessor id (): Integer
  #
  #   attr_accessor name (): String
end

References

• https://github.com/ruby/rbs/blob/master/docs/syntax.md
• https://github.com/ruby/rbs/blob/master/docs/rbs_by_example.md
• https://github.com/soutaro/rbs-inline/wiki/Syntax-guide