open3 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ab5dfcb825c74af61129ee82254609322af777421f454eb90053875bdbc851
-  data.tar.gz: fdf3f7c0783de3763390a6e62a7ec984f262d61ca5d8906e186ad7e7deeff5d2
+  metadata.gz: d381ba178ac3fc0539b0f526890e2951b8e6f0332d294cd4930b895837643b3b
+  data.tar.gz: 7435b46d29c7e24231af4adb8106a32cde9850a896e61153a08fe4b519d5645b
 SHA512:
-  metadata.gz: 3e3508856456efd5c0700447c9e122163ea490b32a7bd4cc09d2d4fa79639b53baac5b8f45d983e5185dd439c93cfba2b546c302569e1dccf6d4086c0a3b0858
-  data.tar.gz: a79fd57d1a714b793ecc3849231cf3d58fd07bcc962ffad144b98ec7443d8da1642e97ab10e6f251c720cc9d0cfe72a809fb71c0c915226fcbed0b2a1c607839
+  metadata.gz: e8770606eb547891a3c87fd8636c7a911189d940aa332909098fff948660978c717bb3bd2727fb13378e6b10ee207b7cee17f91a1b02ef18a20cded2bf76f3a9
+  data.tar.gz: b12409782b071af20bc628579d5a03ea89023c5e3dd1acbae90a67bafbb748d5c7a4de46ecc5d9ddc2da020de5ff53b89448719025706fc08dfe33b87563df83

data/.github/workflows/test-jruby.yml

@@ -11,7 +11,7 @@ jobs:
         os: [ ubuntu-latest, macos-latest ]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/.github/workflows/test.yml

@@ -3,15 +3,22 @@ name: test
 on: [push, pull_request]
 
 jobs:
-  build:
+  ruby-versions:
+    uses: ruby/actions/.github/workflows/ruby_versions.yml@master
+    with:
+      engine: cruby
+      min_version: 2.6
+
+  test:
+    needs: ruby-versions
     name: build (${{ matrix.ruby }} / ${{ matrix.os }})
     strategy:
       matrix:
-        ruby: [ '3.0', 2.7, 2.6, head ]
+        ruby: ${{ fromJson(needs.ruby-versions.outputs.versions) }}
         os: [ ubuntu-latest, macos-latest ]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:

data/Gemfile

@@ -6,4 +6,5 @@ group :development do
   gem "bundler"
   gem "rake"
   gem "test-unit"
+  gem "test-unit-ruby-core"
 end

data/Rakefile

@@ -7,11 +7,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-task :sync_tool do
-  require 'fileutils'
-  FileUtils.cp "../ruby/tool/lib/core_assertions.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/envutil.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/find_executable.rb", "./test/lib"
-end
-
 task :default => :test

data/lib/open3/version.rb

@@ -1,3 +1,3 @@
 module Open3
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/open3.rb

@@ -33,55 +33,133 @@ require 'open3/version'
 
 module Open3
 
-  # Open stdin, stdout, and stderr streams and start external executable.
-  # In addition, a thread to wait for the started process is created.
-  # The thread has a pid method and a thread variable :pid which is the pid of
-  # the started process.
+  # :call-seq:
+  #   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 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
+  # <tt>[stdin, stdout, stderr, wait_thread]</tt>.
+  # 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
   #
-  # Block form:
+  # Output:
   #
-  #   Open3.popen3([env,] cmd... [, opts]) {|stdin, stdout, stderr, wait_thr|
-  #     pid = wait_thr.pid # pid of the started process.
-  #     ...
-  #     exit_status = wait_thr.value # Process::Status object returned.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<IO:fd 9>
+  #   #<Process::Waiter:0x00007f58d53606e8 sleep>
+  #   2211047
+  #   #<Process::Status: pid 2211047 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  #   stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts])
-  #   pid = wait_thr[:pid]  # pid of the started process
-  #   ...
-  #   stdin.close  # stdin, stdout and stderr should be closed explicitly in this form.
-  #   stdout.close
-  #   stderr.close
-  #   exit_status = wait_thr.value  # Process::Status object returned.
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  # The parameters env, cmd, and opts are passed to Process.spawn.
-  # A commandline string and a list of argument strings can be accepted as follows:
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
   #
