* lib/open3.rb (Open3.pipeline_start): return an array of threads if a

block is not given.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@20618 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,8 @@
+Thu Dec 11 02:23:51 2008  Tanaka Akira  <akr@fsij.org>
+
+	* lib/open3.rb (Open3.pipeline_start): return an array of threads if a
+	  block is not given.
+
 Thu Dec 11 01:48:00 2008  Yukihiro Matsumoto  <matz@ruby-lang.org>
 
 	* ext/bigdecimal/bigdecimal.c (BigDecimal_round): should be round

lib/open3.rb

@@ -11,6 +11,8 @@
 #
 # Open3 grants you access to stdin, stdout, stderr and a thread to wait the
 # child process when running another program.
+# You can specify various attributes, redirections, current directory, etc., of
+# the program as Process.spawn.
 #
 # - Open3.popen3 : pipes for stdin, stdout, stderr
 # - Open3.popen2 : pipes for stdin, stdout
@@ -50,14 +52,14 @@ module Open3
   #   stderr.close
   #   exit_status = wait_thr.value  # Process::Status object returned.
   #
-  # The parameters +cmd...+ is passed to Kernel#spawn.
+  # The parameters +cmd...+ is passed to Process.spawn.
   # So a commandline string and list of argument strings can be accepted as follows.
   #
   #   Open3.popen3("echo a") {|i, o, e, t| ... }
   #   Open3.popen3("echo", "a") {|i, o, e, t| ... }
   #   Open3.popen3(["echo", "argv0"], "a") {|i, o, e, t| ... }
   #
-  # If the last parameter, opts, is a Hash, it is recognized as an option for Kernel#spawn.
+  # If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
   #
   #   Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t|
   #     p o.read.chomp #=> "/"
@@ -107,6 +109,8 @@ module Open3
   #   stdin.close  # stdin and stdout should be closed explicitly in this form.
   #   stdout.close
   #
+  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  #
   # Example:
   #
   #   Open3.popen2("wc -c") {|i,o,t|
@@ -163,6 +167,8 @@ module Open3
   #   stdin.close  # stdin and stdout_and_stderr should be closed explicitly in this form.
   #   stdout_and_stderr.close
   #
+  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  #
   # Example:
   #   # check gcc warnings
   #   source = "foo.c"
@@ -216,7 +222,8 @@ module Open3
   #
   #   stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
   #
-  # The arguments cmd and opts are passed to Open3.popen3 except opts[:stdin_data].
+  # The arguments env, cmd and opts are passed to Open3.popen3 except
+  # opts[:stdin_data] and opts[:stdin_data].  See Process.spawn.
   #
   # If opts[:stdin_data] is specified, it is sent to the command's standard input.
   #
@@ -279,7 +286,8 @@ module Open3
   #
   #   stdout_str, status = Open3.capture2([env,] cmd... [, opts])
   #
-  # The arguments cmd and opts are passed to Open3.popen2 except opts[:stdin_data].
+  # The arguments env, cmd and opts are passed to Open3.popen3 except
+  # opts[:stdin_data] and opts[:stdin_data].  See Process.spawn.
   #
   # If opts[:stdin_data] is specified, it is sent to the command's standard input.
   #
@@ -330,7 +338,8 @@ module Open3
   #
   #   stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
   #
-  # The arguments cmd and opts are passed to Open3.popen2e except opts[:stdin_data].
+  # The arguments env, cmd and opts are passed to Open3.popen3 except
+  # opts[:stdin_data] and opts[:stdin_data].  See Process.spawn.
   #
   # If opts[:stdin_data] is specified, it is sent to the command's standard input.
   #
@@ -377,9 +386,17 @@ module Open3
   #   last_stdout.close
   #
   # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Kernel#spawn.
+  # If it is an array, the elements are passed to Process.spawn.
   #
