From 06ac6473cc404941ecc4c631b4f974a744b9213c Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 18 Nov 2023 12:42:29 -0600 Subject: [PATCH 1/3] RDoc for Open3 --- lib/open3.rb | 92 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 67 insertions(+), 25 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 3123f80..030cfa4 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -960,7 +960,7 @@ def pipeline_rw(*cmds, &block) module_function :pipeline_rw # :call-seq: - # Open3.pipeline_r([env, ] *cmds, options = {}) -> [last_stdout, wait_threads] + # Open3.pipeline_r([env, ] *cmds, options = {}) -> array_of_statuses # # Basically a wrapper for # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn] @@ -983,15 +983,19 @@ def pipeline_rw(*cmds, &block) # # => [#, [#, #]] # # With a block given, calls the block with the +stdout+ stream - # of the last child process: + # of the last child process, + # and an array of the wait processes: # - # Open3.pipeline_r('ls', 'grep R') {|x| puts x.read } + # Open3.pipeline_r('ls', 'grep R') do |x, ts| + # puts x.read + # p ts + # end # # Output: # - # CONTRIBUTING.md # Rakefile # README.md + # [#, #] # # Like Process.spawn, this method has potential security vulnerabilities # if called with untrusted input; @@ -1005,7 +1009,7 @@ def pipeline_rw(*cmds, &block) # 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; + # 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: @@ -1030,33 +1034,71 @@ def pipeline_r(*cmds, &block) 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. - # - # Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads| - # ... - # } + # :call-seq: + # Open3.pipeline_w([env, ] *cmds, options = {}) -> array_of_statuses # - # first_stdin, wait_threads = Open3.pipeline_w(cmd1, cmd2, ... [, opts]) - # ... - # first_stdin.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, pipes the caller's +stdout+ to the child's +stdin+. + # - 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 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" - # } + # p Open3.pipeline_r( + # ['ruby', '-e', 'print "Foo"'], + # ['ruby', '-e', 'print STDIN.read + "Bar"'] + # ) + # [#, [#, #]] + # + # 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 |x, ts| + # puts x.read + # p ts + # end + # + # Output: + # + # FooBar + # [#, #] + # + # 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_w(*cmds, &block) if Hash === cmds.last From 8b28acaca0da1f283d5d0c9d76d969804c792bf7 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 18 Nov 2023 16:52:34 -0600 Subject: [PATCH 2/3] RDoc for Open3 --- lib/open3.rb | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/lib/open3.rb b/lib/open3.rb index 030cfa4..d1a569f 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -1009,7 +1009,7 @@ def pipeline_rw(*cmds, &block) # 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' + # 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: @@ -1034,8 +1034,9 @@ def pipeline_r(*cmds, &block) end module_function :pipeline_r + # :call-seq: - # Open3.pipeline_w([env, ] *cmds, options = {}) -> array_of_statuses + # Open3.pipeline_w([env, ] *cmds, options = {}) -> [first_stdin, wait_threads] # # Basically a wrapper for # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn] @@ -1089,7 +1090,7 @@ def pipeline_r(*cmds, &block) # 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' + # 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: From 64a63b3dcdfd9353d7fb1e00b74c21a2d2fc3e00 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 18 Nov 2023 18:12:50 -0600 Subject: [PATCH 3/3] 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 d1a569f..13606ce 100644 --- a/lib/open3.rb +++ b/lib/open3.rb @@ -960,7 +960,7 @@ def pipeline_rw(*cmds, &block) module_function :pipeline_rw # :call-seq: - # Open3.pipeline_r([env, ] *cmds, options = {}) -> array_of_statuses + # Open3.pipeline_r([env, ] *cmds, options = {}) -> [last_stdout, wait_threads] # # Basically a wrapper for # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]