# frozen_string_literal: true
# = open3.rb: Popen, but with stderr, too
# Author:: Yukihiro Matsumoto
# Documentation:: Konrad Meyer
# Open3 gives you access to stdin, stdout, and stderr when running other
# Open3 grants you access to stdin, stdout, stderr and a thread to wait for the
# child process when running another program.
# You can specify various attributes, redirections, current directory, etc., of
# the program in the same way as for Process.spawn.
# - Open3.popen3 : pipes for stdin, stdout, stderr
# - Open3.popen2 : pipes for stdin, stdout
# - Open3.popen2e : pipes for stdin, merged stdout and stderr
# - Open3.capture3 : give a string for stdin; get strings for stdout, stderr
# - Open3.capture2 : give a string for stdin; get a string for stdout
# - Open3.capture2e : give a string for stdin; get a string for merged stdout and stderr
# - Open3.pipeline_rw : pipes for first stdin and last stdout of a pipeline
# - Open3.pipeline_r : pipe for last stdout of a pipeline
# - Open3.pipeline_w : pipe for first stdin of a pipeline
# - Open3.pipeline_start : run a pipeline without waiting
# - Open3.pipeline : run a pipeline and wait for its completion
# 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
# 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.
# 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.
# exit_status = wait_thr.value # Process::Status object returned.
# 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:
# 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| ... }
# If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
# Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t|
# wait_thr.value waits for the termination of the process.
# The block form also waits for the process when it returns.
# Closing stdin, stdout and stderr does not wait for the process to complete.
# 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.
def popen3(*cmd, **opts, &block)
popen_run(cmd, opts, [in_r, out_w, err_w], [in_w, out_r, err_r], &block)
# Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
# the standard error stream.
# 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.
# stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts])
# stdin.close # stdin and stdout should be closed explicitly in this form.
# See Process.spawn for the optional hash arguments _env_ and _opts_.
# Open3.popen2("wc -c") {|i,o,t|
# i.print "answer to life the universe and everything"
# Open3.popen2("bc -q") {|i,o,t|
# Open3.popen2("dc") {|i,o,t|
def popen2(*cmd, **opts, &block)
popen_run(cmd, opts, [in_r, out_w], [in_w, out_r], &block)
# Open3.popen2e is similar to Open3.popen3 except that it merges
# the standard output stream and the standard error stream.
# 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.
# 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
# See Process.spawn for the optional hash arguments _env_ and _opts_.
# Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
def popen2e(*cmd, **opts, &block)
opts[[:out, :err]] = out_w
popen_run(cmd, opts, [in_r, out_w], [in_w, out_r], &block)
def popen_run(cmd, opts, child_io, parent_io) # :nodoc:
if last = Hash.try_convert(cmd.last)
wait_thr = Process.detach(pid)
result = [*parent_io, wait_thr]
module_function :popen_run
# Open3.capture3 captures the standard output and the standard error of a command.
# stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
# 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 <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
# If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
# # dot is a command of graphviz.
# 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 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)
# STDOUT.binmode; print thumbnail
def capture3(*cmd, stdin_data: '', binmode: false, **opts)
popen3(*cmd, opts) {|i, o, e, t|
out_reader = Thread.new { o.read }
err_reader = Thread.new { e.read }
if stdin_data.respond_to? :readpartial
IO.copy_stream(stdin_data, i)
[out_reader.value, err_reader.value, t.value]
module_function :capture3
# Open3.capture2 captures the standard output of a command.
# stdout_str, status = Open3.capture2([env,] cmd... [, opts])
# 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 <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
# If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
# # factor is a command for integer factorization.
# o, s = Open3.capture2("factor", :stdin_data=>"42")
# # generate x**2 graph in png using gnuplot.
# gnuplot_commands = <<"End"
# plot x**2, "-" with lines
# image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
def capture2(*cmd, stdin_data: nil, binmode: false, **opts)
popen2(*cmd, opts) {|i, o, t|
out_reader = Thread.new { o.read }
if stdin_data.respond_to? :readpartial
IO.copy_stream(stdin_data, i)
[out_reader.value, t.value]
module_function :capture2
# Open3.capture2e captures the standard output and the standard error of a command.
# stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
# 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 <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
# If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
# make_log, s = Open3.capture2e("make")
def capture2e(*cmd, stdin_data: nil, binmode: false, **opts)
popen2e(*cmd, opts) {|i, oe, t|
outerr_reader = Thread.new { oe.read }
if stdin_data.respond_to? :readpartial
IO.copy_stream(stdin_data, i)
[outerr_reader.value, t.value]
module_function :capture2e
# Open3.pipeline_rw starts a list of commands as a pipeline with pipes
# which connect to stdin of the first command and stdout of the last command.
# Open3.pipeline_rw(cmd1, cmd2, ... [, opts]) {|first_stdin, last_stdout, wait_threads|
# first_stdin, last_stdout, wait_threads = Open3.pipeline_rw(cmd1, cmd2, ... [, opts])
# Each cmd is a string or an array.
# If it is an array, the elements are passed to Process.spawn.
# commandline command line string which is passed to a shell
# [env, commandline, opts] command line string which is passed to a shell
# [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
# [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
# Note that env and opts are optional, as for Process.spawn.
# The options to pass to Process.spawn are constructed by merging
# +opts+, the last hash element of the array, and
# specifications for the pipes between each of the commands.
# Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i, o, ts|
# i.puts "All persons more than a mile high to leave the court."
# Open3.pipeline_rw("sort", "cat -n") {|stdin, stdout, wait_thrs|
# stdin.close # send EOF to sort.
# p stdout.read #=> " 1\tbar\n 2\tbaz\n 3\tfoo\n"
def pipeline_rw(*cmds, **opts, &block)
pipeline_run(cmds, opts, [in_r, out_w], [in_w, out_r], &block)
module_function :pipeline_rw
# Open3.pipeline_r starts a list of commands as a pipeline with a pipe
# which connects to stdout of the last command.
# Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads|
# last_stdout, wait_threads = Open3.pipeline_r(cmd1, cmd2, ... [, opts])
# Each cmd is a string or an array.
# If it is an array, the elements are passed to Process.spawn.
# commandline command line string which is passed to a shell
# [env, commandline, opts] command line string which is passed to a shell
# [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
# [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
# Note that env and opts are optional, as for Process.spawn.
# Open3.pipeline_r("zcat /var/log/apache2/access.log.*.gz",
# [{"LANG"=>"C"}, "grep", "GET /favicon.ico"],
# Open3.pipeline_r("yes", "head -10") {|o, ts|
# p o.read #=> "y\ny\ny\ny\ny\ny\ny\ny\ny\ny\n"
# p ts[0].value #=> #<Process::Status: pid 24910 SIGPIPE (signal 13)>
# p ts[1].value #=> #<Process::Status: pid 24913 exit 0>
def pipeline_r(*cmds, **opts, &block)
pipeline_run(cmds, opts, [out_w], [out_r], &block)
module_function :pipeline_r
# Open3.pipeline_w starts a list of commands as a pipeline with a pipe
# which connects to stdin of the first command.
# Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads|
# first_stdin, wait_threads = Open3.pipeline_w(cmd1, cmd2, ... [, opts])
# Each cmd is a string or an array.
# If it is an array, the elements are passed to Process.spawn.
# commandline command line string which is passed to a shell
# [env, commandline, opts] command line string which is passed to a shell
# [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
# [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
# Note that env and opts are optional, as for Process.spawn.
# Open3.pipeline_w("bzip2 -c", :out=>"/tmp/hello.bz2") {|i, ts|
def pipeline_w(*cmds, **opts, &block)
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
