Skip to content

Commit f319192

Browse files
[DOC] RDoc for Open3 (#15)
1 parent 4f8142c commit f319192

File tree

1 file changed

+81
-22
lines changed

1 file changed

+81
-22
lines changed

lib/open3.rb

Lines changed: 81 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -519,7 +519,7 @@ class << self
519519
# Open3.capture3('tee', stdin_data: 'Foo')
520520
# # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
521521
#
522-
# - If entry <tt>options[:binmode]</tt> exists, the entry us removed
522+
# - If entry <tt>options[:binmode]</tt> exists, the entry is removed
523523
# the internal streams are set to binary mode.
524524
#
525525
# The single required argument is one of the following:
@@ -604,34 +604,93 @@ def capture3(*cmd)
604604
end
605605
module_function :capture3
606606

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]
608610
#
609-
# stdout_str, status = Open3.capture2([env,] cmd... [, opts])
611+
# Basically a wrapper for Open3.popen3 that:
610612
#
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.
613618
#
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>:
615620
#
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.
617677
#
618678
# Example:
619679
#
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>]
635694
#
636695
def capture2(*cmd)
637696
if Hash === cmd.last

0 commit comments

Comments
 (0)