rbs 3.3.2 → 3.4.0

data/core/io.rbs

@@ -110,7 +110,7 @@
 #
 #
 # Also available are the options offered in String#encode, which may control
-# conversion between external internal encoding.
+# conversion between external and internal encoding.
 #
 # ## Basic IO
 #
@@ -398,7 +398,7 @@
 #         # => 41
 #         f.close
 #
-# *   When a stream is read, `#.` is set to the line number for that stream:
+# *   When a stream is read, `$.` is set to the line number for that stream:
 #
 #         f0 = File.new('t.txt')
 #         f1 = File.new('t.dat')
@@ -684,14 +684,14 @@ class IO < Object
   # -->
   # Sets auto-close flag.
   #
-  #     f = open("/dev/null")
-  #     IO.for_fd(f.fileno)
-  #     # ...
-  #     f.gets # may cause Errno::EBADF
+  #     f = File.open(File::NULL)
+  #     IO.for_fd(f.fileno).close
+  #     f.gets # raises Errno::EBADF
   #
-  #     f = open("/dev/null")
-  #     IO.for_fd(f.fileno).autoclose = false
-  #     # ...
+  #     f = File.open(File::NULL)
+  #     g = IO.for_fd(f.fileno)
+  #     g.autoclose = false
+  #     g.close
   #     f.gets # won't cause Errno::EBADF
   #
   def autoclose=: (boolish bool) -> boolish
@@ -700,8 +700,8 @@ class IO < Object
   #   rdoc-file=io.c
   #   - ios.autoclose?   -> true or false
   # -->
-  # Returns `true` if the underlying file descriptor of *ios* will be closed
-  # automatically at its finalization, otherwise `false`.
+  # Returns `true` if the underlying file descriptor of *ios* will be closed at
+  # its finalization or at calling #close, otherwise `false`.
   #
   def autoclose?: () -> bool
 
@@ -764,7 +764,7 @@ class IO < Object
   # -->
   # Sets a close-on-exec flag.
   #
-  #     f = open("/dev/null")
+  #     f = File.open(File::NULL)
   #     f.close_on_exec = true
   #     system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory
   #     f.closed?                #=> false
@@ -976,8 +976,6 @@ class IO < Object
   # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
   # is not available for some streams).
   #
-  # IO#eof? is an alias for IO#eof.
-  #
   def eof: () -> bool
 
   # <!--
@@ -988,7 +986,7 @@ class IO < Object
   # provides a mechanism for issuing low-level commands to control or query a
   # file-oriented I/O stream. Arguments and results are platform dependent.
   #
-  # If +argument is a number, its value is passed directly; if it is a string, it
+  # If `argument` is a number, its value is passed directly; if it is a string, it
   # is interpreted as a binary sequence of bytes. (Array#pack might be a useful
   # way to build this string.)
   #
@@ -1018,8 +1016,6 @@ class IO < Object
   #     File.open('t.txt').fileno # => 10
   #     f.close
   #
-  # IO#to_i is an alias for IO#fileno.
-  #
   def fileno: () -> Integer
 
   # <!--
@@ -1160,7 +1156,8 @@ class IO < Object
   #     f.gets(chomp: true) # => nil
   #     f.close
   #
-  def gets: (?String sep, ?Integer limit) -> String?
+  def gets: (string? sep, ?int limit, ?chomp: boolish) -> String?
+          | (?int limit, ?chomp: boolish) -> String?
 
   # <!--
   #   rdoc-file=io.c
@@ -1256,8 +1253,6 @@ class IO < Object
   #     f = File.new('/dev/tty').isatty #=> true
   #     f.close
   #
-  # IO#tty? is an alias for IO#isatty.
-  #
   def isatty: () -> bool
 
   # <!--
@@ -1537,7 +1532,8 @@ class IO < Object
   #
   # Related: IO#write.
   #
-  def read: (?int? length, ?string outbuf) -> String?
+  def read: (?nil, ?string outbuf) -> String
+          | (int? length, ?string outbuf) -> String?
 
   # <!--
   #   rdoc-file=io.rb
@@ -1632,7 +1628,7 @@ class IO < Object
   def readchar: () -> String
 
   # <!--
-  #   rdoc-file=io.c
+  #   rdoc-file=io.rb
   #   - readline(sep = $/, chomp: false)   -> string
   #   - readline(limit, chomp: false)      -> string
   #   - readline(sep, limit, chomp: false) -> string
@@ -1915,16 +1911,19 @@ class IO < Object
   # -->
   # See [Encodings](rdoc-ref:File@Encodings).
   #