-  #   Open3.popen3("echo abc") {|i, o, e, t| ... }
-  #   Open3.popen3("echo", "abc") {|i, o, e, t| ... }
-  #   Open3.popen3(["echo", "argv0"], "abc") {|i, o, e, t| ... }
+  # The single required argument is one of the following:
   #
-  # If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
+  # - +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.
   #
-  #   Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t|
-  #     p o.read.chomp #=> "/"
-  #   }
+  # <b>Argument +command_line+</b>
+  #
+  # \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"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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:
   #
-  # wait_thr.value waits for the termination of the process.
-  # The block form also waits for the process when it returns.
+  #   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"
   #
-  # Closing stdin, stdout and stderr does not wait for the process to complete.
+  # 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).
   #
-  # You should be careful to avoid deadlocks.
-  # Since pipes are fixed length buffers,
-  # Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if
-  # the program generates too much output on stderr.
-  # You should read stdout and stderr simultaneously (using threads or IO.select).
-  # However, if you don't need stderr output, you can use Open3.popen2.
-  # If merged stdout and stderr output is not a problem, you can use Open3.popen2e.
-  # If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
+  # 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 popen3(*cmd, &block)
     if Hash === cmd.last
@@ -104,45 +182,124 @@ module Open3
   end
   module_function :popen3
 
-  # Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
-  # the standard error stream.
+  # :call-seq:
+  #   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 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
+  # <tt>[stdin, stdout, wait_thread]</tt>.
+  # 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
   #
-  # Block form:
+  # Output:
   #
-  #   Open3.popen2([env,] cmd... [, opts]) {|stdin, stdout, wait_thr|
-  #     pid = wait_thr.pid # pid of the started process.
-  #     ...
-  #     exit_status = wait_thr.value # Process::Status object returned.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<Process::Waiter:0x00007f58d59a34b0 sleep>
+  #   2263636
+  #   #<Process::Status: pid 2263636 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  #   stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts])
-  #   ...
-  #   stdin.close  # stdin and stdout should be closed explicitly in this form.
-  #   stdout.close
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # Argument +options+ is a hash of options for the new process;
+  # 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.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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):
   #
-  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  #   # => [#<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"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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("wc -c") {|i,o,t|
-  #     i.print "answer to life the universe and everything"
-  #     i.close
-  #     p o.gets #=> "42\n"
-  #   }
+  #   Open3.popen2('/usr/bin/date') { |i, o, t| o.gets }
+  #   # => "Thu Sep 28 09:41:06 AM CDT 2023\n"
   #
-  #   Open3.popen2("bc -q") {|i,o,t|
-  #     i.puts "obase=13"
-  #     i.puts "6 * 9"
-  #     p o.gets #=> "42\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"
   #
-  #   Open3.popen2("dc") {|i,o,t|
-  #     i.print "42P"
-  #     i.close
-  #     p o.read #=> "*"
-  #   }
+  #
+  # 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 popen2(*cmd, &block)
     if Hash === cmd.last
@@ -162,36 +319,123 @@ module Open3
   end
   module_function :popen2
 
-  # Open3.popen2e is similar to Open3.popen3 except that it merges
-  # the standard output stream and the standard error stream.
+  # :call-seq:
+  #   Open3.popen2e([env, ] command_line, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
+  #   Open3.popen2e([env, ] exe_path, *args, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
+  #   Open3.popen2e([env, ] command_line, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
+  #   Open3.popen2e([env, ] exe_path, *args, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
+  #
+  # Basically a wrapper for 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 and the merge of the 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
+  # <tt>[stdin, stdout_and_stderr, wait_thread]</tt>.
+  # The caller should close each of the two returned streams.
+  #
+  #   stdin, stdout_and_stderr, wait_thread = Open3.popen2e('echo')
+  #   # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f7577da4398 run>]
+  #   stdin.close
+  #   stdout_and_stderr.close
+  #   wait_thread.pid   # => 2274600
+  #   wait_thread.value # => #<Process::Status: pid 2274600 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.popen2e('echo') do |stdin, stdout_and_stderr, wait_thread|
+  #     p stdin
+  #     p stdout_and_stderr
+  #     p wait_thread
+  #     p wait_thread.pid
+  #     p wait_thread.value
+  #   end
   #
