rbs 3.10.4 → 4.0.0

data/stdlib/objspace/0/objspace.rbs

@@ -2,7 +2,7 @@
 # The objspace library extends the ObjectSpace module and adds several methods
 # to get internal statistic information about object/memory management.
 #
-# You need to `require 'objspace'` to use this extension module.
+# You need to <code>require 'objspace'</code> to use this extension module.
 #
 # Generally, you **SHOULD** **NOT** use this library if you do not know about
 # the MRI implementation.  Mainly, this library is for (memory) profiler
@@ -126,29 +126,6 @@ module ObjectSpace
   #
   def self?.count_imemo_objects: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
 
-  # <!--
-  #   rdoc-file=ext/objspace/objspace.c
-  #   - ObjectSpace.count_nodes([result_hash]) -> hash
-  # -->
-  # Counts nodes for each node type.
-  #
-  # This method is only for MRI developers interested in performance and memory
-  # usage of Ruby programs.
-  #
-  # It returns a hash as:
-  #
-  #     {:NODE_METHOD=>2027, :NODE_FBODY=>1927, :NODE_CFUNC=>1798, ...}
-  #
-  # If the optional argument, result_hash, is given, it is overwritten and
-  # returned. This is intended to avoid probe effect.
-  #
-  # Note: The contents of the returned hash is implementation defined. It may be
-  # changed in future.
-  #
-  # This method is only expected to work with C Ruby.
-  #
-  def self?.count_nodes: (?Hash[Symbol, Integer] result_hash) -> Hash[Symbol, Integer]
-
   # <!--
   #   rdoc-file=ext/objspace/objspace.c
   #   - ObjectSpace.count_objects_size([result_hash]) -> hash
@@ -237,12 +214,13 @@ module ObjectSpace
   # -->
   # Dump the contents of a ruby object as JSON.
   #
-  # *output* can be one of: `:stdout`, `:file`, `:string`, or IO object.
+  # *output* can be one of: <code>:stdout</code>, <code>:file</code>,
+  # <code>:string</code>, or IO object.
   #
-  # *   `:file` means dumping to a tempfile and returning corresponding File
-  #     object;
-  # *   `:stdout` means printing the dump and returning `nil`;
-  # *   `:string` means returning a string with the dump;
+  # *   <code>:file</code> means dumping to a tempfile and returning corresponding
+  #     File object;
+  # *   <code>:stdout</code> means printing the dump and returning `nil`;
+  # *   <code>:string</code> means returning a string with the dump;
   # *   if an instance of IO object is provided, the output goes there, and the
   #     object is returned.
   #
@@ -277,7 +255,7 @@ module ObjectSpace
   #
   # If *shapes* is a positive integer, only shapes newer than the provided shape
   # id are dumped. The current shape_id can be accessed using
-  # `RubyVM.stat(:next_shape_id)`.
+  # <code>RubyVM.stat(:next_shape_id)</code>.
   #
   # If *shapes* is `false`, no shapes are dumped.
   #

data/stdlib/open-uri/0/open-uri.rbs

@@ -9,9 +9,9 @@ module URI
   # If the first argument responds to the 'open' method, 'open' is called on it
   # with the rest of the arguments.
   #
-  # If the first argument is a string that begins with `(protocol)://`, it is
-  # parsed by URI.parse.  If the parsed object responds to the 'open' method,
-  # 'open' is called on it with the rest of the arguments.
+  # If the first argument is a string that begins with <code>(protocol)://</code>,
+  # it is parsed by URI.parse.  If the parsed object responds to the 'open'
+  # method, 'open' is called on it with the rest of the arguments.
   #
   # Otherwise, Kernel#open is called.
   #
@@ -349,17 +349,17 @@ module OpenURI
     # :   Synopsis:
     #         :ftp_active_mode=>bool
     #
-    #     `:ftp_active_mode => true` is used to make ftp active mode. Ruby 1.9 uses
-    #     passive mode by default. Note that the active mode is default in Ruby 1.8
-    #     or prior.
+    #     <code>:ftp_active_mode => true</code> is used to make ftp active mode.
+    #     Ruby 1.9 uses passive mode by default. Note that the active mode is
+    #     default in Ruby 1.8 or prior.
     #
     #
     # :redirect
     # :   Synopsis:
     #         :redirect=>bool
     #
-    #     `:redirect` is true by default.  `:redirect => false` is used to disable
-    #     all HTTP redirects.
+    #     <code>:redirect</code> is true by default.  <code>:redirect =>
+    #     false</code> is used to disable all HTTP redirects.
     #
     #     OpenURI::HTTPRedirect exception raised on redirection. Using `true` also
     #     means that redirections between http and ftp are permitted.

data/stdlib/open3/0/open3.rbs

@@ -48,6 +48,106 @@
 #     Options](rdoc-ref:Process@Execution+Options).
 #
 module Open3
+  type env = Hash[String, String]
+
+  # <!--
+  #   rdoc-file=lib/open3.rb
+  #   - Open3.capture2([env, ] command_line, options = {}) -> [stdout_s, status]
+  #   - Open3.capture2([env, ] exe_path, *args, options = {}) -> [stdout_s, status]
+  # -->
+  # Basically a wrapper for Open3.popen3 that:
+  #
+  # *   Creates a child process, by calling Open3.popen3 with the given arguments
+  #     (except for certain entries in hash `options`; see below).
+  # *   Returns as string `stdout_s` the standard output of the child process.
+  # *   Returns as `status` a <code>Process::Status</code> object that represents
+  #     the exit status of the child process.
+  #
+  # Returns the array <code>[stdout_s, status]</code>:
+  #
+  #     stdout_s, status = Open3.capture2('echo "Foo"')
+  #     # => ["Foo\n", #<Process::Status: pid 2326047 exit 0>]
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities if
+  # called with untrusted input; see [Command
+  # Injection](rdoc-ref:command_injection.rdoc@Command+Injection).
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit before
+  # returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument `env` in the call
+  # to Open3.popen3; see [Execution
+  # Environment](rdoc-ref:Process@Execution+Environment).
+  #
+  # If the last argument is a hash, it becomes trailing argument `options` in the
+  # call to Open3.popen3; see [Execution
+  # Options](rdoc-ref:Process@Execution+Options).
+  #
+  # The hash `options` is given; two options have local effect in method
+  # Open3.capture2:
+  #
+  # *   If entry <code>options[:stdin_data]</code> exists, the entry is removed
+  #     and its string value is sent to the command's standard input:
+  #
+  #         Open3.capture2('tee', stdin_data: 'Foo')
+  #
+  #         # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
+  #
+  # *   If entry <code>options[:binmode]</code> exists, the entry is removed and
+  #     the internal streams are set to binary mode.
+  #
+  # The single required argument is one of the following:
+  #
+  # *   `command_line` if it is a string, and if it begins with a shell reserved
+  #     word or special built-in, or if it contains one or more metacharacters.
+  # *   `exe_path` otherwise.
+  #
+  # <strong>Argument `command_line`</strong>
+  #
+  # String argument `command_line` is a command line to be passed to a shell; it
+  # must begin with a shell reserved word, begin with a special built-in, or
+  # contain meta characters:
+  #
+  #     Open3.capture2('if true; then echo "Foo"; fi') # Shell reserved word.
+  #     # => ["Foo\n", #<Process::Status: pid 2326131 exit 0>]
+  #     Open3.capture2('echo')                         # Built-in.
+  #     # => ["\n", #<Process::Status: pid 2326139 exit 0>]
+  #     Open3.capture2('date > date.tmp')              # Contains meta character.
+  #     # => ["", #<Process::Status: pid 2326174 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #     Open3.capture2('echo "Foo"')
+  #     # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
+  #
+  # <strong>Argument `exe_path`</strong>
+  #
+  # Argument `exe_path` is one of the following:
+  #
+  # *   The string path to an executable to be called.
+  # *   A 2-element array containing the path to an executable and the string to
+  #     be used as the name of the executing process.
+  #
+  # Example:
+  #
+  #     Open3.capture2('/usr/bin/date')
+  #     # => ["Fri Sep 29 01:00:39 PM CDT 2023\n", #<Process::Status: pid 2326222 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #     Open3.capture2('doesnt_exist') # Raises Errno::ENOENT
+  #
+  # If one or more `args` is given, each is an argument or option to be passed to
+  # the executable:
+  #
+  #     Open3.capture2('echo', 'C #')
+  #     # => ["C #\n", #<Process::Status: pid 2326267 exit 0>]
+  #     Open3.capture2('echo', 'hello', 'world')
+  #     # => ["hello world\n", #<Process::Status: pid 2326299 exit 0>]
+  #
+  def self?.capture2: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, Process::Status]
+                    | (env, *String, ?stdin_data: String, ?binmode: boolish) -> [String, Process::Status]
+
   # <!--
   #   rdoc-file=lib/open3.rb
   #   - Open3.capture2e([env, ] command_line, options = {}) -> [stdout_and_stderr_s, status]