-  # Argument `ext_enc`, if given, must be an Encoding object; it is assigned as
-  # the encoding for the stream.
+  # Argument `ext_enc`, if given, must be an Encoding object or a String with the
+  # encoding name; it is assigned as the encoding for the stream.
   #
-  # Argument `int_enc`, if given, must be an Encoding object; it is assigned as
-  # the encoding for the internal string.
+  # Argument `int_enc`, if given, must be an Encoding object or a String with the
+  # encoding name; it is assigned as the encoding for the internal string.
   #
   # Argument `'ext_enc:int_enc'`, if given, is a string containing two
   # colon-separated encoding names; corresponding Encoding objects are assigned as
   # the external and internal encodings for the stream.
   #
+  # If the external encoding of a string is binary/ASCII-8BIT, the internal
+  # encoding of the string is set to nil, since no transcoding is needed.
+  #
   # Optional keyword arguments `enc_opts` specify [Encoding
   # options](rdoc-ref:encodings.rdoc@Encoding+Options).
   #
@@ -2066,8 +2065,6 @@ class IO < Object
   #
   # Related: IO#pos=, IO#seek.
   #
-  # IO#pos is an alias for IO#tell.
-  #
   def tell: () -> Integer
 
   # <!-- rdoc-file=io.c -->
@@ -2082,8 +2079,6 @@ class IO < Object
   #
   # Related: IO#pos=, IO#seek.
   #
-  # IO#pos is an alias for IO#tell.
-  #
   alias pos tell
 
   # <!--
@@ -2099,8 +2094,11 @@ class IO < Object
   #   - timeout = duration -> duration
   #   - timeout = nil -> nil
   # -->
-  # Set the internal timeout to the specified duration or nil. The timeout applies
-  # to all blocking operations where possible.
+  # Sets the internal timeout to the specified duration or nil. The timeout
+  # applies to all blocking operations where possible.
+  #
+  # When the operation performs longer than the timeout set, IO::TimeoutError is
+  # raised.
   #
   # This affects the following methods (but is not limited to): #gets, #puts,
   # #read, #write, #wait_readable and #wait_writable. This also affects blocking
@@ -2131,8 +2129,6 @@ class IO < Object
   #     f = File.new('/dev/tty').isatty #=> true
   #     f.close
   #
-  # IO#tty? is an alias for IO#isatty.
-  #
   alias tty? isatty
 
   # <!--
@@ -2298,7 +2294,6 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.binread(command, length = nil, offset = 0) -> string or nil
   #   - IO.binread(path, length = nil, offset = 0)    -> string or nil
   # -->
   # Behaves like IO.read, except that the stream is opened in binary mode with
@@ -2312,7 +2307,6 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.binwrite(command, string, offset = 0) -> integer
   #   - IO.binwrite(path, string, offset = 0)    -> integer
   # -->
   # Behaves like IO.write, except that the stream is opened in binary mode with
@@ -2540,19 +2534,25 @@ class IO < Object
   #
   # Raises exceptions that IO.pipe and Kernel.spawn raise.
   #
-  def self.popen: (string cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) -> instance
-                | (Hash[string, string?] env, string cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) -> instance
-                | [X] (string cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) { (instance) -> X } -> X
-                | [X] (Hash[string, string?] env, string cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) { (instance) -> X } -> X
+  def self.popen: (string | cmd_array cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) -> instance
+                | (Hash[string, string?] env, string | cmd_array cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) -> instance
+                | [X] (string | cmd_array cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) { (instance) -> X } -> X
+                | [X] (Hash[string, string?] env, string | cmd_array cmd, ?string | int mode, ?path: string?, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?unsetenv_others: boolish, ?pgroup: true | Integer, ?umask: Integer, ?in: Kernel::redirect_fd, ?out: Kernel::redirect_fd, ?err: Kernel::redirect_fd, ?close_others: boolish, ?chdir: String) { (instance) -> X } -> X
+
+  # The command can be given as:
+  #
+  # * Array of string `["ruby", "-v"]`, or
+  # * Array of string with the first element of array `[["ruby", "RUBY"], "-v"]`
+  #
+  # But RBS cannot define such a type. So this is simply a union of `string` or `[String, String]`.
+  #
+  type cmd_array = array[string | [String, String]]
 
   # <!--
   #   rdoc-file=io.c
   #   - IO.foreach(path, sep = $/, **opts) {|line| block }       -> nil
   #   - IO.foreach(path, limit, **opts) {|line| block }          -> nil
   #   - IO.foreach(path, sep, limit, **opts) {|line| block }     -> nil
