From aa8aa50e2126dfb87b88f7e21ff83494643fe1e4 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 20 Nov 2023 13:38:25 -0600 Subject: [PATCH 01/10] RDoc for Open3 --- lib/open3.rb | 183 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 109 insertions(+), 74 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 13606ce..458c642 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -899,48 +899,73 @@ def capture2e(*cmd) 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}[https://docs.ruby-lang.org/en/master/Process.html#method-c-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+. + # - Waits for all child processes to exit. # - # 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 3-element array containing: # - # 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. + # - 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" - # } + # Open3.pipeline_rw("sort", "cat -n") + # # => [#, #, [#, #]] + # + # 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, ts| + # first_stdin.puts "foo" + # first_stdin.puts "bar" + # first_stdin.puts "baz" + # first_stdin.close # send EOF to sort. + # puts last_stdout.read + # 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]. + # + # Unlike Process.spawn, this method waits for the child processes to exit + # before returning, so the caller need not do so. + # + # If the first argument is a hash, it becomes leading argument +env+ + # in each call to Process.spawn; + # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-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. + # def pipeline_rw(*cmds, &block) if Hash === cmds.last opts = cmds.pop.dup @@ -986,8 +1011,8 @@ def pipeline_rw(*cmds, &block) # of the last child process, # and an array of the wait processes: # - # Open3.pipeline_r('ls', 'grep R') do |x, ts| - # puts x.read + # Open3.pipeline_r('ls', 'grep R') do |last_stdout, ts| + # puts last_stdout.read # p ts # end # @@ -1068,8 +1093,8 @@ def pipeline_r(*cmds, &block) # Open3.pipeline_r( # ['ruby', '-e', 'print "Foo"'], # ['ruby', '-e', 'print STDIN.read + "Bar"'] - # ) do |x, ts| - # puts x.read + # ) do |first_stdin, ts| + # puts first_stdin.read # p ts # end # @@ -1116,49 +1141,59 @@ def pipeline_w(*cmds, &block) 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}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn] + # that: # - # wait_threads = Open3.pipeline_start(cmd1, cmd2, ... [, opts]) - # ... + # - Creates a child process for each of the given +cmds+ + # by calling Process.spawn. + # - Waits for all 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 threads0 + # 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. + # Open3.pipeline_start("sort", "cat -n") + # # => [#, #] # - # Example: + # 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_start("sort", "cat -n") do |ts| + # p ts + # end + # + # Output: + # + # # => [#, #] + # + # 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 processes to exit + # before returning, so the caller need not do so. # - # # Run xeyes in 10 seconds. - # Open3.pipeline_start("xeyes") {|ts| - # sleep 10 - # t = ts[0] - # Process.kill("TERM", t.pid) - # p t.value #=> # - # } - # - # # 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}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. + # + # If the last argument is a hash, it becomes trailing argument +options+ + # in each call to Process.spawn; + # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-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. # def pipeline_start(*cmds, &block) if Hash === cmds.last From 85a7799c355b3739da7b8bc50813b0275c700a6b Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 20 Nov 2023 13:49:21 -0600 Subject: [PATCH 02/10] RDoc for Open3 --- lib/open3.rb | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 458c642..6e4637d 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -929,12 +929,13 @@ def capture2e(*cmd) # 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, ts| + # Open3.pipeline_rw("sort", "cat -n") do |first_stdin, last_stdout, wait_threads| # first_stdin.puts "foo" # first_stdin.puts "bar" # first_stdin.puts "baz" # first_stdin.close # send EOF to sort. # puts last_stdout.read + # p wait_threads # end # # Output: @@ -942,6 +943,7 @@ def capture2e(*cmd) # 1 bar # 2 baz # 3 foo + # [#, #] # # Like Process.spawn, this method has potential security vulnerabilities # if called with untrusted input; @@ -1011,9 +1013,9 @@ def pipeline_rw(*cmds, &block) # of the last child process, # and an array of the wait processes: # - # Open3.pipeline_r('ls', 'grep R') do |last_stdout, ts| + # Open3.pipeline_r('ls', 'grep R') do |last_stdout, wait_threads| # puts last_stdout.read - # p ts + # p wait_threads # end # # Output: @@ -1093,9 +1095,9 @@ def pipeline_r(*cmds, &block) # Open3.pipeline_r( # ['ruby', '-e', 'print "Foo"'], # ['ruby', '-e', 'print STDIN.read + "Bar"'] - # ) do |first_stdin, ts| + # ) do |first_stdin, wait_threads| # puts first_stdin.read - # p ts + # p wait_threads # end # # Output: @@ -1164,8 +1166,8 @@ def pipeline_w(*cmds, &block) # of the last child process, # and an array of the wait processes: # - # Open3.pipeline_start("sort", "cat -n") do |ts| - # p ts + # Open3.pipeline_start("sort", "cat -n") do |wait_threads| + # p wait_threads # end # # Output: From 26f777acbe02db2fcddb48e619907dcd26f793ca Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 09:32:09 -0600 Subject: [PATCH 03/10] RDoc for Open3 --- lib/open3.rb | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 6e4637d..4d032b6 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -911,11 +911,10 @@ def capture2e(*cmd) # - 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+. - # - Waits for all child processes to exit. + # - Does not wait for child processes to exit. # # With no block given, returns a 3-element array containing: # - # # - 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. @@ -997,7 +996,7 @@ def pipeline_rw(*cmds, &block) # 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 all child processes to exit. + # - Does not wait for child processes to exit. # # With no block given, returns a 2-element array containing: # @@ -1073,7 +1072,7 @@ def pipeline_r(*cmds, &block) # 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+. - # - Waits for all child processes to exit. + # - Does not wait for child processes to exit. # # With no block given, returns a 2-element array containing: # @@ -1152,7 +1151,7 @@ def pipeline_w(*cmds, &block) # # - Creates a child process for each of the given +cmds+ # by calling Process.spawn. - # - Waits for all child processes to exit. + # - Does not wait for child processes to exit. # # With no block given, returns an array of the wait threads0 # for all of the child processes. @@ -1224,7 +1223,7 @@ def pipeline_start(*cmds, &block) # 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 all child processes to exit. + # - Does not wait for child processes to exit. # - Returns an array of Process::Status objects (one for each child). # # A simple example: From 2966d045e8d9eea800711ca54700578a27a09294 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 09:35:58 -0600 Subject: [PATCH 04/10] RDoc for Open3 --- lib/open3.rb | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 4d032b6..6653ee7 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -948,9 +948,6 @@ def capture2e(*cmd) # if called with untrusted input; # see {Command Injection}[rdoc-ref:command_injection.rdoc]. # - # Unlike Process.spawn, this method waits for the child processes to exit - # before returning, so the caller need not do so. - # # If the first argument is a hash, it becomes leading argument +env+ # in each call to Process.spawn; # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. @@ -1027,9 +1024,6 @@ def pipeline_rw(*cmds, &block) # if called with untrusted input; # see {Command Injection}[rdoc-ref:command_injection.rdoc]. # - # Unlike Process.spawn, this method waits for the child processes to exit - # before returning, so the caller need not do so. - # # If the first argument is a hash, it becomes leading argument +env+ # in each call to Process.spawn; # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. @@ -1108,9 +1102,6 @@ def pipeline_r(*cmds, &block) # if called with untrusted input; # see {Command Injection}[rdoc-ref:command_injection.rdoc]. # - # Unlike Process.spawn, this method waits for the child processes to exit - # before returning, so the caller need not do so. - # # If the first argument is a hash, it becomes leading argument +env+ # in each call to Process.spawn; # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. @@ -1177,9 +1168,6 @@ def pipeline_w(*cmds, &block) # if called with untrusted input; # see {Command Injection}[rdoc-ref:command_injection.rdoc]. # - # Unlike Process.spawn, this method waits for the child processes to exit - # before returning, so the caller need not do so. - # # If the first argument is a hash, it becomes leading argument +env+ # in each call to Process.spawn; # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. @@ -1242,9 +1230,6 @@ def pipeline_start(*cmds, &block) # 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. - # # If the first argument is a hash, it becomes leading argument +env+ # in each call to Process.spawn; # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment]. From 246362ce9ffb81dae701144f200d666ea2de33d6 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 10:17:31 -0600 Subject: [PATCH 05/10] RDoc for Open3 --- lib/open3.rb | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 6653ee7..c70026d 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -911,7 +911,9 @@ def capture2e(*cmd) # - 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+. - # - Does not wait for child processes to exit. + # + # The method does not wait for child processes to exit, + # so the caller must do so. # # With no block given, returns a 3-element array containing: # @@ -921,20 +923,29 @@ def capture2e(*cmd) # # Example: # - # Open3.pipeline_rw("sort", "cat -n") - # # => [#, #, [#, #]] + # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('ls', 'grep R') + # # => [#, #, [#, #]] + # 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 +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" - # first_stdin.puts "bar" - # first_stdin.puts "baz" + # 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 - # p wait_threads + # wait_threads.each do |wait_thread| + # wait_thread.join + # end # end # # Output: @@ -942,7 +953,6 @@ def capture2e(*cmd) # 1 bar # 2 baz # 3 foo - # [#, #] # # Like Process.spawn, this method has potential security vulnerabilities # if called with untrusted input; @@ -1149,14 +1159,18 @@ def pipeline_w(*cmds, &block) # # Example: # - # Open3.pipeline_start("sort", "cat -n") - # # => [#, #] + # wait_threads = Open3.pipeline_start('sort', 'cat -n') + # # => [#, #] + # + # wait_threads.each do |wait_thread| + # wait_thread.wait + # end # # 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_start("sort", "cat -n") do |wait_threads| + # Open3.pipeline_start('sort', 'cat -n') do |wait_threads| # p wait_threads # end # From aca17f07e55a6e37d4fa4871e35b6bbd1f0794e6 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 10:25:40 -0600 Subject: [PATCH 06/10] RDoc for Open3 --- lib/open3.rb | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index c70026d..1f662fa 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -923,8 +923,10 @@ def capture2e(*cmd) # # Example: # - # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('ls', 'grep R') - # # => [#, #, [#, #]] + # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('sort', 'cat -n') + # # => [#, #, [#, #]] + # 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 @@ -932,8 +934,9 @@ def capture2e(*cmd) # # Output: # - # Rakefile - # README.md + # 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, From 78570d33a41df3b16551bfac92eb97eb1ff17536 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 10:35:37 -0600 Subject: [PATCH 07/10] RDoc for Open3 --- lib/open3.rb | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 1f662fa..e394919 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -1006,7 +1006,9 @@ def pipeline_rw(*cmds, &block) # 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+. - # - Does not wait for child processes to exit. + # + # The method does not wait for child processes to exit, + # so the caller must do so. # # With no block given, returns a 2-element array containing: # @@ -1015,8 +1017,17 @@ def pipeline_rw(*cmds, &block) # # Example: # - # Open3.pipeline_r('ls', 'grep R') - # # => [#, [#, #]] + # last_stdout, wait_threads = Open3.pipeline_r('ls', 'grep R') + # # => [#, [#, #]] + # 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, @@ -1024,14 +1035,15 @@ def pipeline_rw(*cmds, &block) # # Open3.pipeline_r('ls', 'grep R') do |last_stdout, wait_threads| # puts last_stdout.read - # p 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; From 6a0cb8f33fa17fd940f3a4a54cd51508c4f7d22a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 11:16:05 -0600 Subject: [PATCH 08/10] RDoc for Open3 --- lib/open3.rb | 39 +++++++++++++++++++++++++-------------- 1 file changed, 25 insertions(+), 14 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index e394919..0a726f4 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -1091,7 +1091,9 @@ def pipeline_r(*cmds, &block) # 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+. - # - Does not wait for child processes to exit. + # + # The method does not wait for child processes to exit, + # so the caller must do so. # # With no block given, returns a 2-element array containing: # @@ -1100,28 +1102,37 @@ def pipeline_r(*cmds, &block) # # Example: # - # p Open3.pipeline_r( - # ['ruby', '-e', 'print "Foo"'], - # ['ruby', '-e', 'print STDIN.read + "Bar"'] - # ) - # [#, [#, #]] + # first_stdin, wait_threads = Open3.pipeline_w('sort', 'cat -n') + # # => [#, [#, #]] + # 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_r( - # ['ruby', '-e', 'print "Foo"'], - # ['ruby', '-e', 'print STDIN.read + "Bar"'] - # ) do |first_stdin, wait_threads| - # puts first_stdin.read - # p wait_threads + # 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: # - # FooBar - # [#, #] + # 1 bar + # 2 baz + # 3 foo # # Like Process.spawn, this method has potential security vulnerabilities # if called with untrusted input; From 59d06f44a412894e559695db716fa8ce9d8b5d5f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 21 Nov 2023 11:33:36 -0600 Subject: [PATCH 09/10] RDoc for Open3 --- lib/open3.rb | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 0a726f4..1735747 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -1185,24 +1185,29 @@ def pipeline_w(*cmds, &block) # # Example: # - # wait_threads = Open3.pipeline_start('sort', 'cat -n') - # # => [#, #] - # + # wait_threads = Open3.pipeline_start('ls', 'grep R') + # # => [#, #] # wait_threads.each do |wait_thread| - # wait_thread.wait + # wait_thread.join # end # - # With a block given, calls the block with the +stdout+ stream - # of the last child process, - # and an array of the wait processes: + # Output: + # + # Rakefile + # README.md # - # Open3.pipeline_start('sort', 'cat -n') do |wait_threads| - # p wait_threads + # 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; @@ -1251,18 +1256,16 @@ def pipeline_start(*cmds, &block) # 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+. - # - Does not wait for child processes to exit. + # - Waits for the child processes to exit. # - Returns an array of Process::Status objects (one for each child). # - # A simple example: + # Example: # - # Open3.pipeline('ls', 'grep [A-Z]') - # # => [#, #] + # wait_threads = Open3.pipeline('ls', 'grep R') + # # => [#, #] # # Output: # - # Gemfile - # LICENSE.txt # Rakefile # README.md # From 1256f3c5ee3b4a32267557b089d6ecbf45ca1bbe Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Tue, 21 Nov 2023 12:45:09 -0600 Subject: [PATCH 10/10] Update lib/open3.rb Co-authored-by: Peter Zhu --- lib/open3.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/open3.rb b/lib/open3.rb index 1735747..9030f6d 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -1180,7 +1180,7 @@ def pipeline_w(*cmds, &block) # by calling Process.spawn. # - Does not wait for child processes to exit. # - # With no block given, returns an array of the wait threads0 + # With no block given, returns an array of the wait threads # for all of the child processes. # # Example: