rbs 4.0.3 → 4.1.0

data/core/struct.rbs

@@ -104,8 +104,8 @@
 # *   #inspect (aliased as #to_s): Returns a string representation of `self`.
 # *   #to_h: Returns a hash of the member name/value pairs in `self`.
 #
-class Struct[Elem]
-  include Enumerable[Elem]
+class Struct[E]
+  include Enumerable[E]
 
   # The types that can be used when "indexing" into a `Struct` via `[]`, `[]=`, `dig`, and
   # `deconstruct_keys`.
@@ -362,7 +362,7 @@ class Struct[Elem]
   #
   # Related: #members.
   #
-  def to_a: () -> Array[Elem]
+  def to_a: () -> Array[E]
 
   # <!--
   #   rdoc-file=struct.c
@@ -385,8 +385,8 @@ class Struct[Elem]
   #
   # Raises ArgumentError if the block returns an inappropriate value.
   #
-  def to_h: () -> Hash[Symbol, Elem]
-          | [K, V] () { (Symbol key, Elem value) -> [K, V] } -> Hash[K, V]
+  def to_h: () -> Hash[Symbol, E]
+          | [K, V] () { (Symbol key, E value) -> [K, V] } -> Hash[K, V]
 
   # <!-- rdoc-file=struct.c -->
   # Returns the values in `self` as an array:
@@ -441,8 +441,8 @@ class Struct[Elem]
   #
   # Related: #each_pair.
   #
-  def each: () -> Enumerator[Elem, self]
-          | () { (Elem value) -> void } -> self
+  def each: () -> Enumerator[E, self]
+          | () { (E value) -> void } -> self
 
   # <!--
   #   rdoc-file=struct.c
@@ -465,8 +465,8 @@ class Struct[Elem]
   #
   # Related: #each.
   #
-  def each_pair: () -> Enumerator[[Symbol, Elem], self]
-               | () { ([Symbol, Elem] key_value) -> void } -> self
+  def each_pair: () -> Enumerator[[Symbol, E], self]
+               | () { ([Symbol, E] key_value) -> void } -> self
 
   # <!--
   #   rdoc-file=struct.c
@@ -492,7 +492,7 @@ class Struct[Elem]
   #
   # Raises IndexError if `n` is out of range.
   #
-  def []: (index name_or_position) -> Elem
+  def []: (index name_or_position) -> E
 
   # <!--
   #   rdoc-file=struct.c
@@ -521,7 +521,7 @@ class Struct[Elem]
   #
   # Raises IndexError if `n` is out of range.
   #
-  def []=: (index name_or_position, Elem value) -> Elem
+  def []=: (index name_or_position, E value) -> E
 
   # <!--
   #   rdoc-file=struct.c
@@ -540,8 +540,8 @@ class Struct[Elem]
   #
   # With no block given, returns an Enumerator.
   #
-  def select: () -> Enumerator[Elem, Array[Elem]]
-            | () { (Elem value) -> boolish } -> Array[Elem]
+  def select: () -> Enumerator[E, Array[E]]
+            | () { (E value) -> boolish } -> Array[E]
 
   # <!-- rdoc-file=struct.c -->
   # With a block given, returns an array of values from `self` for which the block
@@ -591,7 +591,7 @@ class Struct[Elem]
   # Raises RangeError if any element of the range is negative and out of range;
   # see Array@Array+Indexes.
   #
-  def values_at: (*int | range[int?] positions) -> Array[Elem]
+  def values_at: (*int | range[int?] positions) -> Array[E]
 
   # <!--
   #   rdoc-file=struct.c
@@ -634,7 +634,7 @@ class Struct[Elem]
   #     f.dig(0, 0, :b, 0) # => 1
   #     f.dig(:b, 0) # => nil
   #
-  def dig: (index name_or_position) -> Elem
+  def dig: (index name_or_position) -> E
          | (index name_or_position, untyped, *untyped) -> untyped
 
   # <!-- rdoc-file=struct.c -->