-  #   - IO.foreach(command, sep = $/, **opts) {|line| block }    -> nil
-  #   - IO.foreach(command, limit, **opts) {|line| block }       -> nil
-  #   - IO.foreach(command, sep, limit, **opts) {|line| block }  -> nil
   #   - IO.foreach(...)                                          -> an_enumerator
   # -->
   # Calls the block with each successive line read from the stream.
@@ -2561,17 +2561,7 @@ class IO < Object
   # potential security vulnerabilities if called with untrusted input; see
   # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # The first argument must be a string that is one of the following:
-  #
-  # *   Path: if `self` is a subclass of IO (File, for example), or if the string
-  #     *does* *not* start with the pipe character (`'|'`), the string is the path
-  #     to a file.
-  # *   Command: if `self` is the class IO, and if the string starts with the pipe
-  #     character, the rest of the string is a command to be executed as a
-  #     subprocess. This usage has potential security vulnerabilities if called
-  #     with untrusted input; see [Command
-  #     Injection](rdoc-ref:command_injection.rdoc).
-  #
+  # The first argument must be a string that is the path to a file.
   #
   # With only argument `path` given, parses lines from the file at the given
   # `path`, as determined by the default line separator, and calls the block with
@@ -2631,7 +2621,7 @@ class IO < Object
   #
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
-  # *   [Line Options](rdoc-ref:IO@Line+Options).
+  # *   [Line Options](rdoc-ref:IO@Line+IO).
   #
   #
   # Returns an Enumerator if no block is given.
@@ -2644,9 +2634,9 @@ class IO < Object
   #   - IO.pipe(**opts) -> [read_io, write_io]
   #   - IO.pipe(enc, **opts) -> [read_io, write_io]
   #   - IO.pipe(ext_enc, int_enc, **opts) -> [read_io, write_io]
-  #   - IO.pipe(**opts) {|read_io, write_io] ...} -> object
-  #   - IO.pipe(enc, **opts) {|read_io, write_io] ...} -> object
-  #   - IO.pipe(ext_enc, int_enc, **opts) {|read_io, write_io] ...} -> object
+  #   - IO.pipe(**opts) {|read_io, write_io| ...} -> object
+  #   - IO.pipe(enc, **opts) {|read_io, write_io| ...} -> object
+  #   - IO.pipe(ext_enc, int_enc, **opts) {|read_io, write_io| ...} -> object
   # -->
   # Creates a pair of pipe endpoints, `read_io` and `write_io`, connected to each
   # other.
@@ -2722,7 +2712,6 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.read(command, length = nil, offset = 0, **opts) -> string or nil
   #   - IO.read(path, length = nil, offset = 0, **opts)    -> string or nil
   # -->
   # Opens the stream, reads and returns some or all of its content, and closes the
@@ -2732,19 +2721,7 @@ class IO < Object
   # potential security vulnerabilities if called with untrusted input; see
   # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # The first argument must be a string; its meaning depends on whether it starts
-  # with the pipe character (`'|'`):
-  #
-  # *   If so (and if `self` is IO), the rest of the string is a command to be
-  #     executed as a subprocess.
-  # *   Otherwise, the string is the path to a file.
-  #
-  #
-  # With only argument `command` given, executes the command in a shell, returns
-  # its entire $stdout:
-  #
-  #     IO.read('| cat t.txt')
-  #     # => "First line\nSecond line\n\nThird line\nFourth line\n"
+  # The first argument must be a string that is the path to a file.
   #
   # With only argument `path` given, reads in text mode and returns the entire
   # content of the file at the given path:
@@ -2756,8 +2733,6 @@ class IO < Object
   # when encountering certain special bytes. Consider using IO.binread if all
   # bytes in the file should be read.
   #
-  # For both forms, command and path, the remaining arguments are the same.
-  #
   # With argument `length`, returns `length` bytes if available:
   #
   #     IO.read('t.txt', 7) # => "First l"
@@ -2779,9 +2754,6 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.readlines(command, sep = $/, **opts)     -> array
-  #   - IO.readlines(command, limit, **opts)      -> array
-  #   - IO.readlines(command, sep, limit, **opts) -> array
   #   - IO.readlines(path, sep = $/, **opts)     -> array
   #   - IO.readlines(path, limit, **opts)      -> array
   #   - IO.readlines(path, sep, limit, **opts) -> array
