rbs 3.8.0 → 3.9.0.dev.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b91cbfc2b983ede8389074430b54b2db70d1afee9c54c92cf8bc875568b7cf8
-  data.tar.gz: b0306b614ba8d61f78c78e91340615ee5a5b196d562eaac580c5f2fe66a29927
+  metadata.gz: 311aed14b7b84b6b21cb187b72c1ddd87a427b6ec02805017f83b5fbcbfaac7b
+  data.tar.gz: 4fc2e119368352b2fbded9355834757399cde34f3912c24ae82e91db67042762
 SHA512:
-  metadata.gz: 78e9e035fccfc91fcdf4f37812e56c52d8dd9c4fd19211ad8c3ae1e9ddeda0c4deb3178b5b45e27863e93ebe415605bc83fd6d74ff2e13fc1ff266c82ab74059
-  data.tar.gz: 6e65f935e8e51b9542cfd8b2aab6a367949be17742764dbe0a65532e3a87f9fc1f1ce829eb67783bc7f7c711f8039b59a3e66ef24aeecb698def729908f96139
+  metadata.gz: 6c9b1a6188ac4585b3ea5b9dd72432f12ea13ee4c8311a15a86f0cee5595acef46901e04105e40a84703ea51e036efb645a53cacaa1517d213420b2251f3f506
+  data.tar.gz: 4061149d53166bbe1a6029cebbacc54117eccf5d414c1859b50c5049d2898245a27ccf8f558b9c11d5edaa0b276ba88c111b8c80505a5b911664e77b5351dc2a

data/.github/workflows/comments.yml

@@ -10,13 +10,13 @@ on:
 jobs:
   comments:
     runs-on: "ubuntu-latest"
-    env:
-      RUBY_COMMIT: 1b0c46daed9186b82ab4fef1a4ab225afe582ee6
+    # env:
+    #   RUBY_COMMIT: 1b0c46daed9186b82ab4fef1a4ab225afe582ee6
     steps:
       - uses: actions/checkout@v4
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.4.0-rc1"
+          ruby-version: "3.4.1"
           bundler: none
       - name: Install dependencies
         run: |

data/.github/workflows/dependabot.yml

@@ -14,7 +14,7 @@ jobs:
     if: ${{ github.event.pull_request.user.login == 'dependabot[bot]' }}
     steps:
       - name: Dependabot metadata
-        uses: dependabot/fetch-metadata@dbb049abf0d677abbd7f7eee0375145b417fdd34 # v2.2.0
+        uses: dependabot/fetch-metadata@d7267f607e9d3fb96fc2fbe83e0af444713e90b7 # v2.3.0
         id: metadata
       - name: Checkout repository
         uses: actions/checkout@v4

data/.github/workflows/ruby.yml

@@ -13,26 +13,26 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.1', '3.2', '3.3', '3.4.0-rc1', head]
+        ruby: ['3.1', '3.2', '3.3', '3.4', head]
         rubyopt: [""]
         job:
           - test
         include:
           - ruby: head
             job: stdlib_test rubocop
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: stdlib_test
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: test
             rubyopt: "--enable-frozen-string-literal"
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: stdlib_test
             rubyopt: "--enable-frozen-string-literal"
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: lexer templates compile confirm_lexer confirm_templates
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: rubocop validate test_doc build test_generate_stdlib raap
-          - ruby: "3.4.0-rc1"
+          - ruby: "3.4"
             job: typecheck_test
     env:
       RANDOMIZE_STDLIB_TEST_ORDER: "true"

data/.github/workflows/typecheck.yml

@@ -20,6 +20,8 @@ jobs:
           bundler: none
       - name: Set working directory as safe
         run: git config --global --add safe.directory $(pwd)
+      - name: Set up permission
+        run: chmod -R o-w /opt/hostedtoolcache/Ruby
       - name: Install dependencies
         run: |
           sudo apt-get update

data/.github/workflows/windows.yml

