rbs 3.7.0 → 3.8.0.pre.1

data/core/rbs/unnamed/argf.rbs

@@ -1,45 +1,248 @@
 module RBS
   module Unnamed
     # <!-- rdoc-file=io.c -->
-    # ARGF is a stream designed for use in scripts that process files given as
-    # command-line arguments or passed in via STDIN.
+    # ## ARGF and `ARGV`
     #
-    # The arguments passed to your script are stored in the `ARGV` Array, one
-    # argument per element. ARGF assumes that any arguments that aren't filenames
-    # have been removed from `ARGV`. For example:
+    # The ARGF object works with the array at global variable `ARGV` to make
+    # `$stdin` and file streams available in the Ruby program:
     #
-    #     $ ruby argf.rb --verbose file1 file2
+    # *   **ARGV** may be thought of as the **argument vector** array.
     #
-    #     ARGV  #=> ["--verbose", "file1", "file2"]
-    #     option = ARGV.shift #=> "--verbose"
-    #     ARGV  #=> ["file1", "file2"]
+    #     Initially, it contains the command-line arguments and options that are
+    #     passed to the Ruby program; the program can modify that array as it likes.
     #
-    # You can now use ARGF to work with a concatenation of each of these named
-    # files. For instance, ARGF.read will return the contents of *file1* followed by
-    # the contents of *file2*.
+    # *   **ARGF** may be thought of as the **argument files** object.
     #
-    # After a file in `ARGV` has been read ARGF removes it from the Array. Thus,
-    # after all files have been read `ARGV` will be empty.
+    #     It can access file streams and/or the `$stdin` stream, based on what it
+    #     finds in `ARGV`. This provides a convenient way for the command line to
+    #     specify streams for a Ruby program to read.
     #
-    # You can manipulate `ARGV` yourself to control what ARGF operates on. If you
-    # remove a file from `ARGV`, it is ignored by ARGF; if you add files to `ARGV`,
-    # they are treated as if they were named on the command line. For example:
+    # ## Reading
     #
-    #     ARGV.replace ["file1"]
-    #     ARGF.readlines # Returns the contents of file1 as an Array
-    #     ARGV           #=> []
-    #     ARGV.replace ["file2", "file3"]
-    #     ARGF.read      # Returns the contents of file2 and file3
+    # ARGF may read from *source* streams, which at any particular time are
+    # determined by the content of `ARGV`.
     #
-    # If `ARGV` is empty, ARGF acts as if it contained `"-"` that makes ARGF read
-    # from STDIN, i.e. the data piped or typed to your script. For example:
+    # ### Simplest Case
     #
-    #     $ echo "glark" | ruby -e 'p ARGF.read'
-    #     "glark\n"
+    # When the *very first* ARGF read occurs with an empty `ARGV` (`[]`), the source
+    # is `$stdin`:
     #