@@ -59,10 +159,10 @@ module Open3
   #     (except for certain entries in hash `options`; see below).
   # *   Returns as string `stdout_and_stderr_s` the merged standard output and
   #     standard error of the child process.
-  # *   Returns as `status` a `Process::Status` object that represents the exit
-  #     status of the child process.
+  # *   Returns as `status` a <code>Process::Status</code> object that represents
+  #     the exit status of the child process.
   #
-  # Returns the array `[stdout_and_stderr_s, status]`:
+  # Returns the array <code>[stdout_and_stderr_s, status]</code>:
   #
   #     stdout_and_stderr_s, status = Open3.capture2e('echo "Foo"')
   #     # => ["Foo\n", #<Process::Status: pid 2371692 exit 0>]
@@ -85,14 +185,14 @@ module Open3
   # The hash `options` is given; two options have local effect in method
   # Open3.capture2e:
   #
-  # *   If entry `options[:stdin_data]` exists, the entry is removed and its
-  #     string value is sent to the command's standard input:
+  # *   If entry <code>options[:stdin_data]</code> exists, the entry is removed
+  #     and its string value is sent to the command's standard input:
   #
   #         Open3.capture2e('tee', stdin_data: 'Foo')
   #         # => ["Foo", #<Process::Status: pid 2371732 exit 0>]
   #
-  # *   If entry `options[:binmode]` exists, the entry is removed and the internal
-  #     streams are set to binary mode.
+  # *   If entry <code>options[:binmode]</code> exists, the entry is removed and
+  #     the internal streams are set to binary mode.
   #
   # The single required argument is one of the following:
   #
@@ -100,7 +200,7 @@ module Open3
   #     word or special built-in, or if it contains one or more metacharacters.
   # *   `exe_path` otherwise.
   #
-  # **Argument `command_line`**
+  # <strong>Argument `command_line`</strong>
   #
   # String argument `command_line` is a command line to be passed to a shell; it
   # must begin with a shell reserved word, begin with a special built-in, or
@@ -118,7 +218,7 @@ module Open3
   #     Open3.capture2e('echo "Foo"')
   #     # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
   #
-  # **Argument `exe_path`**
+  # <strong>Argument `exe_path`</strong>
   #
   # Argument `exe_path` is one of the following:
   #
@@ -143,5 +243,364 @@ module Open3
   #     Open3.capture2e('echo', 'hello', 'world')
   #     # => ["hello world\n", #<Process::Status: pid 2371894 exit 0>]
   #
