rbs 4.0.0.dev.4 → 4.0.0.dev.5

data/core/struct.rbs

@@ -130,7 +130,7 @@ class Struct[Elem]
   #     Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
   #     f = Foo.new(0, 1)                   # => #<struct Struct::Foo foo=0, bar=1>
   #
-  # **\Class Name**
+  # **Class Name**
   #
   # With string argument `class_name`, returns a new subclass of `Struct` named
   # `Struct::*class_name`*:

data/core/symbol.rbs

@@ -130,19 +130,25 @@ class Symbol
 
   # <!--
   #   rdoc-file=string.c
-  #   - symbol <=> object -> -1, 0, +1, or nil
+  #   - self <=> other -> -1, 0, 1, or nil
   # -->
-  # If `object` is a symbol, returns the equivalent of `symbol.to_s <=>
-  # object.to_s`:
+  # Compares `self` and `other`, using String#<=>.
   #
-  #     :bar <=> :foo # => -1
-  #     :foo <=> :foo # => 0
-  #     :foo <=> :bar # => 1
+  # Returns:
   #
-  # Otherwise, returns `nil`:
+  # *   `self.to_s <=> other.to_s`, if `other` is a symbol.
+  # *   `nil`, otherwise.
   #
+  # Examples:
+  #
+  #     :bar <=> :foo  # => -1
+  #     :foo <=> :foo  # => 0
+  #     :foo <=> :bar  # => 1
   #     :foo <=> 'bar' # => nil
   #
+  # Class Symbol includes module Comparable, each of whose methods uses Symbol#<=>
+  # for comparison.
+  #
   # Related: String#<=>.
   #
   def <=>: (Symbol object) -> (-1 | 0 | 1)
@@ -188,7 +194,7 @@ class Symbol
 
   # <!--
   #   rdoc-file=string.c
-  #   - capitalize(*options) -> symbol
+  #   - capitalize(mapping) -> symbol
   # -->
   # Equivalent to `sym.to_s.capitalize.to_sym`.
   #
@@ -268,7 +274,7 @@ class Symbol
 
   # <!--
   #   rdoc-file=string.c
-  #   - downcase(*options) -> symbol
+  #   - downcase(mapping) -> symbol
   # -->
   # Equivalent to `sym.to_s.downcase.to_sym`.
   #
@@ -413,7 +419,7 @@ class Symbol
 
   # <!--
   #   rdoc-file=string.c
-  #   - swapcase(*options) -> symbol
+  #   - swapcase(mapping) -> symbol
   # -->
   # Equivalent to `sym.to_s.swapcase.to_sym`.
   #
@@ -462,7 +468,7 @@ class Symbol
 
   # <!--
   #   rdoc-file=string.c
-  #   - upcase(*options) -> symbol
+  #   - upcase(mapping) -> symbol
   # -->
   # Equivalent to `sym.to_s.upcase.to_sym`.
   #

data/core/thread.rbs

@@ -265,7 +265,10 @@ class Thread < Object
   # -->
   # Terminates `thr` and schedules another thread to be run, returning the
   # terminated Thread.  If this is the main thread, or the last thread, exits the
-  # process.
+  # process. Note that the caller does not wait for the thread to terminate if the
+  # receiver is different from the currently running thread. The termination is
+  # asynchronous, and the thread can still run a small amount of ruby code before
+  # exiting.
   #
   def kill: () -> Thread?
 
@@ -334,7 +337,10 @@ class Thread < Object
   # <!-- rdoc-file=thread.c -->
   # Terminates `thr` and schedules another thread to be run, returning the
   # terminated Thread.  If this is the main thread, or the last thread, exits the
-  # process.
+  # process. Note that the caller does not wait for the thread to terminate if the
+  # receiver is different from the currently running thread. The termination is
+  # asynchronous, and the thread can still run a small amount of ruby code before
+  # exiting.
   #
   def exit: () -> Thread?
 
@@ -364,9 +370,9 @@ class Thread < Object
 
   # <!--
   #   rdoc-file=thread.c
-  #   - Thread.new { ... }                  -> thread
-  #   - Thread.new(*args, &proc)            -> thread
-  #   - Thread.new(*args) { |args| ... }    -> thread
+  #   - Thread.new { ... }                -> thread
+  #   - Thread.new(*args, &proc)          -> thread
+  #   - Thread.new(*args) { |args| ... }  -> thread
   # -->
   # Creates a new thread executing the given block.
   #
@@ -660,7 +666,10 @@ class Thread < Object
   # <!-- rdoc-file=thread.c -->
   # Terminates `thr` and schedules another thread to be run, returning the
   # terminated Thread.  If this is the main thread, or the last thread, exits the
-  # process.
+  # process. Note that the caller does not wait for the thread to terminate if the
+  # receiver is different from the currently running thread. The termination is
+  # asynchronous, and the thread can still run a small amount of ruby code before
+  # exiting.
   #
   def terminate: () -> Thread?
 
@@ -947,12 +956,11 @@ class Thread < Object
 
   # <!--
   #   rdoc-file=thread.c
-  #   - thr.raise
-  #   - thr.raise(string)
-  #   - thr.raise(exception [, string [, array]])
+  #   - raise(exception, message = exception.to_s, backtrace = nil, cause: $!)
+  #   - raise(message = nil, cause: $!)
   # -->
   # Raises an exception from the given thread. The caller does not have to be
-  # `thr`. See Kernel#raise for more information.
+  # `thr`. See Kernel#raise for more information on arguments.
   #
   #     Thread.abort_on_exception = true
   #     a = Thread.new { sleep(200) }
@@ -965,8 +973,8 @@ class Thread < Object
   #      from prog.rb:2:in `new'
   #      from prog.rb:2
   #
-  def raise: (?String message) -> nil
-           | (_Exception, ?_ToS message, ?Array[Thread::Backtrace::Location] | Array[String] | nil backtrace) -> nil
+  def raise: (?String message, ?cause: Exception?) -> nil
+           | (_Exception, ?_ToS message, ?Array[Thread::Backtrace::Location] | Array[String] | nil backtrace, ?cause: Exception?) -> nil
 
   # <!--
   #   rdoc-file=thread.c
@@ -1378,28 +1386,80 @@ end
 # <!-- rdoc-file=thread_sync.c -->
 # ConditionVariable objects augment class Mutex. Using condition variables, it
 # is possible to suspend while in the middle of a critical section until a
-# resource becomes available.
+# condition is met, such as a resource becomes available.
+#
+# Due to non-deterministic scheduling and spurious wake-ups, users of condition
+# variables should always use a separate boolean predicate (such as reading from
+# a boolean variable) to check if the condition is actually met before starting
+# to wait, and should wait in a loop, re-checking the condition every time the
+# ConditionVariable is waken up.  The idiomatic way of using condition variables
+# is calling the `wait` method in an `until` loop with the predicate as the loop
+# condition.
+#
+#     condvar.wait(mutex) until condition_is_met
+#
+# In the example below, we use the boolean variable `resource_available` (which
+# is protected by `mutex`) to indicate the availability of the resource, and use
+# `condvar` to wait for that variable to become true.  Note that:
+#
+# 1.  Thread `b` may be scheduled before thread `a1` and `a2`, and may run so
+#     fast that it have already made the resource available before either `a1`
+#     or `a2` starts. Therefore, `a1` and `a2` should check if
+#     `resource_available` is already true before starting to wait.
+# 2.  The `wait` method may spuriously wake up without signalling. Therefore,
+#     thread `a1` and `a2` should recheck `resource_available` after the `wait`
+#     method returns, and go back to wait if the condition is not actually met.
+# 3.  It is possible that thread `a2` starts right after thread `a1` is waken up
+#     by `b`.  Thread `a2` may have acquired the `mutex` and consumed the
+#     resource before thread `a1` acquires the `mutex`.  This necessitates
+#     rechecking after `wait`, too.
 #
 # Example:
 #
 #     mutex = Thread::Mutex.new
-#     resource = Thread::ConditionVariable.new
 #
