open3 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/open3.rb CHANGED
@@ -31,57 +31,189 @@
31
31
 
32
32
  require 'open3/version'
33
33
 
34
+ # \Module \Open3 supports creating child processes
35
+ # with access to their $stdin, $stdout, and $stderr streams.
36
+ #
37
+ # == What's Here
38
+ #
39
+ # Each of these methods executes a given command in a new process or subshell,
40
+ # or multiple commands in new processes and/or subshells:
41
+ #
42
+ # - Each of these methods executes a single command in a process or subshell,
43
+ # accepts a string for input to $stdin,
44
+ # and returns string output from $stdout, $stderr, or both:
45
+ #
46
+ # - Open3.capture2: Executes the command;
47
+ # returns the string from $stdout.
48
+ # - Open3.capture2e: Executes the command;
49
+ # returns the string from merged $stdout and $stderr.
50
+ # - Open3.capture3: Executes the command;
51
+ # returns strings from $stdout and $stderr.
52
+ #
53
+ # - Each of these methods executes a single command in a process or subshell,
54
+ # and returns pipes for $stdin, $stdout, and/or $stderr:
55
+ #
56
+ # - Open3.popen2: Executes the command;
57
+ # returns pipes for $stdin and $stdout.
58
+ # - Open3.popen2e: Executes the command;
59
+ # returns pipes for $stdin and merged $stdout and $stderr.
60
+ # - Open3.popen3: Executes the command;
61
+ # returns pipes for $stdin, $stdout, and $stderr.
62
+ #
63
+ # - Each of these methods executes one or more commands in processes and/or subshells,
64
+ # returns pipes for the first $stdin, the last $stdout, or both:
65
+ #
66
+ # - Open3.pipeline_r: Returns a pipe for the last $stdout.
67
+ # - Open3.pipeline_rw: Returns pipes for the first $stdin and the last $stdout.
68
+ # - Open3.pipeline_w: Returns a pipe for the first $stdin.
69
+ # - Open3.pipeline_start: Does not wait for processes to complete.
70
+ # - Open3.pipeline: Waits for processes to complete.
71
+ #
72
+ # Each of the methods above accepts:
73
+ #
74
+ # - An optional hash of environment variable names and values;
75
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
76
+ # - A required string argument that is a +command_line+ or +exe_path+;
77
+ # see {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
78
+ # - An optional hash of execution options;
79
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
80
+ #
34
81
  module Open3
35
82
 
36
- # Open stdin, stdout, and stderr streams and start external executable.
37
- # In addition, a thread to wait for the started process is created.
38
- # The thread has a pid method and a thread variable :pid which is the pid of
39
- # the started process.
83
+ # :call-seq:
84
+ # Open3.popen3([env, ] command_line, options = {}) -> [stdin, stdout, stderr, wait_thread]
85
+ # Open3.popen3([env, ] exe_path, *args, options = {}) -> [stdin, stdout, stderr, wait_thread]
86
+ # Open3.popen3([env, ] command_line, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
87
+ # Open3.popen3([env, ] exe_path, *args, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
88
+ #
89
+ # Basically a wrapper for
90
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
91
+ # that:
92
+ #
93
+ # - Creates a child process, by calling Process.spawn with the given arguments.
94
+ # - Creates streams +stdin+, +stdout+, and +stderr+,
95
+ # which are the standard input, standard output, and standard error streams
96
+ # in the child process.
97
+ # - Creates thread +wait_thread+ that waits for the child process to exit;
98
+ # the thread has method +pid+, which returns the process ID
99
+ # of the child process.
100
+ #
101
+ # With no block given, returns the array
102
+ # <tt>[stdin, stdout, stderr, wait_thread]</tt>.
103
+ # The caller should close each of the three returned streams.
104
+ #
105
+ # stdin, stdout, stderr, wait_thread = Open3.popen3('echo')
106
+ # # => [#<IO:fd 8>, #<IO:fd 10>, #<IO:fd 12>, #<Process::Waiter:0x00007f58d5428f58 run>]
107
+ # stdin.close
108
+ # stdout.close
109
+ # stderr.close
110
+ # wait_thread.pid # => 2210481
111
+ # wait_thread.value # => #<Process::Status: pid 2210481 exit 0>
112
+ #
113
+ # With a block given, calls the block with the four variables
114
+ # (three streams and the wait thread)
115
+ # and returns the block's return value.
116
+ # The caller need not close the streams:
117
+ #
118
+ # Open3.popen3('echo') do |stdin, stdout, stderr, wait_thread|
119
+ # p stdin
120
+ # p stdout
121
+ # p stderr
122
+ # p wait_thread
123
+ # p wait_thread.pid
124
+ # p wait_thread.value
125
+ # end
40
126
  #
41
- # Block form:
127
+ # Output:
42
128
  #
43
- # Open3.popen3([env,] cmd... [, opts]) {|stdin, stdout, stderr, wait_thr|
44
- # pid = wait_thr.pid # pid of the started process.
45
- # ...
46
- # exit_status = wait_thr.value # Process::Status object returned.
47
- # }
129
+ # #<IO:fd 6>
130
+ # #<IO:fd 7>
131
+ # #<IO:fd 9>
132
+ # #<Process::Waiter:0x00007f58d53606e8 sleep>
133
+ # 2211047
134
+ # #<Process::Status: pid 2211047 exit 0>
48
135
  #
49
- # Non-block form:
136
+ # Like Process.spawn, this method has potential security vulnerabilities
137
+ # if called with untrusted input;
138
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
50
139
  #
51
- # stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts])
52
- # pid = wait_thr[:pid] # pid of the started process
53
- # ...
54
- # stdin.close # stdin, stdout and stderr should be closed explicitly in this form.
55
- # stdout.close
56
- # stderr.close
57
- # exit_status = wait_thr.value # Process::Status object returned.
140
+ # Unlike Process.spawn, this method waits for the child process to exit
141
+ # before returning, so the caller need not do so.
142
+ #
143
+ # If the first argument is a hash, it becomes leading argument +env+
144
+ # in the call to Process.spawn;
145
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
146
+ #
147
+ # If the last argument is a hash, it becomes trailing argument +options+
148
+ # in the call to Process.spawn;
149
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
150
+ #
151
+ # The single required argument is one of the following:
152
+ #
153
+ # - +command_line+ if it is a string,
154
+ # and if it begins with a shell reserved word or special built-in,
155
+ # or if it contains one or more metacharacters.
156
+ # - +exe_path+ otherwise.
157
+ #
158
+ # <b>Argument +command_line+</b>
58
159
  #
59
- # The parameters env, cmd, and opts are passed to Process.spawn.
60
- # A commandline string and a list of argument strings can be accepted as follows:
160
+ # \String argument +command_line+ is a command line to be passed to a shell;
161
+ # it must begin with a shell reserved word, begin with a special built-in,
162
+ # or contain meta characters:
61
163
  #
62
- # Open3.popen3("echo abc") {|i, o, e, t| ... }
63
- # Open3.popen3("echo", "abc") {|i, o, e, t| ... }
64
- # Open3.popen3(["echo", "argv0"], "abc") {|i, o, e, t| ... }
164
+ # Open3.popen3('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
165
+ # Open3.popen3('echo') {|*args| p args } # Built-in.
166
+ # Open3.popen3('date > date.tmp') {|*args| p args } # Contains meta character.
65
167
  #
66
- # If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
168
+ # Output (similar for each call above):
67
169
  #
68
- # Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t|
69
- # p o.read.chomp #=> "/"
70
- # }
170
+ # [#<IO:(closed)>, #<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f58d52f28c8 dead>]
71
171
  #
72
- # wait_thr.value waits for the termination of the process.
73
- # The block form also waits for the process when it returns.
172
+ # The command line may also contain arguments and options for the command:
173
+ #
174
+ # Open3.popen3('echo "Foo"') { |i, o, e, t| o.gets }
175
+ # "Foo\n"
176
+ #
177
+ # <b>Argument +exe_path+</b>
178
+ #
179
+ # Argument +exe_path+ is one of the following:
180
+ #
181
+ # - The string path to an executable to be called.
182
+ # - A 2-element array containing the path to an executable
183
+ # and the string to be used as the name of the executing process.
184
+ #
185
+ # Example:
74
186
  #
75
- # Closing stdin, stdout and stderr does not wait for the process to complete.
187
+ # Open3.popen3('/usr/bin/date') { |i, o, e, t| o.gets }
188
+ # # => "Wed Sep 27 02:56:44 PM CDT 2023\n"
76
189
  #
77
- # You should be careful to avoid deadlocks.
78
- # Since pipes are fixed length buffers,
79
- # Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if
80
- # the program generates too much output on stderr.
81
- # You should read stdout and stderr simultaneously (using threads or IO.select).
82
- # However, if you don't need stderr output, you can use Open3.popen2.
83
- # If merged stdout and stderr output is not a problem, you can use Open3.popen2e.
84
- # If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
190
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
191
+ #
192
+ # Open3.popen3('doesnt_exist') { |i, o, e, t| o.gets } # Raises Errno::ENOENT
193
+ #
194
+ # If one or more +args+ is given, each is an argument or option
195
+ # to be passed to the executable:
196
+ #
197
+ # Open3.popen3('echo', 'C #') { |i, o, e, t| o.gets }
198
+ # # => "C #\n"
199
+ # Open3.popen3('echo', 'hello', 'world') { |i, o, e, t| o.gets }
200
+ # # => "hello world\n"
201
+ #
202
+ # Take care to avoid deadlocks.
203
+ # Output streams +stdout+ and +stderr+ have fixed-size buffers,
204
+ # so reading extensively from one but not the other can cause a deadlock
205
+ # when the unread buffer fills.
206
+ # To avoid that, +stdout+ and +stderr+ should be read simultaneously
207
+ # (using threads or IO.select).
208
+ #
209
+ # Related:
210
+ #
211
+ # - Open3.popen2: Makes the standard input and standard output streams
212
+ # of the child process available as separate streams,
213
+ # with no access to the standard error stream.
214
+ # - Open3.popen2e: Makes the standard input and the merge
215
+ # of the standard output and standard error streams
216
+ # of the child process available as separate streams.
85
217
  #
86
218
  def popen3(*cmd, &block)
87
219
  if Hash === cmd.last
@@ -104,45 +236,131 @@ module Open3
104
236
  end
105
237
  module_function :popen3
106
238
 
107
- # Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
108
- # the standard error stream.
239
+ # :call-seq:
240
+ # Open3.popen2([env, ] command_line, options = {}) -> [stdin, stdout, wait_thread]
241
+ # Open3.popen2([env, ] exe_path, *args, options = {}) -> [stdin, stdout, wait_thread]
242
+ # Open3.popen2([env, ] command_line, options = {}) {|stdin, stdout, wait_thread| ... } -> object
243
+ # Open3.popen2([env, ] exe_path, *args, options = {}) {|stdin, stdout, wait_thread| ... } -> object
244
+ #
245
+ # Basically a wrapper for
246
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
247
+ # that:
248
+ #
249
+ # - Creates a child process, by calling Process.spawn with the given arguments.
250
+ # - Creates streams +stdin+ and +stdout+,
251
+ # which are the standard input and standard output streams
252
+ # in the child process.
253
+ # - Creates thread +wait_thread+ that waits for the child process to exit;
254
+ # the thread has method +pid+, which returns the process ID
255
+ # of the child process.
256
+ #
257
+ # With no block given, returns the array
258
+ # <tt>[stdin, stdout, wait_thread]</tt>.
259
+ # The caller should close each of the two returned streams.
260
+ #
261
+ # stdin, stdout, wait_thread = Open3.popen2('echo')
262
+ # # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f58d52dbe98 run>]
263
+ # stdin.close
264
+ # stdout.close
265
+ # wait_thread.pid # => 2263572
266
+ # wait_thread.value # => #<Process::Status: pid 2263572 exit 0>
267
+ #
268
+ # With a block given, calls the block with the three variables
269
+ # (two streams and the wait thread)
270
+ # and returns the block's return value.
271
+ # The caller need not close the streams:
272
+ #
273
+ # Open3.popen2('echo') do |stdin, stdout, wait_thread|
274
+ # p stdin
275
+ # p stdout
276
+ # p wait_thread
277
+ # p wait_thread.pid
278
+ # p wait_thread.value
279
+ # end
109
280
  #
110
- # Block form:
281
+ # Output:
111
282
  #
112
- # Open3.popen2([env,] cmd... [, opts]) {|stdin, stdout, wait_thr|
113
- # pid = wait_thr.pid # pid of the started process.
114
- # ...
115
- # exit_status = wait_thr.value # Process::Status object returned.
116
- # }
283
+ # #<IO:fd 6>
284
+ # #<IO:fd 7>
285
+ # #<Process::Waiter:0x00007f58d59a34b0 sleep>
286
+ # 2263636
287
+ # #<Process::Status: pid 2263636 exit 0>
117
288
  #
118
- # Non-block form:
289
+ # Like Process.spawn, this method has potential security vulnerabilities
290
+ # if called with untrusted input;
291
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
119
292
  #
120
- # stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts])
121
- # ...
122
- # stdin.close # stdin and stdout should be closed explicitly in this form.
123
- # stdout.close
293
+ # Unlike Process.spawn, this method waits for the child process to exit
294
+ # before returning, so the caller need not do so.
295
+ #
296
+ # If the first argument is a hash, it becomes leading argument +env+
297
+ # in the call to Process.spawn;
298
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
299
+ #
300
+ # If the last argument is a hash, it becomes trailing argument +options+
301
+ # in the call to Process.spawn;
302
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
303
+ #
304
+ # The single required argument is one of the following:
305
+ #
306
+ # - +command_line+ if it is a string,
307
+ # and if it begins with a shell reserved word or special built-in,
308
+ # or if it contains one or more metacharacters.
309
+ # - +exe_path+ otherwise.
124
310
  #
125
- # See Process.spawn for the optional hash arguments _env_ and _opts_.
311
+ # <b>Argument +command_line+</b>
312
+ #
313
+ # \String argument +command_line+ is a command line to be passed to a shell;
314
+ # it must begin with a shell reserved word, begin with a special built-in,
315
+ # or contain meta characters:
316
+ #
317
+ # Open3.popen2('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
318
+ # Open3.popen2('echo') {|*args| p args } # Built-in.
319
+ # Open3.popen2('date > date.tmp') {|*args| p args } # Contains meta character.
320
+ #
321
+ # Output (similar for each call above):
322
+ #
323
+ # # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577dfe410 dead>]
324
+ #
325
+ # The command line may also contain arguments and options for the command:
326
+ #
327
+ # Open3.popen2('echo "Foo"') { |i, o, t| o.gets }
328
+ # "Foo\n"
329
+ #
330
+ # <b>Argument +exe_path+</b>
331
+ #
332
+ # Argument +exe_path+ is one of the following:
333
+ #
334
+ # - The string path to an executable to be called.
335
+ # - A 2-element array containing the path to an executable
336
+ # and the string to be used as the name of the executing process.
126
337
  #
127
338
  # Example:
128
339
  #
