ruby-rbs

RBS provides two distinct Rust crates for interacting with RBS signatures:

• ruby-rbs-sys: Provides low-level FFI bindings to the RBS C parser.
• ruby-rbs: Provides a high-level, safe Rust API for parsing RBS signatures.

Both crates are available on crates.io and are maintained in the rust/ directory of the repository.

If a method behaves differently depending on the input types, you can provide multiple signatures separated by a pipe | symbol. This is common when a method returns different types based on its arguments.

class Array[E]
  def *: (String) -> String
       | (Integer) -> Array[E]
end

RBS does not allow duplicate method definitions. If you need to overload a method (provide multiple definitions for the same method name), you must use the ... syntax in the subsequent definitions to tell RBS that the method is being overloaded.

# First definition
class C
  def foo: () -> untyped
end

# Second definition, use `...` syntax to tell RBS that we're overloading the method
class C
  def foo: () -> untyped
         | ...
end

For complex data structures and nullability:

• Optional type (?): Denotes a type that can be the specified type or nil.
• Record type ({}): Represents a Hash object with a fixed set of keys and heterogeneous values.
• Tuple type ([]): Represents an Array object with a fixed size and heterogeneous values.

Signature testing is configured using the RBS_TEST_TARGET environment variable and several optional configuration variables.

Target Selection

• RBS_TEST_TARGET: Specifies the classes to test. Use comma-separated exact names (e.g., Foo::Bar,Foo::Baz) or wildcards (e.g., Foo::*).
• RBS_TEST_SKIP: (Optional) Skips specific classes that match the RBS_TEST_TARGET pattern.

Test Options and Debugging

• RBS_TEST_OPT: (Optional) Passes options to the RBS handler. By default, it uses -I sig. You can use this to load additional libraries or signature paths (e.g., RBS_TEST_OPT='-r logger -I sig -Iprivate').
• RBS_TEST_LOGLEVEL: (Optional) Configures the log level. Defaults to info.
• RBS_TEST_RAISE: (Optional) If set, the test will raise an exception when a type error is detected, providing a backtrace to help debug the cause of the error.

RBS enforces contextual limitations on certain types. While the parser may accept them, rbs validate will report warnings. In future versions (3.4+), these will be rejected.

void limitations

• Allowed: As a return type or a generic parameter.
• Prohibited: As a function parameter, or inside an optional type (void?) or a union type (void | String).

self limitations

• Allowed: Only in self-context (e.g., instance attributes or method return types).
• Prohibited: In mixin arguments, constant types, class variables, or type aliases.

class and instance limitations

• Allowed: Only in classish-context (e.g., instance attributes, class variables, or mixin arguments).
• Prohibited: In constant types or type aliases.

RBS provides ways to represent values that can be one of several types:

• Union types: Use the pipe | to allow multiple types. Example: String | Integer means the value can be either a String or an Integer.
• Nilable types: Use the ? suffix on a type to indicate it can also be nil. This is a shorthand for a union with nil. Example: E? is equivalent to (E | nil).

# Union type
def <<: (String | Integer) -> String
end

# Nilable type
def first: () -> E?
end

RBS uses optimistic version resolution rather than strict semantic versioning. The goal is to provide type definitions even if they are not a perfect match for the requested version, as having some type definitions is preferred over none.

Resolution Rules:

1. RBS attempts to find the latest available version m such that m <= n (where n is the requested version).
2. If no such version exists (i.e., the requested version is older than any available version), RBS resolves to the oldest available version.

Example Resolution Table: If versions 0.4.0 and 1.0.0 are available:

RBS string literal types can use Unicode codepoint escape sequences (\uXXXX). The parser's behavior depends on the file encoding:

In UTF-8 encoded files

The parser translates the escape sequence into the actual Unicode character.

type t = "\u0123"  # Translated to the actual Unicode character ģ
type s = "\u3042"  # Translated to the actual Unicode character あ

In non-UTF-8 encoded files

The escape sequence is interpreted literally as the string \uXXXX.

type t = "\u0123"  # Remains as the literal string "\u0123"

If you want to include RBS files in your gem package that should not be exported to gem users, place them in a directory starting with an underscore (_).

For example:

• /sig/foo.rbs (Loaded)
• /sig/bar/baz.rbs (Loaded)
• /sig/_private/internal.rbs (Skipped when loading as a library)

Behavior Note:

• When loading as a library (e.g., rbs -r your-gem), files in _ directories are skipped.
• When loading as source code (e.g., rbs -I sig), hidden files will be loaded.

An RBS::Environment is populated by an RBS::EnvironmentLoader. It maps absolute names to their corresponding declarations.

For example, if you have nested declarations:

module Hello
  class World
  end
end

class Hello::World
end

The environment organizes these into:

• A mapping for ::Hello to its module declaration.
• A mapping for ::Hello::World to its two distinct class declarations.