@@ -20,6 +20,21 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
+
+      # ucrt and mswin have the dev version Ruby.
+      # It introduce checksum mismatches for bundled gems. So remove them before `bundle install`
+      - name: Purge gem caches
+        run: |
+          ruby -e '
+            exit if "${{ matrix.ruby }}" != "ucrt" && "${{ matrix.ruby }}" != "mswin"
+
+            require "open-uri"
+            require "json"
+
+            res = URI.parse("https://stdgems.org/bundled_gems.json").read
+            bundled_gems = JSON.parse(res)["gems"].map{_1["gem"]}
+            system "gem uninstall #{bundled_gems.join(" ")}", exception: true
+          '
       - name: bundle install
         run: |
           bundle config set without profilers libs

data/.rubocop.yml

@@ -3,7 +3,7 @@ require:
   - rubocop-on-rbs
 
 AllCops:
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.1
   DisabledByDefault: true
   Exclude:
     - 'vendor/bundle/**/*'
@@ -15,6 +15,7 @@ Rubycw/Rubycw:
 
 RBS:
   Enabled: true
+
 RBS/Layout:
   Enabled: true
   Exclude:
@@ -23,6 +24,7 @@ RBS/Layout:
 RBS/Layout/CommentIndentation:
   Exclude:
     - core/string.rbs
+
 RBS/Lint:
   Enabled: true
   Exclude:
@@ -32,15 +34,32 @@ RBS/Lint/TopLevelInterface:
   Enabled: false
 RBS/Lint/TopLevelTypeAlias:
   Enabled: false
+RBS/Lint/AmbiguousKeywordArgumentKey:
+  Exclude:
+    # OpenSSL::KDF.scrypt
+    - 'stdlib/openssl/0/openssl.rbs'
+
 RBS/Style:
   Enabled: false
   Exclude:
     - 'sig/**/*'
     - 'test/**/*'
+RBS/Style/BlockReturnBoolish:
+  Enabled: true
+RBS/Style/ClassWithSingleton:
+  Enabled: true
+RBS/Style/DuplicatedType:
+  Enabled: true
 RBS/Style/EmptyArgument:
   Enabled: true
 RBS/Style/InitializeReturnType:
   Enabled: true
