@@ -519,7 +519,7 @@ class << self
519
519
# Open3.capture3('tee', stdin_data: 'Foo')
520
520
# # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
521
521
#
522
- # - If entry <tt>options[:binmode]</tt> exists, the entry us removed
522
+ # - If entry <tt>options[:binmode]</tt> exists, the entry is removed
523
523
# the internal streams are set to binary mode.
524
524
#
525
525
# The single required argument is one of the following:
@@ -604,34 +604,93 @@ def capture3(*cmd)
604
604
end
605
605
module_function :capture3
606
606
607
- # Open3.capture2 captures the standard output of a command.
607
+ # :call-seq:
608
+ # Open3.capture2([env, ] command_line, options = {}) -> [stdout_s, status]
609
+ # Open3.capture2([env, ] exe_path, *args, options = {}) -> [stdout_s, status]
608
610
#
609
- # stdout_str, status = Open3.capture2([env,] cmd... [, opts])
611
+ # Basically a wrapper for Open3.popen3 that:
610
612
#
611
- # The arguments env, cmd and opts are passed to Open3.popen3 except
612
- # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>. See Process.spawn.
613
+ # - Creates a child process, by calling Open3.popen3 with the given arguments
614
+ # (except for certain entries in hash +options+; see below).
615
+ # - Returns as string +stdout+ the standard output of the child process.
616
+ # - Returns as +status+ a <tt>Process::Status</tt> object
617
+ # that represents the exit status of the child process.
613
618
#
614
- # If <code>opts[:stdin_data ]</code> is specified, it is sent to the command's standard input.
619
+ # Returns the array <tt>[stdin_s, status ]</tt>:
615
620
#
616
- # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
621
+ # stdout_s, status = Open3.capture2('echo "Foo"')
622
+ # # => ["Foo\n", #<Process::Status: pid 2326047 exit 0>]
623
+ #
624
+ # Like Process.spawn, this method has potential security vulnerabilities
625
+ # if called with untrusted input;
626
+ # see {Command Injection}[rdoc-ref:command_injection.rdoc].
627
+ #
628
+ # Unlike Process.spawn, this method waits for the child process to exit
629
+ # before returning, so the caller need not do so.
630
+ #
631
+ # Argument +options+ is a hash of options for the new process;
632
+ # see {Execution Options}[rdoc-ref:Process@Execution+Options].
633
+ #
634
+ # The hash +options+ is passed to method Open3.popen3;
635
+ # two options have local effect in method Open3.capture2:
636
+ #
637
+ # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
638
+ # and its string value is sent to the command's standard input:
639
+ #
640
+ # Open3.capture2('tee', stdin_data: 'Foo')
641
+ # # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
642
+ #
643
+ # the internal streams are set to binary mode.
644
+ #
645
+ # The single required argument is one of the following:
646
+ #
647
+ # - +command_line+ if it is a string,
648
+ # and if it begins with a shell reserved word or special built-in,
649
+ # or if it contains one or more metacharacters.
650
+ # - +exe_path+ otherwise.
651
+ #
652
+ # <b>Argument +command_line+</b>
653
+ #
654
+ # \String argument +command_line+ is a command line to be passed to a shell;
655
+ # it must begin with a shell reserved word, begin with a special built-in,
656
+ # or contain meta characters:
657
+ #
658
+ # Open3.capture2('if true; then echo "Foo"; fi') # Shell reserved word.
659
+ # # => ["Foo\n", #<Process::Status: pid 2326131 exit 0>]
660
+ # Open3.capture2('echo') # Built-in.
661
+ # # => ["\n", #<Process::Status: pid 2326139 exit 0>]
662
+ # Open3.capture2('date > date.tmp') # Contains meta character.
663
+ # # => ["", #<Process::Status: pid 2326174 exit 0>]
664
+ #
665
+ # The command line may also contain arguments and options for the command:
666
+ #
667
+ # Open3.capture2('echo "Foo"')
668
+ # # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
669
+ #
670
+ # <b>Argument +exe_path+</b>
671
+ #
672
+ # Argument +exe_path+ is one of the following:
673
+ #
674
+ # - The string path to an executable to be called.
675
+ # - A 2-element array containing the path to an executable
676
+ # and the string to be used as the name of the executing process.
617
677
#
618
678
# Example:
619
679
#
620
- # # factor is a command for integer factorization.
621
- # o, s = Open3.capture2("factor", :stdin_data=>"42")
622
- # p o #=> "42: 2 3 7\n"
623
- #
624
- # # generate x**2 graph in png using gnuplot.
625
- # gnuplot_commands = <<"End"
626
- # set terminal png
627
- # plot x**2, "-" with lines
628
- # 1 14
629
- # 2 1
630
- # 3 8
631
- # 4 5
632
- # e
633
- # End
634
- # image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
680
+ # Open3.capture2('/usr/bin/date')
681
+ # # => ["Fri Sep 29 01:00:39 PM CDT 2023\n", #<Process::Status: pid 2326222 exit 0>]
682
+ #
683
+ # Ruby invokes the executable directly, with no shell and no shell expansion:
684
+ #
685
+ # Open3.capture2('doesnt_exist') # Raises Errno::ENOENT
686
+ #
687
+ # If one or more +args+ is given, each is an argument or option
688
+ # to be passed to the executable:
689
+ #
690
+ # Open3.capture2('echo', 'C #')
691
+ # # => ["C #\n", #<Process::Status: pid 2326267 exit 0>]
692
+ # Open3.capture2('echo', 'hello', 'world')
693
+ # # => ["hello world\n", #<Process::Status: pid 2326299 exit 0>]
635
694
#
636
695
def capture2 ( *cmd )
637
696
if Hash === cmd . last
0 commit comments