-    #     $ echo Glark > file1
-    #     $ echo "glark" | ruby -e 'p ARGF.read' -- - file1
-    #     "glark\nGlark\n"
+    # *   File `t.rb`:
+    #
+    #         p ['ARGV', ARGV]
+    #         p ['ARGF.read', ARGF.read]
+    #
+    # *   Commands and outputs (see below for the content of files `foo.txt` and
+    #     `bar.txt`):
+    #
+    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb
+    #         ["ARGV", []]
+    #         ["ARGF.read", "Open the pod bay doors, Hal.\n"]
+    #
+    #         $ cat foo.txt bar.txt | ruby t.rb
+    #         ["ARGV", []]
+    #         ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
+    #
+    # ### About the Examples
+    #
+    # Many examples here assume the existence of files `foo.txt` and `bar.txt`:
+    #
+    #     $ cat foo.txt
+    #     Foo 0
+    #     Foo 1
+    #     $ cat bar.txt
+    #     Bar 0
+    #     Bar 1
+    #     Bar 2
+    #     Bar 3
+    #
+    # ### Sources in `ARGV`
+    #
+    # For any ARGF read *except* the [simplest case](rdoc-ref:ARGF@Simplest+Case)
+    # (that is, *except* for the *very first* ARGF read with an empty `ARGV`), the
+    # sources are found in `ARGV`.
+    #
+    # ARGF assumes that each element in array `ARGV` is a potential source, and is
+    # one of:
+    #
+    # *   The string path to a file that may be opened as a stream.
+    # *   The character `'-'`, meaning stream `$stdin`.
+    #
+    # Each element that is *not* one of these should be removed from `ARGV` before
+    # ARGF accesses that source.
+    #
+    # In the following example:
+    #
+    # *   Filepaths `foo.txt` and `bar.txt` may be retained as potential sources.
+    # *   Options `--xyzzy` and `--mojo` should be removed.
+    #
+    # Example:
+    #
+    # *   File `t.rb`:
+    #
+    #         # Print arguments (and options, if any) found on command line.
+    #         p ['ARGV', ARGV]
+    #
+    # *   Command and output:
+    #
+    #         $ ruby t.rb --xyzzy --mojo foo.txt bar.txt
+    #         ["ARGV", ["--xyzzy", "--mojo", "foo.txt", "bar.txt"]]
+    #
+    # ARGF's stream access considers the elements of `ARGV`, left to right:
+    #
+    # *   File `t.rb`:
+    #
+    #         p "ARGV: #{ARGV}"
+    #         p "Line: #{ARGF.read}" # Read everything from all specified streams.
+    #
+    # *   Command and output:
+    #
+    #         $ ruby t.rb foo.txt bar.txt
+    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
+    #         "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
+    #
+    # Because the value at `ARGV` is an ordinary array, you can manipulate it to
+    # control which sources ARGF considers:
+    #
+    # *   If you remove an element from `ARGV`, ARGF will not consider the
+    #     corresponding source.
+    # *   If you add an element to `ARGV`, ARGF will consider the corresponding
+    #     source.
+    #
+    # Each element in `ARGV` is removed when its corresponding source is accessed;
+    # when all sources have been accessed, the array is empty:
+    #
+    # *   File `t.rb`:
+    #
+    #         until ARGV.empty? && ARGF.eof?
+    #           p "ARGV: #{ARGV}"
+    #           p "Line: #{ARGF.readline}" # Read each line from each specified stream.
+    #         end
+    #
+    # *   Command and output:
+    #
+    #         $ ruby t.rb foo.txt bar.txt
+    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
+    #         "Line: Foo 0\n"
+    #         "ARGV: [\"bar.txt\"]"
+    #         "Line: Foo 1\n"
+    #         "ARGV: [\"bar.txt\"]"
+    #         "Line: Bar 0\n"
+    #         "ARGV: []"
+    #         "Line: Bar 1\n"
+    #         "ARGV: []"
+    #         "Line: Bar 2\n"
+    #         "ARGV: []"
+    #         "Line: Bar 3\n"
+    #
+    # #### Filepaths in `ARGV`
+    #
+    # The `ARGV` array may contain filepaths the specify sources for ARGF reading.
+    #
+    # This program prints what it reads from files at the paths specified on the
+    # command line:
+    #
+    # *   File `t.rb`:
+    #
+    #         p ['ARGV', ARGV]
+    #         # Read and print all content from the specified sources.
+    #         p ['ARGF.read', ARGF.read]
+    #
+    # *   Command and output:
+    #
+    #         $ ruby t.rb foo.txt bar.txt
+    #         ["ARGV", [foo.txt, bar.txt]
+    #         ["ARGF.read", "Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"]
+    #
+    # #### Specifying `$stdin` in `ARGV`
+    #
+    # To specify stream `$stdin` in `ARGV`, us the character `'-'`:
+    #
+    # *   File `t.rb`:
+    #
+    #         p ['ARGV', ARGV]
+    #         p ['ARGF.read', ARGF.read]
+    #
+    # *   Command and output:
+    #
+    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb -
+    #         ["ARGV", ["-"]]
+    #         ["ARGF.read", "Open the pod bay doors, Hal.\n"]
+    #
+    # When no character `'-'` is given, stream `$stdin` is ignored (exception: see
+    # [Specifying $stdin in ARGV](rdoc-ref:ARGF@Specifying+-24stdin+in+ARGV)):
+    #
+    # *   Command and output:
+    #
+    #         $ echo "Open the pod bay doors, Hal." | ruby t.rb foo.txt bar.txt
+    #         "ARGV: [\"foo.txt\", \"bar.txt\"]"
+    #         "Read: Foo 0\nFoo 1\nBar 0\nBar 1\nBar 2\nBar 3\n"
+    #
+    # #### Mixtures and Repetitions in `ARGV`
+    #
+    # For an ARGF reader, `ARGV` may contain any mixture of filepaths and character
+    # `'-'`, including repetitions.
+    #
+    # #### Modifications to `ARGV`
+    #
+    # The running Ruby program may make any modifications to the `ARGV` array; the
+    # current value of `ARGV` affects ARGF reading.
+    #
+    # #### Empty `ARGV`
+    #
+    # For an empty `ARGV`, an ARGF read method either returns `nil` or raises an
+    # exception, depending on the specific method.
+    #
+    # ### More Read Methods
+    #
+    # As seen above, method ARGF#read reads the content of all sources into a single
+    # string. Other ARGF methods provide other ways to access that content; these
+    # include:
+    #
+    # *   Byte access: #each_byte, #getbyte, #readbyte.
+    # *   Character access: #each_char, #getc, #readchar.
+    # *   Codepoint access: #each_codepoint.
+    # *   Line access: #each_line, #gets, #readline, #readlines.
+    # *   Source access: #read, #read_nonblock, #readpartial.
+    #
+    # ### About Enumerable
+    #
+    # ARGF includes module Enumerable. Virtually all methods in Enumerable call
+    # method `#each` in the including class.
+    #
+    # **Note well**: In ARGF, method #each returns data from the *sources*, *not*
+    # from `ARGV`; therefore, for example, `ARGF#entries` returns an array of lines
+    # from the sources, not an array of the strings from `ARGV`:
+    #
+    # *   File `t.rb`:
+    #
+    #         p ['ARGV', ARGV]
+    #         p ['ARGF.entries', ARGF.entries]
+    #
+    # *   Command and output:
+    #
+    #         $ ruby t.rb foo.txt bar.txt
+    #         ["ARGV", ["foo.txt", "bar.txt"]]
+    #         ["ARGF.entries", ["Foo 0\n", "Foo 1\n", "Bar 0\n", "Bar 1\n", "Bar 2\n", "Bar 3\n"]]
+    #
+    # ## Writing
+    #
+    # If *inplace mode* is in effect, ARGF may write to target streams, which at any
+    # particular time are determined by the content of ARGV.
+    #
+    # Methods about inplace mode:
+    #
+    # *   #inplace_mode
+    # *   #inplace_mode=
+    # *   #to_write_io
+    #
+    # Methods for writing:
+    #
+    # *   #print
+    # *   #printf
+    # *   #putc
+    # *   #puts
+    # *   #write
     #
     %a{annotate:rdoc:copy:ARGF}
     class ARGFClass
