cheetah 0.2.1 → 0.3.0

data/CHANGELOG

@@ -1,3 +1,21 @@
+0.3.0 (2012-06-21)
+------------------
+
+* Allowed passing an IO in the :stdin option.
+* Replaced the :capture option with :stdout and :stderr and allowed streaming
+  standard and error output into an IO.
+* Implemented support for piped commands.
+* Implemented the :recorder option allowing to customize logging.
+* Replaced Cheetah.logger with more generic Cheetah.default_options.
+* Commands in logs and exception messages are now directly copy-pastable into
+  the shell.
+* Officially supports Ruby 1.8.7 and 1.9.3 on Unix systems.
+* Added Travis CI integration.
+* Various internal code improvements and fixes.
+* Improved gem description and summary.
+* Improved documentation.
+* Improved README.md.
+
 0.2.1 (2012-04-12)
 ------------------
 

data/README.md

@@ -1,14 +1,20 @@
 Cheetah
 =======
 
-Cheetah is a simple library for executing external commands safely and conveniently.
+Your swiss army knife for executing external commands in Ruby safely and
+conveniently.
 
 Examples
 --------
 
 ```ruby
 # Run a command and capture its output
-files = Cheetah.run("ls", "-la", :capture => :stdout)
+files = Cheetah.run("ls", "-la", :stdout => :capture)
+
+# Run a command and capture its output into a stream
+File.open("files.txt", "w") do |stdout|
+  Cheetah.run("ls", "-la", :stdout => stdout)
+end
 
 # Run a command and handle errors
 begin
@@ -25,6 +31,7 @@ Features
 
   * Easy passing of command input
   * Easy capturing of command output (standard, error, or both)
+  * Piping commands together
   * 100% secure (shell expansion is impossible by design)
   * Raises exceptions on errors (no more manual status code checks)
   * Optional logging for easy debugging
@@ -32,7 +39,6 @@ Features
 Non-features
 ------------
 
-  * Handling of commands producing big outputs
   * Handling of interactive commands
 
 Installation
@@ -49,23 +55,73 @@ First, require the library:
 require "cheetah"
 ```
 
-You can now use the `Cheetah.run` method to run commands, pass them an input and capture their output:
+You can now use the `Cheetah.run` method to run commands.
+
+### Running Commands
+
+To run a command, just specify it together with its arguments:
 
 ```ruby
-# Run a command with arguments
 Cheetah.run("tar", "xzf", "foo.tar.gz")
+```
+### Passing Input
 
-# Pass an input
+Using the `:stdin` option you can pass a string to command's standard input:
+
+```ruby
 Cheetah.run("python", :stdin => source_code)
+```
+
+If the input is big you may want to avoid passing it in one huge string. In that
+case, pass an `IO` as a value of the `:stdin` option. The command will read its
+input from it gradually.
+
+```ruby
+File.open("huge_program.py") do |stdin|
+  Cheetah.run("python", :stdin => stdin)
+end
+```
+
+### Capturing Output
+
+To capture command's standard output, set the `:stdout` option to `:capture`.
+You will receive the output as a return value of the call:
 
-# Capture standard output
-files = Cheetah.run("ls", "-la", :capture => :stdout)
+```ruby
+files = Cheetah.run("ls", "-la", :stdout => :capture)
+```
+
+The same technique works with the error output — just use the `:stderr` option.
+If you specify capturing of both outputs, the return value will be a two-element
+array:
 
-# Capture both standard and error output
-results, errors = Cheetah.run("grep", "-r", "User", ".", :capture => [:stdout, :stderr))
+```ruby
+results, errors = Cheetah.run("grep", "-r", "User", ".", :stdout => :capture, :stderr => :capture)
 ```
 