129
- # Open3.popen2("wc -c") {|i,o,t|
130
- # i.print "answer to life the universe and everything"
131
- # i.close
132
- # p o.gets #=> "42\n"
133
- # }
340
+ # Open3.popen2('/usr/bin/date') { |i, o, t| o.gets }
341
+ # # => "Thu Sep 28 09:41:06 AM CDT 2023\n"
342
+ #
343
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
344
+ #
345
+ # Open3.popen2('doesnt_exist') { |i, o, t| o.gets } # Raises Errno::ENOENT
346
+ #
347
+ # If one or more +args+ is given, each is an argument or option
348
+ # to be passed to the executable:
349
+ #
350
+ # Open3.popen2('echo', 'C #') { |i, o, t| o.gets }
351
+ # # => "C #\n"
352
+ # Open3.popen2('echo', 'hello', 'world') { |i, o, t| o.gets }
353
+ # # => "hello world\n"
134
354
  #
135
- # Open3.popen2("bc -q") {|i,o,t|
136
- # i.puts "obase=13"
137
- # i.puts "6 * 9"
138
- # p o.gets #=> "42\n"
139
- # }
140
355
  #
141
- # Open3.popen2("dc") {|i,o,t|
142
- # i.print "42P"
143
- # i.close
144
- # p o.read #=> "*"
145
- # }
356
+ # Related:
357
+ #
358
+ # - Open3.popen2e: Makes the standard input and the merge
359
+ # of the standard output and standard error streams
360
+ # of the child process available as separate streams.
361
+ # - Open3.popen3: Makes the standard input, standard output,
362
+ # and standard error streams
363
+ # of the child process available as separate streams.
146
364
  #
147
365
  def popen2(*cmd, &block)
148
366
  if Hash === cmd.last
@@ -162,36 +380,130 @@ module Open3
162
380
  end
163
381
  module_function :popen2
164
382
 
165
- # Open3.popen2e is similar to Open3.popen3 except that it merges
166
- # the standard output stream and the standard error stream.
383
+ # :call-seq:
384
+ # Open3.popen2e([env, ] command_line, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
385
+ # Open3.popen2e([env, ] exe_path, *args, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
386
+ # Open3.popen2e([env, ] command_line, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
387
+ # Open3.popen2e([env, ] exe_path, *args, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
388
+ #
389
+ # Basically a wrapper for
390
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
391
+ # that:
392
+ #
393
+ # - Creates a child process, by calling Process.spawn with the given arguments.
394
+ # - Creates streams +stdin+, +stdout_and_stderr+,
395
+ # which are the standard input and the merge of the standard output
396
+ # and standard error streams in the child process.
397
+ # - Creates thread +wait_thread+ that waits for the child process to exit;
398
+ # the thread has method +pid+, which returns the process ID
399
+ # of the child process.
400
+ #
401
+ # With no block given, returns the array
402
+ # <tt>[stdin, stdout_and_stderr, wait_thread]</tt>.
403
+ # The caller should close each of the two returned streams.
404
+ #
405
+ # stdin, stdout_and_stderr, wait_thread = Open3.popen2e('echo')
406
+ # # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f7577da4398 run>]
407
+ # stdin.close
408
+ # stdout_and_stderr.close
409
+ # wait_thread.pid # => 2274600
410
+ # wait_thread.value # => #<Process::Status: pid 2274600 exit 0>
411
+ #
412
+ # With a block given, calls the block with the three variables
413
+ # (two streams and the wait thread)
414
+ # and returns the block's return value.
415
+ # The caller need not close the streams:
416
+ #
417
+ # Open3.popen2e('echo') do |stdin, stdout_and_stderr, wait_thread|
418
+ # p stdin
419
+ # p stdout_and_stderr
420
+ # p wait_thread
421
+ # p wait_thread.pid
422
+ # p wait_thread.value
423
+ # end
167
424
  #
168
- # Block form:
425
+ # Output:
169
426
  #
170
- # Open3.popen2e([env,] cmd... [, opts]) {|stdin, stdout_and_stderr, wait_thr|
171
- # pid = wait_thr.pid # pid of the started process.
172
- # ...
173
- # exit_status = wait_thr.value # Process::Status object returned.
174
- # }
427
+ # #<IO:fd 6>
428
+ # #<IO:fd 7>
429
+ # #<Process::Waiter:0x00007f75777578c8 sleep>
430
+ # 2274763
431
+ # #<Process::Status: pid 2274763 exit 0>
175
432
  #
176
- # Non-block form:
433
+ # Like Process.spawn, this method has potential security vulnerabilities
434
+ # if called with untrusted input;
435
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
177
436
  #
178
- # stdin, stdout_and_stderr, wait_thr = Open3.popen2e([env,] cmd... [, opts])
179
- # ...
180
- # stdin.close # stdin and stdout_and_stderr should be closed explicitly in this form.
181
- # stdout_and_stderr.close
437
+ # Unlike Process.spawn, this method waits for the child process to exit
438
+ # before returning, so the caller need not do so.
439
+ #
440
+ # If the first argument is a hash, it becomes leading argument +env+
441
+ # in the call to Process.spawn;
442
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
443
+ #
444
+ # If the last argument is a hash, it becomes trailing argument +options+
445
+ # in the call to Process.spawn;
446
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
447
+ #
448
+ # The single required argument is one of the following:
449
+ #
450
+ # - +command_line+ if it is a string,
451
+ # and if it begins with a shell reserved word or special built-in,
452
+ # or if it contains one or more metacharacters.
453
+ # - +exe_path+ otherwise.
454
+ #
455
+ # <b>Argument +command_line+</b>
456
+ #
457
+ # \String argument +command_line+ is a command line to be passed to a shell;
458
+ # it must begin with a shell reserved word, begin with a special built-in,
459
+ # or contain meta characters:
460
+ #
461
+ # Open3.popen2e('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
462
+ # Open3.popen2e('echo') {|*args| p args } # Built-in.
463
+ # Open3.popen2e('date > date.tmp') {|*args| p args } # Contains meta character.
464
+ #
465
+ # Output (similar for each call above):
466
+ #
467
+ # # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577d8a1f0 dead>]
182
468
  #
183
- # See Process.spawn for the optional hash arguments _env_ and _opts_.
469
+ # The command line may also contain arguments and options for the command:
470
+ #
471
+ # Open3.popen2e('echo "Foo"') { |i, o_and_e, t| o_and_e.gets }
472
+ # "Foo\n"
473
+ #
474
+ # <b>Argument +exe_path+</b>
475
+ #
476
+ # Argument +exe_path+ is one of the following:
477
+ #
478
+ # - The string path to an executable to be called.
479
+ # - A 2-element array containing the path to an executable
480
+ # and the string to be used as the name of the executing process.
184
481
  #
185
482
  # Example:
186
- # # check gcc warnings
187
- # source = "foo.c"
188
- # Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
189
- # oe.each {|line|
190
- # if /warning/ =~ line
191
- # ...
192
- # end
193
- # }
194
- # }
483
+ #
484
+ # Open3.popen2e('/usr/bin/date') { |i, o_and_e, t| o_and_e.gets }
485
+ # # => "Thu Sep 28 01:58:45 PM CDT 2023\n"
486
+ #
487
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
488
+ #
489
+ # Open3.popen2e('doesnt_exist') { |i, o_and_e, t| o_and_e.gets } # Raises Errno::ENOENT
490
+ #
491
+ # If one or more +args+ is given, each is an argument or option
492
+ # to be passed to the executable:
493
+ #
494
+ # Open3.popen2e('echo', 'C #') { |i, o_and_e, t| o_and_e.gets }
495
+ # # => "C #\n"
496
+ # Open3.popen2e('echo', 'hello', 'world') { |i, o_and_e, t| o_and_e.gets }
497
+ # # => "hello world\n"
498
+ #
499
+ # Related:
500
+ #
501
+ # - Open3.popen2: Makes the standard input and standard output streams
502
+ # of the child process available as separate streams,
503
+ # with no access to the standard error stream.
504
+ # - Open3.popen3: Makes the standard input, standard output,
505
+ # and standard error streams
506
+ # of the child process available as separate streams.
195
507
  #
196
508
  def popen2e(*cmd, &block)
197
509
  if Hash === cmd.last
@@ -238,44 +550,100 @@ module Open3
238
550
  private :popen_run
239
551
  end
240
552
 
241
- # Open3.capture3 captures the standard output and the standard error of a command.
553
+ # :call-seq:
554
+ # Open3.capture3([env, ] command_line, options = {}) -> [stdout_s, stderr_s, status]
555
+ # Open3.capture3([env, ] exe_path, *args, options = {}) -> [stdout_s, stderr_s, status]
242
556
  #
243
- # stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
557
+ # Basically a wrapper for Open3.popen3 that:
244
558
  #
245
- # The arguments env, cmd and opts are passed to Open3.popen3 except
246
- # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>. See Process.spawn.
559
+ # - Creates a child process, by calling Open3.popen3 with the given arguments
560
+ # (except for certain entries in hash +options+; see below).
561
+ # - Returns as strings +stdout_s+ and +stderr_s+ the standard output
562
+ # and standard error of the child process.
563
+ # - Returns as +status+ a <tt>Process::Status</tt> object
564
+ # that represents the exit status of the child process.
247
565
  #
248
- # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
566
+ # Returns the array <tt>[stdout_s, stderr_s, status]</tt>:
249
567
  #
250
- # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
568
+ # stdout_s, stderr_s, status = Open3.capture3('echo "Foo"')
569
+ # # => ["Foo\n", "", #<Process::Status: pid 2281954 exit 0>]
251
570
  #
252
- # Examples:
571
+ # Like Process.spawn, this method has potential security vulnerabilities
572
+ # if called with untrusted input;
573
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
253
574
  #
254
- # # dot is a command of graphviz.
255
- # graph = <<'End'
256
- # digraph g {
257
- # a -> b
258
- # }
259
- # End
260
- # drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
575
+ # Unlike Process.spawn, this method waits for the child process to exit
576
+ # before returning, so the caller need not do so.
261
577
  #
262
- # o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n")
263
- # p o #=> "abc\n"
264
- # p e #=> "bar\nbaz\nfoo\n"
265
- # p s #=> #<Process::Status: pid 32682 exit 0>
578
+ # If the first argument is a hash, it becomes leading argument +env+
579
+ # in the call to Open3.popen3;
580
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
266
581
  #
267
- # # generate a thumbnail image using the convert command of ImageMagick.
268
- # # However, if the image is really stored in a file,
269
- # # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better
270
- # # because of reduced memory consumption.
271
- # # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example,
272
- # # Open3.capture3 should be considered.
273
- # #
274
- # image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true)
275
- # thumbnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true)
276
- # if s.success?
277
- # STDOUT.binmode; print thumbnail
278
- # end
582
+ # If the last argument is a hash, it becomes trailing argument +options+
583
+ # in the call to Open3.popen3;
584
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
585
+ #
586
+ # The hash +options+ is given;
587
+ # two options have local effect in method Open3.capture3:
588
+ #
589
+ # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
590
+ # and its string value is sent to the command's standard input:
591
+ #
592
+ # Open3.capture3('tee', stdin_data: 'Foo')
593
+ # # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
594
+ #
595
+ # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
596
+ # the internal streams are set to binary mode.
597
+ #
598
+ # The single required argument is one of the following:
599
+ #
600
+ # - +command_line+ if it is a string,
601
+ # and if it begins with a shell reserved word or special built-in,
602
+ # or if it contains one or more metacharacters.
603
+ # - +exe_path+ otherwise.
604
+ #
605
+ # <b>Argument +command_line+</b>
606
+ #
607
+ # \String argument +command_line+ is a command line to be passed to a shell;
608
+ # it must begin with a shell reserved word, begin with a special built-in,
609
+ # or contain meta characters:
610
+ #
611
+ # Open3.capture3('if true; then echo "Foo"; fi') # Shell reserved word.
612
+ # # => ["Foo\n", "", #<Process::Status: pid 2282025 exit 0>]
613
+ # Open3.capture3('echo') # Built-in.
614
+ # # => ["\n", "", #<Process::Status: pid 2282092 exit 0>]
615
+ # Open3.capture3('date > date.tmp') # Contains meta character.
616
+ # # => ["", "", #<Process::Status: pid 2282110 exit 0>]
617
+ #
618
+ # The command line may also contain arguments and options for the command:
619
+ #
620
+ # Open3.capture3('echo "Foo"')
621
+ # # => ["Foo\n", "", #<Process::Status: pid 2282092 exit 0>]
622
+ #
623
+ # <b>Argument +exe_path+</b>
624
+ #
625
+ # Argument +exe_path+ is one of the following:
626
+ #
627
+ # - The string path to an executable to be called.
628
+ # - A 2-element array containing the path to an executable
629
+ # and the string to be used as the name of the executing process.
630
+ #
631
+ # Example:
632
+ #
633
+ # Open3.capture3('/usr/bin/date')
634
+ # # => ["Thu Sep 28 05:03:51 PM CDT 2023\n", "", #<Process::Status: pid 2282300 exit 0>]
635
+ #
636
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
637
+ #
638
+ # Open3.capture3('doesnt_exist') # Raises Errno::ENOENT
639
+ #
640
+ # If one or more +args+ is given, each is an argument or option
641
+ # to be passed to the executable:
642
+ #
643
+ # Open3.capture3('echo', 'C #')
644
+ # # => ["C #\n", "", #<Process::Status: pid 2282368 exit 0>]
645
+ # Open3.capture3('echo', 'hello', 'world')
646
+ # # => ["hello world\n", "", #<Process::Status: pid 2282372 exit 0>]
279
647
  #
280
648
  def capture3(*cmd)
281
649
  if Hash === cmd.last
@@ -309,34 +677,100 @@ module Open3
309
677
  end
310
678
  module_function :capture3
311
679
 
312
- # Open3.capture2 captures the standard output of a command.
680
+ # :call-seq:
681
+ # Open3.capture2([env, ] command_line, options = {}) -> [stdout_s, status]
682
+ # Open3.capture2([env, ] exe_path, *args, options = {}) -> [stdout_s, status]
683
+ #
684
+ # Basically a wrapper for Open3.popen3 that:
685
+ #
686
+ # - Creates a child process, by calling Open3.popen3 with the given arguments
687
+ # (except for certain entries in hash +options+; see below).
688
+ # - Returns as string +stdout_s+ the standard output of the child process.
689
+ # - Returns as +status+ a <tt>Process::Status</tt> object
690
+ # that represents the exit status of the child process.
691
+ #
692
+ # Returns the array <tt>[stdout_s, status]</tt>:
693
+ #
694
+ # stdout_s, status = Open3.capture2('echo "Foo"')
695
+ # # => ["Foo\n", #<Process::Status: pid 2326047 exit 0>]
696
+ #
697
+ # Like Process.spawn, this method has potential security vulnerabilities
698
+ # if called with untrusted input;
699
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
700
+ #
701
+ # Unlike Process.spawn, this method waits for the child process to exit
702
+ # before returning, so the caller need not do so.
313
703
  #
