rbs 3.9.5 → 4.0.0

data/stdlib/random-formatter/0/random-formatter.rbs

@@ -0,0 +1,277 @@
+module RBS
+  module Unnamed
+    module Random_Formatter
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - base64(n=nil)
+      # -->
+      # Generate a random base64 string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the result string is about 4/3 of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain A-Z, a-z, 0-9, "+", "/" and "=".
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.base64 #=> "/2BuBuLf3+WfSKyQbRcc/A=="
+      #     # or
+      #     prng = Random.new
+      #     prng.base64 #=> "6BbW0pxO0YENxn38HMUbcQ=="
+      #
+      # See RFC 3548 for the definition of base64.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#base64}
+      def base64: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - hex(n=nil)
+      # -->
+      # Generate a random hexadecimal string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the resulting hexadecimal string is twice of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain 0-9 and a-f.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.hex #=> "eb693ec8252cd630102fd0d0fb7c3485"
+      #     # or
+      #     prng = Random.new
+      #     prng.hex #=> "91dc3bfb4de5b11d029d376634589b61"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#hex}
+      def hex: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - random_bytes(n=nil)
+      # -->
+      # Generate a random binary string.
+      #
+      # The argument *n* specifies the length of the result string.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in future.
+      #
+      # The result may contain any byte: "x00" - "xff".
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.random_bytes #=> "\xD8\\\xE0\xF4\r\xB2\xFC*WM\xFF\x83\x18\xF45\xB6"
+      #     # or
+      #     prng = Random.new
+      #     prng.random_bytes #=> "m\xDC\xFC/\a\x00Uf\xB2\xB2P\xBD\xFF6S\x97"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#random_bytes}
+      def random_bytes: (?Integer? n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - urlsafe_base64(n=nil, padding=false)
+      # -->
+      # Generate a random URL-safe base64 string.
+      #
+      # The argument *n* specifies the length, in bytes, of the random number to be
+      # generated. The length of the result string is about 4/3 of *n*.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The boolean argument *padding* specifies the padding. If it is false or nil,
+      # padding is not generated. Otherwise padding is generated. By default, padding
+      # is not generated because "=" may be used as a URL delimiter.
+      #
+      # The result may contain A-Z, a-z, 0-9, "-" and "_". "=" is also used if
+      # *padding* is true.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.urlsafe_base64 #=> "b4GOKm4pOYU_-BOXcrUGDg"
+      #     # or
+      #     prng = Random.new
+      #     prng.urlsafe_base64 #=> "UZLdOkzop70Ddx-IJR0ABg"
+      #
+      #     prng.urlsafe_base64(nil, true) #=> "i0XQ-7gglIsHGV2_BNPrdQ=="
+      #     prng.urlsafe_base64(nil, true) #=> "-M8rLhr7JEpJlqFGUMmOxg=="
+      #
+      # See RFC 3548 for the definition of URL-safe base64.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#urlsafe_base64}
+      def urlsafe_base64: (?Integer? n, ?boolish padding) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid()
+      # -->
+      # Generate a random v4 UUID (Universally Unique IDentifier).
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.uuid #=> "2d931510-d99f-494a-8c67-87feb05e1594"
+      #     Random.uuid #=> "bad85eb9-0713-4da7-8d36-07a8e4b00eab"
+      #     # or
+      #     prng = Random.new
+      #     prng.uuid #=> "62936e70-1815-439b-bf89-8492855a7e6b"
+      #
+      # The version 4 UUID is purely random (except the version). It doesn't contain
+      # meaningful information such as MAC addresses, timestamps, etc.
+      #
+      # The result contains 122 random bits (15.25 random bytes).
+      #
+      # See [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) for details of UUIDv4.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid}
+      def uuid: () -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid_v4()
+      # -->
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid_v4}
+      alias uuid_v4 uuid
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - uuid_v7(extra_timestamp_bits: 0)
+      # -->
+      # Generate a random v7 UUID (Universally Unique IDentifier).
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.uuid_v7 # => "0188d4c3-1311-7f96-85c7-242a7aa58f1e"
+      #     Random.uuid_v7 # => "0188d4c3-16fe-744f-86af-38fa04c62bb5"
+      #     Random.uuid_v7 # => "0188d4c3-1af8-764f-b049-c204ce0afa23"
+      #     Random.uuid_v7 # => "0188d4c3-1e74-7085-b14f-ef6415dc6f31"
+      #     #                    |<--sorted-->| |<----- random ---->|
+      #
+      #     # or
+      #     prng = Random.new
+      #     prng.uuid_v7 # => "0188ca51-5e72-7950-a11d-def7ff977c98"
+      #
+      # The version 7 UUID starts with the least significant 48 bits of a 64 bit Unix
+      # timestamp (milliseconds since the epoch) and fills the remaining bits with
+      # random data, excluding the version and variant bits.
+      #
+      # This allows version 7 UUIDs to be sorted by creation time.  Time ordered UUIDs
+      # can be used for better database index locality of newly inserted records,
+      # which may have a significant performance benefit compared to random data
+      # inserts.
+      #
+      # The result contains 74 random bits (9.25 random bytes).
+      #
+      # Note that this method cannot be made reproducible because its output includes
+      # not only random bits but also timestamp.
+      #
+      # See [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) for details of UUIDv7.
+      #
+      # #### Monotonicity
+      #
+      # UUIDv7 has millisecond precision by default, so multiple UUIDs created within
+      # the same millisecond are not issued in monotonically increasing order.  To
+      # create UUIDs that are time-ordered with sub-millisecond precision, up to 12
+      # bits of additional timestamp may added with `extra_timestamp_bits`.  The extra
+      # timestamp precision comes at the expense of random bits.  Setting
+      # <code>extra_timestamp_bits: 12</code> provides ~244ns of precision, but only
+      # 62 random bits (7.75 random bytes).
+      #
+      #     prng = Random.new
+      #     Array.new(4) { prng.uuid_v7(extra_timestamp_bits: 12) }
+      #     # =>
+      #     ["0188d4c7-13da-74f9-8b53-22a786ffdd5a",
+      #      "0188d4c7-13da-753b-83a5-7fb9b2afaeea",
+      #      "0188d4c7-13da-754a-88ea-ac0baeedd8db",
+      #      "0188d4c7-13da-7557-83e1-7cad9cda0d8d"]
+      #     # |<--- sorted --->| |<-- random --->|
+      #
+      #     Array.new(4) { prng.uuid_v7(extra_timestamp_bits: 8) }
+      #     # =>
+      #     ["0188d4c7-3333-7a95-850a-de6edb858f7e",
+      #      "0188d4c7-3333-7ae8-842e-bc3a8b7d0cf9",  # <- out of order
+      #      "0188d4c7-3333-7ae2-995a-9f135dc44ead",  # <- out of order
+      #      "0188d4c7-3333-7af9-87c3-8f612edac82e"]
+      #     # |<--- sorted -->||<---- random --->|
+      #
+      # Any rollbacks of the system clock will break monotonicity.  UUIDv7 is based on
+      # UTC, which excludes leap seconds and can rollback the clock.  To avoid this,
+      # the system clock can synchronize with an NTP server configured to use a "leap
+      # smear" approach.  NTP or PTP will also be needed to synchronize across
+      # distributed nodes.
+      #
+      # Counters and other mechanisms for stronger guarantees of monotonicity are not
+      # implemented.  Applications with stricter requirements should follow [Section
+      # 6.2](https://www.rfc-editor.org/rfc/rfc9562.html#name-monotonicity-and-counter
+      # s) of the specification.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#uuid_v7}
+      def uuid_v7: (?extra_timestamp_bits: Integer) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - alphanumeric(n = nil, chars: ALPHANUMERIC)
+      # -->
+      # Generate a random alphanumeric string.
+      #
+      # The argument *n* specifies the length, in characters, of the alphanumeric
+      # string to be generated. The argument *chars* specifies the character list
+      # which the result is consist of.
+      #
+      # If *n* is not specified or is nil, 16 is assumed. It may be larger in the
+      # future.
+      #
+      # The result may contain A-Z, a-z and 0-9, unless *chars* is specified.
+      #
+      #     require 'random/formatter'
+      #
+      #     Random.alphanumeric     #=> "2BuBuLf3WfSKyQbR"
+      #     # or
+      #     prng = Random.new
+      #     prng.alphanumeric(10) #=> "i6K93NdqiH"
+      #
+      #     Random.alphanumeric(4, chars: [*"0".."9"]) #=> "2952"
+      #     # or
+      #     prng = Random.new
+      #     prng.alphanumeric(10, chars: [*"!".."/"]) #=> ",.,++%/''."
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#alphanumeric}
+      def alphanumeric: (?Numeric?, ?chars: Array[String]) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - gen_random(n)
+      # -->
+      # Internal interface to Random; Generate random data *n* bytes.
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#gen_random}
+      private def gen_random: (Integer n) -> String
+
+      # <!--
+      #   rdoc-file=lib/random/formatter.rb
+      #   - choose(source, n)
+      # -->
+      # Generate a string that randomly draws from a source array of characters.
+      #
+      # The argument *source* specifies the array of characters from which to generate
+      # the string. The argument *n* specifies the length, in characters, of the
+      # string to be generated.
+      #
+      # The result may contain whatever characters are in the source array.
+      #
+      #     require 'random/formatter'
+      #
+      #     prng.choose([*'l'..'r'], 16) #=> "lmrqpoonmmlqlron"
+      #     prng.choose([*'0'..'9'], 5)  #=> "27309"
+      #
+      %a{annotate:rdoc:copy:Random::Formatter#choose}
+      private def choose: (Array[String] source, Integer n) -> String
+    end
+  end
+end

data/stdlib/rdoc/0/code_object.rbs

@@ -22,15 +22,16 @@ module RDoc
   #         *   RDoc::MetaMethod
   # *   RDoc::Alias
   # *   RDoc::Constant
+  # *   RDoc::Require
   # *   RDoc::Mixin
-  #     *   RDoc::Require
   #     *   RDoc::Include
+  #     *   RDoc::Extend
   #
   class CodeObject
     # <!-- rdoc-file=lib/rdoc/code_object.rb -->
     # Our comment
     #
-    attr_reader comment: Markup::Document | Comment | String
+    attr_reader comment: Comment | String
 
     # <!--
     #   rdoc-file=lib/rdoc/code_object.rb
@@ -46,6 +47,6 @@ module RDoc
     # -->
     # Replaces our comment with `comment`, unless it is empty.
     #
-    def comment=: (Markup::Document | Comment | String | nil) -> (Markup::Document | Comment | String)
+    def comment=: (Comment | String | nil) -> (Comment | String | nil)
   end
 end

data/stdlib/rdoc/0/comment.rbs

@@ -20,6 +20,8 @@ module RDoc
     #
     attr_accessor location: String
 
+    alias file location
+
     # <!--
     #   rdoc-file=lib/rdoc/comment.rb
     #   - new(text = nil, location = nil, language = nil)

data/stdlib/rdoc/0/options.rbs

@@ -0,0 +1,76 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/options.rb -->
+  # RDoc::Options handles the parsing and storage of options
+  #
+  # ## Saved Options
+  #
+  # You can save some options like the markup format in the `.rdoc_options` file
+  # in your gem.  The easiest way to do this is:
+  #
+  #     rdoc --markup tomdoc --write-options
+  #
+  # Which will automatically create the file and fill it with the options you
+  # specified.
+  #
+  # The following options will not be saved since they interfere with the user's
+  # preferences or with the normal operation of RDoc:
+  #
+  # *   `--coverage-report`
+  # *   `--dry-run`
+  # *   `--encoding`
+  # *   `--force-update`
+  # *   `--format`
+  # *   `--pipe`
+  # *   `--quiet`
+  # *   `--template`
+  # *   `--verbose`
+  #
+  # ## Custom Options
+  #
+  # Generators can hook into RDoc::Options to add generator-specific command line
+  # options.
+  #
+  # When `--format` is encountered in ARGV, RDoc calls ::setup_options on the
+  # generator class to add extra options to the option parser.  Options for custom
+  # generators must occur after `--format`.  `rdoc --help` will list options for
+  # all installed generators.
+  #
+  # Example:
+  #
+  #     class RDoc::Generator::Spellcheck
+  #       RDoc::RDoc.add_generator self
+  #
+  #       def self.setup_options rdoc_options
+  #         op = rdoc_options.option_parser
+  #
+  #         op.on('--spell-dictionary DICTIONARY',
+  #               RDoc::Options::Path) do |dictionary|
+  #           rdoc_options.spell_dictionary = dictionary
+  #         end
+  #       end
+  #     end
+  #
+  # Of course, RDoc::Options does not respond to `spell_dictionary` by default so
+  # you will need to add it:
+  #
+  #     class RDoc::Options
+  #
+  #       ##
+  #       # The spell dictionary used by the spell-checking plugin.
+  #
+  #       attr_accessor :spell_dictionary
+  #
+  #     end
+  #
+  # ## Option Validators
+  #
+  # OptionParser validators will validate and cast user input values.  In addition
+  # to the validators that ship with OptionParser (String, Integer, Float,
+  # TrueClass, FalseClass, Array, Regexp, Date, Time, URI, etc.), RDoc::Options
+  # adds Path, PathArray and Template.
+  #
+  class Options
+    def initialize: (?untyped loaded_options) -> void
+  end
+end

data/stdlib/rdoc/0/parser.rbs

@@ -42,7 +42,7 @@ module RDoc
 
     # <!--
     #   rdoc-file=lib/rdoc/parser.rb
-    #   - new(top_level, file_name, content, options, stats)
+    #   - new(top_level, content, options, stats)
     # -->
     # Creates a new Parser storing `top_level`, `file_name`, `content`, `options`
     # and `stats` in instance variables.  In +@preprocess+ an

data/stdlib/rdoc/0/rdoc.rbs

@@ -84,7 +84,7 @@ module RDoc
     # -->
     # Starts collecting tokens
     #
-    def collect_tokens: () -> void
+    def collect_tokens: (Symbol) -> void
 
     # <!--
     #   rdoc-file=lib/rdoc/token_stream.rb
@@ -190,7 +190,7 @@ module RDoc
     #
     # Usually this is called by super from a subclass.
     #
-    def initialize: (String text, String name) -> void
+    def initialize: (String text, String name, ?singleton: bool) -> void
 
     # <!--
     #   rdoc-file=lib/rdoc/method_attr.rb
@@ -267,7 +267,7 @@ module RDoc
     # -->
     # Creates a new AnyMethod with a token stream `text` and `name`
     #
-    def initialize: (String? text, String name) -> void
+    def initialize: (String? text, String name, ?singleton: bool) -> void
   end
 
   # <!-- rdoc-file=lib/rdoc/attr.rb -->
@@ -286,7 +286,7 @@ module RDoc
     # Creates a new Attr with body `text`, `name`, read/write status `rw` and
     # `comment`.  `singleton` marks this as a class attribute.
     #
-    def initialize: (String? text, String name, String rw, RDoc::Comment? comment, ?bool `singleton`) -> void
+    def initialize: (String? text, String name, String rw, RDoc::Comment? comment, ?singleton: bool) -> void
   end
 
   # <!-- rdoc-file=lib/rdoc/constant.rb -->
@@ -372,6 +372,8 @@ module RDoc
     #
     attr_accessor old_name: String
 
+    attr_reader singleton: bool
+
     # <!--
     #   rdoc-file=lib/rdoc/alias.rb
     #   - new(text, old_name, new_name, comment, singleton = false)
@@ -379,7 +381,7 @@ module RDoc
     # Creates a new Alias with a token stream of `text` that aliases `old_name` to
     # `new_name`, has `comment` and is a `singleton` context.
     #
-    def initialize: (String? text, String name, String old_name, RDoc::Comment? comment, ?bool `singleton`) -> void
+    def initialize: (String? text, String name, String old_name, RDoc::Comment? comment, ?singleton: bool) -> void
   end
 
   # <!-- rdoc-file=lib/rdoc/stats.rb -->

data/stdlib/rdoc/0/store.rbs

@@ -22,11 +22,11 @@ module RDoc
   class Store
     # <!--
     #   rdoc-file=lib/rdoc/store.rb
-    #   - new(path = nil, type = nil)
+    #   - new(options, path: nil, type: nil)
     # -->
     # Creates a new Store of `type` that will load or save to `path`
     #
-    def initialize: (?String? path, ?Symbol? type) -> void
+    def initialize: (Options, ?path: String? , ?type: Symbol?) -> void
 
     # <!--
     #   rdoc-file=lib/rdoc/store.rb