@@ -585,7 +788,6 @@ module RBS
       # *   If not the last object, writes the output field separator
       #     `$OUTPUT_FIELD_SEPARATOR` (`$,`) if it is not `nil`.
       #
-      #
       # With default separators:
       #
       #     f = File.open('t.tmp', 'w+')
@@ -678,7 +880,6 @@ module RBS
       # *   Neither string nor array: writes `object.to_s`.
       # *   Array: writes each element of the array; arrays may be nested.
       #
-      #
       # To keep these examples brief, we define this helper method:
       #
       #     def show(*objects)
@@ -1009,9 +1210,9 @@ module RBS
 
       # <!--
       #   rdoc-file=io.c
-      #   - ARGF.write(string)   -> integer
+      #   - ARGF.write(*objects)  -> integer
       # -->
-      # Writes *string* if inplace mode.
+      # Writes each of the given `objects` if inplace mode.
       #
       %a{annotate:rdoc:copy:ARGF#write}
       def write: (_ToS string) -> Integer

data/core/rbs/unnamed/env_class.rbs

@@ -1,20 +1,19 @@
 module RBS
   module Unnamed
     # <!-- rdoc-file=hash.c -->
-    # ENV is a hash-like accessor for environment variables.
+    # `ENV` is a hash-like accessor for environment variables.
     #
     # ### Interaction with the Operating System
     #
-    # The ENV object interacts with the operating system's environment variables:
+    # The `ENV` object interacts with the operating system's environment variables:
     #
-    # *   When you get the value for a name in ENV, the value is retrieved from
+    # *   When you get the value for a name in `ENV`, the value is retrieved from
     #     among the current environment variables.
-    # *   When you create or set a name-value pair in ENV, the name and value are
+    # *   When you create or set a name-value pair in `ENV`, the name and value are
     #     immediately set in the environment variables.
-    # *   When you delete a name-value pair in ENV, it is immediately deleted from
+    # *   When you delete a name-value pair in `ENV`, it is immediately deleted from
     #     the environment variables.
     #
-    #
     # ### Names and Values
     #
     # Generally, a name or value is a String.
@@ -27,7 +26,6 @@ module RBS
     # *   An object that responds to #to_str by returning a String, in which case
     #     that String will be used as the name or value.
     #
-    #
     # #### Invalid Names and Values
     #
     # A new name:
@@ -40,7 +38,6 @@ module RBS
     #         ENV['='] = '0'
     #         # Raises Errno::EINVAL (Invalid argument - ruby_setenv(=))
     #
-    #
     # A new name or value:
     #
     # *   May not be a non-String that does not respond to #to_str:
@@ -65,39 +62,36 @@ module RBS
     #         ENV["foo".force_encoding(Encoding::ISO_2022_JP)] = '0'
     #         # Raises ArgumentError (bad environment variable name: ASCII incompatible encoding: ISO-2022-JP)
     #
-    #
     # ### About Ordering
     #
-    # ENV enumerates its name/value pairs in the order found in the operating
-    # system's environment variables. Therefore the ordering of ENV content is
+    # `ENV` enumerates its name/value pairs in the order found in the operating
+    # system's environment variables. Therefore the ordering of `ENV` content is
     # OS-dependent, and may be indeterminate.
     #
     # This will be seen in:
-    # *   A Hash returned by an ENV method.
-    # *   An Enumerator returned by an ENV method.
+    # *   A Hash returned by an `ENV` method.
+    # *   An Enumerator returned by an `ENV` method.
     # *   An Array returned by ENV.keys, ENV.values, or ENV.to_a.
     # *   The String returned by ENV.inspect.
     # *   The Array returned by ENV.shift.
     # *   The name returned by ENV.key.
     #
-    #
     # ### About the Examples
-    # Some methods in ENV return ENV itself. Typically, there are many environment
-    # variables. It's not useful to display a large ENV in the examples here, so
-    # most example snippets begin by resetting the contents of ENV:
-    # *   ENV.replace replaces ENV with a new collection of entries.
-    # *   ENV.clear empties ENV.
+    # Some methods in `ENV` return `ENV` itself. Typically, there are many
+    # environment variables. It's not useful to display a large `ENV` in the
+    # examples here, so most example snippets begin by resetting the contents of
+    # `ENV`:
+    # *   ENV.replace replaces `ENV` with a new collection of entries.
+    # *   ENV.clear empties `ENV`.
     #
+    # ### What's Here
     #
-    # ## What's Here
-    #
-    # First, what's elsewhere. Class ENV:
+    # First, what's elsewhere. Class `ENV`:
     #
     # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
     # *   Extends [module Enumerable](rdoc-ref:Enumerable@What-27s+Here),
     #
-    #
-    # Here, class ENV provides methods that are useful for:
+    # Here, class `ENV` provides methods that are useful for:
     #
     # *   [Querying](rdoc-ref:ENV@Methods+for+Querying)
     # *   [Assigning](rdoc-ref:ENV@Methods+for+Assigning)
@@ -106,31 +100,28 @@ module RBS
     # *   [Converting](rdoc-ref:ENV@Methods+for+Converting)
     # *   [And more ....](rdoc-ref:ENV@More+Methods)
     #
-    #
-    # ### Methods for Querying
+    # #### Methods for Querying
     #
     # *   ::[]: Returns the value for the given environment variable name if it
     #     exists:
-    # *   ::empty?: Returns whether ENV is empty.
-    # *   ::has_value?, ::value?: Returns whether the given value is in ENV.
+    # *   ::empty?: Returns whether `ENV` is empty.
+    # *   ::has_value?, ::value?: Returns whether the given value is in `ENV`.
     # *   ::include?, ::has_key?, ::key?, ::member?: Returns whether the given name
-    #     is in ENV.
+    #     is in `ENV`.
     # *   ::key: Returns the name of the first entry with the given value.
     # *   ::size, ::length: Returns the number of entries.
     # *   ::value?: Returns whether any entry has the given value.
     #
-    #
-    # ### Methods for Assigning
+    # #### Methods for Assigning
     #
     # *   ::[]=, ::store: Creates, updates, or deletes the named environment
     #     variable.
-    # *   ::clear: Removes every environment variable; returns ENV:
-    # *   ::update, ::merge!: Adds to ENV each key/value pair in the given hash.
-    # *   ::replace: Replaces the entire content of the ENV with the name/value
+    # *   ::clear: Removes every environment variable; returns `ENV`:
+    # *   ::update, ::merge!: Adds to `ENV` each key/value pair in the given hash.
+    # *   ::replace: Replaces the entire content of the `ENV` with the name/value
     #     pairs in the given hash.
     #
-    #
-    # ### Methods for Deleting
+    # #### Methods for Deleting
     #
     # *   ::delete: Deletes the named environment variable name if it exists.
     # *   ::delete_if: Deletes entries selected by the block.
@@ -139,24 +130,22 @@ module RBS
     # *   ::select!, ::filter!: Deletes entries selected by the block.
     # *   ::shift: Removes and returns the first entry.
     #
-    #
-    # ### Methods for Iterating
+    # #### Methods for Iterating
     #
     # *   ::each, ::each_pair: Calls the block with each name/value pair.
     # *   ::each_key: Calls the block with each name.
     # *   ::each_value: Calls the block with each value.
     #
-    #
-    # ### Methods for Converting
+    # #### Methods for Converting
     #
     # *   ::assoc: Returns a 2-element array containing the name and value of the
     #     named environment variable if it exists:
-    # *   ::clone: Returns ENV (and issues a warning).
+    # *   ::clone: Returns `ENV` (and issues a warning).
     # *   ::except: Returns a hash of all name/value pairs except those given.
     # *   ::fetch: Returns the value for the given name.
-    # *   ::inspect: Returns the contents of ENV as a string.
-    # *   ::invert: Returns a hash whose keys are the ENV values, and whose values
-    #     are the corresponding ENV names.
+    # *   ::inspect: Returns the contents of `ENV` as a string.
+    # *   ::invert: Returns a hash whose keys are the `ENV` values, and whose values
+    #     are the corresponding `ENV` names.
     # *   ::keys: Returns an array of all names.
     # *   ::rassoc: Returns the name and value of the first found entry that has the
     #     given value.
@@ -171,12 +160,11 @@ module RBS
     # *   ::values: Returns all values as an array.
     # *   ::values_at: Returns an array of the values for the given name.
     #
-    #
-    # ### More Methods
+    # #### More Methods
     #
     # *   ::dup: Raises an exception.
     # *   ::freeze: Raises an exception.
-    # *   ::rehash: Returns `nil`, without modifying ENV.
+    # *   ::rehash: Returns `nil`, without modifying `ENV`.
     #
     %a{annotate:rdoc:copy:ENV}
     class ENVClass
@@ -260,7 +248,6 @@ module RBS
       #             ENV.store('bar', '1') # => '1'
       #             ENV['bar'] # => '1'
       #
-      #
       # *   If the named environment variable exists:
       #     *   If `value` is not `nil`, updates the environment variable with value
       #         `value`:
@@ -279,8 +266,6 @@ module RBS
       #             ENV.store('bar', nil) # => nil
       #             ENV.include?('bar') # => false
       #
-      #
-      #
       # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
       # Values](rdoc-ref:ENV@Invalid+Names+and+Values).
       #
@@ -313,7 +298,6 @@ module RBS
       #             ENV.store('bar', '1') # => '1'
       #             ENV['bar'] # => '1'
       #
-      #
       # *   If the named environment variable exists:
       #     *   If `value` is not `nil`, updates the environment variable with value
       #         `value`:
@@ -332,8 +316,6 @@ module RBS
       #             ENV.store('bar', nil) # => nil
       #             ENV.include?('bar') # => false
       #
-      #
-      #
       # Raises an exception if `name` or `value` is invalid. See [Invalid Names and
       # Values](rdoc-ref:ENV@Invalid+Names+and+Values).
       #

data/core/rbs/unnamed/random.rbs

@@ -284,8 +284,7 @@ module RBS
       #
       # The result contains 122 random bits (15.25 random bytes).
       #
-      # See [RFC4122](https://datatracker.ietf.org/doc/html/rfc4122) for details of
-      # UUID.
+      # See [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) for details of UUIDv4.
       #
       %a{annotate:rdoc:copy:Random::Formatter#uuid}
       def uuid: () -> String