diff options
Diffstat (limited to 'lib/open3.rb')
| -rw-r--r-- | lib/open3.rb | 1274 |
1 files changed, 962 insertions, 312 deletions
diff --git a/lib/open3.rb b/lib/open3.rb index c574696bb1..74d00b86d9 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -29,58 +29,191 @@ # - Open3.pipeline : run a pipeline and wait for its completion # +require 'open3/version' + +# \Module \Open3 supports creating child processes +# with access to their $stdin, $stdout, and $stderr streams. +# +# == What's Here +# +# Each of these methods executes a given command in a new process or subshell, +# or multiple commands in new processes and/or subshells: +# +# - Each of these methods executes a single command in a process or subshell, +# accepts a string for input to $stdin, +# and returns string output from $stdout, $stderr, or both: +# +# - Open3.capture2: Executes the command; +# returns the string from $stdout. +# - Open3.capture2e: Executes the command; +# returns the string from merged $stdout and $stderr. +# - Open3.capture3: Executes the command; +# returns strings from $stdout and $stderr. +# +# - Each of these methods executes a single command in a process or subshell, +# and returns pipes for $stdin, $stdout, and/or $stderr: +# +# - Open3.popen2: Executes the command; +# returns pipes for $stdin and $stdout. +# - Open3.popen2e: Executes the command; +# returns pipes for $stdin and merged $stdout and $stderr. +# - Open3.popen3: Executes the command; +# returns pipes for $stdin, $stdout, and $stderr. +# +# - Each of these methods executes one or more commands in processes and/or subshells, +# returns pipes for the first $stdin, the last $stdout, or both: +# +# - Open3.pipeline_r: Returns a pipe for the last $stdout. +# - Open3.pipeline_rw: Returns pipes for the first $stdin and the last $stdout. +# - Open3.pipeline_w: Returns a pipe for the first $stdin. +# - Open3.pipeline_start: Does not wait for processes to complete. +# - Open3.pipeline: Waits for processes to complete. +# +# Each of the methods above accepts: +# +# - An optional hash of environment variable names and values; +# see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. +# - A required string argument that is a +command_line+ or +exe_path+; +# see {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. +# - An optional hash of execution options; +# see {Execution Options}[rdoc-ref:Process@Execution+Options]. +# 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}[rdoc-ref:Process.spawn] + # that: + # + # - Creates a child process, by calling Process.spawn with the given arguments. + # - Creates streams +stdin+, +stdout+, and +stderr+, + # which are the standard input, standard output, and standard error streams + # in the child process. + # - Creates thread +wait_thread+ that waits for the child process to exit; + # the thread has method +pid+, which returns the process ID + # of the child process. + # + # With no block given, returns the array + # <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@Command+Injection]. # - # 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. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in the call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # The single required argument is one of the following: + # + # - +command_line+ if it is a string, + # and if it begins with a shell reserved word or special built-in, + # or if it contains one or more metacharacters. + # - +exe_path+ otherwise. # - # 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: + # <b>Argument +command_line+</b> # - # 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| ... } + # \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: # - # If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn. + # 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. # - # Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t| - # p o.read.chomp #=> "/" - # } + # Output (similar for each call above): # - # wait_thr.value waits for the termination of the process. - # The block form also waits for the process when it returns. + # [#<IO:(closed)>, #<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f58d52f28c8 dead>] # - # Closing stdin, stdout and stderr does not wait for the process to complete. + # 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: # - # 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. + # Open3.popen3('/usr/bin/date') { |i, o, e, t| o.gets } + # # => "Wed Sep 27 02:56:44 PM CDT 2023\n" + # + # Ruby invokes the executable directly, with no shell and no shell expansion: + # + # Open3.popen3('doesnt_exist') { |i, o, e, t| o.gets } # Raises Errno::ENOENT + # + # If one or more +args+ is given, each is an argument or option + # to be passed to the executable: + # + # Open3.popen3('echo', 'C #') { |i, o, e, t| o.gets } + # # => "C #\n" + # Open3.popen3('echo', 'hello', 'world') { |i, o, e, t| o.gets } + # # => "hello world\n" + # + # Take care to avoid deadlocks. + # Output streams +stdout+ and +stderr+ have fixed-size buffers, + # so reading extensively from one but not the other can cause a deadlock + # when the unread buffer fills. + # To avoid that, +stdout+ and +stderr+ should be read simultaneously + # (using threads or IO.select). + # + # Related: + # + # - Open3.popen2: Makes the standard input and standard output streams + # of the child process available as separate streams, + # with no access to the standard error stream. + # - Open3.popen2e: Makes the standard input and the merge + # of the standard output and standard error streams + # of the child process available as separate streams. # def popen3(*cmd, &block) if Hash === cmd.last @@ -103,45 +236,131 @@ 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}[rdoc-ref:Process.spawn] + # that: + # + # - Creates a child process, by calling Process.spawn with the given arguments. + # - Creates streams +stdin+ and +stdout+, + # which are the standard input and standard output streams + # in the child process. + # - Creates thread +wait_thread+ that waits for the child process to exit; + # the thread has method +pid+, which returns the process ID + # of the child process. + # + # With no block given, returns the array + # <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@Command+Injection]. # - # 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. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in the call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # The single required argument is one of the following: # - # See Process.spawn for the optional hash arguments _env_ and _opts_. + # - +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): + # + # # => [#<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" + # + # 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("bc -q") {|i,o,t| - # i.puts "obase=13" - # i.puts "6 * 9" - # p o.gets #=> "42\n" - # } + # 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 @@ -161,36 +380,130 @@ 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}[rdoc-ref:Process.spawn] + # that: + # + # - Creates a child process, by calling Process.spawn with the given arguments. + # - Creates streams +stdin+, +stdout_and_stderr+, + # which are the standard input 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@Command+Injection]. # - # 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. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in the call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # The single required argument is one of the following: + # + # - +command_line+ if it is a string, + # and if it begins with a shell reserved word or special built-in, + # or if it contains one or more metacharacters. + # - +exe_path+ otherwise. + # + # <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.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>] # - # See Process.spawn for the optional hash arguments _env_ and _opts_. + # 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 +550,100 @@ 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@Command+Injection]. # - # # dot is a command of graphviz. - # graph = <<'End' - # digraph g { - # a -> b - # } - # End - # drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph) + # Unlike Process.spawn, this method waits for the child process to exit + # before returning, so the caller need not do so. # - # 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> + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Open3.popen3; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. # - # # 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 + # If the last argument is a hash, it becomes trailing argument +options+ + # in the call to Open3.popen3; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # The hash +options+ is given; + # two options have local effect in method Open3.capture3: + # + # - If entry <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 and + # the internal streams are set to binary mode. + # + # The single required argument is one of the following: + # + # - +command_line+ if it is a string, + # and if it begins with a shell reserved word or special built-in, + # or if it contains one or more metacharacters. + # - +exe_path+ otherwise. + # + # <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 +677,100 @@ 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@Command+Injection]. + # + # 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]) + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Open3.popen3; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. # - # 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 the last argument is a hash, it becomes trailing argument +options+ + # in the call to Open3.popen3; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. # - # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input. + # The hash +options+ is given; + # two options have local effect in method Open3.capture2: # - # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode. + # - 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.capture2('tee', stdin_data: 'Foo') + # + # # => ["Foo", #<Process::Status: pid 2326087 exit 0>] + # + # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and + # the internal streams are set to binary mode. + # + # The single required argument is one of the following: + # + # - +command_line+ if it is a string, + # and if it begins with a shell reserved word or special built-in, + # or if it contains one or more metacharacters. + # - +exe_path+ otherwise. + # + # <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 +804,100 @@ 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>] + # + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. + # + # Unlike Process.spawn, this method waits for the child process to exit + # before returning, so the caller need not do so. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in the call to Open3.popen3; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in the call to Open3.popen3; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # The hash +options+ is given; + # two options have local effect in method Open3.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: # - # stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts]) + # Open3.capture2e('tee', stdin_data: 'Foo') + # # => ["Foo", #<Process::Status: pid 2371732 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. + # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and + # the internal streams are set to binary mode. # - # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input. + # The single required argument is one of the following: # - # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode. + # - +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 @@ -417,48 +931,86 @@ module Open3 end 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| - # ... - # } + # :call-seq: + # Open3.pipeline_rw([env, ] *cmds, options = {}) -> [first_stdin, last_stdout, wait_threads] # - # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw(cmd1, cmd2, ... [, opts]) - # ... - # first_stdin.close - # last_stdout.close + # Basically a wrapper for + # {Process.spawn}[rdoc-ref:Process.spawn] + # that: # - # Each cmd is a string or an array. - # If it is an array, the elements are passed to Process.spawn. + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Pipes the +stdout+ from each child to the +stdin+ of the next child, + # or, for the first child, from the caller's +stdin+, + # or, for the last child, to the caller's +stdout+. # - # cmd: - # 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) + # The method does not wait for child processes to exit, + # so the caller must do so. # - # Note that env and opts are optional, as for Process.spawn. + # With no block given, returns a 3-element array containing: # - # 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. + # - The +stdin+ stream of the first child process. + # - The +stdout+ stream of the last child process. + # - An array of the wait threads for all of the child processes. # # Example: # - # 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." - # i.close - # p o.gets #=> "42\n" - # } - # - # Open3.pipeline_rw("sort", "cat -n") {|stdin, stdout, wait_thrs| - # stdin.puts "foo" - # stdin.puts "bar" - # stdin.puts "baz" - # stdin.close # send EOF to sort. - # p stdout.read #=> " 1\tbar\n 2\tbaz\n 3\tfoo\n" - # } + # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('sort', 'cat -n') + # # => [#<IO:fd 20>, #<IO:fd 21>, [#<Process::Waiter:0x000055e8de29ab40 sleep>, #<Process::Waiter:0x000055e8de29a690 sleep>]] + # first_stdin.puts("foo\nbar\nbaz") + # first_stdin.close # Send EOF to sort. + # puts last_stdout.read + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # + # Output: + # + # 1 bar + # 2 baz + # 3 foo + # + # With a block given, calls the block with the +stdin+ stream of the first child, + # the +stdout+ stream of the last child, + # and an array of the wait processes: + # + # Open3.pipeline_rw('sort', 'cat -n') do |first_stdin, last_stdout, wait_threads| + # first_stdin.puts "foo\nbar\nbaz" + # first_stdin.close # send EOF to sort. + # puts last_stdout.read + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # end + # + # Output: + # + # 1 bar + # 2 baz + # 3 foo + # + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # Each remaining argument in +cmds+ is one of: + # + # - A +command_line+: a string that begins with a shell reserved word + # or special built-in, or contains one or more metacharacters. + # - An +exe_path+: the string path to an executable to be called. + # - An array containing a +command_line+ or an +exe_path+, + # along with zero or more string arguments for the command. + # + # See {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. + # def pipeline_rw(*cmds, &block) if Hash === cmds.last opts = cmds.pop.dup @@ -477,43 +1029,77 @@ module Open3 end 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. + # :call-seq: + # Open3.pipeline_r([env, ] *cmds, options = {}) -> [last_stdout, wait_threads] # - # Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads| - # ... - # } + # Basically a wrapper for + # {Process.spawn}[rdoc-ref:Process.spawn] + # that: # - # last_stdout, wait_threads = Open3.pipeline_r(cmd1, cmd2, ... [, opts]) - # ... - # last_stdout.close + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Pipes the +stdout+ from each child to the +stdin+ of the next child, + # or, for the last child, to the caller's +stdout+. # - # Each cmd is a string or an array. - # If it is an array, the elements are passed to Process.spawn. + # The method does not wait for child processes to exit, + # so the caller must do so. # - # cmd: - # 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) + # With no block given, returns a 2-element array containing: # - # Note that env and opts are optional, as for Process.spawn. + # - The +stdout+ stream of the last child process. + # - An array of the wait threads for all of the child processes. # # Example: # - # Open3.pipeline_r("zcat /var/log/apache2/access.log.*.gz", - # [{"LANG"=>"C"}, "grep", "GET /favicon.ico"], - # "logresolve") {|o, ts| - # o.each_line {|line| - # ... - # } - # } + # last_stdout, wait_threads = Open3.pipeline_r('ls', 'grep R') + # # => [#<IO:fd 5>, [#<Process::Waiter:0x000055e8de2f9898 dead>, #<Process::Waiter:0x000055e8de2f94b0 sleep>]] + # puts last_stdout.read + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # + # Output: + # + # Rakefile + # README.md + # + # With a block given, calls the block with the +stdout+ stream + # of the last child process, + # and an array of the wait processes: + # + # Open3.pipeline_r('ls', 'grep R') do |last_stdout, wait_threads| + # puts last_stdout.read + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # end + # + # Output: + # + # Rakefile + # README.md + # + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # Each remaining argument in +cmds+ is one of: # - # 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> - # } + # - A +command_line+: a string that begins with a shell reserved word + # or special built-in, or contains one or more metacharacters. + # - An +exe_path+: the string path to an executable to be called. + # - An array containing a +command_line+ or an +exe_path+, + # along with zero or more string arguments for the command. + # + # See {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. # def pipeline_r(*cmds, &block) if Hash === cmds.last @@ -529,33 +1115,82 @@ module Open3 end 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. + + # :call-seq: + # Open3.pipeline_w([env, ] *cmds, options = {}) -> [first_stdin, wait_threads] # - # Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads| - # ... - # } + # Basically a wrapper for + # {Process.spawn}[rdoc-ref:Process.spawn] + # that: # - # first_stdin, wait_threads = Open3.pipeline_w(cmd1, cmd2, ... [, opts]) - # ... - # first_stdin.close + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Pipes the +stdout+ from each child to the +stdin+ of the next child, + # or, for the first child, pipes the caller's +stdout+ to the child's +stdin+. # - # Each cmd is a string or an array. - # If it is an array, the elements are passed to Process.spawn. + # The method does not wait for child processes to exit, + # so the caller must do so. # - # cmd: - # 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) + # With no block given, returns a 2-element array containing: # - # Note that env and opts are optional, as for Process.spawn. + # - The +stdin+ stream of the first child process. + # - An array of the wait threads for all of the child processes. # # Example: # - # Open3.pipeline_w("bzip2 -c", :out=>"/tmp/hello.bz2") {|i, ts| - # i.puts "hello" - # } + # first_stdin, wait_threads = Open3.pipeline_w('sort', 'cat -n') + # # => [#<IO:fd 7>, [#<Process::Waiter:0x000055e8de928278 run>, #<Process::Waiter:0x000055e8de923e80 run>]] + # first_stdin.puts("foo\nbar\nbaz") + # first_stdin.close # Send EOF to sort. + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # + # Output: + # + # 1 bar + # 2 baz + # 3 foo + # + # With a block given, calls the block with the +stdin+ stream + # of the first child process, + # and an array of the wait processes: + # + # Open3.pipeline_w('sort', 'cat -n') do |first_stdin, wait_threads| + # first_stdin.puts("foo\nbar\nbaz") + # first_stdin.close # Send EOF to sort. + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # end + # + # Output: + # + # 1 bar + # 2 baz + # 3 foo + # + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # Each remaining argument in +cmds+ is one of: + # + # - A +command_line+: a string that begins with a shell reserved word + # or special built-in, or contains one or more metacharacters. + # - An +exe_path+: the string path to an executable to be called. + # - An array containing a +command_line+ or an +exe_path+, + # along with zero or more string arguments for the command. + # + # See {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. # def pipeline_w(*cmds, &block) if Hash === cmds.last @@ -572,49 +1207,67 @@ module Open3 end module_function :pipeline_w - # Open3.pipeline_start starts a list of commands as a pipeline. - # No pipes are created for stdin of the first command and - # stdout of the last command. + # :call-seq: + # Open3.pipeline_start([env, ] *cmds, options = {}) -> [wait_threads] # - # Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads| - # ... - # } + # Basically a wrapper for + # {Process.spawn}[rdoc-ref:Process.spawn] + # that: # - # wait_threads = Open3.pipeline_start(cmd1, cmd2, ... [, opts]) - # ... + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Does not wait for child processes to exit. # - # Each cmd is a string or an array. - # If it is an array, the elements are passed to Process.spawn. + # With no block given, returns an array of the wait threads + # for all of the child processes. # - # cmd: - # 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) + # Example: # - # Note that env and opts are optional, as for Process.spawn. + # wait_threads = Open3.pipeline_start('ls', 'grep R') + # # => [#<Process::Waiter:0x000055e8de9d2bb0 run>, #<Process::Waiter:0x000055e8de9d2890 run>] + # wait_threads.each do |wait_thread| + # wait_thread.join + # end # - # Example: + # Output: + # + # Rakefile + # README.md + # + # With a block given, calls the block with an array of the wait processes: + # + # Open3.pipeline_start('ls', 'grep R') do |wait_threads| + # wait_threads.each do |wait_thread| + # wait_thread.join + # end + # end + # + # Output: + # + # Rakefile + # README.md + # + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. # - # # Run xeyes in 10 seconds. - # Open3.pipeline_start("xeyes") {|ts| - # sleep 10 - # t = ts[0] - # Process.kill("TERM", t.pid) - # p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)> - # } - # - # # Convert pdf to ps and send it to a printer. - # # Collect error message of pdftops and lpr. - # pdf_file = "paper.pdf" - # printer = "printer-name" - # err_r, err_w = IO.pipe - # Open3.pipeline_start(["pdftops", pdf_file, "-"], - # ["lpr", "-P#{printer}"], - # :err=>err_w) {|ts| - # err_w.close - # p err_r.read # error messages of pdftops and lpr. - # } + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # Each remaining argument in +cmds+ is one of: + # + # - A +command_line+: a string that begins with a shell reserved word + # or special built-in, or contains one or more metacharacters. + # - An +exe_path+: the string path to an executable to be called. + # - An array containing a +command_line+ or an +exe_path+, + # along with zero or more string arguments for the command. + # + # See {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. # def pipeline_start(*cmds, &block) if Hash === cmds.last @@ -632,57 +1285,51 @@ module Open3 end module_function :pipeline_start - # Open3.pipeline starts a list of commands as a pipeline. - # It waits for the completion of the commands. - # No pipes are created for stdin of the first command and - # stdout of the last command. + # :call-seq: + # Open3.pipeline([env, ] *cmds, options = {}) -> array_of_statuses # - # status_list = Open3.pipeline(cmd1, cmd2, ... [, opts]) + # Basically a wrapper for + # {Process.spawn}[rdoc-ref:Process.spawn] + # that: # - # Each cmd is a string or an array. - # If it is an array, the elements are passed to Process.spawn. + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Pipes the +stdout+ from each child to the +stdin+ of the next child, + # or, for the last child, to the caller's +stdout+. + # - Waits for the child processes to exit. + # - Returns an array of Process::Status objects (one for each child). # - # cmd: - # 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) + # Example: # - # Note that env and opts are optional, as Process.spawn. + # wait_threads = Open3.pipeline('ls', 'grep R') + # # => [#<Process::Status: pid 2139200 exit 0>, #<Process::Status: pid 2139202 exit 0>] # - # Example: + # Output: + # + # Rakefile + # README.md # - # fname = "/usr/share/man/man1/ruby.1.gz" - # p Open3.pipeline(["zcat", fname], "nroff -man", "less") - # #=> [#<Process::Status: pid 11817 exit 0>, - # # #<Process::Status: pid 11820 exit 0>, - # # #<Process::Status: pid 11828 exit 0>] - # - # fname = "/usr/share/man/man1/ls.1.gz" - # Open3.pipeline(["zcat", fname], "nroff -man", "colcrt") - # - # # convert PDF to PS and send to a printer by lpr - # pdf_file = "paper.pdf" - # printer = "printer-name" - # Open3.pipeline(["pdftops", pdf_file, "-"], - # ["lpr", "-P#{printer}"]) - # - # # count lines - # Open3.pipeline("sort", "uniq -c", :in=>"names.txt", :out=>"count") - # - # # cyclic pipeline - # r,w = IO.pipe - # w.print "ibase=14\n10\n" - # Open3.pipeline("bc", "tee /dev/tty", :in=>r, :out=>w) - # #=> 14 - # # 18 - # # 22 - # # 30 - # # 42 - # # 58 - # # 78 - # # 106 - # # 202 + # Like Process.spawn, this method has potential security vulnerabilities + # if called with untrusted input; + # see {Command Injection}[rdoc-ref:command_injection.rdoc@Command+Injection]. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn' + # see {Execution Options}[rdoc-ref:Process@Execution+Options]. + # + # Each remaining argument in +cmds+ is one of: + # + # - A +command_line+: a string that begins with a shell reserved word + # or special built-in, or contains one or more metacharacters. + # - An +exe_path+: the string path to an executable to be called. + # - An array containing a +command_line+ or an +exe_path+, + # along with zero or more string arguments for the command. + # + # See {Argument command_line or exe_path}[rdoc-ref:Process@Argument+command_line+or+exe_path]. # def pipeline(*cmds) if Hash === cmds.last @@ -758,3 +1405,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 |