-  def self.capture2e: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, Process::Status]
+  def self?.capture2e: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, Process::Status]
+                     | (env, *String, ?stdin_data: String, ?binmode: boolish) -> [String, Process::Status]
+
+  # <!--
+  #   rdoc-file=lib/open3.rb
+  #   - Open3.capture3([env, ] command_line, options = {}) -> [stdout_s, stderr_s, status]
+  #   - Open3.capture3([env, ] exe_path, *args, options = {}) -> [stdout_s, stderr_s, status]
+  # -->
+  # Basically a wrapper for Open3.popen3 that:
+  #
+  # *   Creates a child process, by calling Open3.popen3 with the given arguments
+  #     (except for certain entries in hash `options`; see below).
+  # *   Returns as strings `stdout_s` and `stderr_s` the standard output and
+  #     standard error of the child process.
+  # *   Returns as `status` a <code>Process::Status</code> object that represents
+  #     the exit status of the child process.
+  #
+  # Returns the array <code>[stdout_s, stderr_s, status]</code>:
+  #
+  #     stdout_s, stderr_s, status = Open3.capture3('echo "Foo"')
+  #     # => ["Foo\n", "", #<Process::Status: pid 2281954 exit 0>]
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities if
+  # called with untrusted input; see [Command
+  # Injection](rdoc-ref:command_injection.rdoc@Command+Injection).
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit before
+  # returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument `env` in the call
+  # to Open3.popen3; see [Execution
+  # Environment](rdoc-ref:Process@Execution+Environment).
+  #
+  # If the last argument is a hash, it becomes trailing argument `options` in the
+  # call to Open3.popen3; see [Execution
+  # Options](rdoc-ref:Process@Execution+Options).
+  #
+  # The hash `options` is given; two options have local effect in method
+  # Open3.capture3:
+  #
+  # *   If entry <code>options[:stdin_data]</code> exists, the entry is removed
+  #     and its string value is sent to the command's standard input:
+  #
+  #         Open3.capture3('tee', stdin_data: 'Foo')
+  #         # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
+  #
+  # *   If entry <code>options[:binmode]</code> exists, the entry is removed and
+  #     the internal streams are set to binary mode.
+  #
+  # The single required argument is one of the following:
+  #
+  # *   `command_line` if it is a string, and if it begins with a shell reserved
+  #     word or special built-in, or if it contains one or more metacharacters.
+  # *   `exe_path` otherwise.
+  #
+  # <strong>Argument `command_line`</strong>
+  #
+  # String argument `command_line` is a command line to be passed to a shell; it
+  # must begin with a shell reserved word, begin with a special built-in, or
+  # contain meta characters:
+  #
+  #     Open3.capture3('if true; then echo "Foo"; fi') # Shell reserved word.
+  #     # => ["Foo\n", "", #<Process::Status: pid 2282025 exit 0>]
+  #     Open3.capture3('echo')                         # Built-in.
+  #     # => ["\n", "", #<Process::Status: pid 2282092 exit 0>]
+  #     Open3.capture3('date > date.tmp')              # Contains meta character.
+  #     # => ["", "", #<Process::Status: pid 2282110 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #     Open3.capture3('echo "Foo"')
+  #     # => ["Foo\n", "", #<Process::Status: pid 2282092 exit 0>]
+  #
+  # <strong>Argument `exe_path`</strong>
+  #
+  # Argument `exe_path` is one of the following:
+  #
+  # *   The string path to an executable to be called.
+  # *   A 2-element array containing the path to an executable and the string to
+  #     be used as the name of the executing process.
+  #
+  # Example:
+  #
+  #     Open3.capture3('/usr/bin/date')
+  #     # => ["Thu Sep 28 05:03:51 PM CDT 2023\n", "", #<Process::Status: pid 2282300 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #     Open3.capture3('doesnt_exist') # Raises Errno::ENOENT
+  #
+  # If one or more `args` is given, each is an argument or option to be passed to
+  # the executable:
+  #
+  #     Open3.capture3('echo', 'C #')
+  #     # => ["C #\n", "", #<Process::Status: pid 2282368 exit 0>]
+  #     Open3.capture3('echo', 'hello', 'world')
+  #     # => ["hello world\n", "", #<Process::Status: pid 2282372 exit 0>]
+  #
+  def self?.capture3: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, String, Process::Status]
+                    | (env, *String, ?stdin_data: String, ?binmode: boolish) -> [String, String, Process::Status]
+
+  # <!--
+  #   rdoc-file=lib/open3.rb
+  #   - Open3.popen2([env, ] command_line, options = {}) -> [stdin, stdout, wait_thread]
+  #   - Open3.popen2([env, ] exe_path, *args, options = {}) -> [stdin, stdout, wait_thread]
+  #   - Open3.popen2([env, ] command_line, options = {}) {|stdin, stdout, wait_thread| ... } -> object
+  #   - Open3.popen2([env, ] exe_path, *args, options = {}) {|stdin, stdout, wait_thread| ... } -> object
+  # -->
+  # Basically a wrapper for [Process.spawn](rdoc-ref:Process.spawn) that:
+  #
+  # *   Creates a child process, by calling Process.spawn with the given
+  #     arguments.
+  # *   Creates streams `stdin` and `stdout`, which are the standard input and
+  #     standard output streams in the child process.
+  # *   Creates thread `wait_thread` that waits for the child process to exit; the
+  #     thread has method `pid`, which returns the process ID of the child
+  #     process.
+  #
+  # With no block given, returns the array <code>[stdin, stdout,
+  # wait_thread]</code>. The caller should close each of the two returned streams.
+  #
+  #     stdin, stdout, wait_thread = Open3.popen2('echo')
+  #     # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f58d52dbe98 run>]
+  #     stdin.close
+  #     stdout.close
+  #     wait_thread.pid   # => 2263572
+  #     wait_thread.value # => #<Process::Status: pid 2263572 exit 0>
+  #
+  # With a block given, calls the block with the three variables (two streams and
+  # the wait thread) and returns the block's return value. The caller need not
+  # close the streams:
+  #
+  #     Open3.popen2('echo') do |stdin, stdout, wait_thread|
+  #       p stdin
+  #       p stdout
+  #       p wait_thread
+  #       p wait_thread.pid
+  #       p wait_thread.value
+  #     end
+  #
+  # Output:
+  #
+  #     #<IO:fd 6>
+  #     #<IO:fd 7>
+  #     #<Process::Waiter:0x00007f58d59a34b0 sleep>
+  #     2263636
+  #     #<Process::Status: pid 2263636 exit 0>
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities if
+  # called with untrusted input; see [Command
+  # Injection](rdoc-ref:command_injection.rdoc@Command+Injection).
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit before
+  # returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument `env` in the call
+  # to Process.spawn; see [Execution
+  # Environment](rdoc-ref:Process@Execution+Environment).
+  #
+  # If the last argument is a hash, it becomes trailing argument `options` in the
+  # call to Process.spawn; see [Execution
+  # Options](rdoc-ref:Process@Execution+Options).
+  #
+  # The single required argument is one of the following:
+  #
+  # *   `command_line` if it is a string, and if it begins with a shell reserved
+  #     word or special built-in, or if it contains one or more metacharacters.
+  # *   `exe_path` otherwise.
+  #
+  # <strong>Argument `command_line`</strong>
+  #
+  # String argument `command_line` is a command line to be passed to a shell; it
+  # must begin with a shell reserved word, begin with a special built-in, or
+  # contain meta characters:
+  #
+  #     Open3.popen2('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #     Open3.popen2('echo') {|*args| p args }                         # Built-in.
+  #     Open3.popen2('date > date.tmp') {|*args| p args }              # Contains meta character.
+  #
+  # Output (similar for each call above):
+  #
+  #     # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577dfe410 dead>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #     Open3.popen2('echo "Foo"') { |i, o, t| o.gets }
+  #     "Foo\n"
+  #
+  # <strong>Argument `exe_path`</strong>
+  #
+  # Argument `exe_path` is one of the following:
+  #
+  # *   The string path to an executable to be called.
+  # *   A 2-element array containing the path to an executable and the string to
+  #     be used as the name of the executing process.
+  #
+  # Example:
+  #
+  #     Open3.popen2('/usr/bin/date') { |i, o, t| o.gets }
+  #     # => "Thu Sep 28 09:41:06 AM CDT 2023\n"
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #     Open3.popen2('doesnt_exist') { |i, o, t| o.gets } # Raises Errno::ENOENT
+  #
+  # If one or more `args` is given, each is an argument or option to be passed to
+  # the executable:
+  #
+  #     Open3.popen2('echo', 'C #') { |i, o, t| o.gets }
+  #     # => "C #\n"
+  #     Open3.popen2('echo', 'hello', 'world') { |i, o, t| o.gets }
+  #     # => "hello world\n"
+  #
+  # Related:
+  #
+  # *   Open3.popen2e: Makes the standard input and the merge of the standard
+  #     output and standard error streams of the child process available as
+  #     separate streams.
+  # *   Open3.popen3: Makes the standard input, standard output, and standard
+  #     error streams of the child process available as separate streams.
+  #
+  def self?.popen2: (*String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) -> [IO, IO, Process::Waiter]
+                  | (env, *String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) -> [IO, IO, Process::Waiter]
+                  | [T] (*String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) { (IO, IO, Process::Waiter) -> T } -> T
+                  | [T] (env, *String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) { (IO, IO, Process::Waiter) -> T } -> T
+
+  # <!--
+  #   rdoc-file=lib/open3.rb
+  #   - Open3.popen3([env, ] command_line, options = {}) -> [stdin, stdout, stderr, wait_thread]
+  #   - Open3.popen3([env, ] exe_path, *args, options = {}) -> [stdin, stdout, stderr, wait_thread]
+  #   - Open3.popen3([env, ] command_line, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
+  #   - Open3.popen3([env, ] exe_path, *args, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
+  # -->
+  # Basically a wrapper for [Process.spawn](rdoc-ref:Process.spawn) that:
+  #
+  # *   Creates a child process, by calling Process.spawn with the given
+  #     arguments.
+  # *   Creates streams `stdin`, `stdout`, and `stderr`, which are the standard
+  #     input, standard output, and standard error streams in the child process.
+  # *   Creates thread `wait_thread` that waits for the child process to exit; the
+  #     thread has method `pid`, which returns the process ID of the child
+  #     process.
+  #
+  # With no block given, returns the array <code>[stdin, stdout, stderr,
+  # wait_thread]</code>. The caller should close each of the three returned
+  # streams.
+  #
+  #     stdin, stdout, stderr, wait_thread = Open3.popen3('echo')
+  #     # => [#<IO:fd 8>, #<IO:fd 10>, #<IO:fd 12>, #<Process::Waiter:0x00007f58d5428f58 run>]
+  #     stdin.close
+  #     stdout.close
+  #     stderr.close
+  #     wait_thread.pid   # => 2210481
+  #     wait_thread.value # => #<Process::Status: pid 2210481 exit 0>
+  #
+  # With a block given, calls the block with the four variables (three streams and
+  # the wait thread) and returns the block's return value. The caller need not
+  # close the streams:
+  #
+  #     Open3.popen3('echo') do |stdin, stdout, stderr, wait_thread|
+  #       p stdin
+  #       p stdout
+  #       p stderr
+  #       p wait_thread
+  #       p wait_thread.pid
+  #       p wait_thread.value
+  #     end
+  #
+  # Output:
+  #
+  #     #<IO:fd 6>
+  #     #<IO:fd 7>
+  #     #<IO:fd 9>
+  #     #<Process::Waiter:0x00007f58d53606e8 sleep>
+  #     2211047
+  #     #<Process::Status: pid 2211047 exit 0>
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities if
+  # called with untrusted input; see [Command
+  # Injection](rdoc-ref:command_injection.rdoc@Command+Injection).
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit before
+  # returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument `env` in the call
+  # to Process.spawn; see [Execution
+  # Environment](rdoc-ref:Process@Execution+Environment).
+  #
+  # If the last argument is a hash, it becomes trailing argument `options` in the
+  # call to Process.spawn; see [Execution
+  # Options](rdoc-ref:Process@Execution+Options).
+  #
+  # The single required argument is one of the following:
+  #
+  # *   `command_line` if it is a string, and if it begins with a shell reserved
+  #     word or special built-in, or if it contains one or more metacharacters.
+  # *   `exe_path` otherwise.
+  #
+  # <strong>Argument `command_line`</strong>
+  #
+  # String argument `command_line` is a command line to be passed to a shell; it
+  # must begin with a shell reserved word, begin with a special built-in, or
+  # contain meta characters:
+  #
+  #     Open3.popen3('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #     Open3.popen3('echo') {|*args| p args }                         # Built-in.
+  #     Open3.popen3('date > date.tmp') {|*args| p args }              # Contains meta character.
+  #
+  # Output (similar for each call above):
+  #
+  #     [#<IO:(closed)>, #<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f58d52f28c8 dead>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #     Open3.popen3('echo "Foo"') { |i, o, e, t| o.gets }
+  #     "Foo\n"
+  #
+  # <strong>Argument `exe_path`</strong>
+  #
+  # Argument `exe_path` is one of the following:
+  #
+  # *   The string path to an executable to be called.
+  # *   A 2-element array containing the path to an executable and the string to
+  #     be used as the name of the executing process.
+  #
+  # Example:
+  #
+  #     Open3.popen3('/usr/bin/date') { |i, o, e, t| o.gets }
+  #     # => "Wed Sep 27 02:56:44 PM CDT 2023\n"
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #     Open3.popen3('doesnt_exist') { |i, o, e, t| o.gets } # Raises Errno::ENOENT
+  #
+  # If one or more `args` is given, each is an argument or option to be passed to
+  # the executable:
+  #
+  #     Open3.popen3('echo', 'C #') { |i, o, e, t| o.gets }
+  #     # => "C #\n"
+  #     Open3.popen3('echo', 'hello', 'world') { |i, o, e, t| o.gets }
+  #     # => "hello world\n"
+  #
+  # Take care to avoid deadlocks. Output streams `stdout` and `stderr` have
+  # fixed-size buffers, so reading extensively from one but not the other can
+  # cause a deadlock when the unread buffer fills. To avoid that, `stdout` and
+  # `stderr` should be read simultaneously (using threads or IO.select).
+  #
+  # Related:
+  #
+  # *   Open3.popen2: Makes the standard input and standard output streams of the
+  #     child process available as separate streams, with no access to the
+  #     standard error stream.
+  # *   Open3.popen2e: Makes the standard input and the merge of the standard
+  #     output and standard error streams of the child process available as
+  #     separate streams.
+  #
+  def self?.popen3: (*String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) -> [IO, IO, IO, Process::Waiter]
+                  | (env, *String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) -> [IO, IO, IO, Process::Waiter]
+                  | [T] (*String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) { (IO, IO, IO, Process::Waiter) -> T } -> T
+                  | [T] (env, *String, ?unsetenv_others: bool, ?pgroup: true | Integer, ?umask: Integer, ?close_others: bool, ?chdir: String) { (IO, IO, IO, Process::Waiter) -> T } -> T
 end