-If the command can't be executed for some reason or returns a non-zero exit status, the method raises an exception with detailed information about the failure:
+If the output is big you may want to avoid capturing it into a huge string. In
+that case, pass an `IO` as a value of the `:stdout` or `:stderr` option. The
+command will write its output into it gradually.
+
+```ruby
+File.open("files.txt", "w") do |stdout|
+  Cheetah.run("ls", "-la", :stdout => stdout)
+end
+```
+
+### Piping Commands
+
+You can pipe multiple commands together and execute them as one. Just specify
+the commands together with their arguments as arrays:
+
+```ruby
+processes = Cheetah.run(["ps", "aux"], ["grep", "ruby"], :stdout => :capture)
+```
+
+### Error Handling
+
+If the command can't be executed for some reason or returns a non-zero exit
+status, Cheetah raises an exception with detailed information about the failure:
 
 ```ruby
 # Run a command and handle errors
@@ -77,19 +133,43 @@ rescue Cheetah::ExecutionFailed => e
   puts "Error ouptut:    #{e.stderr}"
 end
 ```
+### Logging
 
-For debugging purposes, you can also use a logger. Cheetah will log the command, its status, input and both outputs to it. The `:info` level will be used for normal messages, the `:error` level for messages about errors (non-zero exit status or non-empty error output):
+For debugging purposes, you can use a logger. Cheetah will log the command, its
+status, input and both outputs to it:
 
 ```ruby
-# Log the execution
 Cheetah.run("ls -l", :logger => logger)
+```
+
+### Setting Defaults
+
+To avoid repetition, you can set global default value of any option passed too
+`Cheetah.run`:
 
-# Or, if you're tired of passing the :logger option all the time...
-Cheetah.logger = my_logger
+```ruby
+# If you're tired of passing the :logger option all the time...
+Cheetah.default_options = { :logger = my_logger }
 Cheetah.run("./configure")
 Cheetah.run("make")
 Cheetah.run("make", "install")
-Cheetah.logger = nil
+Cheetah.default_options = {}
 ```
 
