toys-core 0.7.0 → 0.8.0

data/lib/toys/utils/completion_engine.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+require "shellwords"
+
+module Toys
+  module Utils
+    ##
+    # Implementations of tab completion.
+    #
+    # This module is not loaded by default. Before using it directly, you must
+    # `require "toys/utils/completion_engine"`
+    #
+    module CompletionEngine
+      ##
+      # A completion engine for bash.
+      #
+      class Bash
+        ##
+        # Create a bash completion engine.
+        #
+        # @param cli [Toys::CLI] The CLI.
+        #
+        def initialize(cli)
+          @cli = cli
+        end
+
+        ##
+        # Perform completion in the current shell environment, which must
+        # include settings for the `COMP_LINE` and `COMP_POINT` environment
+        # variables. Prints out completion candidates, one per line, and
+        # returns a status code indicating the result.
+        #
+        #  *  **0** for success.
+        #  *  **1** if completion failed.
+        #  *  **2** if the environment is incorrect (e.g. expected environment
+        #     variables not found)
+        #
+        # @return [Integer] status code
+        #
+        def run
+          return 2 if !::ENV.key?("COMP_LINE") || !::ENV.key?("COMP_POINT")
+          line = ::ENV["COMP_LINE"].to_s
+          point = ::ENV["COMP_POINT"].to_i
+          point = line.length if point.negative?
+          line = line[0, point]
+          completions = run_internal(line)
+          if completions
+            completions.each { |completion| puts completion }
+            0
+          else
+            1
+          end
+        end
+
+        ##
+        # Internal completion method designed for testing.
+        # @private
+        #
+        def run_internal(line)
+          words = CompletionEngine.split(line)
+          quote_type, last = words.pop
+          return nil unless words.shift
+          words.map! { |_type, word| word }
+          prefix = ""
+          if (match = /\A(.*[=:])(.*)\z/.match(last))
+            prefix = match[1]
+            last = match[2]
+          end
+          context = Completion::Context.new(
+            cli: @cli, previous_words: words, fragment_prefix: prefix, fragment: last,
+            params: {shell: :bash, quote_type: quote_type}
+          )
+          candidates = @cli.completion.call(context)
+          candidates.uniq.sort.map do |candidate|
+            CompletionEngine.format_candidate(candidate, quote_type)
+          end
+        end
+      end
+
+      class << self
+        ## @private
+        def split(line)
+          words = []
+          field = ::String.new
+          quote_type = nil
+          line.scan(split_regex) do |word, sqw, dqw, esc, garbage, sep|
+            raise ArgumentError, "Didn't expect garbage: #{line.inspect}" if garbage
+            field << field_str(word, sqw, dqw, esc)
+            quote_type = update_quote_type(quote_type, sqw, dqw)
+            if sep
+              words << [quote_type, field]
+              quote_type = nil
+              field = sep.empty? ? nil : ::String.new
+            end
+          end
+          words << [quote_type, field] if field
+          words
+        end
+
+        ## @private
+        def format_candidate(candidate, quote_type)
+          str = candidate.to_s
+          partial = candidate.is_a?(Completion::Candidate) ? candidate.partial? : false
+          quote_type = nil if candidate.string.include?("'") && quote_type == :single
+          case quote_type
+          when :single
+            partial ? "'#{str}" : "'#{str}' "
+          when :double
+            str = str.gsub(/[$`"\\\n]/, '\\\\\\1')
+            partial ? "\"#{str}" : "\"#{str}\" "
+          else
+            str = ::Shellwords.escape(str)
+            partial ? str : "#{str} "
+          end
+        end
+
+        private
+
+        def split_regex
+          word_re = "([^\\s\\\\\\'\\\"]+)"
+          sq_re = "'([^\\']*)(?:'|\\z)"
+          dq_re = "\"((?:[^\\\"\\\\]|\\\\.)*)(?:\"|\\z)"
+          esc_re = "(\\\\.?)"
+          sep_re = "(\\s|\\z)"
+          /\G\s*(?>#{word_re}|#{sq_re}|#{dq_re}|#{esc_re}|(\S))#{sep_re}?/m
+        end
+
+        def field_str(word, sqw, dqw, esc)
+          word ||
+            sqw ||
+            dqw&.gsub(/\\([$`"\\\n])/, '\\1') ||
+            esc&.gsub(/\\(.)/, '\\1') ||
+            ""
+        end
+
+        def update_quote_type(quote_type, sqw, dqw)
+          if quote_type
+            :multi
+          elsif sqw
+            :single
+          elsif dqw
+            :double
+          else
+            :bare
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toys/utils/exec.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 require "logger"
@@ -41,36 +33,43 @@ module Toys
     # processes and their streams. It also provides shortcuts for common cases
     # such as invoking Ruby in a subprocess or capturing output in a string.
     #
+    # This class is not loaded by default. Before using it directly, you should
+    # `require "toys/utils/exec"`
+    #
     # ## Configuration options
     #
     # A variety of options can be used to control subprocesses. These include:
     #
-    # *  **:env** (Hash) Environment variables to pass to the subprocess
-    # *  **:logger** (Logger) Logger to use for logging the actual command.
-    #    If not present, the command is not logged.
-    # *  **:log_level** (Integer,false) Level for logging the actual command.
-    #    Defaults to Logger::INFO if not present. You may also pass `false` to
-    #    disable logging of the command.
-    # *  **:log_cmd** (String) The string logged for the actual command.
-    #    Defaults to the `inspect` representation of the command.
-    # *  **:background** (Boolean) Runs the process in the background,
-    #    returning a controller object instead of a result object.
-    # *  **:in** Connects the input stream of the subprocess. See the section
-    #    on stream handling.
-    # *  **:out** Connects the standard output stream of the subprocess. See
-    #    the section on stream handling.
-    # *  **:err** Connects the standard error stream of the subprocess. See the
-    #    section on stream handling.
+    #  *  `:name` (Object) An optional object that can be used to identify this
+    #     subprocess. It is available in the controller and result objects.
+    #  *  `:env` (Hash) Environment variables to pass to the subprocess
+    #  *  `:logger` (Logger) Logger to use for logging the actual command. If
+    #     not present, the command is not logged.
+    #  *  `:log_level` (Integer,false) Level for logging the actual command.
+    #     Defaults to Logger::INFO if not present. You may also pass `false` to
+    #     disable logging of the command.
+    #  *  `:log_cmd` (String) The string logged for the actual command.
+    #     Defaults to the `inspect` representation of the command.
+    #  *  `:background` (Boolean) Runs the process in the background, returning
+    #     a controller object instead of a result object.
+    #  *  `:result_callback` (Proc) Called and passed the result object when a
+    #     subprocess exits.
+    #  *  `:in` Connects the input stream of the subprocess. See the section on
+    #     stream handling.
+    #  *  `:out` Connects the standard output stream of the subprocess. See the
+    #     section on stream handling.
+    #  *  `:err` Connects the standard error stream of the subprocess. See the
+    #     section on stream handling.
     #
     # In addition, the following options recognized by `Process#spawn` are
     # supported.
     #
-    # *  `:chdir`
-    # *  `:close_others`
-    # *  `:new_pgroup`
-    # *  `:pgroup`
-    # *  `:umask`
-    # *  `:unsetenv_others`
+    #  *  `:chdir`
+    #  *  `:close_others`
+    #  *  `:new_pgroup`
+    #  *  `:pgroup`
+    #  *  `:umask`
+    #  *  `:unsetenv_others`
     #
     # Any other options are ignored.
     #
@@ -95,48 +94,53 @@ module Toys
     # Following is a full list of the stream handling options, along with how
     # to specify them using the `:in`, `:out`, and `:err` options.
     #
-    # *  **Close the stream:** You may close the stream by passing `:close` as
-    #    the option value. This is the same as passing `:close` to
-    #    `Process#spawn`.
-    # *  **Redirect to null:** You may redirect to a null stream by passing
-    #    `:null` as the option value. This connects to a stream that is not
-    #    closed but contains no data, i.e. `/dev/null` on unix systems. This is
-    #    the default if the subprocess is run in the background.
-    # *  **Inherit parent stream:** You may inherit the corresponding stream in
-    #    the parent process by passing `:inherit` as the option value. This is
-    #    the default if the subprocess is *not* run in the background.
-    # *  **Redirect to a file:** You may redirect to a file. This reads from an
-    #    existing file when connected to `:in`, and creates or appends to a
-    #    file when connected to `:out` or `:err`. To specify a file, use the
-    #    setting `[:file, "/path/to/file"]`. You may also, when writing a file,
-    #    append an optional mode and permission code to the array. For
-    #    example, `[:file, "/path/to/file", "a", 0644]`.
-    # *  **Redirect to an IO object:** You may redirect to an IO object in the
-    #    parent process, by passing the IO object as the option value. You may
-    #    use any IO object. For example, you could connect the child's output
-    #    to the parent's error using `out: $stderr`, or you could connect to an
-    #    existing File stream. Unlike `Process#spawn`, this works for IO
-    #    objects that do not have a corresponding file descriptor (such as
-    #    StringIO objects). In such a case, a thread will be spawned to pipe
-    #    the IO data through to the child process.
-    # *  **Combine with another child stream:** You may redirect one child
-    #    output stream to another, to combine them. To merge the child's error
-    #    stream into its output stream, use `err: [:child, :out]`.
-    # *  **Read from a string:** You may pass a string to the input stream by
-    #    setting `[:string, "the string"]`. This works only for `:in`.
-    # *  **Capture output stream:** You may capture a stream and make it
-    #    available on the {Toys::Utils::Exec::Result} object, using the setting
-    #    `:capture`. This works only for the `:out` and `:err` streams.
-    # *  **Use the controller:** You may hook a stream to the controller using
-    #    the setting `:controller`. You can then manipulate the stream via the
-    #    controller. If you pass a block to {Toys::Utils::Exec#exec}, it yields
-    #    the {Toys::Utils::Exec::Controller}, giving you access to streams.
+    #  *  **Close the stream:** You may close the stream by passing `:close` as
+    #     the option value. This is the same as passing `:close` to
+    #     `Process#spawn`.
+    #  *  **Redirect to null:** You may redirect to a null stream by passing
+    #     `:null` as the option value. This connects to a stream that is not
+    #     closed but contains no data, i.e. `/dev/null` on unix systems. This
+    #     is the default if the subprocess is run in the background.
+    #  *  **Inherit parent stream:** You may inherit the corresponding stream
+    #     in the parent process by passing `:inherit` as the option value. This
+    #     is the default if the subprocess is *not* run in the background.
+    #  *  **Redirect to a file:** You may redirect to a file. This reads from
+    #     an existing file when connected to `:in`, and creates or appends to a
+    #     file when connected to `:out` or `:err`. To specify a file, use the
+    #     setting `[:file, "/path/to/file"]`. You may also, when writing a
+    #     file, append an optional mode and permission code to the array. For
+    #     example, `[:file, "/path/to/file", "a", 0644]`.
+    #  *  **Redirect to an IO object:** You may redirect to an IO object in the
+    #     parent process, by passing the IO object as the option value. You may
+    #     use any IO object. For example, you could connect the child's output
+    #     to the parent's error using `out: $stderr`, or you could connect to
+    #     an existing File stream. Unlike `Process#spawn`, this works for IO
+    #     objects that do not have a corresponding file descriptor (such as
+    #     StringIO objects). In such a case, a thread will be spawned to pipe
+    #     the IO data through to the child process.
+    #  *  **Combine with another child stream:** You may redirect one child
+    #     output stream to another, to combine them. To merge the child's error
+    #     stream into its output stream, use `err: [:child, :out]`.
+    #  *  **Read from a string:** You may pass a string to the input stream by
+    #     setting `[:string, "the string"]`. This works only for `:in`.
+    #  *  **Capture output stream:** You may capture a stream and make it
+    #     available on the {Toys::Utils::Exec::Result} object, using the
+    #     setting `:capture`. This works only for the `:out` and `:err`
+    #     streams.
+    #  *  **Use the controller:** You may hook a stream to the controller using
+    #     the setting `:controller`. You can then manipulate the stream via the
+    #     controller. If you pass a block to {Toys::Utils::Exec#exec}, it
+    #     yields the {Toys::Utils::Exec::Controller}, giving you access to
+    #     streams.
     #
     class Exec
       ##
       # Create an exec service.
       #
-      # @param [Hash] opts Initial default options.
+      # @param block [Proc] A block that is called if a key is not found. It is
+      #     passed the unknown key, and expected to return a default value
+      #     (which can be nil).
+      # @param opts [Hash] Initial default options.
       #
       def initialize(opts = {}, &block)
         @default_opts = Opts.new(&block).add(opts)
@@ -145,7 +149,8 @@ module Toys
       ##
       # Set default options
       #
-      # @param [Hash] opts New default options to set
+      # @param opts [Hash] New default options to set
+      # @return [self]
       #
       def configure_defaults(opts = {})
         @default_opts.add(opts)
@@ -159,15 +164,16 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. See the section on
+      # @param cmd [String,Array<String>] The command to execute.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec(cmd, opts = {}, &block)
         exec_opts = Opts.new(@default_opts).add(opts)
@@ -191,15 +197,16 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. See the section on
+      # @param args [String,Array<String>] The arguments to ruby.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec_ruby(args, opts = {}, &block)
         cmd = args.is_a?(::Array) ? [::RbConfig.ruby] + args : "#{::RbConfig.ruby} #{args}"
@@ -214,15 +221,16 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. See the section on
+      # @param func [Proc] The proc to call.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec_proc(func, opts = {}, &block)
         exec_opts = Opts.new(@default_opts).add(opts)
@@ -240,8 +248,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. See the section on
+      # @param cmd [String,Array<String>] The command to execute.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
@@ -261,8 +269,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. See the section on
+      # @param args [String,Array<String>] The arguments to ruby.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
@@ -282,8 +290,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. See the section on
+      # @param func [Proc] The proc to call.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
@@ -298,8 +306,11 @@ module Toys
       # Execute the given string in a shell. Returns the exit code.
       # Cannot be run in the background.
       #
-      # @param [String] cmd The shell command to execute.
-      # @param [Hash] opts The command options. See the section on
+      # If a block is provided, a {Toys::Utils::Exec::Controller} will be
+      # yielded to it.
+      #
+      # @param cmd [String] The shell command to execute.
+      # @param opts [Hash] The command options. See the section on
       #     configuration options in the {Toys::Utils::Exec} module docs.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
@@ -319,33 +330,35 @@ module Toys
         # Option keys that belong to exec configuration
         # @private
         #
-        CONFIG_KEYS = %i[
-          argv0
-          background
-          cli
-          env
-          err
-          in
-          logger
-          log_cmd
-          log_level
-          nonzero_status_handler
-          out
+        CONFIG_KEYS = [
+          :argv0,
+          :background,
+          :cli,
+          :env,
+          :err,
+          :in,
+          :logger,
+          :log_cmd,
+          :log_level,
+          :name,
+          :out,
+          :result_callback,
         ].freeze
 
         ##
         # Option keys that belong to spawn configuration
         # @private
         #
-        SPAWN_KEYS = %i[
-          chdir
-          close_others
-          new_pgroup
-          pgroup
-          umask
-          unsetenv_others
+        SPAWN_KEYS = [
+          :chdir,
+          :close_others,
+          :new_pgroup,
+          :pgroup,
+          :umask,
+          :unsetenv_others,
         ].freeze
 
+        ## @private
         def initialize(parent = nil)
           if parent
             @config_opts = ::Hash.new { |_h, k| parent.config_opts[k] }
@@ -359,6 +372,7 @@ module Toys
           end
         end
 
+        ## @private
         def add(config)
           config.each do |k, v|
             if CONFIG_KEYS.include?(k)
@@ -372,6 +386,7 @@ module Toys
           self
         end
 
+        ## @private
         def delete(*keys)
           keys.each do |k|
             if CONFIG_KEYS.include?(k)
@@ -385,7 +400,10 @@ module Toys
           self
         end
 
+        ## @private
         attr_reader :config_opts
+
+        ## @private
         attr_reader :spawn_opts
       end
 
@@ -398,53 +416,84 @@ module Toys
       #
       class Controller
         ## @private
-        def initialize(controller_streams, captures, pid, join_threads, nonzero_status_handler)
+        def initialize(name, controller_streams, captures, pid, join_threads, result_callback)
+          @name = name
           @in = controller_streams[:in]
           @out = controller_streams[:out]
           @err = controller_streams[:err]
           @captures = captures
-          @pid = pid
+          @pid = @exception = @wait_thread = nil
+          case pid
+          when ::Integer
+            @pid = pid
+            @wait_thread = ::Process.detach(pid)
+          when ::Exception
+            @exception = pid
+          end
           @join_threads = join_threads
-          @nonzero_status_handler = nonzero_status_handler
-          @wait_thread = ::Process.detach(pid)
+          @result_callback = result_callback
           @result = nil
         end
 
         ##
-        # Return the subcommand's standard input stream (which can be written
-        # to), if the command was configured with `in: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
+        # The subcommand's name.
+        # @return [Object]
+        #
+        attr_reader :name
+
+        ##
+        # The subcommand's standard input stream (which can be written to).
+        #
+        # @return [IO] if the command was configured with `in: :controller`
+        # @return [nil] if the command was not configured with
+        #     `in: :controller`
         #
         attr_reader :in
 
         ##
-        # Return the subcommand's standard output stream (which can be read
-        # from), if the command was configured with `out: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
+        # The subcommand's standard output stream (which can be read from).
+        #
+        # @return [IO] if the command was configured with `out: :controller`
+        # @return [nil] if the command was not configured with
+        #     `out: :controller`
         #
         attr_reader :out
 
         ##
-        # Return the subcommand's standard error stream (which can be read
-        # from), if the command was configured with `err: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
+        # The subcommand's standard error stream (which can be read from).
+        #
+        # @return [IO] if the command was configured with `err: :controller`
+        # @return [nil] if the command was not configured with
+        #     `err: :controller`
         #
         attr_reader :err
 
         ##
-        # Returns the process ID.
-        # @return [Integer]
+        # The process ID.
+        #
+        # Exactly one of `exception` and `pid` will be non-nil.
+        #
+        # @return [Integer] if the process start was successful
+        # @return [nil] if the process could not be started.
         #
         attr_reader :pid
 
+        ##
+        # The exception raised when the process failed to start.
+        #
+        # Exactly one of `exception` and `pid` will be non-nil.
+        #
+        # @return [Exception] if the process failed to start.
+        # @return [nil] if the process start was successful.
+        #
+        attr_reader :exception
+
         ##
         # Captures the remaining data in the given stream.
         # After calling this, do not read directly from the stream.
         #
-        # @param [:out,:err] which Which stream to capture
+        # @param which [:out,:err] Which stream to capture
+        # @return [self]
         #
         def capture(which)
           stream = stream_for(which)
@@ -462,6 +511,8 @@ module Toys
         # Captures the remaining data in the standard output stream.
         # After calling this, do not read directly from the stream.
         #
+        # @return [self]
+        #
         def capture_out
           capture(:out)
         end
@@ -470,6 +521,8 @@ module Toys
         # Captures the remaining data in the standard error stream.
         # After calling this, do not read directly from the stream.
         #
+        # @return [self]
+        #
         def capture_err
           capture(:err)
         end
@@ -484,10 +537,11 @@ module Toys
         #
         # After calling this, do not interact directly with the stream.
         #
-        # @param [:in,:out,:err] which Which stream to redirect
-        # @param [IO,StringIO,String,:null] io Where to redirect the stream
-        # @param [Object...] io_args The mode and permissions for opening the
+        # @param which [:in,:out,:err] Which stream to redirect
+        # @param io [IO,StringIO,String,:null] Where to redirect the stream
+        # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to/from a file.
+        # @return [self]
         #
         def redirect(which, io, *io_args)
           io = ::File::NULL if io == :null
@@ -508,6 +562,7 @@ module Toys
               io.close
             end
           end
+          self
         end
 
         ##
@@ -520,9 +575,10 @@ module Toys
         #
         # After calling this, do not interact directly with the stream.
         #
-        # @param [IO,StringIO,String,:null] io Where to redirect the stream
-        # @param [Object...] io_args The mode and permissions for opening the
+        # @param io [IO,StringIO,String,:null] Where to redirect the stream
+        # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting from a file.
+        # @return [self]
         #
         def redirect_in(io, *io_args)
           redirect(:in, io, *io_args)
@@ -538,9 +594,10 @@ module Toys
         #
         # After calling this, do not interact directly with the stream.
         #
-        # @param [IO,StringIO,String,:null] io Where to redirect the stream
-        # @param [Object...] io_args The mode and permissions for opening the
+        # @param io [IO,StringIO,String,:null] Where to redirect the stream
+        # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to a file.
+        # @return [self]
         #
         def redirect_out(io, *io_args)
           redirect(:out, io, *io_args)
@@ -555,9 +612,10 @@ module Toys
         #
         # After calling this, do not interact directly with the stream.
         #
-        # @param [IO,StringIO,String] io Where to redirect the stream
-        # @param [Object...] io_args The mode and permissions for opening the
+        # @param io [IO,StringIO,String] Where to redirect the stream
+        # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to a file.
+        # @return [self]
         #
         def redirect_err(io, *io_args)
           redirect(:err, io, *io_args)
@@ -567,10 +625,12 @@ module Toys
         # Send the given signal to the process. The signal may be specified
         # by name or number.
         #
-        # @param [Integer,String] sig The signal to send.
+        # @param sig [Integer,String] The signal to send.
+        # @return [self]
         #
         def kill(sig)
-          ::Process.kill(sig, pid)
+          ::Process.kill(sig, pid) if pid
+          self
         end
         alias signal kill
 
@@ -580,27 +640,24 @@ module Toys
         # @return [Boolean]
         #
         def executing?
-          @wait_thread.status ? true : false
+          @wait_thread&.status ? true : false
         end
 
         ##
         # Wait for the subcommand to complete, and return a result object.
         #
-        # @param [Numeric,nil] timeout The timeout in seconds, or `nil` to
+        # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
         #     wait indefinitely.
-        # @return [Toys::Utils::Exec::Result,nil] The result object, or `nil`
-        #     if a timeout occurred.
+        # @return [Toys::Utils::Exec::Result] The result object
+        # @return [nil] if a timeout occurred.
         #
         def result(timeout: nil)
-          return nil unless @wait_thread.join(timeout)
+          return nil if @wait_thread && !@wait_thread.join(timeout)
           @result ||= begin
             close_streams
             @join_threads.each(&:join)
-            status = @wait_thread.value
-            if @nonzero_status_handler && status.exitstatus != 0
-              @nonzero_status_handler.call(status)
-            end
-            Result.new(@captures[:out], @captures[:err], status)
+            Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
+                  .tap { |result| @result_callback&.call(result) }
           end
         end
 
@@ -640,46 +697,76 @@ module Toys
       end
 
       ##
-      # The return result from a subcommand
+      # The result returned from a subcommand execution.
       #
       class Result
         ## @private
-        def initialize(out, err, status)
+        def initialize(name, out, err, status, exception)
+          @name = name
           @captured_out = out
           @captured_err = err
           @status = status
+          @exception = exception
         end
 
         ##
-        # Returns the captured output string, if the command was configured
-        # with `out: :capture`. Returns `nil` otherwise.
-        # @return [String,nil]
+        # The subcommand's name.
+        #
+        # @return [Object]
+        #
+        attr_reader :name
+
+        ##
+        # The captured output string.
+        #
+        # @return [String] The string captured from stdout.
+        # @return [nil] if the command was not configured to capture stdout.
         #
         attr_reader :captured_out
 
         ##
-        # Returns the captured error string, if the command was configured
-        # with `err: :capture`. Returns `nil` otherwise.
-        # @return [String,nil]
+        # The captured error string.
+        #
+        # @return [String] The string captured from stderr.
+        # @return [nil] if the command was not configured to capture stderr.
         #
         attr_reader :captured_err
 
         ##
-        # Returns the status code object.
-        # @return [Process::Status]
+        # The status code object.
+        #
+        # Exactly one of `exception` and `status` will be non-nil.
+        #
+        # @return [Process::Status] The status code.
+        # @return [nil] if the process could not be started.
         #
         attr_reader :status
 
         ##
-        # Returns the numeric status code.
+        # The exception raised if a process couldn't be started.
+        #
+        # Exactly one of `exception` and `status` will be non-nil.
+        #
+        # @return [Exception] The exception raised from process start.
+        # @return [nil] if the process started successfully.
+        #
+        attr_reader :exception
+
+        ##
+        # The numeric status code.
+        #
+        # This will be a nonzero integer if the process failed to start. That
+        # is, `exit_code` will never be `nil`, even if `status` is `nil`.
+        #
         # @return [Integer]
         #
         def exit_code
-          status.exitstatus
+          status ? status.exitstatus : 127
         end
 
         ##
         # Returns true if the subprocess terminated with a zero status.
+        #
         # @return [Boolean]
         #
         def success?
@@ -688,6 +775,7 @@ module Toys
 
         ##
         # Returns true if the subprocess terminated with a nonzero status.
+        #
         # @return [Boolean]
         #
         def error?
@@ -719,10 +807,7 @@ module Toys
           setup_out_stream(:out)
           setup_out_stream(:err)
           log_command
-          pid = @fork_func ? start_fork : start_process
-          @child_streams.each(&:close)
-          controller = Controller.new(@controller_streams, @captures, pid, @join_threads,
-                                      @config_opts[:nonzero_status_handler])
+          controller = start_with_controller
           return controller if @config_opts[:background]
           begin
             @block&.call(controller)
@@ -743,6 +828,18 @@ module Toys
           end
         end
 
+        def start_with_controller
+          pid =
+            begin
+              @fork_func ? start_fork : start_process
+            rescue ::StandardError => e
+              e
+            end
+          @child_streams.each(&:close)
+          Controller.new(@config_opts[:name], @controller_streams, @captures, pid,
+                         @join_threads, @config_opts[:result_callback])
+        end
+
         def start_process
           args = []
           args << @config_opts[:env] if @config_opts[:env]