+RBS/Style/InstanceWithInstance:
+  Enabled: true
+RBS/Style/OptionalNil:
+  Enabled: true
+RBS/Style/RedundantParentheses:
+  Enabled: true
 
 Lint/DuplicateMethods:
   Enabled: true

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## 3.8.1 (2024-12-27)
+
+### Signature updates
+
+* `Ractor.store_if_absent` ([#2206](https://github.com/ruby/rbs/pull/2206))
+* `Time#iso860t1` ([#2207](https://github.com/ruby/rbs/pull/2207))
+* `Time#xmlschema` ([#2207](https://github.com/ruby/rbs/pull/2207))
+
+### Miscellaneous
+
+* Update rubocop-on-rbs ([#2200](https://github.com/ruby/rbs/pull/2200))
+* Update docs based on Ruby 3.4.1 ([#2208](https://github.com/ruby/rbs/pull/2208))
+* Ruby 3.4.1 ([#2206](https://github.com/ruby/rbs/pull/2206))
+
 ## 3.8.0 (2024-12-24)
 
 ### Signature updates

data/Rakefile

@@ -112,7 +112,7 @@ end
 
 task :stdlib_test => :compile do
   test_files = FileList["test/stdlib/**/*_test.rb"].reject do |path|
-    path =~ %r{Ractor} || path =~ %r{Encoding}
+    path =~ %r{Ractor} || path =~ %r{Encoding} || path =~ %r{CGI_test}
   end
 
   if ENV["RANDOMIZE_STDLIB_TEST_ORDER"] == "true"
@@ -121,6 +121,7 @@ task :stdlib_test => :compile do
 
   sh "#{ruby} -Ilib #{bin}/test_runner.rb #{test_files.join(' ')}"
   # TODO: Ractor tests need to be run in a separate process
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/CGI_test.rb"
   sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Ractor_test.rb"
   sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Encoding_test.rb"
 end
@@ -139,7 +140,9 @@ task :typecheck_test => :compile do
 end
 
 task :raap => :compile do
-  sh %q[ruby test/raap.rb | xargs bundle exec raap -r digest/bubblebabble --library digest --allow-private]
+  sh "ruby test/raap/core.rb"
+  sh "ruby test/raap/digest.rb"
+  sh "ruby test/raap/openssl.rb"
 end
 
 task :rubocop do

data/config.yml

@@ -27,18 +27,21 @@ nodes:
       - name: old_name
       - name: location
       - name: comment
+      - name: annotations
   - name: RBS::AST::Declarations::Constant
     fields:
       - name: name
       - name: type
       - name: location
       - name: comment
+      - name: annotations
   - name: RBS::AST::Declarations::Global
     fields:
       - name: name
       - name: type
       - name: location
       - name: comment
+      - name: annotations
   - name: RBS::AST::Declarations::Interface
     fields:
       - name: name
@@ -67,6 +70,7 @@ nodes:
       - name: old_name
       - name: location
       - name: comment
+      - name: annotations
   - name: RBS::AST::Declarations::TypeAlias
     fields:
       - name: name
@@ -191,6 +195,7 @@ nodes:
       - name: variance
       - name: upper_bound
       - name: default_type
+      - name: unchecked
       - name: location
   - name: RBS::MethodType
     fields:
@@ -213,6 +218,7 @@ nodes:
       - name: location
   - name: RBS::Types::Bases::Any
     fields:
+      - name: todo
       - name: location
   - name: RBS::Types::Bases::Bool
     fields:

data/core/data.rbs

@@ -411,5 +411,5 @@ class Data
   #     out = origin.with(z: 1) # ArgumentError: unknown keyword: :z
   #     some_point = origin.with(1, 2) # ArgumentError: expected keyword arguments, got positional arguments
   #
-  def with: (**untyped) -> instance
+  def with: (**untyped) -> self
 end

data/core/enumerator.rbs

@@ -613,7 +613,18 @@ end
 # This type of objects can be created by Enumerable#chain and Enumerator#+.
 #
 class Enumerator::Chain[out Elem] < Enumerator[Elem, void]
-  include Enumerable[Elem]
+  # <!--
+  #   rdoc-file=enumerator.c
+  #   - Enumerator::Chain.new(*enums) -> enum
+  # -->
+  # Generates a new enumerator object that iterates over the elements of given
+  # enumerable objects in sequence.
+  #
+  #     e = Enumerator::Chain.new(1..3, [4, 5])
+  #     e.to_a #=> [1, 2, 3, 4, 5]
+  #     e.size #=> 5
+  #
+  def initialize: (*_Each[Elem] enums) -> void
 
   # <!--
   #   rdoc-file=enumerator.c
@@ -626,5 +637,6 @@ class Enumerator::Chain[out Elem] < Enumerator[Elem, void]
   #
   # If no block is given, returns an enumerator.
   #
-  def each: () { (Elem) -> void } -> void
+  def each: () { (Elem) -> void } -> self
+          | () -> Enumerator[Elem, self]
 end

data/core/exception.rbs

@@ -99,24 +99,31 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of strings.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns the array of strings
-  #     given by `Exception#backtrace_locations.map {|loc| loc.to_s }`. This is
-  #     the normal case, where the backtrace value was stored by Kernel#raise.
-  # *   Array of strings: returns that array. This is the unusual case, where the
-  #     backtrace value was explicitly stored as an array of strings.
-  # *   `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace.first
+  #       p loc.class
+  #       # String
   #     end
-  #     # => ["(irb):132:in `/'", "(irb):132:in `<top (required)>'"]
+  #
+  # The value returned by this method migth be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace_locations that provide the same value, as structured
+  # objects. (Note though that two values might not be consistent with each other
+  # when backtraces are manually adjusted.)
   #
   # see [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -126,20 +133,37 @@ class Exception
   #   rdoc-file=error.c
   #   - backtrace_locations -> array or nil
   # -->
-  # Returns a backtrace value for `self`; the returned value depends on the form
-  # of the stored backtrace value:
+  # Returns the backtrace (the list of code locations that led to the exception),
+  # as an array of Thread::Backtrace::Location instances.
   #
-  # *   Array of Thread::Backtrace::Location objects: returns that array.
-  # *   Array of strings or `nil`: returns `nil`.
+  # Example (assuming the code is stored in the file named `t.rb`):
   #
-  # Example:
+  #     def division(numerator, denominator)
+  #       numerator / denominator
+  #     end
   #
   #     begin
-  #       1 / 0
-  #     rescue => x
-  #       x.backtrace_locations.take(2)
+  #       division(1, 0)
+  #     rescue => ex
+  #       p ex.backtrace_locations
+  #       # ["t.rb:2:in 'Integer#/'", "t.rb:2:in 'Object#division'", "t.rb:6:in '<main>'"]
+  #       loc = ex.backtrace_locations.first
+  #       p loc.class
+  #       # Thread::Backtrace::Location
+  #       p loc.path
+  #       # "t.rb"
+  #       p loc.lineno
+  #       # 2
+  #       p loc.label
+  #       # "Integer#/"
   #     end
-  #     # => ["(irb):150:in `/'", "(irb):150:in `<top (required)>'"]
+  #
+  # The value returned by this method might be adjusted when raising (see
+  # Kernel#raise), or during intermediate handling by #set_backtrace.
+  #
+  # See also #backtrace that provide the same value as an array of strings. (Note
+  # though that two values might not be consistent with each other when backtraces
+  # are manually adjusted.)
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -246,7 +270,7 @@ class Exception
   #     x0..equal?(x1)            # => false
   #
   def exception: (?self) -> self
-               | (string | _ToS message) -> instance
+               | (string | _ToS message) -> self
 
   # <!--
   #   rdoc-file=error.c
@@ -294,15 +318,100 @@ class Exception
   #   rdoc-file=error.c
   #   - set_backtrace(value) -> value
   # -->
-  # Sets the backtrace value for `self`; returns the given +value:
+  # Sets the backtrace value for `self`; returns the given `value`.
   #
-  #     x = RuntimeError.new('Boom')
-  #     x.set_backtrace(%w[foo bar baz]) # => ["foo", "bar", "baz"]
-  #     x.backtrace                      # => ["foo", "bar", "baz"]
+  # The `value` might be:
   #
-  # The given `value` must be an array of strings, a single string, or `nil`.
+  # *   an array of Thread::Backtrace::Location;
+  # *   an array of String instances;
+  # *   a single String instance; or
+  # *   `nil`.
+  #
+  # Using array of Thread::Backtrace::Location is the most consistent option: it
+  # sets both #backtrace and #backtrace_locations. It should be preferred when
+  # possible. The suitable array of locations can be obtained from
+  # Kernel#caller_locations, copied from another error, or just set to the
+  # adjusted result of the current error's #backtrace_locations:
+  #
+  #     require 'json'
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)  # test.rb, line 4
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(ex.backtrace_locations[2...])
+  #       raise
+  #     end
   #
-  # Does not affect the value returned by #backtrace_locations.
+  #     parse_payload('{"wrong: "json"')
+  #     # test.rb:4:in 'Object#parse_payload': unexpected token at '{"wrong: "json"' (JSON::ParserError)
+  #     #
+  #     # An error points to the body of parse_payload method,
+  #     # hiding the parts of the backtrace related to the internals
+  #     # of the "json" library
+  #
+  #     # The error has both #backtace and #backtrace_locations set
+  #     # consistently:
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:4:in 'Object#parse_payload'", "test.rb:20:in '<main>'"]
+  #     end
+  #
+  # When the desired stack of locations is not available and should be constructed
+  # from scratch, an array of strings or a singular string can be used. In this
+  # case, only #backtrace is affected:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(["dsl.rb:34", "framework.rb:1"])
+  #       # The error have the new value in #backtrace:
+  #       p ex.backtrace
+  #       # ["dsl.rb:34", "framework.rb:1"]
+  #
+  #       # but the original one in #backtrace_locations
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # Calling #set_backtrace with `nil` clears up #backtrace but doesn't affect
+  # #backtrace_locations:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       p ex.backtrace
+  #       # nil
+  #       p ex.backtrace_locations
+  #       # [".../json/common.rb:221:in 'JSON::Ext::Parser.parse'", ...]
+  #     end
+  #
+  #     parse_payload('{"wrong: "json"')
+  #
+  # On reraising of such an exception, both #backtrace and #backtrace_locations is
+  # set to the place of reraising:
+  #
+  #     def parse_payload(text)
+  #       JSON.parse(text)
+  #     rescue JSON::ParserError => ex
+  #       ex.set_backtrace(nil)
+  #       raise # test.rb, line 7
+  #     end
+  #
+  #     begin
+  #       parse_payload('{"wrong: "json"')
+  #     rescue => ex
+  #       p ex.backtrace
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #       p ex.backtrace_locations
+  #       # ["test.rb:7:in 'Object#parse_payload'", "test.rb:11:in '<main>'"]
+  #     end
   #
   # See [Backtraces](rdoc-ref:exceptions.md@Backtraces).
   #
@@ -358,16 +467,16 @@ class Exception
   # Output:
   #
   #     "divided by 0"
-  #     ["t.rb:3:in `/': divided by 0 (ZeroDivisionError)",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
-  #     ["t.rb:3:in `/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
-  #      "\tfrom t.rb:3:in `baz'",
-  #      "\tfrom t.rb:10:in `bar'",
-  #      "\tfrom t.rb:11:in `foo'",
-  #      "\tfrom t.rb:12:in `<main>'"]
+  #     ["t.rb:3:in 'Integer#/': divided by 0 (ZeroDivisionError)",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
+  #     ["t.rb:3:in 'Integer#/': \e[1mdivided by 0 (\e[1;4mZeroDivisionError\e[m\e[1m)\e[m",
+  #      "\tfrom t.rb:3:in 'Object#baz'",
+  #      "\tfrom t.rb:10:in 'Object#bar'",
+  #      "\tfrom t.rb:11:in 'Object#foo'",
+  #      "\tfrom t.rb:12:in '<main>'"]
   #
   # An overriding method should be careful with ANSI code enhancements; see
   # [Messages](rdoc-ref:exceptions.md@Messages).

data/core/gc.rbs

@@ -111,7 +111,7 @@ module GC
     # `:HAVE_FINALIZE`
     # :
     #
-    def self.raw_data: () -> Array[Hash[Symbol, untyped]]
+    def self.raw_data: () -> Array[Hash[Symbol, untyped]]?
 
     # <!--
     #   rdoc-file=gc.c
@@ -587,7 +587,7 @@ module GC
 
   # The type that `GC.compact` and related functions can return.
   #
-  type compact_info = Hash[:considered | :moved |:moved_up | :moved_down, Hash[Symbol, Integer]]
+  type compact_info = Hash[:considered | :moved | :moved_up | :moved_down, Hash[Symbol, Integer]]
 
   # <!--
   #   rdoc-file=gc.rb

data/core/io.rbs

@@ -2278,7 +2278,7 @@ class IO < Object
   # potential security vulnerabilities if called with untrusted input; see
   # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  def self.binread: (String name, ?Integer length, ?Integer offset) -> String
+  def self.binread: (String name, ?Integer? length, ?Integer offset) -> String
 
   # <!--
   #   rdoc-file=io.c
@@ -2343,7 +2343,7 @@ class IO < Object
   #     IO.copy_stream('t.txt', 't.tmp', 11, 11) # => 11
   #     IO.read('t.tmp')                         # => "Second line"
   #
-  def self.copy_stream: (String | _Reader | _ReaderPartial src, String | _Writer dst, ?Integer copy_length, ?Integer src_offset) -> Integer
+  def self.copy_stream: (String | _Reader | _ReaderPartial src, String | _Writer dst, ?Integer? copy_length, ?Integer src_offset) -> Integer
 
   # <!--
   #   rdoc-file=io.c
@@ -2716,7 +2716,7 @@ class IO < Object
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
-  def self.read: (String name, ?Integer length, ?Integer offset, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String) -> String
+  def self.read: (String name, ?Integer? length, ?Integer offset, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String) -> String
 
   # <!--
   #   rdoc-file=io.c
@@ -3251,6 +3251,10 @@ class IO < Object
   #     f.close
   #
   alias to_i fileno
+
+  interface _ForFd[RET]
+    def for_fd: (?) -> RET
+  end
 end
 
 IO::APPEND: Integer