314
- # stdout_str, status = Open3.capture2([env,] cmd... [, opts])
704
+ # If the first argument is a hash, it becomes leading argument +env+
705
+ # in the call to Open3.popen3;
706
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
315
707
  #
316
- # The arguments env, cmd and opts are passed to Open3.popen3 except
317
- # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>. See Process.spawn.
708
+ # If the last argument is a hash, it becomes trailing argument +options+
709
+ # in the call to Open3.popen3;
710
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
318
711
  #
319
- # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
712
+ # The hash +options+ is given;
713
+ # two options have local effect in method Open3.capture2:
320
714
  #
321
- # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
715
+ # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
716
+ # and its string value is sent to the command's standard input:
717
+ #
718
+ # Open3.capture2('tee', stdin_data: 'Foo')
719
+ #
720
+ # # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
721
+ #
722
+ # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
723
+ # the internal streams are set to binary mode.
724
+ #
725
+ # The single required argument is one of the following:
726
+ #
727
+ # - +command_line+ if it is a string,
728
+ # and if it begins with a shell reserved word or special built-in,
729
+ # or if it contains one or more metacharacters.
730
+ # - +exe_path+ otherwise.
731
+ #
732
+ # <b>Argument +command_line+</b>
733
+ #
734
+ # \String argument +command_line+ is a command line to be passed to a shell;
735
+ # it must begin with a shell reserved word, begin with a special built-in,
736
+ # or contain meta characters:
737
+ #
738
+ # Open3.capture2('if true; then echo "Foo"; fi') # Shell reserved word.
739
+ # # => ["Foo\n", #<Process::Status: pid 2326131 exit 0>]
740
+ # Open3.capture2('echo') # Built-in.
741
+ # # => ["\n", #<Process::Status: pid 2326139 exit 0>]
742
+ # Open3.capture2('date > date.tmp') # Contains meta character.
743
+ # # => ["", #<Process::Status: pid 2326174 exit 0>]
744
+ #
745
+ # The command line may also contain arguments and options for the command:
746
+ #
747
+ # Open3.capture2('echo "Foo"')
748
+ # # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
749
+ #
750
+ # <b>Argument +exe_path+</b>
751
+ #
752
+ # Argument +exe_path+ is one of the following:
753
+ #
754
+ # - The string path to an executable to be called.
755
+ # - A 2-element array containing the path to an executable
756
+ # and the string to be used as the name of the executing process.
322
757
  #
323
758
  # Example:
324
759
  #
325
- # # factor is a command for integer factorization.
326
- # o, s = Open3.capture2("factor", :stdin_data=>"42")
327
- # p o #=> "42: 2 3 7\n"
328
- #
329
- # # generate x**2 graph in png using gnuplot.
330
- # gnuplot_commands = <<"End"
331
- # set terminal png
332
- # plot x**2, "-" with lines
333
- # 1 14
334
- # 2 1
335
- # 3 8
336
- # 4 5
337
- # e
338
- # End
339
- # image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
760
+ # Open3.capture2('/usr/bin/date')
761
+ # # => ["Fri Sep 29 01:00:39 PM CDT 2023\n", #<Process::Status: pid 2326222 exit 0>]
762
+ #
763
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
764
+ #
765
+ # Open3.capture2('doesnt_exist') # Raises Errno::ENOENT
766
+ #
767
+ # If one or more +args+ is given, each is an argument or option
768
+ # to be passed to the executable:
769
+ #
770
+ # Open3.capture2('echo', 'C #')
771
+ # # => ["C #\n", #<Process::Status: pid 2326267 exit 0>]
772
+ # Open3.capture2('echo', 'hello', 'world')
773
+ # # => ["hello world\n", #<Process::Status: pid 2326299 exit 0>]
340
774
  #
341
775
  def capture2(*cmd)
342
776
  if Hash === cmd.last
@@ -370,21 +804,100 @@ module Open3
370
804
  end
371
805
  module_function :capture2
372
806
 
373
- # Open3.capture2e captures the standard output and the standard error of a command.
807
+ # :call-seq:
808
+ # Open3.capture2e([env, ] command_line, options = {}) -> [stdout_and_stderr_s, status]
809
+ # Open3.capture2e([env, ] exe_path, *args, options = {}) -> [stdout_and_stderr_s, status]
810
+ #
811
+ # Basically a wrapper for Open3.popen3 that:
812
+ #
813
+ # - Creates a child process, by calling Open3.popen3 with the given arguments
814
+ # (except for certain entries in hash +options+; see below).
815
+ # - Returns as string +stdout_and_stderr_s+ the merged standard output
816
+ # and standard error of the child process.
817
+ # - Returns as +status+ a <tt>Process::Status</tt> object
818
+ # that represents the exit status of the child process.
819
+ #
820
+ # Returns the array <tt>[stdout_and_stderr_s, status]</tt>:
821
+ #
822
+ # stdout_and_stderr_s, status = Open3.capture2e('echo "Foo"')
823
+ # # => ["Foo\n", #<Process::Status: pid 2371692 exit 0>]
824
+ #
825
+ # Like Process.spawn, this method has potential security vulnerabilities
826
+ # if called with untrusted input;
827
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
828
+ #
829
+ # Unlike Process.spawn, this method waits for the child process to exit
830
+ # before returning, so the caller need not do so.
831
+ #
832
+ # If the first argument is a hash, it becomes leading argument +env+
833
+ # in the call to Open3.popen3;
834
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
835
+ #
836
+ # If the last argument is a hash, it becomes trailing argument +options+
837
+ # in the call to Open3.popen3;
838
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
839
+ #
840
+ # The hash +options+ is given;
841
+ # two options have local effect in method Open3.capture2e:
842
+ #
843
+ # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
844
+ # and its string value is sent to the command's standard input:
374
845
  #
375
- # stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
846
+ # Open3.capture2e('tee', stdin_data: 'Foo')
847
+ # # => ["Foo", #<Process::Status: pid 2371732 exit 0>]
376
848
  #
377
- # The arguments env, cmd and opts are passed to Open3.popen3 except
378
- # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>. See Process.spawn.
849
+ # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
850
+ # the internal streams are set to binary mode.
379
851
  #
380
- # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
852
+ # The single required argument is one of the following:
381
853
  #
382
- # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
854
+ # - +command_line+ if it is a string,
855
+ # and if it begins with a shell reserved word or special built-in,
856
+ # or if it contains one or more metacharacters.
857
+ # - +exe_path+ otherwise.
858
+ #
859
+ # <b>Argument +command_line+</b>
860
+ #
861
+ # \String argument +command_line+ is a command line to be passed to a shell;
862
+ # it must begin with a shell reserved word, begin with a special built-in,
863
+ # or contain meta characters:
864
+ #
865
+ # Open3.capture2e('if true; then echo "Foo"; fi') # Shell reserved word.
866
+ # # => ["Foo\n", #<Process::Status: pid 2371740 exit 0>]
867
+ # Open3.capture2e('echo') # Built-in.
868
+ # # => ["\n", #<Process::Status: pid 2371774 exit 0>]
869
+ # Open3.capture2e('date > date.tmp') # Contains meta character.
870
+ # # => ["", #<Process::Status: pid 2371812 exit 0>]
871
+ #
872
+ # The command line may also contain arguments and options for the command:
873
+ #
874
+ # Open3.capture2e('echo "Foo"')
875
+ # # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
876
+ #
877
+ # <b>Argument +exe_path+</b>
878
+ #
879
+ # Argument +exe_path+ is one of the following:
880
+ #
881
+ # - The string path to an executable to be called.
882
+ # - A 2-element array containing the path to an executable
883
+ # and the string to be used as the name of the executing process.
383
884
  #
