open3 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f598d530ced19be109f452253e266841b9c00d71e96687d31c2e5fa5db86957
-  data.tar.gz: be2ec8a86eeaa8e60907e9c95268d6b65ef3b477083051054a6adb1521a0fceb
+  metadata.gz: d381ba178ac3fc0539b0f526890e2951b8e6f0332d294cd4930b895837643b3b
+  data.tar.gz: 7435b46d29c7e24231af4adb8106a32cde9850a896e61153a08fe4b519d5645b
 SHA512:
-  metadata.gz: c327ed7dd6b0769dd17809b7b155028ea6604364ce6a123b5f59d7f9a98ffe4e078e170f0268fb5eccdfc96a10bf9d284bdd85391052b104469906d410e010e9
-  data.tar.gz: b641d417656c67cd4199a0592ef71dc24d852fda7084cf31b89e4172eebf91e660f585a3213ab8257cfa942fa928be5ee7fc8dd2b693a76605b0f9acd38f1033
+  metadata.gz: e8770606eb547891a3c87fd8636c7a911189d940aa332909098fff948660978c717bb3bd2727fb13378e6b10ee207b7cee17f91a1b02ef18a20cded2bf76f3a9
+  data.tar.gz: b12409782b071af20bc628579d5a03ea89023c5e3dd1acbae90a67bafbb748d5c7a4de46ecc5d9ddc2da020de5ff53b89448719025706fc08dfe33b87563df83

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'

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

@@ -0,0 +1,21 @@
+name: test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    name: build (${{ matrix.ruby }} / ${{ matrix.os }})
+    strategy:
+      matrix:
+        ruby: [ 2.7, 2.6, head, jruby-9.3 ]
+        os: [ ubuntu-latest, macos-latest ]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # 'bundle install' and cache
+    - name: Run test
+      run: bundle exec rake test

data/.github/workflows/test.yml