-  # The option to pass Kernel#spawn is constructed by merging
+  #   cmd:
+  #     commandline                              command line string which is passed to a shell
+  #     [env, commandline, opts]                 command line string which is passed to a 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)
+  #
+  #   Note that env and opts are optional, as 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.
   #
@@ -427,6 +444,17 @@ module Open3
   #   ...
   #   last_stdout.close
   #
+  # Each cmd is a string or an array.
+  # If it is an array, the elements are passed to Process.spawn.
+  #
+  #   cmd:
+  #     commandline                              command line string which is passed to a shell
+  #     [env, commandline, opts]                 command line string which is passed to a 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)
+  #
+  #   Note that env and opts are optional, as Process.spawn.
+  #
   # Example:
   #
   #   Open3.pipeline_r("zcat /var/log/apache2/access.log.*.gz",
@@ -468,6 +496,17 @@ module Open3
   #   ...
   #   first_stdin.close
   #
+  # Each cmd is a string or an array.
+  # If it is an array, the elements are passed to Process.spawn.
+  #
+  #   cmd:
+  #     commandline                              command line string which is passed to a shell
+  #     [env, commandline, opts]                 command line string which is passed to a 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)
+  #
+  #   Note that env and opts are optional, as Process.spawn.
+  #
   # Example:
   #
   #   Open3.pipeline_w("bzip2 -c", :out=>"/tmp/hello.bz2") {|w, ts|
@@ -500,6 +539,17 @@ module Open3
   #   wait_threads = Open3.pipeline_start(cmd1, cmd2, ... [, opts])
   #   ...
   #
+  # Each cmd is a string or an array.
+  # If it is an array, the elements are passed to Process.spawn.
+  #
+  #   cmd:
+  #     commandline                              command line string which is passed to a shell
+  #     [env, commandline, opts]                 command line string which is passed to a 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)
+  #
+  #   Note that env and opts are optional, as Process.spawn.
+  #
   # Example:
   #
   #   # run xeyes in 10 seconds.
@@ -510,6 +560,18 @@ 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.
+  #   pdf_file = "paper.pdf"
+  #   printer = "printer-name"
+  #   err_r, err_w = IO.pipe
+  #   Open3.pipeline_start(["pdftops", pdf_file, "-"],
+  #                        ["lpr", "-P#{printer}"],
+  #                        :err=>err_w) {|ts|
+  #     err_w.close
+  #     p err_r.read # error messages of pdftops and lpr.
+  #   }
+  #
   def pipeline_start(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -517,7 +579,12 @@ module Open3
       opts = {}
     end
 
+    if block
       pipeline_run(cmds, opts, [], [], &block)
+    else
+      ts, = pipeline_run(cmds, opts, [], [])
+      ts
+    end
   end
   module_function :pipeline_start
 
@@ -528,6 +595,17 @@ module Open3
   #
   #   status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])
   #
+  # Each cmd is a string or an array.
+  # If it is an array, the elements are passed to Process.spawn.
+  #
+  #   cmd:
+  #     commandline                              command line string which is passed to a shell
+  #     [env, commandline, opts]                 command line string which is passed to a 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)
+  #
+  #   Note that env and opts are optional, as Process.spawn.
+  #
   # Example:
   #
   #   fname = "/usr/share/man/man1/ruby.1.gz"

test/test_open3.rb

@@ -214,6 +214,15 @@ class TestOpen3 < Test::Unit::TestCase
     }
   end
 
+  def test_pipeline_start_noblock
+    ts = Open3.pipeline_start([RUBY, '-e', ''])
+    assert_kind_of(Array, ts)
+    assert_equal(1, ts.length)
+    ts.each {|t| assert_kind_of(Thread, t) }
+    t = ts[0]
+    assert(t.value.success?)
+  end
+
   def test_pipeline
     command = [RUBY, '-e', 's=STDIN.read; print s[1..-1]; exit s[0] == ?t']
     str = 'ttftff'