@@ -2792,20 +2764,7 @@ class IO < Object
   # potential security vulnerabilities if called with untrusted input; see
   # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # The first argument must be a string; its meaning depends on whether it starts
-  # with the pipe character (`'|'`):
-  #
-  # *   If so (and if `self` is IO), the rest of the string is a command to be
-  #     executed as a subprocess.
-  # *   Otherwise, the string is the path to a file.
-  #
-  #
-  # With only argument `command` given, executes the command in a shell, parses
-  # its $stdout into lines, as determined by the default line separator, and
-  # returns those lines in an array:
-  #
-  #     IO.readlines('| cat t.txt')
-  #     # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
+  # The first argument must be a string that is the path to a file.
   #
   # With only argument `path` given, parses lines from the file at the given
   # `path`, as determined by the default line separator, and returns those lines
@@ -2814,8 +2773,6 @@ class IO < Object
   #     IO.readlines('t.txt')
   #     # => ["First line\n", "Second line\n", "\n", "Third line\n", "Fourth line\n"]
   #
-  # For both forms, command and path, the remaining arguments are the same.
-  #
   # With argument `sep` given, parses lines as determined by that line separator
   # (see [Line Separator](rdoc-ref:IO@Line+Separator)):
   #
@@ -2844,7 +2801,7 @@ class IO < Object
   #
   # *   [Open Options](rdoc-ref:IO@Open+Options).
   # *   [Encoding options](rdoc-ref:encodings.rdoc@Encoding+Options).
-  # *   [Line Options](rdoc-ref:IO@Line+Options).
+  # *   [Line Options](rdoc-ref:IO@Line+IO).
   #
   def self.readlines: (String | _ToPath name, ?String sep, ?Integer limit, ?external_encoding: String | Encoding | nil, ?internal_encoding: String | Encoding | nil, ?encoding: String | Encoding | nil, ?textmode: boolish, ?binmode: boolish, ?autoclose: boolish, ?mode: String, ?chomp: boolish) -> ::Array[String]
 
@@ -3022,7 +2979,6 @@ class IO < Object
 
   # <!--
   #   rdoc-file=io.c
-  #   - IO.write(command, data, **opts)             -> integer
   #   - IO.write(path, data, offset = 0, **opts)    -> integer
   # -->
   # Opens the stream, writes the given `data` to it, and closes the stream;
@@ -3032,25 +2988,10 @@ class IO < Object
   # potential security vulnerabilities if called with untrusted input; see
   # [Command Injection](rdoc-ref:command_injection.rdoc).
   #
-  # The first argument must be a string; its meaning depends on whether it starts
-  # with the pipe character (`'|'`):
-  #
-  # *   If so (and if `self` is IO), the rest of the string is a command to be
-  #     executed as a subprocess.
-  # *   Otherwise, the string is the path to a file.
+  # The first argument must be a string that is the path to a file.
   #
-  #
-  # With argument `command` given, executes the command in a shell, passes `data`
-  # through standard input, writes its output to $stdout, and returns the length
-  # of the given `data`:
-  #
-  #     IO.write('| cat', 'Hello World!') # => 12
-  #
-  # Output:
-  #
-  #     Hello World!
-  #
-  # With argument `path` given, writes the given `data` to the file at that path:
+  # With only argument `path` given, writes the given `data` to the file at that
+  # path:
   #
   #     IO.write('t.tmp', 'abc')    # => 3
   #     File.read('t.tmp')          # => "abc"
@@ -3200,8 +3141,6 @@ class IO < Object
   #
   # Returns an Enumerator if no block is given.
   #
-  # IO#each is an alias for IO#each_line.
-  #
   def each_line: (?String sep, ?Integer limit) { (String line) -> void } -> self
                | (?String sep, ?Integer limit) -> ::Enumerator[String, self]
 
@@ -3307,8 +3246,6 @@ class IO < Object
   #
   # Returns an Enumerator if no block is given.
   #
-  # IO#each is an alias for IO#each_line.
-  #
   alias each each_line
 
   # <!-- rdoc-file=io.c -->
@@ -3342,8 +3279,6 @@ class IO < Object
   # not behave as you intend with IO#eof?, unless you call IO#rewind first (which
   # is not available for some streams).
   #
-  # IO#eof? is an alias for IO#eof.
-  #
   alias eof? eof
 
   # <!-- rdoc-file=io.c -->
@@ -3355,8 +3290,6 @@ class IO < Object
   #     File.open('t.txt').fileno # => 10
   #     f.close
   #
-  # IO#to_i is an alias for IO#fileno.
-  #
   alias to_i fileno
 end