Merge pull request #2699 from ksss/more-open3

Add type of `Open3.popen3`

Author: ksss

stdlib/open3/0/open3.rbs

@@ -245,4 +245,138 @@ module Open3
   #
   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.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 `[stdin, stdout, stderr, wait_thread]`.
+  # 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.
+  #
+  # **Argument `command_line`**
+  #
+  # 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"
+  #
+  # **Argument `exe_path`**
+  #
+  # 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

test/stdlib/Open3_test.rb

@@ -27,6 +27,24 @@ def test_capture2e
     assert_send_type "(::Hash[::String, ::String], *::String) -> [ ::String, ::Process::Status ]",
                      Open3, :capture2e, { 'FOO' => 'BAR' }, "echo $FOO"
   end
+
+  def test_popen3
+    assert_send_type "(::String) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     Open3, :popen3, 'echo "Foo"'
+    assert_send_type "(::String, unsetenv_others: bool) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     Open3, :popen3, 'env', unsetenv_others: true
+    assert_send_type "(::String, close_others: bool) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     Open3, :popen3, 'env', close_others: true
+    assert_send_type "(::String, chdir: ::String) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     Open3, :popen3, 'echo "Foo"', chdir: '.'
+    assert_send_type "(::Hash[::String, ::String], ::String) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     Open3, :popen3, { 'FOO' => 'BAR' }, "echo $FOO"
+
+    assert_send_type "(::String) { (::IO, ::IO, ::IO, ::Process::Waiter) -> [::IO, ::IO, ::IO, ::Process::Waiter] } -> [::IO, ::IO, ::IO, ::Process::Waiter]",
+                     Open3, :popen3, 'echo "Foo"' do |*args| args end
+    assert_send_type "(::Hash[::String, ::String], ::String) { (::IO, ::IO, ::IO, ::Process::Waiter) -> [::IO, ::IO, ::IO, ::Process::Waiter] } -> [::IO, ::IO, ::IO, ::Process::Waiter]",
+                     Open3, :popen3, { 'FOO' => 'BAR' }, 'echo $FOO' do |*args| args end
+  end
 end
 
 class Open3InstanceTest < Test::Unit::TestCase
@@ -48,4 +66,9 @@ def test_capture2e
     assert_send_type "(*::String) -> [ ::String, ::Process::Status ]",
                      CustomOpen3.new, :capture2e, 'echo "Foo"'
   end
+
+  def test_popen3
+    assert_send_type "(::String) -> [ ::IO, ::IO, ::IO, ::Process::Waiter ]",
+                     CustomOpen3.new, :popen3, 'echo "Foo"'
+  end
 end