-  # Block form:
+  # Output:
   #
-  #   Open3.popen2e([env,] cmd... [, opts]) {|stdin, stdout_and_stderr, wait_thr|
-  #     pid = wait_thr.pid # pid of the started process.
-  #     ...
-  #     exit_status = wait_thr.value # Process::Status object returned.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<Process::Waiter:0x00007f75777578c8 sleep>
+  #   2274763
+  #   #<Process::Status: pid 2274763 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  #   stdin, stdout_and_stderr, wait_thr = Open3.popen2e([env,] cmd... [, opts])
-  #   ...
-  #   stdin.close  # stdin and stdout_and_stderr should be closed explicitly in this form.
-  #   stdout_and_stderr.close
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # Argument +options+ is a hash of options for the new process;
+  # 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.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
   #
-  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  #   Open3.popen2e('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #   Open3.popen2e('echo') {|*args| p args }                         # Built-in.
+  #   Open3.popen2e('date > date.tmp') {|*args| p args }              # Contains meta character.
+  #
+  # Output (similar for each call above):
+  #
+  #   # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577d8a1f0 dead>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.popen2e('echo "Foo"') { |i, o_and_e, t| o_and_e.gets }
+  #   "Foo\n"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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:
-  #   # check gcc warnings
-  #   source = "foo.c"
-  #   Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
-  #     oe.each {|line|
-  #       if /warning/ =~ line
-  #         ...
-  #       end
-  #     }
-  #   }
+  #
+  #   Open3.popen2e('/usr/bin/date') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "Thu Sep 28 01:58:45 PM CDT 2023\n"
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.popen2e('doesnt_exist') { |i, o_and_e, t| o_and_e.gets } # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.popen2e('echo', 'C #') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "C #\n"
+  #   Open3.popen2e('echo', 'hello', 'world') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "hello world\n"
+  #
+  # 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.popen3: Makes the standard input, standard output,
+  #   and standard error streams
+  #   of the child process available as separate streams.
   #
   def popen2e(*cmd, &block)
     if Hash === cmd.last
@@ -238,44 +482,95 @@ module Open3
     private :popen_run
   end
 
-  # Open3.capture3 captures the standard output and the standard error of a command.
+  # :call-seq:
+  #   Open3.capture3([env, ] command_line, options = {}) -> [stdout_s, stderr_s, status]
+  #   Open3.capture3([env, ] exe_path, *args, options = {}) -> [stdout_s, stderr_s, status]
   #
-  #   stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
+  # Basically a wrapper for Open3.popen3 that:
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # - 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 <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # Returns the array <tt>[stdout_s, stderr_s, status]</tt>:
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  #   stdout_s, stderr_s, status = Open3.capture3('echo "Foo"')
+  #   # => ["Foo\n", "", #<Process::Status: pid 2281954 exit 0>]
   #
-  # Examples:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  #   # dot is a command of graphviz.
-  #   graph = <<'End'
-  #     digraph g {
-  #       a -> b
-  #     }
-  #   End
-  #   drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
-  #
-  #   o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n")
-  #   p o #=> "abc\n"
-  #   p e #=> "bar\nbaz\nfoo\n"
-  #   p s #=> #<Process::Status: pid 32682 exit 0>
-  #
-  #   # generate a thumbnail image using the convert command of ImageMagick.
-  #   # However, if the image is really stored in a file,
-  #   # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better
-  #   # because of reduced memory consumption.
-  #   # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example,
-  #   # Open3.capture3 should be considered.
-  #   #
-  #   image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true)
-  #   thumbnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true)
-  #   if s.success?
-  #     STDOUT.binmode; print thumbnail
-  #   end
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  #
+  # The hash +options+ is passed to method Open3.popen3;
+  # two options have local effect in method Open3.capture3:
+  #
+  # - If entry <tt>options[:stdin_data]</tt> 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 <tt>options[:binmode]</tt> exists, the entry is removed
+  #   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.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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 capture3(*cmd)
     if Hash === cmd.last
