lib/ztk/command.rb in ztk-0.0.7 vs lib/ztk/command.rb in ztk-0.0.8

@@ -1,8 +1,8 @@
 ################################################################################
 #
-#      Author: Zachary Patten <[e-mail]>
+#      Author: Zachary Patten <[e-mail]>
 #   Copyright: Copyright (c) Jove Labs
 #     License: Apache License, Version 2.0
 #
 #   Licensed under the Apache License, Version 2.0 (the "License");
 #   you may not use this file except in compliance with the License.
@@ -21,25 +21,45 @@
 require "ostruct"
 
 module ZTK
 
   # ZTK::Command error class
-  # @author Zachary Patten <[e-mail]>
+  #
+  # @author Zachary Patten <[e-mail]>
   class CommandError < Error; end
 
-################################################################################
-
+  # Command Execution Class
+  #
+  # We can get a new instance of Command like so:
+  #
+  #     cmd = ZTK::Command.new
+  #
+  # If we wanted to redirect STDOUT and STDERR to a StringIO we can do this:
+  #
+  #     std_combo = StringIO.new
+  #     cmd = ZTK::Command.new(:stdout => std_combo, :stderr => std_combo)
+  #
+  # @author Zachary Patten <[e-mail]>
   class Command < ZTK::Base
 
-################################################################################
-
     def initialize(config={})
       super(config)
     end
 
-################################################################################
-
+    # Executes a local command.
+    #
+    # @param [String] command The command to execute.
+    # @param [Hash] options The options hash for executing the command.
+    #
+    # @return [OpenStruct#output] The output of the command, both STDOUT and
+    #   STDERR.
+    # @return [OpenStruct#exit] The exit status (i.e. $?).
+    #
+    # @example Execute a command:
+    #
+    #   cmd = ZTK::Command.new
+    #   puts cmd.exec("hostname -f").inspect
     def exec(command, options={})
       options = OpenStruct.new({ :exit_code => 0, :silence => false }.merge(options))
       log(:debug) { "config(#{@config.inspect})" }
       log(:debug) { "options(#{options.inspect})" }
       log(:debug) { "command(#{command.inspect})" }
@@ -63,13 +83,17 @@
       child_stdout_writer.close
       child_stderr_writer.close
 
       Process.waitpid(pid)
 
-      @config.stdout.write(parent_stdout_reader.read) unless options.silence
-      @config.stderr.write(parent_stderr_reader.read) unless options.silence
+      stdout = parent_stdout_reader.read
+      stderr = parent_stderr_reader.read
+      output = (stdout || '') + (stderr || '')
 
+      @config.stdout.write(stdout) unless options.silence
+      @config.stderr.write(stderr) unless options.silence
+
       parent_stdout_reader.close
       parent_stderr_reader.close
 
       log(:debug) { "exit_code(#{$?.inspect})" }
 
@@ -77,25 +101,19 @@
         message = "exec(#{command.inspect}, #{options.inspect}) failed! [#{$?.inspect}]"
         log(:fatal) { message }
         raise CommandError, message
       end
 
-      $?
+      OpenStruct.new(:output => output, :exit => $?)
     end
 
     def upload(*args)
       raise CommandError, "Not Implemented"
     end
 
     def download(*args)
       raise CommandError, "Not Implemented"
     end
 
-################################################################################
-
   end
 
-################################################################################
-
 end
-
-################################################################################