Add a "capture" helper, for capturing the stdout of a remote command and returning it as a string

git-svn-id: http://svn.rubyonrails.org/rails/tools/capistrano@6010 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

CHANGELOG

@@ -1,5 +1,7 @@
 *SVN*
 
+* Add a "capture" helper, for capturing the stdout of a remote command and returning it as a string [Jamis Buck]
+
 * Add a "get" helper, to pull a file from a remote server to the localhost [bmihelac]
 
 * Fix gateway to actually increment local_port if a port is in use, so that multiple capistrano instances can run at the same time [Mark Imbriaco]

lib/capistrano/actor.rb

@@ -290,6 +290,19 @@ module Capistrano
       end
     end
 
+    # Executes the given command on the first server targetted by the current
+    # task, collects it's stdout into a string, and returns the string.
+    def capture(command, options={})
+      output = ""
+      run(command, options.merge(:once => true)) do |ch, stream, data|
+        case stream
+        when :out then output << data
+        when :err then raise "error processing #{command.inspect}: #{data.inspect}"
+        end
+      end
+      output
+    end
+
     # Like #run, but executes the command via <tt>sudo</tt>. This assumes that
     # the sudo password (if required) is the same as the password for logging
     # in to the server.