384
885
  # Example:
385
886
  #
386
- # # capture make log
387
- # make_log, s = Open3.capture2e("make")
887
+ # Open3.capture2e('/usr/bin/date')
888
+ # # => ["Sat Sep 30 09:01:46 AM CDT 2023\n", #<Process::Status: pid 2371820 exit 0>]
889
+ #
890
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
891
+ #
892
+ # Open3.capture2e('doesnt_exist') # Raises Errno::ENOENT
893
+ #
894
+ # If one or more +args+ is given, each is an argument or option
895
+ # to be passed to the executable:
896
+ #
897
+ # Open3.capture2e('echo', 'C #')
898
+ # # => ["C #\n", #<Process::Status: pid 2371856 exit 0>]
899
+ # Open3.capture2e('echo', 'hello', 'world')
900
+ # # => ["hello world\n", #<Process::Status: pid 2371894 exit 0>]
388
901
  #
389
902
  def capture2e(*cmd)
390
903
  if Hash === cmd.last
@@ -418,48 +931,86 @@ module Open3
418
931
  end
419
932
  module_function :capture2e
420
933
 
421
- # Open3.pipeline_rw starts a list of commands as a pipeline with pipes
422
- # which connect to stdin of the first command and stdout of the last command.
423
- #
424
- # Open3.pipeline_rw(cmd1, cmd2, ... [, opts]) {|first_stdin, last_stdout, wait_threads|
425
- # ...
426
- # }
934
+ # :call-seq:
935
+ # Open3.pipeline_rw([env, ] *cmds, options = {}) -> [first_stdin, last_stdout, wait_threads]
427
936
  #
428
- # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw(cmd1, cmd2, ... [, opts])
429
- # ...
430
- # first_stdin.close
431
- # last_stdout.close
937
+ # Basically a wrapper for
938
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
939
+ # that:
432
940
  #
433
- # Each cmd is a string or an array.
434
- # If it is an array, the elements are passed to Process.spawn.
941
+ # - Creates a child process for each of the given +cmds+
942
+ # by calling Process.spawn.
943
+ # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
944
+ # or, for the first child, from the caller's +stdin+,
945
+ # or, for the last child, to the caller's +stdout+.
435
946
  #
436
- # cmd:
437
- # commandline command line string which is passed to a shell
438
- # [env, commandline, opts] command line string which is passed to a shell
439
- # [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
440
- # [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
947
+ # The method does not wait for child processes to exit,
948
+ # so the caller must do so.
441
949
  #
442
- # Note that env and opts are optional, as for Process.spawn.
950
+ # With no block given, returns a 3-element array containing:
443
951
  #
444
- # The options to pass to Process.spawn are constructed by merging
445
- # +opts+, the last hash element of the array, and
446
- # specifications for the pipes between each of the commands.
952
+ # - The +stdin+ stream of the first child process.
953
+ # - The +stdout+ stream of the last child process.
954
+ # - An array of the wait threads for all of the child processes.
447
955
  #
448
956
  # Example:
449
957
  #
450
- # Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i, o, ts|
451
- # i.puts "All persons more than a mile high to leave the court."
452
- # i.close
453
- # p o.gets #=> "42\n"
454
- # }
455
- #
456
- # Open3.pipeline_rw("sort", "cat -n") {|stdin, stdout, wait_thrs|
457
- # stdin.puts "foo"
458
- # stdin.puts "bar"
459
- # stdin.puts "baz"
460
- # stdin.close # send EOF to sort.
461
- # p stdout.read #=> " 1\tbar\n 2\tbaz\n 3\tfoo\n"
462
- # }
958
+ # first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('sort', 'cat -n')
959
+ # # => [#<IO:fd 20>, #<IO:fd 21>, [#<Process::Waiter:0x000055e8de29ab40 sleep>, #<Process::Waiter:0x000055e8de29a690 sleep>]]
960
+ # first_stdin.puts("foo\nbar\nbaz")
961
+ # first_stdin.close # Send EOF to sort.
962
+ # puts last_stdout.read
963
+ # wait_threads.each do |wait_thread|
964
+ # wait_thread.join
965
+ # end
966
+ #
967
+ # Output:
968
+ #
969
+ # 1 bar
970
+ # 2 baz
971
+ # 3 foo
972
+ #
973
+ # With a block given, calls the block with the +stdin+ stream of the first child,
974
+ # the +stdout+ stream of the last child,
975
+ # and an array of the wait processes:
976
+ #
977
+ # Open3.pipeline_rw('sort', 'cat -n') do |first_stdin, last_stdout, wait_threads|
978
+ # first_stdin.puts "foo\nbar\nbaz"
979
+ # first_stdin.close # send EOF to sort.
980
+ # puts last_stdout.read
981
+ # wait_threads.each do |wait_thread|
982
+ # wait_thread.join
983
+ # end
984
+ # end
985
+ #
986
+ # Output:
987
+ #
988
+ # 1 bar
989
+ # 2 baz
990
+ # 3 foo
991
+ #
992
+ # Like Process.spawn, this method has potential security vulnerabilities
993
+ # if called with untrusted input;
994
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
995
+ #
996
+ # If the first argument is a hash, it becomes leading argument +env+
997
+ # in each call to Process.spawn;
998
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
999
+ #
1000
+ # If the last argument is a hash, it becomes trailing argument +options+
1001
+ # in each call to Process.spawn;
1002
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
1003
+ #
1004
+ # Each remaining argument in +cmds+ is one of:
1005
+ #
1006
+ # - A +command_line+: a string that begins with a shell reserved word
1007
+ # or special built-in, or contains one or more metacharacters.
1008
+ # - An +exe_path+: the string path to an executable to be called.
1009
+ # - An array containing a +command_line+ or an +exe_path+,
1010
+ # along with zero or more string arguments for the command.
1011
+ #
1012
+ # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
1013
+ #
463
1014
  def pipeline_rw(*cmds, &block)
464
1015
  if Hash === cmds.last
465
1016
  opts = cmds.pop.dup
@@ -478,43 +1029,77 @@ module Open3
478
1029
  end
479
1030
  module_function :pipeline_rw
480
1031
 
481
- # Open3.pipeline_r starts a list of commands as a pipeline with a pipe
482
- # which connects to stdout of the last command.
1032
+ # :call-seq:
1033
+ # Open3.pipeline_r([env, ] *cmds, options = {}) -> [last_stdout, wait_threads]
483
1034
  #
484
- # Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads|
485
- # ...
486
- # }
1035
+ # Basically a wrapper for
1036
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
1037
+ # that:
487
1038
  #
488
- # last_stdout, wait_threads = Open3.pipeline_r(cmd1, cmd2, ... [, opts])
489
- # ...
490
- # last_stdout.close
1039
+ # - Creates a child process for each of the given +cmds+
1040
+ # by calling Process.spawn.
1041
+ # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
1042
+ # or, for the last child, to the caller's +stdout+.
491
1043
  #
492
- # Each cmd is a string or an array.
493
- # If it is an array, the elements are passed to Process.spawn.
1044
+ # The method does not wait for child processes to exit,
1045
+ # so the caller must do so.
494
1046
  #
495
- # cmd:
496
- # commandline command line string which is passed to a shell
497
- # [env, commandline, opts] command line string which is passed to a shell
498
- # [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
499
- # [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
1047
+ # With no block given, returns a 2-element array containing:
500
1048
  #
501
- # Note that env and opts are optional, as for Process.spawn.
1049
+ # - The +stdout+ stream of the last child process.
1050
+ # - An array of the wait threads for all of the child processes.
502
1051
  #
