1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

lib/open3.rb: tweaked grammar in comments

Browse Source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43554 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
duerst 2013-11-06 07:32:56 +00:00
parent e7194e9648
commit d5f642ecc7
2 changed files with 49 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
ChangeLog
View File

@ -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> 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() * array.c (rb_ary_sample): use RARRAY_AREF() and RARRAY_PTR_USE()

90
lib/open3.rb
View File

@ -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. # child process when running another program.
# You can specify various attributes, redirections, current directory, etc., of # 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.popen3 : pipes for stdin, stdout, stderr
# - Open3.popen2 : pipes for stdin, stdout # - Open3.popen2 : pipes for stdin, stdout
# - Open3.popen2e : pipes for stdin, merged stdout and stderr # - Open3.popen2e : pipes for stdin, merged stdout and stderr
# - Open3.capture3 : give a string for stdin. get strings for stdout, 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.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.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_rw : pipes for first stdin and last stdout of a pipeline
# - Open3.pipeline_r : pipe for 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_w : pipe for first stdin of a pipeline
# - Open3.pipeline_start : run a pipeline and don't wait # - Open3.pipeline_start : run a pipeline without waiting
# - Open3.pipeline : run a pipeline and wait # - Open3.pipeline : run a pipeline and wait for its completion
# #
module Open3 module Open3
# Open stdin, stdout, and stderr streams and start external executable. # Open stdin, stdout, and stderr streams and start external executable.
# In addition, a thread for waiting the started process is noticed. # In addition, a thread to wait for the started process is created.
# The thread has a pid method and thread variable :pid which is the pid of # The thread has a pid method and a thread variable :pid which is the pid of
# the started process. # the started process.
# #
# Block form: # Block form:
@ -45,15 +45,15 @@ module Open3
# Non-block form: # Non-block form:
# #
# stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts]) # 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. # stdin.close # stdin, stdout and stderr should be closed explicitly in this form.
# stdout.close # stdout.close
# stderr.close # stderr.close
# exit_status = wait_thr.value # Process::Status object returned. # exit_status = wait_thr.value # Process::Status object returned.
# #
# The parameters +cmd...+ is passed to Process.spawn. # The parameters env, cmd, and opts are passed to Process.spawn.
# So a commandline string and list of argument strings can be accepted as follows. # 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| ... }
# 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 #=> "/" # p o.read.chomp #=> "/"
# } # }
# #
# wait_thr.value waits the termination of the process. # wait_thr.value waits for the termination of the process.
# The block form also waits the process when it returns. # 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. # 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 # Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if
# the program generates many output on stderr. # the program generates too much output on stderr.
# You should be read stdout and stderr simultaneously (using thread or IO.select). # You should read stdout and stderr simultaneously (using threads or IO.select).
# However if you don't need stderr output, Open3.popen2 can be used. # 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 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) def popen3(*cmd, &block)
if Hash === cmd.last if Hash === cmd.last
@ -100,7 +100,7 @@ module Open3
end end
module_function :popen3 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. # the standard error stream.
# #
# Block form: # Block form:
@ -158,7 +158,7 @@ module Open3
end end
module_function :popen2 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. # the standard output stream and the standard error stream.
# #
# Block form: # Block form:
@ -238,7 +238,7 @@ module Open3
# #
# If opts[:binmode] is true, internal pipes are set to binary mode. # If opts[:binmode] is true, internal pipes are set to binary mode.
# #
# Example: # Examples:
# #
# # dot is a command of graphviz. # # dot is a command of graphviz.
# graph = <<'End' # graph = <<'End'
@ -246,7 +246,7 @@ module Open3
# a -> b # a -> b
# } # }
# End # 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") # o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n")
# p o #=> "abc\n" # p o #=> "abc\n"
@ -254,11 +254,11 @@ module Open3
# p s #=> #<Process::Status: pid 32682 exit 0> # p s #=> #<Process::Status: pid 32682 exit 0>
# #
# # generate a thumnail image using the convert command of ImageMagick. # # 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 # # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better
# # because memory consumption. # # because of reduced memory consumption.
# # But if the image is stored in a DB or generated by gnuplot Open3.capture2 example, # # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example,
# # Open3.capture3 is considerable. # # Open3.capture3 should be considered.
# # # #
# image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true) # 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) # thumnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true)
@ -383,7 +383,7 @@ module Open3
module_function :capture2e module_function :capture2e
# Open3.pipeline_rw starts a list of commands as a pipeline with pipes # 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| # 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, 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) # [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 # The options to pass to Process.spawn are constructed by merging
# +opts+, the last hash element of the array and # +opts+, the last hash element of the array, and
# specification for the pipe between each commands. # specifications for the pipes between each of the commands.
# #
# Example: # 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.puts "All persons more than a mile high to leave the court."
# i.close # i.close
# p o.gets #=> "42\n" # p o.gets #=> "42\n"
@ -443,7 +443,7 @@ module Open3
module_function :pipeline_rw module_function :pipeline_rw
# Open3.pipeline_r starts a list of commands as a pipeline with a pipe # 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| # 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, 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) # [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: # Example:
# #
@ -495,7 +495,7 @@ module Open3
module_function :pipeline_r module_function :pipeline_r
# Open3.pipeline_w starts a list of commands as a pipeline with a pipe # 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| # 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, 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) # [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: # Example:
# #
@ -538,7 +538,7 @@ module Open3
module_function :pipeline_w module_function :pipeline_w
# Open3.pipeline_start starts a list of commands as a pipeline. # 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. # stdout of the last command.
# #
# Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads| # 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, 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) # [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: # Example:
# #
# # run xeyes in 10 seconds. # # Run xeyes in 10 seconds.
# Open3.pipeline_start("xeyes") {|ts| # Open3.pipeline_start("xeyes") {|ts|
# sleep 10 # sleep 10
# t = ts[0] # t = ts[0]
@ -569,8 +569,8 @@ module Open3
# p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)> # p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)>
# } # }
# #
# # convert pdf to ps and send it to a printer. # # Convert pdf to ps and send it to a printer.
# # collect error message of pdftops and lpr. # # Collect error message of pdftops and lpr.
# pdf_file = "paper.pdf" # pdf_file = "paper.pdf"
# printer = "printer-name" # printer = "printer-name"
# err_r, err_w = IO.pipe # err_r, err_w = IO.pipe
@ -598,8 +598,8 @@ module Open3
module_function :pipeline_start module_function :pipeline_start
# Open3.pipeline starts a list of commands as a pipeline. # Open3.pipeline starts a list of commands as a pipeline.
# It waits the finish of the commands. # It waits for the completion of the commands.
# 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. # stdout of the last command.
# #
# status_list = Open3.pipeline(cmd1, cmd2, ... [, opts]) # status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])