-#     a = Thread.new {
-#        mutex.synchronize {
-#          # Thread 'a' now needs the resource
-#          resource.wait(mutex)
-#          # 'a' can now have the resource
-#        }
+#     resource_available = false
+#     condvar = Thread::ConditionVariable.new
+#
+#     a1 = Thread.new {
+#       # Thread 'a1' waits for the resource to become available and consumes
+#       # the resource.
+#       mutex.synchronize {
+#         condvar.wait(mutex) until resource_available
+#         # After the loop, 'resource_available' is guaranteed to be true.
+#
+#         resource_available = false
+#         puts "a1 consumed the resource"
+#       }
+#     }
+#
+#     a2 = Thread.new {
+#       # Thread 'a2' behaves like 'a1'.
+#       mutex.synchronize {
+#         condvar.wait(mutex) until resource_available
+#         resource_available = false
+#         puts "a2 consumed the resource"
+#       }
 #     }
 #
 #     b = Thread.new {
-#        mutex.synchronize {
-#          # Thread 'b' has finished using the resource
-#          resource.signal
-#        }
+#       # Thread 'b' periodically makes the resource available.
+#       loop {
+#         mutex.synchronize {
+#           resource_available = true
+#
+#           # Notify one waiting thread if any.  It is possible that neither
+#           # 'a1' nor 'a2 is waiting on 'condvar' at this moment.  That's OK.
+#           condvar.signal
+#         }
+#         sleep 1
+#       }
 #     }
 #
+#     # Eventually both 'a1' and 'a2' will have their resources, albeit in an
+#     # unspecified order.
+#     [a1, a2].each {|th| th.join}
+#
 class Thread::ConditionVariable < Object
   # <!--
   #   rdoc-file=thread_sync.c
@@ -1426,6 +1486,8 @@ class Thread::ConditionVariable < Object
   # If `timeout` is given, this method returns after `timeout` seconds passed,
   # even if no other thread doesn't signal.
   #
+  # This method may wake up spuriously due to underlying implementation details.
+  #
   # Returns the slept result on `mutex`.
   #
   def wait: (Thread::Mutex mutex, ?Time::_Timeout? timeout) -> Integer?
@@ -1453,7 +1515,7 @@ end
 #
 class Thread::Mutex < Object
   # <!--
-  #   rdoc-file=thread_sync.c
+  #   rdoc-file=thread_sync.rb
   #   - mutex.lock  -> self
   # -->
   # Attempts to grab the lock and waits if it isn't available. Raises
@@ -1462,7 +1524,7 @@ class Thread::Mutex < Object
   def lock: () -> self
 
   # <!--
-  #   rdoc-file=thread_sync.c
+  #   rdoc-file=thread_sync.rb
   #   - mutex.locked?  -> true or false
   # -->
   # Returns `true` if this lock is currently held by some thread.
@@ -1470,7 +1532,7 @@ class Thread::Mutex < Object
   def locked?: () -> bool
 
   # <!--
-  #   rdoc-file=thread_sync.c
+  #   rdoc-file=thread_sync.rb
   #   - mutex.owned?  -> true or false
   # -->
   # Returns `true` if this lock is currently held by current thread.
@@ -1478,7 +1540,7 @@ class Thread::Mutex < Object
   def owned?: () -> bool
 
   # <!--
-  #   rdoc-file=thread_sync.c
+  #   rdoc-file=thread_sync.rb
   #   - mutex.synchronize { ... }    -> result of the block
   # -->
   # Obtains a lock, runs the block, and releases the lock when the block
@@ -1487,7 +1549,7 @@ class Thread::Mutex < Object
   def synchronize: [X] () { () -> X } -> X
 
   # <!--
-  #   rdoc-file=thread_sync.c
+  #   rdoc-file=thread_sync.rb
   #   - mutex.try_lock  -> true or false
   # -->
   # Attempts to obtain the lock and returns immediately. Returns `true` if the
@@ -1496,11 +1558,11 @@ class Thread::Mutex < Object
   def try_lock: () -> bool
 
   # <!--
-  #   rdoc-file=thread_sync.c
-  #   - mutex.unlock    -> self
+  #   rdoc-file=thread_sync.rb
+  #   - mutex.lock  -> self
   # -->
-  # Releases the lock. Raises `ThreadError` if `mutex` wasn't locked by the
-  # current thread.
+  # Attempts to grab the lock and waits if it isn't available. Raises
+  # `ThreadError` if `mutex` was locked by the current thread.
   #
   def unlock: () -> self
 end

data/core/time.rbs

@@ -47,24 +47,30 @@
 #
 # ## Time Internal Representation
 #
-# Time implementation uses a signed 63 bit integer, Integer, or Rational. It is
-# a number of nanoseconds since the *Epoch*. The signed 63 bit integer can
-# represent 1823-11-12 to 2116-02-20. When Integer or Rational is used (before
+# Conceptually, Time class uses a rational value to represent the number of
+# seconds from *Epoch*, 1970-01-01 00:00:00 UTC. There are no boundary or
+# resolution limitations. The value can be obtained using Time#to_r.
+#
+# The Time class always uses the Gregorian calendar. I.e. the proleptic
+# Gregorian calendar is used. Other calendars, such as Julian calendar, are not
+# supported.
+#
+# The implementation uses a signed 63 bit integer, Integer (Bignum) object or
+# Ratoinal object to represent a rational value. (The signed 63 bit integer is
+# used regardless of 32 and 64 bit environments.) The value represents the
+# number of nanoseconds from *Epoch*. The signed 63 bit integer can represent
+# 1823-11-12 to 2116-02-20. When Integer or Rational object is used (before
 # 1823, after 2116, under nanosecond), Time works slower than when the signed 63
 # bit integer is used.
 #
 # Ruby uses the C function `localtime` and `gmtime` to map between the number
 # and 6-tuple (year,month,day,hour,minute,second). `localtime` is used for local
-# time and "gmtime" is used for UTC.
+# time and `gmtime` is used for UTC.
 #
 # Integer and Rational has no range limit, but the localtime and gmtime has
 # range limits due to the C types `time_t` and `struct tm`. If that limit is
 # exceeded, Ruby extrapolates the localtime function.
 #
-# The Time class always uses the Gregorian calendar. I.e. the proleptic
-# Gregorian calendar is used. Other calendars, such as Julian calendar, are not
-# supported.
-#
 # `time_t` can represent 1901-12-14 to 2038-01-19 if it is 32 bit signed
 # integer, -292277022657-01-27 to 292277026596-12-05 if it is 64 bit signed
 # integer. However `localtime` on some platforms doesn't supports negative
@@ -72,7 +78,7 @@
 #
 # `struct tm` has *tm_year* member to represent years. (`tm_year = 0` means the
 # year 1900.) It is defined as `int` in the C standard. *tm_year* can represent
-# between -2147481748 to 2147485547 if `int` is 32 bit.
+# years between -2147481748 to 2147485547 if `int` is 32 bit.
 #
 # Ruby supports leap seconds as far as if the C function `localtime` and
 # `gmtime` supports it. They use the tz database in most Unix systems. The tz
@@ -984,10 +990,20 @@ class Time < Object
   #     now = Time.now
   #     # => 2022-08-18 10:24:13.5398485 -0500
   #     now.utc? # => false
+  #     now.getutc.utc? # => true
   #     utc = Time.utc(2000, 1, 1, 20, 15, 1)
   #     # => 2000-01-01 20:15:01 UTC
   #     utc.utc? # => true
   #
+  # `Time` objects created with these methods are considered to be in UTC:
+  #
+  # *   Time.utc
+  # *   Time#utc
+  # *   Time#getutc
+  #
+  # Objects created in other ways will not be treated as UTC even if the
+  # environment variable "TZ" is "UTC".
+  #
   # Related: Time.utc.
   #
   def gmt?: () -> bool
@@ -1560,10 +1576,20 @@ class Time < Object
   #     now = Time.now
   #     # => 2022-08-18 10:24:13.5398485 -0500
   #     now.utc? # => false
+  #     now.getutc.utc? # => true
   #     utc = Time.utc(2000, 1, 1, 20, 15, 1)
   #     # => 2000-01-01 20:15:01 UTC
   #     utc.utc? # => true
   #
+  # `Time` objects created with these methods are considered to be in UTC:
+  #
+  # *   Time.utc
+  # *   Time#utc
+  # *   Time#getutc
+  #
+  # Objects created in other ways will not be treated as UTC even if the
+  # environment variable "TZ" is "UTC".
+  #
   # Related: Time.utc.
   #
   def utc?: () -> bool

