lib/open3.rb

   1 #
   2 # = open3.rb: Popen, but with stderr, too
   3 #
   4 # Author:: Yukihiro Matsumoto
   5 # Documentation:: Konrad Meyer
   6 #
   7 # Open3 gives you access to stdin, stdout, and stderr when running other
   8 # programs.
   9 #
  10
  11 #
  12 # Open3 grants you access to stdin, stdout, stderr and a thread to wait the
  13 # child process when running another program.
  14 #
  15 # Example:
  16 #
  17 #   require "open3"
  18 #   include Open3
  19 #
  20 #   stdin, stdout, stderr, wait_thr = popen3('nroff -man')
  21 #
  22 # Open3.popen3 can also take a block which will receive stdin, stdout,
  23 # stderr and wait_thr as parameters.
  24 # This ensures stdin, stdout and stderr are closed and
  25 # the process is terminated once the block exits.
  26 #
  27 # Example:
  28 #
  29 #   require "open3"
  30 #
  31 #   Open3.popen3('nroff -man') { |stdin, stdout, stderr, wait_thr| ... }
  32 #
  33
  34 module Open3
  35   #
  36   # Open stdin, stdout, and stderr streams and start external executable.
  37   # In addition, a thread for waiting the started process is noticed.
  38   # The thread has a thread variable :pid which is the pid of the started
  39   # process.
  40   #
  41   # Non-block form:
  42   #
  43   #   stdin, stdout, stderr, wait_thr = Open3.popen3(cmd)
  44   #   pid = wait_thr[:pid]  # pid of the started process.
  45   #   ...
  46   #   stdin.close  # stdin, stdout and stderr should be closed in this form.
  47   #   stdout.close
  48   #   stderr.close
  49   #   exit_status = wait_thr.value  # Process::Status object returned.
  50   #
  51   # Block form:
  52   #
  53   #   Open3.popen3(cmd) { |stdin, stdout, stderr, wait_thr| ... }
  54   #
  55   # The parameter +cmd+ is passed directly to Kernel#spawn.
  56   #
  57   # wait_thr.value waits the termination of the process.
  58   # The block form also waits the process when it returns.
  59   #
  60   # Closing stdin, stdout and stderr does not wait the process.
  61   #
  62   def popen3(*cmd)
  63     pw = IO::pipe   # pipe[0] for read, pipe[1] for write
  64     pr = IO::pipe
  65     pe = IO::pipe
  66
  67     pid = spawn(*cmd, STDIN=>pw[0], STDOUT=>pr[1], STDERR=>pe[1])
  68     wait_thr = Process.detach(pid)
  69     pw[0].close
  70     pr[1].close
  71     pe[1].close
  72     pi = [pw[1], pr[0], pe[0], wait_thr]
  73     pw[1].sync = true
  74     if defined? yield
  75       begin
  76         return yield(*pi)
  77       ensure
  78         [pw[1], pr[0], pe[0]].each{|p| p.close unless p.closed?}
  79         wait_thr.join
  80       end
  81     end
  82     pi
  83   end
  84   module_function :popen3
  85 end
  86
  87 if $0 == __FILE__
  88   a = Open3.popen3("nroff -man")
  89   Thread.start do
  90     while line = gets
  91       a[0].print line
  92     end
  93     a[0].close
  94   end
  95   while line = a[1].gets
  96     print ":", line
  97   end
  98 end