503
1052
  # Example:
504
1053
  #
505
- # Open3.pipeline_r("zcat /var/log/apache2/access.log.*.gz",
506
- # [{"LANG"=>"C"}, "grep", "GET /favicon.ico"],
507
- # "logresolve") {|o, ts|
508
- # o.each_line {|line|
509
- # ...
510
- # }
511
- # }
1054
+ # last_stdout, wait_threads = Open3.pipeline_r('ls', 'grep R')
1055
+ # # => [#<IO:fd 5>, [#<Process::Waiter:0x000055e8de2f9898 dead>, #<Process::Waiter:0x000055e8de2f94b0 sleep>]]
1056
+ # puts last_stdout.read
1057
+ # wait_threads.each do |wait_thread|
1058
+ # wait_thread.join
1059
+ # end
1060
+ #
1061
+ # Output:
1062
+ #
1063
+ # Rakefile
1064
+ # README.md
1065
+ #
1066
+ # With a block given, calls the block with the +stdout+ stream
1067
+ # of the last child process,
1068
+ # and an array of the wait processes:
1069
+ #
1070
+ # Open3.pipeline_r('ls', 'grep R') do |last_stdout, wait_threads|
1071
+ # puts last_stdout.read
1072
+ # wait_threads.each do |wait_thread|
1073
+ # wait_thread.join
1074
+ # end
1075
+ # end
1076
+ #
1077
+ # Output:
1078
+ #
1079
+ # Rakefile
1080
+ # README.md
1081
+ #
1082
+ # Like Process.spawn, this method has potential security vulnerabilities
1083
+ # if called with untrusted input;
1084
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
1085
+ #
1086
+ # If the first argument is a hash, it becomes leading argument +env+
1087
+ # in each call to Process.spawn;
1088
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
1089
+ #
1090
+ # If the last argument is a hash, it becomes trailing argument +options+
1091
+ # in each call to Process.spawn;
1092
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
512
1093
  #
513
- # Open3.pipeline_r("yes", "head -10") {|o, ts|
514
- # p o.read #=> "y\ny\ny\ny\ny\ny\ny\ny\ny\ny\n"
515
- # p ts[0].value #=> #<Process::Status: pid 24910 SIGPIPE (signal 13)>
516
- # p ts[1].value #=> #<Process::Status: pid 24913 exit 0>
517
- # }
1094
+ # Each remaining argument in +cmds+ is one of:
1095
+ #
1096
+ # - A +command_line+: a string that begins with a shell reserved word
1097
+ # or special built-in, or contains one or more metacharacters.
1098
+ # - An +exe_path+: the string path to an executable to be called.
1099
+ # - An array containing a +command_line+ or an +exe_path+,
1100
+ # along with zero or more string arguments for the command.
1101
+ #
1102
+ # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
518
1103
  #
519
1104
  def pipeline_r(*cmds, &block)
520
1105
  if Hash === cmds.last
@@ -530,33 +1115,82 @@ module Open3
530
1115
  end
531
1116
  module_function :pipeline_r
532
1117
 
533
- # Open3.pipeline_w starts a list of commands as a pipeline with a pipe
534
- # which connects to stdin of the first command.
1118
+
1119
+ # :call-seq:
1120
+ # Open3.pipeline_w([env, ] *cmds, options = {}) -> [first_stdin, wait_threads]
535
1121
  #
536
- # Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads|
537
- # ...
538
- # }
1122
+ # Basically a wrapper for
1123
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
1124
+ # that:
539
1125
  #
540
- # first_stdin, wait_threads = Open3.pipeline_w(cmd1, cmd2, ... [, opts])
541
- # ...
542
- # first_stdin.close
1126
+ # - Creates a child process for each of the given +cmds+
1127
+ # by calling Process.spawn.
1128
+ # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
1129
+ # or, for the first child, pipes the caller's +stdout+ to the child's +stdin+.
543
1130
  #
544
- # Each cmd is a string or an array.
545
- # If it is an array, the elements are passed to Process.spawn.
1131
+ # The method does not wait for child processes to exit,
1132
+ # so the caller must do so.
546
1133
  #
547
- # cmd:
548
- # commandline command line string which is passed to a shell
549
- # [env, commandline, opts] command line string which is passed to a shell
550
- # [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
551
- # [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
1134
+ # With no block given, returns a 2-element array containing:
552
1135
  #
553
- # Note that env and opts are optional, as for Process.spawn.
1136
+ # - The +stdin+ stream of the first child process.
1137
+ # - An array of the wait threads for all of the child processes.
554
1138
  #
555
1139
  # Example:
556
1140
  #
557
- # Open3.pipeline_w("bzip2 -c", :out=>"/tmp/hello.bz2") {|i, ts|
558
- # i.puts "hello"
559
- # }
1141
+ # first_stdin, wait_threads = Open3.pipeline_w('sort', 'cat -n')
1142
+ # # => [#<IO:fd 7>, [#<Process::Waiter:0x000055e8de928278 run>, #<Process::Waiter:0x000055e8de923e80 run>]]
1143
+ # first_stdin.puts("foo\nbar\nbaz")
1144
+ # first_stdin.close # Send EOF to sort.
1145
+ # wait_threads.each do |wait_thread|
1146
+ # wait_thread.join
1147
+ # end
1148
+ #
1149
+ # Output:
1150
+ #
1151
+ # 1 bar
1152
+ # 2 baz
1153
+ # 3 foo
1154
+ #
1155
+ # With a block given, calls the block with the +stdin+ stream
1156
+ # of the first child process,
1157
+ # and an array of the wait processes:
1158
+ #
1159
+ # Open3.pipeline_w('sort', 'cat -n') do |first_stdin, wait_threads|
1160
+ # first_stdin.puts("foo\nbar\nbaz")
1161
+ # first_stdin.close # Send EOF to sort.
1162
+ # wait_threads.each do |wait_thread|
1163
+ # wait_thread.join
1164
+ # end
1165
+ # end
1166
+ #
1167
+ # Output:
1168
+ #
1169
+ # 1 bar
1170
+ # 2 baz
1171
+ # 3 foo
1172
+ #
1173
+ # Like Process.spawn, this method has potential security vulnerabilities
1174
+ # if called with untrusted input;
1175
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
1176
+ #
1177
+ # If the first argument is a hash, it becomes leading argument +env+
1178
+ # in each call to Process.spawn;
1179
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
1180
+ #
1181
+ # If the last argument is a hash, it becomes trailing argument +options+
1182
+ # in each call to Process.spawn;
1183
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
1184
+ #
1185
+ # Each remaining argument in +cmds+ is one of:
1186
+ #
1187
+ # - A +command_line+: a string that begins with a shell reserved word
1188
+ # or special built-in, or contains one or more metacharacters.
1189
+ # - An +exe_path+: the string path to an executable to be called.
1190
+ # - An array containing a +command_line+ or an +exe_path+,
1191
+ # along with zero or more string arguments for the command.
1192
+ #
1193
+ # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
560
1194
  #
561
1195
  def pipeline_w(*cmds, &block)
562
1196
  if Hash === cmds.last
@@ -573,49 +1207,67 @@ module Open3
573
1207
  end
574
1208
  module_function :pipeline_w
575
1209
 
576
- # Open3.pipeline_start starts a list of commands as a pipeline.
577
- # No pipes are created for stdin of the first command and
578
- # stdout of the last command.
1210
+ # :call-seq:
1211
+ # Open3.pipeline_start([env, ] *cmds, options = {}) -> [wait_threads]
579
1212
  #
580
- # Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads|
581
- # ...
582
- # }
1213
+ # Basically a wrapper for
1214
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
1215
+ # that:
583
1216
  #