data/core/trace_point.rbs

@@ -25,7 +25,8 @@
 # change. Instead, it is recommended to specify the types of events you want to
 # use.
 #
-# To filter what is traced, you can pass any of the following as `events`:
+# To filter what is traced, you can pass any number of the following as
+# `events`:
 #
 # `:line`
 # :   Execute an expression or statement on a new line.
@@ -107,8 +108,8 @@ class TracePoint
   #
   # A block must be given; otherwise, an ArgumentError is raised.
   #
-  # If the trace method isn't included in the given events filter, a RuntimeError
-  # is raised.
+  # If the trace method isn't supported for the given event(s) filter, a
+  # RuntimeError is raised.
   #
   #     TracePoint.trace(:line) do |tp|
   #       p tp.raised_exception
@@ -122,7 +123,9 @@ class TracePoint
   #     end
   #     $tp.lineno #=> access from outside (RuntimeError)
   #
-  # Access from other threads is also forbidden.
+  # Access from other ractors, threads or fibers is forbidden. TracePoints are
+  # active per-ractor so if you enable a TracePoint in one ractor, other ractors
+  # will not be affected.
   #
   def self.new: (*_ToSym events) { (instance tp) -> void } -> instance
 

data/core/unbound_method.rbs

@@ -1,5 +1,5 @@
 # <!-- rdoc-file=proc.c -->
-# Ruby supports two forms of objectified methods. Class Method is used to
+# Ruby supports two forms of objectified methods. Class `Method` is used to
 # represent methods that are associated with a particular object: these method
 # objects are bound to that object. Bound method objects for an object can be
 # created using Object#method.
@@ -287,10 +287,18 @@ class UnboundMethod
 
   # <!--
   #   rdoc-file=proc.c
-  #   - meth.source_location  -> [String, Integer]
+  #   - meth.source_location  -> [String, Integer, Integer, Integer, Integer]
   # -->
-  # Returns the Ruby source filename and line number containing this method or nil
-  # if this method was not defined in Ruby (i.e. native).
+  # Returns the location where the method was defined. The returned Array
+  # contains:
+  #     (1) the Ruby source filename
+  #     (2) the line number where the definition starts
+  #     (3) the column number where the definition starts
+  #     (4) the line number where the definition ends
+  #     (5) the column number where the definitions ends
+  #
+  # This method will return `nil` if the method was not defined in Ruby (i.e.
+  # native).
   #
   def source_location: () -> [String, Integer]?
 
@@ -298,8 +306,8 @@ class UnboundMethod
   #   rdoc-file=proc.c
   #   - meth.super_method  -> method
   # -->
-  # Returns a Method of superclass which would be called when super is used or nil
-  # if there is no method on superclass.
+  # Returns a `Method` of superclass which would be called when super is used or
+  # nil if there is no method on superclass.
   #
   def super_method: () -> UnboundMethod?
 

data/docs/aliases.md

@@ -0,0 +1,79 @@
+# Aliases
+
+This document explains module/class aliases and type aliases.
+
+## Module/class alias
+
+Module/class aliases give another name to a module/class.
+This is useful for some syntaxes that has lexical constraints.
+
+```rbs
+class C
+end
+
+class D = C         # ::D is an alias for ::C
+
+class E < D         # ::E inherits from ::D, which is actually ::C
+end
+```
+
+Note that module/class aliases cannot be recursive.
+
+So, we can define a *normalization* of aliased module/class names.
+Normalization follows the chain of alias definitions and resolves them to the original module/class defined with `module`/`class` syntax.
+
+```rbs
+class C
+end
+
+class D = C
+class E = D
+```
+
+`::E` is defined as an alias, and it can be normalized to `::C`.
+
+## Type alias
+
+The biggest difference from module/class alias is that type alias can be recursive.
+
+```rbs
+# cons_cell type is defined recursively
+type cons_cell = nil
+               | [Integer, cons_cell]
+```
+
+This means type aliases *cannot be* normalized generally.
+So, we provide another operation for type alias, `DefinitionBuilder#expand_alias` and its family.
+It substitutes with the immediate right hand side of a type alias.
+
+```
+cons_cell ===> nil | [Integer, cons_cell]                   (expand 1 step)
+          ===> nil | [Integer, nil | [Integer, cons_cell]]  (expand 2 steps)
+          ===> ...                                          (expand will go infinitely)
+```
+
+Note that the namespace of a type alias *can be* normalized, because they are module names.
+
+```rbs
+module M
+  type t = String
+end
+
+module N = M
+```
+
+With the type definition above, a type `::N::t` can be normalized to `::M::t`.
+And then it can be expanded to `::String`.
+
+> [!NOTE]
+> This is something like an *unfold* operation in type theory.
+
+## Type name resolution
+
+Type name resolution in RBS usually rewrites *relative* type names to *absolute* type names.
+`Environment#resolve_type_names` converts all type names in the RBS type definitions, and returns a new `Environment` object.
+
+It also *normalizes* modules names in type names.
+
+- If the type name can be resolved and normalized successfully, the AST has *absolute* type names.
+- If the type name resolution/normalization fails, the AST has *relative* type names.

data/docs/collection.md

@@ -159,9 +159,9 @@ For example:
 # manifest.yaml
 
 dependencies:
-  # If your gem depends on pathname but the gemspec doesn't include pathname,
+  # If your gem depends on logger but the gemspec doesn't include logger,
   # you need to write the following.
-  - name: pathname
+  - name: logger
 ```
 
 If the gem's RBS is managed with [ruby/gem_rbs_collection](https://github.com/ruby/gem_rbs_collection), put it as `gems/GEM_NAME/VERSION/manifest.yaml`.  For example, `gems/activesupport/6.0/manifest.yaml`.

data/docs/encoding.md

@@ -0,0 +1,56 @@
+# RBS File Encoding
+
+## Best Practice
+
+**Use UTF-8** for both file encoding and your system locale.
+
+## Supported Encodings
+
+RBS parser supports ASCII-compatible encodings (similar to Ruby's script encoding support).
+
+**Examples**: UTF-8, US-ASCII, Shift JIS, EUC-JP, ...
+
+## Unicode Codepoint Symbols
+
+String literal types in RBS can contain Unicode codepoint escape sequences (`\uXXXX`).
+
+When the file encoding is UTF-8, the parser translates Unicode codepoint symbols:
+
+```rbs
+# In UTF-8 encoded files
+
+type t = "\u0123"  # Translated to the actual Unicode character ģ
+type s = "\u3042"  # Translated to the actual Unicode character あ
+```
+
+When the file encoding is not UTF-8, Unicode escape sequences are interpreted literally as the string `\uXXXX`:
+
+```rbs
+# In non-UTF-8 encoded files
+
+type t = "\u0123"  # Remains as the literal string "\u0123"
+```
+
+## Implementation
+
+RBS gem currently doesn't do anything for file encoding. It relies on Ruby's encoding handling, specifically `Encoding.default_external` and `Encoding.default_internal`.
+
+`Encoding.default_external` is the encoding Ruby assumes when it reads external resources like files. The Ruby interpreter sets it based on the locale. `Encoding.default_internal` is the encoding Ruby converts the external resources to. The default is `nil` (no conversion.)
+
+When your locale is set to use `UTF-8` encoding, `default_external` is `Encoding::UTF_8`. So the RBS file content read from the disk will have UTF-8 encoding.
+
+### Parsing non UTF-8 RBS source text
+
+If you want to work with another encoding, ensure the source string has ASCII compatible encoding.
+
+```ruby
+source = '"日本語"'
+RBS::Parser.parse_type(source.encode(Encoding::EUC_JP))  # => Parses successfully
+RBS::Parser.parse_type(source.encode(Encoding::UTF_32))  # => Returns `nil` since UTF-32 is not ASCII compatible
+```
+
+### Specifying file encoding
+
+Currently, RBS doesn't support specifying file encoding directly.
+
+You can use `Encoding.default_external` while the gem loads RBS files from the storage.

data/docs/gem.md

@@ -34,7 +34,6 @@ dependencies:
   - name: json
   - name: logger
   - name: optparse
-  - name: pathname
   - name: rdoc
   - name: tsort
 ```