mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
lib/open3.rb: tweaked grammar in comments
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43554 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
duerst
parent
e7194e9648
commit
d5f642ecc7
2 changed files with 49 additions and 45 deletions
|
|
@ -1,3 +1,7 @@
|
|||
Wed Nov 6 16:32:32 2013 Martin Duerst <duerst@it.aoyama.ac.jp>
|
||||
|
||||
* lib/open3.rb: tweaked grammar in comments
|
||||
|
||||
Wed Nov 6 11:46:36 2013 Masaki Matsushita <glass.saga@gmail.com>
|
||||
|
||||
* array.c (rb_ary_sample): use RARRAY_AREF() and RARRAY_PTR_USE()
|
||||
|
|
|
|||
90
lib/open3.rb
90
lib/open3.rb
|
|
@ -9,29 +9,29 @@
|
|||
#
|
||||
|
||||
#
|
||||
# Open3 grants you access to stdin, stdout, stderr and a thread to wait the
|
||||
# Open3 grants you access to stdin, stdout, stderr and a thread to wait for the
|
||||
# child process when running another program.
|
||||
# You can specify various attributes, redirections, current directory, etc., of
|
||||
# the program as Process.spawn.
|
||||
# the program in the same way as for Process.spawn.
|
||||
#
|
||||
# - Open3.popen3 : pipes for stdin, stdout, stderr
|
||||
# - Open3.popen2 : pipes for stdin, stdout
|
||||
# - Open3.popen2e : pipes for stdin, merged stdout and stderr
|
||||
# - Open3.capture3 : give a string for stdin. get strings for stdout, stderr
|
||||
# - Open3.capture2 : give a string for stdin. get a string for stdout
|
||||
# - Open3.capture2e : give a string for stdin. get a string for merged stdout and stderr
|
||||
# - Open3.capture3 : give a string for stdin; get strings for stdout, stderr
|
||||
# - Open3.capture2 : give a string for stdin; get a string for stdout
|
||||
# - Open3.capture2e : give a string for stdin; get a string for merged stdout and stderr
|
||||
# - Open3.pipeline_rw : pipes for first stdin and last stdout of a pipeline
|
||||
# - Open3.pipeline_r : pipe for last stdout of a pipeline
|
||||
# - Open3.pipeline_w : pipe for first stdin of a pipeline
|
||||
# - Open3.pipeline_start : run a pipeline and don't wait
|
||||
# - Open3.pipeline : run a pipeline and wait
|
||||
# - Open3.pipeline_start : run a pipeline without waiting
|
||||
# - Open3.pipeline : run a pipeline and wait for its completion
|
||||
#
|
||||
|
||||
module Open3
|
||||
|
||||
# Open stdin, stdout, and stderr streams and start external executable.
|
||||
# In addition, a thread for waiting the started process is noticed.
|
||||
# The thread has a pid method and thread variable :pid which is the pid of
|
||||
# In addition, a thread to wait for the started process is created.
|
||||
# The thread has a pid method and a thread variable :pid which is the pid of
|
||||
# the started process.
|
||||
#
|
||||
# Block form:
|
||||
|
|
@ -45,15 +45,15 @@ module Open3
|
|||
# Non-block form:
|
||||
#
|
||||
# stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts])
|
||||
# pid = wait_thr[:pid] # pid of the started process.
|
||||
# pid = wait_thr[:pid] # pid of the started process
|
||||
# ...
|
||||
# stdin.close # stdin, stdout and stderr should be closed explicitly in this form.
|
||||
# stdout.close
|
||||
# stderr.close
|
||||
# exit_status = wait_thr.value # Process::Status object returned.
|
||||
#
|
||||
# The parameters +cmd...+ is passed to Process.spawn.
|
||||
# So a commandline string and list of argument strings can be accepted as follows.
|
||||
# The parameters env, cmd, and opts are passed to Process.spawn.
|
||||
# A commandline string and a list of argument strings can be accepted as follows:
|
||||
#
|
||||
# Open3.popen3("echo abc") {|i, o, e, t| ... }
|
||||
# Open3.popen3("echo", "abc") {|i, o, e, t| ... }
|
||||
|
|
@ -65,19 +65,19 @@ module Open3
|
|||
# p o.read.chomp #=> "/"
|
||||
# }
|
||||
#
|
||||
# wait_thr.value waits the termination of the process.
|
||||
# The block form also waits the process when it returns.
|
||||
# wait_thr.value waits for the termination of the process.
|
||||
# The block form also waits for the process when it returns.
|
||||
#
|
||||
# Closing stdin, stdout and stderr does not wait the process.
|
||||
# Closing stdin, stdout and stderr does not wait for the process to complete.
|
||||
#
|
||||
# You should be careful to avoid deadlocks.
|
||||
# Since pipes are fixed length buffer,
|
||||
# Since pipes are fixed length buffers,
|
||||
# Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if
|
||||
# the program generates many output on stderr.
|
||||
# You should be read stdout and stderr simultaneously (using thread or IO.select).
|
||||
# However if you don't need stderr output, Open3.popen2 can be used.
|
||||
# the program generates too much output on stderr.
|
||||
# You should read stdout and stderr simultaneously (using threads or IO.select).
|
||||
# However, if you don't need stderr output, you can use Open3.popen2.
|
||||
# If merged stdout and stderr output is not a problem, you can use Open3.popen2e.
|
||||
# If you really needs stdout and stderr output as separate strings, you can consider Open3.capture3.
|
||||
# If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
|
||||
#
|
||||
def popen3(*cmd, &block)
|
||||
if Hash === cmd.last
|
||||
|
|
@ -100,7 +100,7 @@ module Open3
|
|||
end
|
||||
module_function :popen3
|
||||
|
||||
# Open3.popen2 is similer to Open3.popen3 except it doesn't make a pipe for
|
||||
# Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
|
||||
# the standard error stream.
|
||||
#
|
||||
# Block form:
|
||||
|
|
@ -158,7 +158,7 @@ module Open3
|
|||
end
|
||||
module_function :popen2
|
||||
|
||||
# Open3.popen2e is similer to Open3.popen3 except it merges
|
||||
# Open3.popen2e is similar to Open3.popen3 except that it merges
|
||||
# the standard output stream and the standard error stream.
|
||||
#
|
||||
# Block form:
|
||||
|
|
@ -238,7 +238,7 @@ module Open3
|
|||
#
|
||||
# If opts[:binmode] is true, internal pipes are set to binary mode.
|
||||
#
|
||||
# Example:
|
||||
# Examples:
|
||||
#
|
||||
# # dot is a command of graphviz.
|
||||
# graph = <<'End'
|
||||
|
|
@ -246,7 +246,7 @@ module Open3
|
|||
# a -> b
|
||||
# }
|
||||
# End
|
||||
# layouted_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
|
||||
# drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
|
||||
#
|
||||
# o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n")
|
||||
# p o #=> "abc\n"
|
||||
|
|
@ -254,11 +254,11 @@ module Open3
|
|||
# p s #=> #<Process::Status: pid 32682 exit 0>
|
||||
#
|
||||
# # generate a thumnail image using the convert command of ImageMagick.
|
||||
# # However, if the image stored really in a file,
|
||||
# # However, if the image is really stored in a file,
|
||||
# # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better
|
||||
# # because memory consumption.
|
||||
# # But if the image is stored in a DB or generated by gnuplot Open3.capture2 example,
|
||||
# # Open3.capture3 is considerable.
|
||||
# # because of reduced memory consumption.
|
||||
# # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example,
|
||||
# # Open3.capture3 should be considered.
|
||||
# #
|
||||
# image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true)
|
||||
# thumnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true)
|
||||
|
|
@ -383,7 +383,7 @@ module Open3
|
|||
module_function :capture2e
|
||||
|
||||
# Open3.pipeline_rw starts a list of commands as a pipeline with pipes
|
||||
# which connects stdin of the first command and stdout of the last command.
|
||||
# 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|
|
||||
# ...
|
||||
|
|
@ -403,15 +403,15 @@ module Open3
|
|||
# [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)
|
||||
#
|
||||
# Note that env and opts are optional, as Process.spawn.
|
||||
# Note that env and opts are optional, as for Process.spawn.
|
||||
#
|
||||
# The option to pass Process.spawn is constructed by merging
|
||||
# +opts+, the last hash element of the array and
|
||||
# specification for the pipe between each commands.
|
||||
# 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.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i,o,ts|
|
||||
# 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"
|
||||
|
|
@ -443,7 +443,7 @@ module Open3
|
|||
module_function :pipeline_rw
|
||||
|
||||
# Open3.pipeline_r starts a list of commands as a pipeline with a pipe
|
||||
# which connects stdout of the last command.
|
||||
# which connects to stdout of the last command.
|
||||
#
|
||||
# Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads|
|
||||
# ...
|
||||
|
|
@ -462,7 +462,7 @@ module Open3
|
|||
# [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)
|
||||
#
|
||||
# Note that env and opts are optional, as Process.spawn.
|
||||
# Note that env and opts are optional, as for Process.spawn.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
|
|
@ -495,7 +495,7 @@ module Open3
|
|||
module_function :pipeline_r
|
||||
|
||||
# Open3.pipeline_w starts a list of commands as a pipeline with a pipe
|
||||
# which connects stdin of the first command.
|
||||
# which connects to stdin of the first command.
|
||||
#
|
||||
# Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads|
|
||||
# ...
|
||||
|
|
@ -514,7 +514,7 @@ module Open3
|
|||
# [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)
|
||||
#
|
||||
# Note that env and opts are optional, as Process.spawn.
|
||||
# Note that env and opts are optional, as for Process.spawn.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
|
|
@ -538,7 +538,7 @@ module Open3
|
|||
module_function :pipeline_w
|
||||
|
||||
# Open3.pipeline_start starts a list of commands as a pipeline.
|
||||
# No pipe made for stdin of the first command and
|
||||
# No pipes are created for stdin of the first command and
|
||||
# stdout of the last command.
|
||||
#
|
||||
# Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads|
|
||||
|
|
@ -557,11 +557,11 @@ module Open3
|
|||
# [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)
|
||||
#
|
||||
# Note that env and opts are optional, as Process.spawn.
|
||||
# Note that env and opts are optional, as for Process.spawn.
|
||||
#
|
||||
# Example:
|
||||
#
|
||||
# # run xeyes in 10 seconds.
|
||||
# # Run xeyes in 10 seconds.
|
||||
# Open3.pipeline_start("xeyes") {|ts|
|
||||
# sleep 10
|
||||
# t = ts[0]
|
||||
|
|
@ -569,8 +569,8 @@ module Open3
|
|||
# p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)>
|
||||
# }
|
||||
#
|
||||
# # convert pdf to ps and send it to a printer.
|
||||
# # collect error message of pdftops and lpr.
|
||||
# # 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
|
||||
|
|
@ -598,8 +598,8 @@ module Open3
|
|||
module_function :pipeline_start
|
||||
|
||||
# Open3.pipeline starts a list of commands as a pipeline.
|
||||
# It waits the finish of the commands.
|
||||
# No pipe made for stdin of the first command and
|
||||
# It waits for the completion of the commands.
|
||||
# No pipes are created for stdin of the first command and
|
||||
# stdout of the last command.
|
||||
#
|
||||
# status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])
|
||||
|
|
|
|||
Loading…
Reference in a new issue