-For more information, see the [API documentation](http://rubydoc.info/github/openSUSE/cheetah/frames).
+### More Information
+
+For more information, see the
+[API documentation](http://rubydoc.info/github/openSUSE/cheetah/frames).
+
+Compatibility
+-------------
+
+Cheetah should run well on any Unix system with Ruby 1.8.7 or 1.9.3. Non-Unix
+systems and different Ruby implementations/versions may work too but they were
+not tested.
+
+Authors
+-------
+
+  * [David Majda](http://github.com/dmajda)
+  * [Josef Reidinger](http://github.com/jreidinger)

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/lib/cheetah.rb

@@ -1,20 +1,33 @@
-# A simple library for executing external commands safely and conveniently.
+require "abstract_method"
+require "logger"
+require "shellwords"
+require "stringio"
+
+require File.expand_path(File.dirname(__FILE__) + "/cheetah/version")
+
+# Your swiss army knife for executing external commands in Ruby safely and
+# conveniently.
 #
 # ## Features
 #
 #   * Easy passing of command input
 #   * Easy capturing of command output (standard, error, or both)
+#   * Piping commands together
 #   * 100% secure (shell expansion is impossible by design)
 #   * Raises exceptions on errors (no more manual status code checks)
 #   * Optional logging for easy debugging
 #
 # ## Non-features
 #
-#   * Handling of commands producing big outputs
 #   * Handling of interactive commands
 #
 # @example Run a command and capture its output
-#   files = Cheetah.run("ls", "-la", :capture => :stdout)
+#   files = Cheetah.run("ls", "-la", :stdout => :capture)
+#
+# @example Run a command and capture its output into a stream
+#   File.open("files.txt", "w") do |stdout|
+#     Cheetah.run("ls", "-la", :stdout => stdout)
+#   end
 #
 # @example Run a command and handle errors
 #   begin
@@ -25,102 +38,271 @@
 #     puts "Error ouptut:    #{e.stderr}"
 #   end
 module Cheetah
-  # Cheetah version (uses [semantic versioning](http://semver.org/)).
-  VERSION = File.read(File.dirname(__FILE__) + "/../VERSION").strip
-
   # Exception raised when a command execution fails.
   class ExecutionFailed < StandardError
-    # @return [String] the executed command
-    attr_reader :command
-
-    # @return [Array<String>] the executed command arguments
-    attr_reader :args
+    # @return [Array<Array<String>>] the executed commands as an array where
+    #   each item is again an array containing an executed command in the first
+    #   element and its arguments in the remaining ones
+    attr_reader :commands
 
     # @return [Process::Status] the executed command exit status
     attr_reader :status
 
-    # @return [String] the output the executed command wrote to stdout
+    # @return [String, nil] the output the executed command wrote to stdout; can
+    #   be `nil` if stdout was captured into a stream
     attr_reader :stdout
 
-    # @return [String] the output the executed command wrote to stderr
+    # @return [String, nil] the output the executed command wrote to stderr; can
+    #   be `nil` if stderr was captured into a stream
     attr_reader :stderr
 
     # Initializes a new {ExecutionFailed} instance.
     #
-    # @param [String] command the executed command
-    # @param [Array<String>] args the executed command arguments
+    # @param [Array<Array<String>>] commands the executed commands as an array
+    #   where each item is again an array containing an executed command in the
+    #   first element and its arguments in the remaining ones
     # @param [Process::Status] status the executed command exit status
-    # @param [String] stdout the output the executed command wrote to stdout
-    # @param [String] stderr the output the executed command wrote to stderr
+    # @param [String, nil] stdout the output the executed command wrote to stdout
+    # @param [String, nil] stderr the output the executed command wrote to stderr
     # @param [String, nil] message the exception message
-    def initialize(command, args, status, stdout, stderr, message = nil)
+    def initialize(commands, status, stdout, stderr, message = nil)
       super(message)
-      @command = command
-      @args    = args
-      @status  = status
-      @stdout  = stdout
-      @stderr  = stderr
+      @commands = commands
+      @status   = status
+      @stdout   = stdout
+      @stderr   = stderr
+    end
+  end
+
+  # Defines a recorder interface. Recorder is an object that handles recording
+  # of the command execution into a logger. It decides what exactly gets logged,
+  # at what level and using what messages.
+  #
+  # @abstract
+  class Recorder
+    # @!method record_commands(commands)
+    #   Called to record the executed commands.
+    #
+    #   @abstract
+    #   @param [Array<Array<String>>] commands the executed commands as an array
+    #     where each item is again an array containing an executed command in
+    #     the first element and its arguments in the remaining ones
+    abstract_method :record_commands
+
+    # @!method record_stdin(stdin)
+    #   Called to record the executed command input (if it wasn't read from a
+    #   stream).
+    #
+    #   @abstract
+    #   @param [String] stdin the executed command input
+    abstract_method :record_stdin
+
+    # @!method record_status(status)
+    #   Called to record the executed command exit status.
+    #
+    #   @abstract
+    #   @param [Process::Status] status the executed command exit status
+    abstract_method :record_status
+
+    # @!method record_stdout(stdout)
+    #   Called to record the output the executed command wrote to stdout (if it
+    #   wasn't captured into a stream).
+    #
+    #   @abstract
+    #   @param [String] stdout the output the executed command wrote to stdout
+    abstract_method :record_stdout
+
+    # @!method record_stderr(stderr)
+    #   Called to record the output the executed command wrote to stderr (if it
+    #   wasn't captured into a stream).
+    #
+    #   @abstract
+    #   @param [String] stderr the output the executed command wrote to stderr
+    abstract_method :record_stderr
+  end
+
+  # A recorder that does not record anyting. Used by {Cheetah.run} when no
+  # logger is passed.
+  class NullRecorder < Recorder
+    def record_commands(commands); end
+    def record_stdin(stdin);       end
+    def record_status(status);     end
+    def record_stdout(stdout);     end
+    def record_stderr(stderr);     end
+  end
+
+  # A default recorder. It uses the `Logger::INFO` level for normal messages and
+  # the `Logger::ERROR` level for messages about errors (non-zero exit status or
+  # non-empty error output). Used by {Cheetah.run} when a logger is passed.
+  class DefaultRecorder < Recorder
+    def initialize(logger)
+      @logger = logger
+    end
+
+    def record_commands(commands)
+      @logger.info "Executing #{format_commands(commands)}."
+    end
+
+    def record_stdin(stdin)
+      @logger.info "Standard input: #{format_input_output(stdin)}"
+    end
+
+    def record_status(status)
+      @logger.send status.success? ? :info : :error,
+        "Status: #{status.exitstatus}"
+    end
+
+    def record_stdout(stdout)
+      @logger.info "Standard output: #{format_input_output(stdout)}"
+    end
+
+    def record_stderr(stderr)
+      @logger.send stderr.empty? ? :info : :error,
+        "Error output: #{format_input_output(stderr)}"
+    end
+
+    protected
+
+    def format_input_output(s)
+      s.empty? ? "(none)" : s
+    end
+
+    def format_commands(commands)
+      '"' + commands.map { |c| Shellwords.join(c) }.join(" | ") + '"'
     end
   end
 
+  # @private
+  BUILTIN_DEFAULT_OPTIONS = {
+    :stdin              => "",
+    :stdout             => nil,
+    :stderr             => nil,
+    :logger             => nil
+  }
+
+  READ  = 0 # @private
+  WRITE = 1 # @private
+
   class << self
-    # The global logger or `nil` if none is set (the default). This logger is
-    # used by {Cheetah.run} unless overridden by the `:logger` option.
+    # The default options of the {Cheetah.run} method. Values of options not
+    # specified in its `options` parameter are taken from here. If a value is
+    # not specified here too, the default value described in the {Cheetah.run}
+    # documentation is used.
+    #
+    # By default, no values are specified here.
+    #
+    # @example Setting a logger once for execution of multiple commands
+    #   Cheetah.default_options = { :logger = my_logger }
+    #   Cheetah.run("./configure")
+    #   Cheetah.run("make")
+    #   Cheetah.run("make", "install")
+    #   Cheetah.default_options = {}
     #
-    # @return [Logger, nil] the global logger
-    attr_accessor :logger
+    # @return [Hash] the default options of the {Cheetah.run} method
+    attr_accessor :default_options
 
-    # Runs an external command with specified arguments, optionally passing it
-    # an input and capturing its output.
+    # Runs external command(s) with specified arguments.
     #
-    # If the command execution succeeds, the returned value depends on the value
-    # of the `:capture` option (see below). If the command can't be executed for
-    # some reason or returns a non-zero exit status, the method raises an
-    # {ExecutionFailed} exception with detailed information about the failure.
+    # If the execution succeeds, the returned value depends on the value of the
+    # `:stdout` and `:stderr` options (see below). If the execution fails, the
+    # method raises an {ExecutionFailed} exception with detailed information
+    # about the failure. (In the single command case, the execution succeeds if
+    # the command can be executed and returns a zero exit status. In the
+    # multiple command case, the execution succeeds if the last command can be
+    # executed and returns a zero exit status.)
     #
-    # The command and its arguments never undergo shell expansion — they are
+    # Commands and their arguments never undergo shell expansion — they are
     # passed directly to the operating system. While this may create some
     # inconvenience in certain cases, it eliminates a whole class of security
     # bugs.
     #
-    # The command execution can be logged using a logger. It can be set globally
-    # (using the {Cheetah.logger} attribute) or locally (using the `:logger`
-    # option).  The local setting overrides the global one. If a logger is set,
-    # the method will log the command, its status, input and both outputs to it.
-    # The `:info` level will be used for normal messages, the `:error` level for
-    # messages about errors (non-zero exit status or non-empty error output).
+    # The execution can be logged using a logger passed in the `:logger` option.
+    # If a logger is set, the method will log the executed command(s), final
+    # exit status, passed input and both captured outputs (unless the `:stdin`,
+    # `:stdout` or `:stderr` option is set to an `IO`, which prevents logging
+    # the corresponding input or output).
+    #
+    # The actual logging is handled by a separate object called recorder. By
+    # default, {DefaultRecorder} instance is used. It uses the `Logger::INFO`
+    # level for normal messages and the `Logger::ERROR` level for messages about
+    # errors (non-zero exit status or non-empty error output). If you need to
+    # customize the recording, you can create your own recorder (implementing
+    # the {Recorder} interface) and pass it in the `:recorder` option.
+    #
+    # Values of options not set using the `options` parameter are taken from
+    # {Cheetah.default_options}. If a value is not specified there too, the
+    # default value described in the `options` parameter documentation is used.
     #
     # @overload run(command, *args, options = {})
+    #   Runs a command with its arguments specified separately.
+    #
     #   @param [String] command the command to execute
     #   @param [Array<String>] args the command arguments
     #   @param [Hash] options the options to execute the command with
-    #   @option options [String] :stdin ('') command's input
-    #   @option options [String] :capture (nil) configures which output(s) to
-    #     capture, the valid values are:
+    #   @option options [String, IO] :stdin ('') a `String` to use as command's
+    #     standard input or an `IO` to read it from
+    #   @option options [nil, :capture, IO] :stdout (nil) specifies command's
+    #     standard output handling
     #
-    #       * `nil` — no output is captured and returned
-    #       * `:stdout` — standard output is captured and returned as a string
-    #       * `:stderr` — error output is captured and returned as a string
-    #       * `[:stdout, :stderr]` — both outputs are captured and returned as a
-    #         two-element array of strings
+    #     * if set to `nil`, ignore the output
+    #     * if set to `:capture`, capture the output and return it as a string
+    #       (or as the first element of a two-element array of strings if the
+    #       `:stderr` option is set to `:capture` too)
+    #     * if set to an `IO`, write the ouptut into it gradually as the command
+    #       produces it
+    #   @option options [nil, :capture, IO] :stderr (nil) specifies command's
+    #     error output handling
+    #
+    #     * if set to `nil`, ignore the output
+    #     * if set to `:capture`, capture the output and return it as a string
+    #       (or as the second element of a two-element array of strings if the
+    #       `:stdout` option is set to `:capture` too)
+    #     * if set to an `IO`, write the ouptut into it gradually as the command
+    #       produces it
     #   @option options [Logger, nil] :logger (nil) logger to log the command
-    #     execution; if set, overrides the global logger (set by
-    #     {Cheetah.logger})
+    #     execution
+    #   @option options [Recorder, nil] :recorder (DefaultRecorder.new) recorder
+    #     to handle the command execution logging
+    #
+    #   @example
+    #     Cheetah.run("tar", "xzf", "foo.tar.gz")
     #
     # @overload run(command_and_args, options = {})
-    #   This variant is useful mainly when building the command and its
-    #   arguments programmatically.
+    #   Runs a command with its arguments specified together. This variant is
+    #   useful mainly when building the command and its arguments
+    #   programmatically.
     #
     #   @param [Array<String>] command_and_args the command to execute (first
     #     element of the array) and its arguments (remaining elements)
     #   @param [Hash] options the options to execute the command with, same as
     #     in the first variant
     #
-    # @raise [ExecutionFailed] when the command can't be executed for some
-    #   reason or returns a non-zero exit status
+    #   @example
+    #     Cheetah.run(["tar", "xzf", "foo.tar.gz"])
+    #
+    # @overload run(*commands_and_args, options = {})
+    #   Runs multiple commands piped togeter. Standard output of each command
+    #   execpt the last one is connected to the standard input of the next
+    #   command. Error outputs are aggregated together.
+    #
+    #   @param [Array<Array<String>>] commands_and_args the commands to execute
+    #     as an array where each item is again an array containing an executed
+    #     command in the first element and its arguments in the remaining ones
+    #   @param [Hash] options the options to execute the commands with, same as
+    #     in the first variant
+    #
+    #   @example
+    #     processes = Cheetah.run(["ps", "aux"], ["grep", "ruby"], :stdout => :capture)
+    #
+    # @raise [ExecutionFailed] when the execution fails
     #
     # @example Run a command and capture its output
-    #   files = Cheetah.run("ls", "-la", :capture => :stdout)
+    #   files = Cheetah.run("ls", "-la", :stdout => capture)
+    #
+    # @example Run a command and capture its output into a stream
+    #   File.open("files.txt", "w") do |stdout|
+    #     Cheetah.run("ls", "-la", :stdout => stdout)
+    #   end
     #
     # @example Run a command and handle errors
     #   begin
@@ -130,52 +312,144 @@ module Cheetah
     #     puts "Standard output: #{e.stdout}"
     #     puts "Error ouptut:    #{e.stderr}"
     #   end
-    def run(command, *args)
+    def run(*args)
       options = args.last.is_a?(Hash) ? args.pop : {}
+      options = BUILTIN_DEFAULT_OPTIONS.merge(@default_options).merge(options)
+
+      streamed = compute_streamed(options)
+      streams  = build_streams(options, streamed)
+      commands = build_commands(args)
+      recorder = build_recorder(options)
 
-      stdin   = options[:stdin] || ""
-      logger  = options[:logger] || @logger
+      recorder.record_commands(commands)
+      recorder.record_stdin(streams[:stdin].string) unless streamed[:stdin]
 
-      if command.is_a?(Array)
-        args    = command[1..-1]
-        command = command.first
+      pid, pipes = fork_commands(commands)
+      select_loop(streams, pipes)
+      pid, status = Process.wait2(pid)
+
+      begin
+        check_errors(commands, status, streams, streamed)
+      ensure
+        recorder.record_status(status)
+        recorder.record_stdout(streams[:stdout].string) unless streamed[:stdout]
+        recorder.record_stderr(streams[:stderr].string) unless streamed[:stderr]
       end
 
-      pipe_stdin_read,  pipe_stdin_write  = IO.pipe
-      pipe_stdout_read, pipe_stdout_write = IO.pipe
-      pipe_stderr_read, pipe_stderr_write = IO.pipe
+      build_result(streams, options)
+    end
+
+    private
+
+    # Parts of Cheetah.run
+
+    def compute_streamed(options)
+      # The assumption for :stdout and :stderr is that anything except :capture
+      # and nil is an IO-like object. We avoid detecting it directly to allow
+      # passing StringIO, mocks, etc.
+      {
+        :stdin  => !options[:stdin].is_a?(String),
+        :stdout => ![nil, :capture].include?(options[:stdout]),
+        :stderr => ![nil, :capture].include?(options[:stderr])
+      }
+    end
+
+    def build_streams(options, streamed)
+      {
+        :stdin  => streamed[:stdin]  ? options[:stdin]  : StringIO.new(options[:stdin]),
+        :stdout => streamed[:stdout] ? options[:stdout] : StringIO.new(""),
+        :stderr => streamed[:stderr] ? options[:stderr] : StringIO.new("")
+      }
+    end
+
+    def build_commands(args)
+      # There are three valid ways how to call Cheetah.run:
+      #
+      #   1. Single command, e.g. Cheetah.run("ls", "-la")
+      #
+      #        args == ["ls", "-la"]
+      #
+      #   2. Single command passed as an array, e.g. Cheetah.run(["ls", "-la"])
+      #
+      #        args == [["ls", "-la"]]
+      #
+      #   3. Piped command, e.g. Cheetah.run(["ps", "aux"], ["grep", "ruby"])
+      #
+      #        args == [["ps", "aux"], ["grep", "ruby"]]
+      #
+      # The following code ensures that the result consistently (in all three
+      # cases) contains an array of arrays specifying commands and their
+      # arguments.
+      args.all? { |a| a.is_a?(Array) } ? args : [args]
+    end
 
-      if logger
-        logger.info "Executing command #{command.inspect} with #{describe_args(args)}."
-        logger.info "Standard input: " + (stdin.empty? ? "(none)" : stdin)
+    def build_recorder(options)
+      if options[:recorder]
+        options[:recorder]
+      else
+        options[:logger] ? DefaultRecorder.new(options[:logger]) : NullRecorder.new
       end
+    end
 
-      pid = fork do
+    def fork_commands_recursive(commands, pipes)
+      fork do
         begin
-          pipe_stdin_write.close
-          STDIN.reopen(pipe_stdin_read)
-          pipe_stdin_read.close
+          if commands.size == 1
+            pipes[:stdin][WRITE].close
+            STDIN.reopen(pipes[:stdin][READ])
+            pipes[:stdin][READ].close
+          else
+            pipe_to_child = IO.pipe
+
+            fork_commands_recursive(commands[0..-2], {
+              :stdin  => pipes[:stdin],
+              :stdout => pipe_to_child,
+              :stderr => pipes[:stderr]
+            })
 
-          pipe_stdout_read.close
-          STDOUT.reopen(pipe_stdout_write)
-          pipe_stdout_write.close
+            pipes[:stdin][READ].close
+            pipes[:stdin][WRITE].close
+
+            pipe_to_child[WRITE].close
+            STDIN.reopen(pipe_to_child[READ])
+            pipe_to_child[READ].close
+          end
 
-          pipe_stderr_read.close
-          STDERR.reopen(pipe_stderr_write)
-          pipe_stderr_write.close
+          pipes[:stdout][READ].close
+          STDOUT.reopen(pipes[:stdout][WRITE])
+          pipes[:stdout][WRITE].close
+
+          pipes[:stderr][READ].close
+          STDERR.reopen(pipes[:stderr][WRITE])
+          pipes[:stderr][WRITE].close
 
           # All file descriptors from 3 above should be closed here, but since I
           # don't know about any way how to detect the maximum file descriptor
           # number portably in Ruby, I didn't implement it. Patches welcome.
 
+          command, *args = commands.last
           exec([command, command], *args)
         rescue SystemCallError => e
           exit!(127)
         end
       end
+    end
+
+    def fork_commands(commands)
+      pipes = { :stdin => IO.pipe, :stdout => IO.pipe, :stderr => IO.pipe }
 
-      [pipe_stdin_read, pipe_stdout_write, pipe_stderr_write].each { |p| p.close }
+      pid = fork_commands_recursive(commands, pipes)
 
+      [
+        pipes[:stdin][READ],
+        pipes[:stdout][WRITE],
+        pipes[:stderr][WRITE]
+      ].each(&:close)
+
+      [pid, pipes]
+    end
+
+    def select_loop(streams, pipes)
       # We write the command's input and read its output using a select loop.
       # Why? Because otherwise we could end up with a deadlock.
       #
@@ -186,9 +460,13 @@ module Cheetah
       # deadlock.
       #
       # Similar issues can happen with standard input vs. one of the outputs.
-      outputs = { pipe_stdout_read => "", pipe_stderr_read => "" }
-      pipes_readable = [pipe_stdout_read, pipe_stderr_read]
-      pipes_writable = [pipe_stdin_write]
+      stdin_buffer = ""
+      outputs = {
+        pipes[:stdout][READ] => streams[:stdout],
+        pipes[:stderr][READ] => streams[:stderr]
+      }
+      pipes_readable = [pipes[:stdout][READ], pipes[:stderr][READ]]
+      pipes_writable = [pipes[:stdin][WRITE]]
       loop do
         pipes_readable.reject!(&:closed?)
         pipes_writable.reject!(&:closed?)
@@ -211,49 +489,58 @@ module Cheetah
         end
 
         ios_write.each do |pipe|
-          n = pipe.syswrite(stdin)
-          stdin = stdin[n..-1]
-          pipe.close if stdin.empty?
+          stdin_buffer = streams[:stdin].read(4096) if stdin_buffer.empty?
+          if !stdin_buffer
+            pipe.close
+            next
+          end
+
+          n = pipe.syswrite(stdin_buffer)
+          stdin_buffer = stdin_buffer[n..-1]
         end
       end
+    end
 
-      stdout = outputs[pipe_stdout_read]
-      stderr = outputs[pipe_stderr_read]
+    def check_errors(commands, status, streams, streamed)
+      return if status.success?
 
-      pid, status = Process.wait2(pid)
-      begin
-        if !status.success?
-          raise ExecutionFailed.new(command, args, status, stdout, stderr,
-            "Execution of command #{command.inspect} " +
-            "with #{describe_args(args)} " +
-            "failed with status #{status.exitstatus}.")
-        end
-      ensure
-        if logger
-          logger.add status.success? ? Logger::INFO : Logger::ERROR,
-            "Status: #{status.exitstatus}"
-          logger.info "Standard output: " + (stdout.empty? ? "(none)" : stdout)
-          logger.add stderr.empty?  ? Logger::INFO : Logger::ERROR,
-            "Error output: " + (stderr.empty? ? "(none)" : stderr)
-        end
+      stderr_part = if streamed[:stderr]
+        " (error output streamed away)"
+      elsif streams[:stderr].string.empty?
+        " (no error output)"
+      else
+        lines = streams[:stderr].string.split("\n")
+        ": " + lines.first + (lines.size > 1 ? " (...)" : "")
       end
 
-      case options[:capture]
-        when nil
+      raise ExecutionFailed.new(
+        commands,
+        status,
+        streamed[:stdout] ? nil : streams[:stdout].string,
+        streamed[:stderr] ? nil : streams[:stderr].string,
+        "Execution of #{format_commands(commands)} " +
+          "failed with status #{status.exitstatus}#{stderr_part}."
+      )
+    end
+
+    def build_result(streams, options)
+      case [options[:stdout] == :capture, options[:stderr] == :capture]
+        when [false, false]
           nil
-        when :stdout
-          stdout
-        when :stderr
-          stderr
-        when [:stdout, :stderr]
-          [stdout, stderr]
+        when [true, false]
+          streams[:stdout].string
+        when [false, true]
+          streams[:stderr].string
+        when [true, true]
+          [streams[:stdout].string, streams[:stderr].string]
       end
     end
 
-    private
-
-    def describe_args(args)
-      args.empty? ? "no arguments" : "arguments #{args.map(&:inspect).join(", ")}"
+    def format_commands(commands)
+      '"' + commands.map { |c| Shellwords.join(c) }.join(" | ") + '"'
     end
   end
+
+  self.default_options = {}
 end
+

data/lib/cheetah/version.rb

@@ -0,0 +1,4 @@
+module Cheetah
+  # Cheetah version (uses [semantic versioning](http://semver.org/)).
+  VERSION = File.read(File.dirname(__FILE__) + "/../../VERSION").strip
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cheetah
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 0
-  - 2
-  - 1
-  version: 0.2.1
+  - 3
+  - 0
+  version: 0.3.0
 platform: ruby
 authors: 
 - David Majda
@@ -15,13 +15,28 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-12 00:00:00 +02:00
+date: 2012-06-21 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: abstract_method
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 1
+        - 2
+        version: "1.2"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -31,11 +46,11 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id001
+  version_requirements: *id002
 - !ruby/object:Gem::Dependency 
   name: redcarpet
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -45,11 +60,11 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id002
+  version_requirements: *id003
 - !ruby/object:Gem::Dependency 
   name: yard
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -59,8 +74,8 @@ dependencies:
         - 0
         version: "0"
   type: :development
-  version_requirements: *id003
-description: Cheetah is a simple library for executing external commands safely and conveniently.
+  version_requirements: *id004
+description: Your swiss army knife for executing external commands in Ruby safely and conveniently.
 email: dmajda@suse.de
 executables: []
 
@@ -74,6 +89,7 @@ files:
 - README.md
 - VERSION
 - lib/cheetah.rb
+- lib/cheetah/version.rb
 has_rdoc: true
 homepage: https://github.com/openSUSE/cheetah
 licenses: 
@@ -107,6 +123,6 @@ rubyforge_project:
 rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: Simple library for executing external commands safely and conveniently
+summary: Your swiss army knife for executing external commands in Ruby safely and conveniently.
 test_files: []