@@ -309,34 +604,94 @@ module Open3
   end
   module_function :capture3
 
-  # Open3.capture2 captures the standard output of a command.
+  # :call-seq:
+  #   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 <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
+  #
+  # Returns the array <tt>[stdout_s, status]</tt>:
+  #
+  #   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].
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  #   stdout_str, status = Open3.capture2([env,] cmd... [, opts])
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # The hash +options+ is passed to method Open3.popen3;
+  # two options have local effect in method Open3.capture2:
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
+  #   and its string value is sent to the command's standard input:
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  #     Open3.capture2('tee', stdin_data: 'Foo')
+  #
+  #     # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
+  #
+  #   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.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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:
   #
-  #   # factor is a command for integer factorization.
-  #   o, s = Open3.capture2("factor", :stdin_data=>"42")
-  #   p o #=> "42: 2 3 7\n"
-  #
-  #   # generate x**2 graph in png using gnuplot.
-  #   gnuplot_commands = <<"End"
-  #     set terminal png
-  #     plot x**2, "-" with lines
-  #     1 14
-  #     2 1
-  #     3 8
-  #     4 5
-  #     e
-  #   End
-  #   image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
+  #   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 capture2(*cmd)
     if Hash === cmd.last
@@ -370,21 +725,94 @@ module Open3
   end
   module_function :capture2
 
-  # Open3.capture2e captures the standard output and the standard error of a command.
+  # :call-seq:
+  #   Open3.capture2e([env, ] command_line, options = {}) -> [stdout_and_stderr_s, status]
+  #   Open3.capture2e([env, ] exe_path, *args, options = {}) -> [stdout_and_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 string +stdout_and_stderr_s+ the merged standard output
+  #   and standard error of the child process.
+  # - Returns as +status+ a <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
+  #
+  # Returns the array <tt>[stdout_and_stderr_s, status]</tt>:
   #
-  #   stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
+  #   stdout_and_stderr_s, status = Open3.capture2e('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2371692 exit 0>]
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  #
+  # The hash +options+ is passed to method Open3.popen3;
+  # two options have local effect in method Open3.capture2e:
+  #
+  # - If entry <tt>options[:stdin_data]</tt> 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>]
+  #
+  #   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.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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.capture2e('if true; then echo "Foo"; fi') # Shell reserved word.
+  #   # => ["Foo\n", #<Process::Status: pid 2371740 exit 0>]
+  #   Open3.capture2e('echo')                         # Built-in.
+  #   # => ["\n", #<Process::Status: pid 2371774 exit 0>]
+  #   Open3.capture2e('date > date.tmp')              # Contains meta character.
+  #   # => ["", #<Process::Status: pid 2371812 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.capture2e('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # 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:
   #
-  #   # capture make log
-  #   make_log, s = Open3.capture2e("make")
+  #   Open3.capture2e('/usr/bin/date')
+  #   # => ["Sat Sep 30 09:01:46 AM CDT 2023\n", #<Process::Status: pid 2371820 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.capture2e('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.capture2e('echo', 'C #')
+  #   # => ["C #\n", #<Process::Status: pid 2371856 exit 0>]
+  #   Open3.capture2e('echo', 'hello', 'world')
+  #   # => ["hello world\n", #<Process::Status: pid 2371894 exit 0>]
   #
   def capture2e(*cmd)
     if Hash === cmd.last

data/open3.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z 2>/dev/null`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z 2>#{IO::NULL}`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open3
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Yukihiro Matsumoto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-14 00:00:00.000000000 Z
+date: 2023-11-07 00:00:00.000000000 Z
 dependencies: []
 description: Popen, but with stderr, too
 email:
@@ -53,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.0.dev
+rubygems_version: 3.5.0.dev
 signing_key:
 specification_version: 4
 summary: Popen, but with stderr, too