584
- # wait_threads = Open3.pipeline_start(cmd1, cmd2, ... [, opts])
585
- # ...
1217
+ # - Creates a child process for each of the given +cmds+
1218
+ # by calling Process.spawn.
1219
+ # - Does not wait for child processes to exit.
586
1220
  #
587
- # Each cmd is a string or an array.
588
- # If it is an array, the elements are passed to Process.spawn.
1221
+ # With no block given, returns an array of the wait threads
1222
+ # for all of the child processes.
589
1223
  #
590
- # cmd:
591
- # commandline command line string which is passed to a shell
592
- # [env, commandline, opts] command line string which is passed to a shell
593
- # [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
594
- # [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
1224
+ # Example:
595
1225
  #
596
- # Note that env and opts are optional, as for Process.spawn.
1226
+ # wait_threads = Open3.pipeline_start('ls', 'grep R')
1227
+ # # => [#<Process::Waiter:0x000055e8de9d2bb0 run>, #<Process::Waiter:0x000055e8de9d2890 run>]
1228
+ # wait_threads.each do |wait_thread|
1229
+ # wait_thread.join
1230
+ # end
597
1231
  #
598
- # Example:
1232
+ # Output:
1233
+ #
1234
+ # Rakefile
1235
+ # README.md
1236
+ #
1237
+ # With a block given, calls the block with an array of the wait processes:
1238
+ #
1239
+ # Open3.pipeline_start('ls', 'grep R') do |wait_threads|
1240
+ # wait_threads.each do |wait_thread|
1241
+ # wait_thread.join
1242
+ # end
1243
+ # end
1244
+ #
1245
+ # Output:
1246
+ #
1247
+ # Rakefile
1248
+ # README.md
599
1249
  #
600
- # # Run xeyes in 10 seconds.
601
- # Open3.pipeline_start("xeyes") {|ts|
602
- # sleep 10
603
- # t = ts[0]
604
- # Process.kill("TERM", t.pid)
605
- # p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)>
606
- # }
607
- #
608
- # # Convert pdf to ps and send it to a printer.
609
- # # Collect error message of pdftops and lpr.
610
- # pdf_file = "paper.pdf"
611
- # printer = "printer-name"
612
- # err_r, err_w = IO.pipe
613
- # Open3.pipeline_start(["pdftops", pdf_file, "-"],
614
- # ["lpr", "-P#{printer}"],
615
- # :err=>err_w) {|ts|
616
- # err_w.close
617
- # p err_r.read # error messages of pdftops and lpr.
618
- # }
1250
+ # Like Process.spawn, this method has potential security vulnerabilities
1251
+ # if called with untrusted input;
1252
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
1253
+ #
1254
+ # If the first argument is a hash, it becomes leading argument +env+
1255
+ # in each call to Process.spawn;
1256
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
1257
+ #
1258
+ # If the last argument is a hash, it becomes trailing argument +options+
1259
+ # in each call to Process.spawn;
1260
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
1261
+ #
1262
+ # Each remaining argument in +cmds+ is one of:
1263
+ #
1264
+ # - A +command_line+: a string that begins with a shell reserved word
1265
+ # or special built-in, or contains one or more metacharacters.
1266
+ # - An +exe_path+: the string path to an executable to be called.
1267
+ # - An array containing a +command_line+ or an +exe_path+,
1268
+ # along with zero or more string arguments for the command.
1269
+ #
1270
+ # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
619
1271
  #
620
1272
  def pipeline_start(*cmds, &block)
621
1273
  if Hash === cmds.last
@@ -633,57 +1285,51 @@ module Open3
633
1285
  end
634
1286
  module_function :pipeline_start
635
1287
 
636
- # Open3.pipeline starts a list of commands as a pipeline.
637
- # It waits for the completion of the commands.
638
- # No pipes are created for stdin of the first command and
639
- # stdout of the last command.
1288
+ # :call-seq:
1289
+ # Open3.pipeline([env, ] *cmds, options = {}) -> array_of_statuses
640
1290
  #
641
- # status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])
1291
+ # Basically a wrapper for
1292
+ # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
1293
+ # that:
642
1294
  #
643
- # Each cmd is a string or an array.
644
- # If it is an array, the elements are passed to Process.spawn.
1295
+ # - Creates a child process for each of the given +cmds+
1296
+ # by calling Process.spawn.
1297
+ # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
1298
+ # or, for the last child, to the caller's +stdout+.
1299
+ # - Waits for the child processes to exit.
1300
+ # - Returns an array of Process::Status objects (one for each child).
645
1301
  #
646
- # cmd:
647
- # commandline command line string which is passed to a shell
648
- # [env, commandline, opts] command line string which is passed to a shell
649
- # [env, cmdname, arg1, ..., opts] command name and one or more arguments (no shell)
650
- # [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
1302
+ # Example:
651
1303
  #
652
- # Note that env and opts are optional, as Process.spawn.
1304
+ # wait_threads = Open3.pipeline('ls', 'grep R')
1305
+ # # => [#<Process::Status: pid 2139200 exit 0>, #<Process::Status: pid 2139202 exit 0>]
653
1306
  #
654
- # Example:
1307
+ # Output:
1308
+ #
1309
+ # Rakefile
1310
+ # README.md
1311
+ #
1312
+ # Like Process.spawn, this method has potential security vulnerabilities
1313
+ # if called with untrusted input;
1314
+ # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
1315
+ #
1316
+ # If the first argument is a hash, it becomes leading argument +env+
1317
+ # in each call to Process.spawn;
1318
+ # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
1319
+ #
1320
+ # If the last argument is a hash, it becomes trailing argument +options+
1321
+ # in each call to Process.spawn'
1322
+ # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
1323
+ #
1324
+ # Each remaining argument in +cmds+ is one of:
1325
+ #
1326
+ # - A +command_line+: a string that begins with a shell reserved word
1327
+ # or special built-in, or contains one or more metacharacters.
1328
+ # - An +exe_path+: the string path to an executable to be called.
1329
+ # - An array containing a +command_line+ or an +exe_path+,
1330
+ # along with zero or more string arguments for the command.
655
1331
  #
656
- # fname = "/usr/share/man/man1/ruby.1.gz"
657
- # p Open3.pipeline(["zcat", fname], "nroff -man", "less")
658
- # #=> [#<Process::Status: pid 11817 exit 0>,
659
- # # #<Process::Status: pid 11820 exit 0>,
660
- # # #<Process::Status: pid 11828 exit 0>]
661
- #
662
- # fname = "/usr/share/man/man1/ls.1.gz"
663
- # Open3.pipeline(["zcat", fname], "nroff -man", "colcrt")
664
- #
665
- # # convert PDF to PS and send to a printer by lpr
666
- # pdf_file = "paper.pdf"
667
- # printer = "printer-name"
668
- # Open3.pipeline(["pdftops", pdf_file, "-"],
669
- # ["lpr", "-P#{printer}"])
670
- #
671
- # # count lines
672
- # Open3.pipeline("sort", "uniq -c", :in=>"names.txt", :out=>"count")
673
- #
674
- # # cyclic pipeline
675
- # r,w = IO.pipe
676
- # w.print "ibase=14\n10\n"
677
- # Open3.pipeline("bc", "tee /dev/tty", :in=>r, :out=>w)
678
- # #=> 14
679
- # # 18
680
- # # 22
681
- # # 30
682
- # # 42
683
- # # 58
684
- # # 78
685
- # # 106
686
- # # 202
1332
+ # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
687
1333
  #
688
1334
  def pipeline(*cmds)
689
1335
  if Hash === cmds.last