@@ -664,5 +664,5 @@ class Struct[Elem]
   #     h = joe.deconstruct_keys(nil)
   #     h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
   #
-  def deconstruct_keys: (Array[index & Hash::_Key]? indices) -> Hash[index & Hash::_Key, Elem]
+  def deconstruct_keys: (Array[index & Hash::_Key]? indices) -> Hash[index & Hash::_Key, E]
 end

data/core/thread.rbs

@@ -1565,10 +1565,10 @@ class Thread::Mutex < Object
 
   # <!--
   #   rdoc-file=thread_sync.rb
-  #   - mutex.lock  -> self
+  #   - mutex.unlock  -> self
   # -->
-  # Attempts to grab the lock and waits if it isn't available. Raises
-  # `ThreadError` if `mutex` was locked by the current thread.
+  # Releases the lock. Raises `ThreadError` if `mutex` wasn't locked by the
+  # current thread.
   #
   def unlock: () -> self
 end
@@ -1604,7 +1604,7 @@ end
 #
 #     consumer.join
 #
-class Thread::Queue[Elem = untyped] < Object
+class Thread::Queue[E = untyped] < Object
   # <!-- rdoc-file=thread_sync.c -->
   # Pushes the given `object` to the queue.
   #
@@ -1719,7 +1719,7 @@ class Thread::Queue[Elem = untyped] < Object
   # If `timeout` seconds have passed and no data is available `nil` is returned.
   # If `timeout` is `0` it returns immediately.
   #
-  def pop: (?boolish non_block, ?timeout: _ToF?) -> Elem?
+  def pop: (?boolish non_block, ?timeout: _ToF?) -> E?
 
   # <!--
   #   rdoc-file=thread_sync.c
@@ -1729,7 +1729,7 @@ class Thread::Queue[Elem = untyped] < Object
   # -->
   # Pushes the given `object` to the queue.
   #
-  def push: (Elem obj) -> void
+  def push: (E obj) -> void
 
   # <!--
   #   rdoc-file=thread_sync.rb
@@ -1750,12 +1750,7 @@ end
 #
 # See Thread::Queue for an example of how a Thread::SizedQueue works.
 #
-class Thread::SizedQueue[Elem = untyped] < Thread::Queue[Elem]
-  # <!--
-  #   rdoc-file=thread_sync.rb
-  #   - <<(object, non_block = false, timeout: nil)
-  # -->
-  #
+class Thread::SizedQueue[E = untyped] < Thread::Queue[E]
   alias << push
 
   # <!--
@@ -1813,8 +1808,8 @@ class Thread::SizedQueue[Elem = untyped] < Thread::Queue[Elem]
   # If `timeout` seconds have passed and no space is available `nil` is returned.
   # If `timeout` is `0` it returns immediately. Otherwise it returns `self`.
   #
-  def push: (Elem obj, ?boolish non_block) -> void
-          | (Elem obj, timeout: _ToF?) -> self?
+  def push: (E obj, ?boolish non_block) -> void
+          | (E obj, timeout: _ToF?) -> self?
 end
 
 class ConditionVariable = Thread::ConditionVariable

data/docs/CONTRIBUTING.md

@@ -12,7 +12,8 @@
 The RBS repository contains the type definitions of Core API and Standard Libraries.
 There are some discussions whether if it is the best to have them in this repository, but we have them and continue updating the files meanwhile.
 
-The target version of the bundled type definitions is the latest _release_ of Ruby -- `3.1` as of January 2022.
+The target version of the bundled type definitions is the [latest _release_ of Ruby](https://www.ruby-lang.org/en/downloads/branches/) -- `4.0` as of 2026.
+Note, however, that the CI runs the tests on every non-EOL Ruby -- `3.3` and later as of 2026.
 
 **The core API** type definitions are in `core` directory.
 You will find the familiar class names in the directory, like `string.rbs` or `array.rbs`.

data/docs/inline.md

@@ -123,10 +123,38 @@ end
 
 This creates the types `::API`, `::API::V1`, and `::API::V1::Resources`.
 
+### `module-self` constraint
+
+The `module-self` constraint declares which classes or modules the module can be mixed into.
+
+```ruby
+# @rbs module-self: _Each[String]
+module Enumerable2
+end
+```
+
+This is equivalent to `module Enumerable2 : _Each[String]` in RBS, meaning `Enumerable2` can only be included in classes that satisfy the `_Each[String]` interface.
+
+Multiple `module-self` constraints can be declared with separate annotations:
+
+```ruby
+# @rbs module-self: _Each[String]
+# @rbs module-self: Comparable
+module StringCollection
+end
+```
+
+You can add a description after `--`:
+
+```ruby
+# @rbs module-self: Minitest::Test -- depending on assertion methods
+module TestHelper
+end
+```
+
 ### Current Limitations
 
 - Generic module definitions are not supported
-- Module self-type constraints are not supported
 
 ## Method Definitions
 
@@ -135,6 +163,8 @@ Inline RBS supports methods defined using the `def` syntax in Ruby.
 ```ruby
 class Calculator
   def add(x, y) = x+y
+
+  def self.zero = 0
 end
 ```
 
@@ -205,6 +235,18 @@ The type of both methods is `(Integer, Integer) -> Integer | (Float, Float) -> F
 > The `@rbs METHOD-TYPE` syntax allows overloads with the `|` operator, just like in RBS files.
 > Multiple `: METHOD-TYPE` declarations are required for overloads.
 
+The `#:` syntax can also be used as a trailing annotation to declare the return type of a method:
+
+```ruby
+class Calculator
+  def add(x, y) #: Integer
+    x + y
+  end
+
+  def subtract(x, y) = x - y #: Integer
+end
+```
+
 The `@rbs METHOD-TYPE` syntax allows having `...` at the last part.
 
 ```ruby
@@ -309,9 +351,10 @@ end
 
 ### Current Limitations
 
-- Class methods and singleton methods are not supported
-- Only positional and keyword parameters are supported. Splat parameters (`*x`, `**y`) and block parameter (`&block`) are not supported yet.
 - Method visibility declaration is not supported yet
+- The `class << self` syntax is not supported
+- Top-level method definitions (outside any class/module) are not supported
+- Method definitions with a non-self receiver (e.g. `def obj.foo`) are not supported
 
 ## Attributes
 
@@ -389,6 +432,7 @@ The attribute definitions are ignored because the names are given by string lite
 ### Current Limitations
 
 - Attribute visibility is not supported yet. All attributes are _public_
+- Top-level attribute definitions (outside any class/module) are not supported
 
 ## Mixin
 
@@ -487,7 +531,7 @@ end
 ```
 
 The `@rbs @VAR-NAME: TYPE` syntax enclosed in `class`/`module` syntax declares instance variables.
-You can add the documentation of the variable followed by two hyphones (`--`).
+You can add the documentation of the variable followed by two hyphens (`--`).
 
 Instance variable declarations must be under the `class`/`module` syntax, and they are ignored if written inside method definitions.
 
@@ -519,14 +563,16 @@ The types of constants may be automatically inferred when the right-hand side co
 - **Floats**: `RATE = 3.14` → `Float`
 - **Booleans**: `ENABLED = true` → `bool`
 - **Strings**: `NAME = "test"` → `String`
-- **Symbols**: `STATUS = :ready` → `:ready`
+- **Symbols**: `STATUS = :ready` → `Symbol`
+- **Nil**: `EMPTY = nil` → `nil`
 
 ```ruby
 MAX_SIZE = 100           # Inferred as Integer
 PI = 3.14159            # Inferred as Float
 DEBUG = false           # Inferred as bool
 APP_NAME = "MyApp"      # Inferred as String
-DEFAULT_MODE = :strict  # Inferred as :strict
+DEFAULT_MODE = :strict  # Inferred as Symbol
+NONE = nil              # Inferred as nil
 ```
 
 ### Explicit Type Annotations
@@ -567,10 +613,22 @@ MyKernel = Kernel #: module-alias
 
 This creates new type names that refer to the same class or module as the original.
 
-The annotations can have optional type name to specify the class/module name, for the case it cannot be infered through the right-hand-side of the constant declaration.
+The annotations can have optional type name to specify the class/module name, for the case it cannot be inferred through the right-hand-side of the constant declaration.
 
 ```ruby
 MyObject = object #: class-alias Object
 
 MyKernel = kernel #: module-alias Kernel
 ```
+
+## Skip Annotation
+
+The `@rbs skip` annotation makes inline RBS ignore the following declaration.
+
+```ruby
+class Calculator
+  # @rbs skip
+  def debug_internal
+  end
+end
+```

data/docs/rbs_by_example.md

@@ -107,14 +107,14 @@ end
 For now, it's safe to ignore them, but they're included for completeness.
 
 ```rbs
-class Array[Elem]
+class Array[E]
   def *: (String) -> String
-       | (Integer) -> Array[Elem]
+       | (Integer) -> Array[E]
 end
 ```
 
 `Array`'s `*` method, when given a `String` returns a `String`. When given an
-`Integer`, it returns an `Array` of the same contained type `Elem` (in our example case, `Elem` corresponds to `Integer`).
+`Integer`, it returns an `Array` of the same contained type `E` (in our example case, `E` corresponds to `Integer`).
 
 ### Union types
 
@@ -150,9 +150,9 @@ end
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def first: () -> Elem?
-           | (Integer) -> Array[Elem]
+class Enumerable[E]
+  def first: () -> E?
+           | (Integer) -> Array[E]
 end
 ```
 
@@ -160,12 +160,12 @@ end
 
 When called with no arguments, the return value will either be an instance of
 whatever type is contained in the enumerable, or `nil`. We represent that with
-the type variable `Elem`, and the `?` suffix nilable marker.
+the type variable `E`, and the `?` suffix nilable marker.
 
 When called with an `Integer` positional argument, the return value will be an
 `Array` of whatever type is contained.
 
-The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(Elem | nil)`.
+The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(E | nil)`.
 
 ### Keyword Arguments
 
@@ -222,9 +222,9 @@ end
 ```
 
 ```rbs
-class Array[Elem]
-  def filter: () { (Elem) -> boolish } -> ::Array[Elem]
-            | () -> ::Enumerator[Elem, ::Array[Elem]]
+class Array[E]
+  def filter: () { (E) -> boolish } -> ::Array[E]
+            | () -> ::Enumerator[E, ::Array[E]]
 end
 ```
 
@@ -264,13 +264,13 @@ a.collect.with_index {|x, i| x * i}
 ```
 
 ```rbs
-class Array[Elem]
-  def collect: [U] () { (Elem) -> U } -> Array[U]
-             | () -> Enumerator[Elem, Array[untyped]]
+class Array[E]
+  def collect: [U] () { (E) -> U } -> Array[U]
+             | () -> Enumerator[E, Array[untyped]]
 end
 ```
 
-Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `Elem`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
+Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `E`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
 
 In this example, the method receives its signature from the inferred return type of the passed block. When then block is absent, as in when the method returns an `Enumerator`, we can't infer the type, and so the return value of the enumerator can only be described as `Array[untyped]`.
 
@@ -284,9 +284,9 @@ In this example, the method receives its signature from the inferred return type
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def partition: () { (Elem) -> boolish } -> [Array[Elem], Array[Elem]]
-               | () -> ::Enumerator[Elem, [Array[Elem], Array[Elem] ]]
+class Enumerable[E]
+  def partition: () { (E) -> boolish } -> [Array[E], Array[E]]
+               | () -> ::Enumerator[E, [Array[E], Array[E] ]]
 end
 ```
 
@@ -300,9 +300,9 @@ Tuples can be of any size, and they can have mixed types.
 ```
 
 ```rbs
-class Enumerable[Elem]
+class Enumerable[E]
   def to_h: () -> ::Hash[untyped, untyped]
-          | [T, U] () { (Elem) -> [T, U] } -> ::Hash[T, U]
+          | [T, U] () { (E) -> [T, U] } -> ::Hash[T, U]
 end
 ```
 

data/docs/release.md

@@ -0,0 +1,69 @@
+# Releasing RBS
+
+Each release ships **two gems**:
+
+| Gem | Platform | Parser | How it is built |
+| --- | --- | --- | --- |
+| `rbs-X.Y.Z.gem` | `ruby` (MRI) | C extension | `rake release` (re-builds it) |
+| `rbs-X.Y.Z-java.gem` | `java` (JRuby) | WebAssembly (`lib/rbs/wasm`) | Docker image, pushed manually |
+
+The `-java` gem contains no native code — just `rbs_parser.wasm`. The Chicory/ASM
+jars it needs are not shipped in the gem; they are declared as `jar-dependencies`
+requirements and fetched from Maven when the gem is installed. So the gem can be
+built once in any environment and runs on every JRuby.
+
+## Prerequisites
+
+- Push rights to the `rbs` gem on RubyGems (`gem signin`). If your account has
+  MFA enabled, `gem push` / `rake release` will prompt for an OTP.
+- Docker, for the `-java` gem. The WASI SDK is baked into the image, so there is
+  nothing to install on the host.
+
+## Steps
+
+### 1. Release the `ruby` gem
+
+Once the version is bumped and committed, run on CRuby:
+
+```console
+$ bundle exec rake release
+```
+
+This re-builds the `ruby`-platform gem and then:
+
+- creates the tag `vX.Y.Z`,
+- pushes the current branch and the tag to `origin`,
+- pushes the gem to RubyGems,
+- runs `release:note`, which opens a GitHub **draft** release (with
+  `--prerelease` for `*.pre.*` versions) and prints the remaining manual steps.
+
+### 2. Build and push the `java` gem
+
+The `java` gem is not built by `rake release`, so build and push it manually:
+
+```console
+# Build from the committed state (the gemspec's file list comes from `git ls-files`).
+$ docker build -f Dockerfile.jruby -t rbs-jruby .
+
+# Build rbs_parser.wasm and the -java gem into ./pkg on the host. The Chicory/ASM
+# jars are not bundled; they are fetched from Maven when the gem is installed.
+$ docker run --rm -e RBS_PLATFORM=java -v "$PWD/pkg:/out" rbs-jruby \
+    gem build rbs.gemspec -o /out/rbs-X.Y.Z-java.gem
+
+$ gem push pkg/rbs-X.Y.Z-java.gem
+```
+
+Optionally confirm it installs and runs on JRuby before pushing:
+
+```console
+$ docker run --rm -v "$PWD/pkg:/pkg" -w /tmp rbs-jruby bash -c \
+    'gem install /pkg/rbs-X.Y.Z-java.gem && ruby -e "require %q{rbs}; puts [RUBY_ENGINE, RBS::VERSION].join(%q{ })"'
+```
+
+## Notes
+
+- Prereleases (`X.Y.Z.pre.N`) are only installed with `gem install rbs --pre`;
+  a plain `gem install rbs` is unaffected. On JRuby, `gem install rbs [--pre]`
+  resolves to the `-java` gem automatically.
+- The Dockerfile pins the WASI SDK / Chicory / ASM versions to match the
+  `wasm` and `jruby` CI workflows. Keep them in sync when bumping.

data/docs/syntax.md

@@ -196,8 +196,8 @@ It is an alias of `top` type, and you can use `boolish` if we want to allow any
 We can see an example at the definition of `Enumerable#find`:
 
 ```rbs
-module Enumerable[Elem, Return]
-  def find: () { (Elem) -> boolish } -> Elem?
+module Enumerable[E, R]
+  def find: () { (E) -> boolish } -> E?
 end
 ```
 

data/docs/wasm_serialization.md

@@ -0,0 +1,80 @@
+# RBS AST binary serialization
+
+This document describes the binary format used to move a parsed RBS AST out of
+the parser and into Ruby objects without going through the Ruby C API. It exists
+so that RBS can run on Ruby implementations that cannot load the C extension
+(notably JRuby): the parser runs inside WebAssembly, serializes the result with
+this format, and the host rebuilds `RBS::AST` objects in pure Ruby.
+
+The encoder (`rbs_serialize_node`, `src/serialize.c`) and the schema that drives
+the decoder (`RBS::WASM::SerializationSchema`, `lib/rbs/wasm/serialization_schema.rb`)
+are both generated from `config.yml`, so they always agree. The decoder itself
+is `RBS::WASM::Deserializer`.
+
+## Conventions
+
+- All multi-byte integers are **little-endian**.
+- `u8`, `u32` are unsigned; `i32` is signed.
+- `str` is a `u32` byte length followed by that many raw bytes (no terminator).
+- A value is reconstructed to mirror exactly what `ast_translation.c` produces,
+  including string encodings: string/integer literal nodes are UTF-8, while
+  comments, annotations and symbols use the source buffer's encoding.
+
+## Nodes
+
+Every node begins with a `u8` **tag**:
+
+- `0` — a NULL node (`nil` on the Ruby side).
+- `1..N` — a node type, in the order they appear in `SerializationSchema::SCHEMA`.
+- `SYMBOL_TAG` (`N + 1`) — an interned symbol, followed by `str` (the symbol's
+  bytes). Decoded with `String#to_sym`.
+
+A few node types are encoded specially, matching their bespoke handling in
+`ast_translation.c`:
+
+| Node | Payload after tag | Decoded as |
+| --- | --- | --- |
+| `RBS::AST::Bool` | `u8` | `true` / `false` |
+| `RBS::AST::Integer` | `str` | `String#to_i` |
+| `RBS::AST::String` | `str` | the string (UTF-8) |
+| `RBS::Types::Record::FieldType` | node, then `u8` | `[type, required]` |
+| `RBS::Signature` | node-list, then node-list | `[directives, declarations]` |
+| `RBS::Namespace` | node-list, then `u8` | `RBS::Namespace[path, absolute]` |
+| `RBS::TypeName` | node, then node | `RBS::TypeName[namespace, name]` |
+
+Every other node is encoded generically:
+
+1. If the node exposes a location, its **base location** is written (see below),
+   followed by one location range per declared child, in order.
+2. Each field is written in declaration order, encoded by its type (see below).
+
+The decoder constructs `Klass.new(location:, **fields)` (omitting `location:`
+for nodes that do not expose one). For `Class`, `Module`, `Interface`,
+`TypeAlias` and `MethodType`, `RBS::AST::TypeParam.resolve_variables` is applied
+to `type_params` first, exactly as the C translation does.
+
+## Fields
+
+| Field type | Encoding |
+| --- | --- |
+| node (`rbs_node`, `rbs_type_name`, `rbs_ast_comment`, `rbs_ast_symbol`, ...) | a node (recursive; NULL allowed) |
+| `rbs_node_list` | `u32` count, then that many nodes |
+| `rbs_hash` | `u32` count, then count × (key node, value node) |
+| `rbs_string` | `str` (source encoding) |
+| `bool` | `u8` |
+| enum | `u8` index into the enum's values (see `SCHEMA`) |
+| `rbs_location_range` | a location range |
+| `rbs_location_range_list` | `u32` count, then that many location ranges |
+| `rbs_attr_ivar_name` | `u8` tag: `0` → `nil`, `1` → `false`, `2` → `str` → symbol |
+
+## Location ranges
+
+A location range is a `u8` presence flag:
+
+- `0` — null range (`nil`, or a node with no location).
+- `1` — followed by `i32` start and `i32` end **character** positions.
+
+The base location and child ranges together let the decoder rebuild an
+`RBS::Location` (with its required/optional children) through the public
+`RBS::Location` API, so the same decoder works whether `RBS::Location` is backed
+by the C extension or a pure-Ruby implementation.