@@ -3,22 +3,26 @@ 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: [ 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@master
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
-    - name: Install dependencies
-      run: |
-        gem install bundler --no-document
-        bundle install
+        bundler-cache: true # 'bundle install' and cache
     - name: Run test
-      run: rake test
+      run: bundle exec rake test

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/test/unit/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/jruby_windows.rb

@@ -0,0 +1,127 @@
+#
+# Custom implementation of Open3.popen{3,2,2e} that uses java.lang.ProcessBuilder rather than pipes and spawns.
+#
+
+require 'jruby' # need access to runtime for RubyStatus construction
+
+module Open3
+
+  java_import java.lang.ProcessBuilder
+  java_import org.jruby.RubyProcess
+  java_import org.jruby.util.ShellLauncher
+
+  def popen3(*cmd, &block)
+    if cmd.size > 0 && Hash === cmd[-1]
+      opts = cmd.pop
+    else
+      opts = {}
+    end
+    processbuilder_run(cmd, opts, io: IO_3, &block)
+  end
+  module_function :popen3
+
+  IO_3 = proc do |process|
+    [process.getOutputStream.to_io, process.getInputStream.to_io, process.getErrorStream.to_io]
+  end
+
+  BUILD_2 = proc do |builder|
+    builder.redirectError(ProcessBuilder::Redirect::INHERIT)
+  end
+
+  IO_2 = proc do |process|
+    [process.getOutputStream.to_io, process.getInputStream.to_io]
+  end
+
+  def popen2(*cmd, &block)
+    if cmd.size > 0 && Hash === cmd[-1]
+      opts = cmd.pop
+    else
+      opts = {}
+    end
+    processbuilder_run(cmd, opts, build: BUILD_2, io: IO_2, &block)
+  end
+  module_function :popen2
+
+  BUILD_2E = proc do |builder|
+    builder.redirectErrorStream(true)
+  end
+
+  def popen2e(*cmd, &block)
+    if cmd.size > 0 && Hash === cmd[-1]
+      opts = cmd.pop
+    else
+      opts = {}
+    end
+    processbuilder_run(cmd, opts, build: BUILD_2E, io: IO_2, &block)
+  end
+  module_function :popen2e
+
+  def processbuilder_run(cmd, opts, build: nil, io:)
+    opts.each do |k, v|
+      if Integer === k
+        if IO == v || !(String === v || v.respond_to?(:to_path))
+          # target is an open IO or a non-pathable object, bail out
+          raise NotImplementedError.new("redirect to an open IO is not implemented on this platform")
+        end
+      end
+    end
+
+    if Hash === cmd[0]
+      env = cmd.shift;
+    else
+      env = {}
+    end
+
+    if cmd.size == 1 && (cmd[0] =~ / / || ShellLauncher.shouldUseShell(cmd[0]))
+      cmd = [RbConfig::CONFIG['SHELL'], JRuby::Util::ON_WINDOWS ? '/c' : '-c', cmd[0]]
+    end
+
+    builder = ProcessBuilder.new(cmd.to_java(:string))
+
+    builder.directory(java.io.File.new(opts[:chdir] || Dir.pwd))
+
+    environment = builder.environment
+    env.each { |k, v| v.nil? ? environment.remove(k) : environment.put(k, v) }
+
+    build.call(builder) if build
+
+    process = builder.start
+
+    pid = org.jruby.util.ShellLauncher.getPidFromProcess(process)
+
+    parent_io = io.call(process)
+
+    parent_io.each {|i| i.sync = true}
+
+    wait_thr = DetachThread.new(pid) { RubyProcess::RubyStatus.newProcessStatus(JRuby.runtime, process.waitFor << 8, pid) }
+
+    result = [*parent_io, wait_thr]
+
+    if defined? yield
+      begin
+        return yield(*result)
+      ensure
+        parent_io.each(&:close)
+        wait_thr.join
+      end
+    end
+
+    result
+  end
+  module_function :processbuilder_run
+  class << self
+    private :processbuilder_run
+  end
+
+  class DetachThread < Thread
+    attr_reader :pid
+
+    def initialize(pid)
+      super
+
+      @pid = pid
+      self[:pid] = pid
+    end
+  end
+
+end

data/lib/open3/version.rb

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

data/lib/open3.rb

@@ -29,58 +29,137 @@
 # - Open3.pipeline : run a pipeline and wait for its completion
 #
 
+require 'open3/version'
+
 module Open3
-  VERSION = "0.1.1"
 
-  # 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.
   #
-  # wait_thr.value waits for the termination of the process.
-  # The block form also waits for the process when it returns.
+  # 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:
   #
-  # Closing stdin, stdout and stderr does not wait for the process to complete.
+  #   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"
   #
-  # 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.
+  # 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 popen3(*cmd, &block)
     if Hash === cmd.last
@@ -103,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.
   #
-  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  # 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"
+  #
+  # <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("dc") {|i,o,t|
-  #     i.print "42P"
-  #     i.close
-  #     p o.read #=> "*"
-  #   }
+  #   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 popen2(*cmd, &block)
     if Hash === cmd.last
@@ -161,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
@@ -237,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
@@ -308,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.
+  #
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
   #
-  #   stdout_str, status = Open3.capture2([env,] cmd... [, opts])
+  # The hash +options+ is passed to method Open3.popen3;
+  # two options have local effect in method Open3.capture2:
   #
-  # 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.
+  # - 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[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  #     Open3.capture2('tee', stdin_data: 'Foo')
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  #     # => ["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
@@ -369,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_s, status = Open3.capture2e('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2371692 exit 0>]
   #
-  #   stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
   #
-  # 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.
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # Argument +options+ is a hash of options for the new process;
+  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  # 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
@@ -758,3 +1187,6 @@ module Open3
   end
 
 end
+
+# JRuby uses different popen logic on Windows, require it here to reuse wrapper methods above.
+require 'open3/jruby_windows' if RUBY_ENGINE == 'jruby' && JRuby::Util::ON_WINDOWS

data/open3.gemspec

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 name = File.basename(__FILE__, ".gemspec")
-version = ["lib", Array.new(name.count("-"), "..").join("/")].find do |dir|
-  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}.rb")) do |line|
+version = ["lib", Array.new(name.count("-")+1, "..").join("/")].find do |dir|
+  break File.foreach(File.join(__dir__, dir, "#{name.tr('-', '/')}/version.rb")) do |line|
     /^\s*VERSION\s*=\s*"(.*)"/ =~ line and break $1
   end rescue nil
 end
@@ -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.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Yukihiro Matsumoto
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-22 00:00:00.000000000 Z
+date: 2023-11-07 00:00:00.000000000 Z
 dependencies: []
 description: Popen, but with stderr, too
 email:
@@ -17,6 +17,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
+- ".github/workflows/test-jruby.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - Gemfile
@@ -26,6 +28,8 @@ files:
 - bin/console
 - bin/setup
 - lib/open3.rb
+- lib/open3/jruby_windows.rb
+- lib/open3/version.rb
 - open3.gemspec
 homepage: https://github.com/ruby/open3
 licenses:
@@ -49,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.2
+rubygems_version: 3.5.0.dev
 signing_key:
 specification_version: 4
 summary: Popen, but with stderr, too