toys-core 0.10.0 → 0.10.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a9f077375706e67827afa561f71081c121d0eb00c30be6586501e6c76ab47c5
-  data.tar.gz: 305e31b023d22f687a2406efdd0cea377a1c9725626c8320cebbf013b10f145b
+  metadata.gz: 3f0e62a1c71082677fd2c257f95adec476cd8c1f5d83a8f42854e48cfe52d1bf
+  data.tar.gz: d5940e36d77ce386ce7be949b2e16af08454095300a5beb3ffafdf4f691abe26
 SHA512:
-  metadata.gz: 661b472175296ea3224e3dee08902ca8b2bf04e78f949109a91f4fa471c0b7904a454e0b18e845cf46d8cf04458872c84f55fd3f43bcbb2f3ecd40478783b8a5
-  data.tar.gz: f9761ab43fffd295af8629906ae3fdee621c42d5df49a92b3539cc68a9588546338a4fdd3a70459639c3127c261de443c5f2359778807d281b451b4c2655316a
+  metadata.gz: a59b68df5403e100330518056d0e8d9b8792f9e01e36792b445413300e40e2637a86847af9afe565084a55e3bf3b332f1eff15cacc42a56c95597c94a47bd27a
+  data.tar.gz: a8d943e4ccb7a2b9f3278a0eabf4c33485fb09d2fce2440d3f3c3cdc605a30977a0d43da993018b6affb51933686f69e038b5bf1847df54e1cdfab981af77309

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Release History
 
+### 0.10.5 / 2020-07-18
+
+* IMPROVED: The bundler mixin silences bundler output during bundle setup.
+* IMPROVED: The bundler mixin allows toys and toys-core to be in the Gemfile. It checks their version requirements against the running Toys version, and either adds the corret version to the bundle or raises IncompatibleToysError.
+* IMPROVED: The bundler mixin utomatically updates the bundle if install fails (typically because a transitive dependency has been explicitly updated.)
+* FIXED: Some cases of transitive dependency handling by the bundler mixin.
+* FIXED: Fixed a crash when computing suggestions, when running with a bundle on Ruby 2.6 or earlier.
+
+### 0.10.4 / 2020-07-11
+
+* IMPROVED: Bundler integration can now handle Toys itself being in the bundle, as long as the version requirements cover the running Toys version.
+* IMPROVED: Passing `static: true` to the `:bundler` mixin installs the bundle at definition rather than execution time.
+
+### 0.10.3 / 2020-07-04
+
+* FIXED: The `exec_separate_tool` method in the `:exec` mixin no longer throws ENOEXEC on Windows.
+
+### 0.10.2 / 2020-07-03
+
+* FIXED: The load path no longer loses the toys and toys-core directories after a bundle install.
+
+### 0.10.1 / 2020-03-07
+
+* FIXED: Setting `:exit_on_nonzero_status` explicitly to false now works as expected.
+
 ### 0.10.0 / 2020-02-24
 
 Functional changes:

data/README.md

@@ -258,7 +258,7 @@ itself. However, the `toys-core` gem is a dependency, and your users will need
 to have it installed. You could alleviate this by wrapping your executable in a
 gem that can declare `toys-core` as a dependency explicitly.
 
-The [examples directory](https://github.com/dazuma/toys/tree/master/toys-core/examples)
+The [examples directory](https://github.com/dazuma/toys/tree/main/toys-core/examples)
 includes a few simple examples that you can use as a starting point.
 
 To experiment with the examples, clone the Toys repo from GitHub:
@@ -272,7 +272,7 @@ Navigate to the simple-gem example:
 
 This example wraps the simple "greet" executable that we
 [covered earlier](#Add_some_functionality) in a gem. You can see the
-[executable file](https://github.com/dazuma/toys/tree/master/toys-core/examples/simple-gem/bin/toys-core-simple-example)
+[executable file](https://github.com/dazuma/toys/tree/main/toys-core/examples/simple-gem/bin/toys-core-simple-example)
 in the bin directory.
 
 Try it out by building and installing the gem. From the `examples/simple-gem`
@@ -297,16 +297,16 @@ break it up into multiple files. The multi-file gem example demonstrates this.
     $ cd ../multi-file-gem
 
 This executable's implementation resides in its
-[lib directory](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/lib),
+[lib directory](https://github.com/dazuma/toys/tree/main/toys-core/examples/multi-file-gem/lib),
 a technique that may be familiar to writers of command line executables. More
 interestingly, the tools themselves are no longer defined in a block passed to
 the CLI object, but have been moved into a separate
-["tools" directory](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/tools).
+["tools" directory](https://github.com/dazuma/toys/tree/main/toys-core/examples/multi-file-gem/tools).
 This directory has the same structure and supports the same features that are
 available when writing complex sets of tools in a `.toys` directory. You then
 configure the CLI object to look in this directory for its tools definitions,
 as you can see in
-[the code](https://github.com/dazuma/toys/tree/master/toys-core/examples/multi-file-gem/lib/toys-core-multi-gem-example.rb).
+[the code](https://github.com/dazuma/toys/tree/main/toys-core/examples/multi-file-gem/lib/toys-core-multi-gem-example.rb).
 
 Try it out now. From the `examples/multi-file-gem` directory, run:
 

data/lib/toys-core.rb

@@ -58,6 +58,9 @@ module Toys
     #
     attr_accessor :executable_path
   end
+
+  # @private
+  CORE_LIB_PATH = __dir__
 end
 
 require "toys/acceptor"

data/lib/toys/compat.rb

@@ -16,21 +16,30 @@ module Toys
       ::RUBY_PLATFORM == "java"
     end
 
+    # @private
+    def self.windows?
+      ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+    end
+
     # @private
     def self.allow_fork?
-      !jruby? && ::RbConfig::CONFIG["host_os"] !~ /mswin/
+      !jruby? && !windows?
     end
 
     # @private
     def self.supports_suggestions?
       unless defined?(@supports_suggestions)
-        require "rubygems"
         begin
           require "did_you_mean"
-          @supports_suggestions = defined?(::DidYouMean::SpellChecker)
         rescue ::LoadError
-          @supports_suggestions = false
+          require "rubygems"
+          begin
+            require "did_you_mean"
+          rescue ::LoadError
+            # Oh well, it's not available
+          end
         end
+        @supports_suggestions = defined?(::DidYouMean::SpellChecker)
       end
       @supports_suggestions
     end

data/lib/toys/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.10.0"
+    VERSION = "0.10.5"
   end
 
   ## @private deprecated

data/lib/toys/standard_mixins/bundler.rb

@@ -7,6 +7,10 @@ module Toys
     #
     # The following parameters can be passed when including this mixin:
     #
+    #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
+    #     defining the tool. If `false` (the default), installs the bundle just
+    #     before the tool runs.
+    #
     #  *  `:groups` (Array<String>) The groups to include in setup
     #
     #  *  `:search_dirs` (Array<String,Symbol>) Directories to search for a
@@ -41,32 +45,39 @@ module Toys
     module Bundler
       include Mixin
 
-      on_initialize do
-        |groups: nil,
-         search_dirs: nil,
-         on_missing: nil,
-         on_conflict: nil,
-         terminal: nil,
-         input: nil,
-         output: nil|
-        require "toys/utils/gems"
-        search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(search_dirs, self)
-        gems = ::Toys::Utils::Gems.new(on_missing: on_missing, on_conflict: on_conflict,
-                                       terminal: terminal, input: input, output: output)
-        gems.bundle(groups: groups, search_dirs: search_dirs)
+      on_initialize do |static: false, search_dirs: nil, **kwargs|
+        unless static
+          require "toys/utils/gems"
+          search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(
+            search_dirs,
+            self[::Toys::Context::Key::CONTEXT_DIRECTORY],
+            self[::Toys::Context::Key::TOOL_SOURCE]
+          )
+          ::Toys::StandardMixins::Bundler.setup_bundle(search_dirs, **kwargs)
+        end
+      end
+
+      on_include do |static: false, search_dirs: nil, **kwargs|
+        if static
+          require "toys/utils/gems"
+          search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(
+            search_dirs, context_directory, source_info
+          )
+          ::Toys::StandardMixins::Bundler.setup_bundle(search_dirs, **kwargs)
+        end
       end
 
       ## @private
-      def self.resolve_search_dirs(search_dirs, context)
+      def self.resolve_search_dirs(search_dirs, context_dir, source_info)
         search_dirs ||= [:toys, :context, :current]
         Array(search_dirs).flat_map do |dir|
           case dir
           when :context
-            context[::Toys::Context::Key::CONTEXT_DIRECTORY]
+            context_dir
           when :current
             ::Dir.getwd
           when :toys
-            toys_dir_stack(context[::Toys::Context::Key::TOOL_SOURCE])
+            toys_dir_stack(source_info)
           when ::String
             dir
           else
@@ -84,6 +95,19 @@ module Toys
         end
         dirs
       end
+
+      ## @private
+      def self.setup_bundle(search_dirs,
+                            groups: nil,
+                            on_missing: nil,
+                            on_conflict: nil,
+                            terminal: nil,
+                            input: nil,
+                            output: nil)
+        gems = ::Toys::Utils::Gems.new(on_missing: on_missing, on_conflict: on_conflict,
+                                       terminal: terminal, input: input, output: output)
+        gems.bundle(groups: groups, search_dirs: search_dirs)
+      end
     end
   end
 end

data/lib/toys/standard_mixins/exec.rb

@@ -16,54 +16,211 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
+    # ## Features
+    #
+    # ### Controlling processes
+    #
+    # A process can be started in the *foreground* or the *background*. If you
+    # start a foreground process, it will "take over" your standard input and
+    # output streams by default, and it will keep control until it completes.
+    # If you start a background process, its streams will be redirected to null
+    # by default, and control will be returned to you immediately.
+    #
+    # When a process is running, you can control it using a
+    # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
+    # the process's input and output streams, send it signals, or wait for it
+    # to complete.
+    #
+    # When running a process in the foreground, the controller will be yielded
+    # to an optional block. For example, the following code starts a process in
+    # the foreground and passes its output stream to a controller.
+    #
+    #     exec(["git", "init"], out: :controller) do |controller|
+    #       loop do
+    #         line = controller.out.gets
+    #         break if line.nil?
+    #         puts "Got line: #{line}"
+    #       end
+    #     end
+    #
+    # When running a process in the background, the controller is returned from
+    # the method that starts the process:
+    #
+    #     controller = exec_service.exec(["git", "init"], background: true)
+    #
+    # ### Stream handling
+    #
+    # By default, subprocess streams are connected to the corresponding streams
+    # in the parent process. You can change this behavior, redirecting streams
+    # or providing ways to control them, using the `:in`, `:out`, and `:err`
+    # options.
+    #
+    # Three general strategies are available for custom stream handling. First,
+    # you may redirect to other streams such as files, IO objects, or Ruby
+    # strings. Some of these options map directly to options provided by the
+    # `Process#spawn` method. Second, you may use a controller to manipulate
+    # the streams programmatically. Third, you may capture output stream data
+    # and make it available in the result.
+    #
+    # Following is a full list of the stream handling options, along with how
+    # to specify them using the `:in`, `:out`, and `:err` options.
+    #
+    #  *  **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 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.
+    #  *  **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 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::StandardMixins::Exec#exec},
+    #     it yields the {Toys::Utils::Exec::Controller}, giving you access to
+    #     streams.
+    #
+    # ### Result handling
+    #
+    # A subprocess result is represented by a {Toys::Utils::Exec::Result}
+    # object, which includes the exit code, the content of any captured output
+    # streams, and any exeption raised when attempting to run the process.
+    # When you run a process in the foreground, the method will return a result
+    # object. When you run a process in the background, you can obtain the
+    # result from the controller once the process completes.
+    #
+    # The following example demonstrates running a process in the foreground
+    # and getting the exit code:
+    #
+    #     result = exec(["git", "init"])
+    #     puts "exit code: #{result.exit_code}"
+    #
+    # The following example demonstrates starting a process in the background,
+    # waiting for it to complete, and getting its exit code:
+    #
+    #     controller = exec(["git", "init"], background: true)
+    #     result = controller.result(timeout: 1.0)
+    #     if result
+    #       puts "exit code: #{result.exit_code}"
+    #     else
+    #       puts "timed out"
+    #     end
+    #
+    # You can also provide a callback that is executed once a process
+    # completes. This callback can be specified as a method name or a `Proc`
+    # object, and will be passed the result object. For example:
+    #
+    #     def run
+    #       exec(["git", "init"], result_callback: :handle_result)
+    #     end
+    #     def handle_result(result)
+    #       puts "exit code: #{result.exit_code}"
+    #     end
+    #
+    # Finally, you can force your tool to exit if a subprocess fails, similar
+    # to setting the `set -e` option in bash, by setting the
+    # `:exit_on_nonzero_status` option. This is often set as a default
+    # configuration for all subprocesses run in a tool, by passing it as an
+    # argument to the `include` directive:
+    #
+    #     include :exec, exit_on_nonzero_status: true
+    #
     # ## Configuration Options
     #
-    # Subprocesses may be configured using the options in the
-    # {Toys::Utils::Exec} class. These include a variety of options supported
-    # by `Process#spawn`, and some options supported by {Toys::Utils::Exec}
-    # itself.
+    # A variety of options can be used to control subprocesses. These can be
+    # provided to any method that starts a subprocess. You can also set
+    # defaults by passing them as keyword arguments when you `include` the
+    # mixin.
+    #
+    # Options that affect the behavior of subprocesses:
+    #
+    #  *  `:env` (Hash) Environment variables to pass to the subprocess.
+    #     Keys represent variable names and should be strings. Values should be
+    #     either strings or `nil`, which unsets the variable.
+    #
+    #  *  `:background` (Boolean) Runs the process in the background if `true`.
+    #
+    # Options related to handling results
+    #
+    #  *  `:result_callback` (Proc,Symbol) A procedure that is called, and
+    #     passed the result object, when the subprocess exits. You can provide
+    #     a `Proc` object, or the name of a method as a `Symbol`.
+    #
+    #  *  `:exit_on_nonzero_status` (Boolean) If set to true, a nonzero exit
+    #     code will cause the tool to exit immediately with that same code.
+    #
+    #  *  `:e` (Boolean) A short name for `:exit_on_nonzero_status`.
+    #
+    # Options for connecting input and output streams. See the section above on
+    # stream handling for info on the values that can be passed.
+    #
+    #  *  `: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.
     #
-    # You can set default configuration by passing options to the `include`
-    # directive. For example, to log commands at the debug level for all
-    # subprocesses spawned by this tool:
+    #  *  `:err` Connects the standard error stream of the subprocess. See the
+    #     section on stream handling.
     #
-    #     include :exec, log_level: Logger::DEBUG
+    # Options related to logging and reporting:
     #
-    # Two special options are also recognized by the mixin.
+    #  *  `:logger` (Logger) Logger to use for logging the actual command. If
+    #     not present, the command is not logged.
     #
-    #  *  A **:result_callback** proc may take a second argument. If it does,
-    #     the context object is passed as the second argument. This is useful
-    #     if a `:result_callback` is applied to the entire tool by passing it
-    #     to the `include` directive. In that case, `self` is not set to the
-    #     context object as it normally would be in a tool's `run` method, so
-    #     you cannot access it otherwise. For example, here is how to log the
-    #     exit code for every subcommand:
+    #  *  `: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.
     #
-    #         tool "mytool" do
-    #           callback = proc do |result, context|
-    #             context.logger.info "Exit code: #{result.exit_code}"
-    #           end
-    #           include :exec, result_callback: callback
-    #           # ...
-    #         end
+    #  *  `:log_cmd` (String) The string logged for the actual command.
+    #     Defaults to the `inspect` representation of the command.
     #
-    #     You may also pass a symbol as the `:result_callback`. The method with
-    #     that name is then called as the callback. The method must take one
-    #     argument, the result object.
+    #  *  `:name` (Object) An optional object that can be used to identify this
+    #     subprocess. It is available in the controller and result objects.
     #
-    #  *  If **:exit_on_nonzero_status** is set to true, a nonzero exit code
-    #     returned by the subprocess will also cause the tool to exit
-    #     immediately with that same code.
+    # In addition, the following options recognized by
+    # [`Process#spawn`](https://ruby-doc.org/core/Process.html#method-c-spawn)
+    # are supported.
     #
-    #     This is particularly useful as an option to the `include` directive,
-    #     where it causes any subprocess failure to abort the tool, similar to
-    #     setting `set -e` in a bash script.
+    #  *  `:chdir` (String) Set the working directory for the command.
     #
-    #         include :exec, exit_on_nonzero_status: true
+    #  *  `:close_others` (Boolean) Whether to close non-redirected
+    #     non-standard file descriptors.
     #
-    #     **:e** can be used as a shortcut for **:exit_on_nonzero_status**
+    #  *  `:new_pgroup` (Boolean) Create new process group (Windows only).
     #
-    #         include :exec, e: true
+    #  *  `:pgroup` (Integer,true,nil) The process group setting.
+    #
+    #  *  `:umask` (Integer) Umask setting for the new process.
+    #
+    #  *  `:unsetenv_others` (Boolean) Clear environment variables except those
+    #     explicitly set.
+    #
+    # Any other option key will result in an `ArgumentError`.
     #
     module Exec
       include Mixin
@@ -89,10 +246,10 @@ module Toys
       end
 
       ##
-      # Set default configuration keys.
+      # Set default configuration options.
       #
-      # All options listed in the {Toys::Utils::Exec} documentation are
-      # supported, plus the `exit_on_nonzero_status` option.
+      # See the {Toys::StandardMixins::Exec} module documentation for a
+      # description of the options.
       #
       # @param opts [keywords] The default options.
       # @return [self]
@@ -110,12 +267,25 @@ 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.
       #
+      # ## Examples
+      #
+      # Run a command without a shell, and print the exit code (0 for success):
+      #
+      #     result = exec(["git", "init"])
+      #     puts "exit code: #{result.exit_code}"
+      #
+      # Run a shell command:
+      #
+      #     result = exec("cd mydir && git init")
+      #     puts "exit code: #{result.exit_code}"
+      #
       # @param cmd [String,Array<String>] The command to execute.
-      # @param opts [keywords] The command options. All options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
-      #     the subprocess streams.
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
       #     the process is running in the background.
@@ -133,12 +303,19 @@ 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.
       #
+      # ## Example
+      #
+      # Execute a small script with warnings
+      #
+      #     exec_ruby("-w", "-e", "(1..10).each { |i| puts i }")
+      #
       # @param args [String,Array<String>] The arguments to ruby.
-      # @param opts [keywords] The command options. All options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
-      #     for the subprocess streams.
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
       #     the process is running in the background.
@@ -160,12 +337,23 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
+      # ## Example
+      #
+      # Run a proc in a forked process.
+      #
+      #     code = proc do
+      #       puts "Spawned process ID is #{Process.pid}"
+      #     end
+      #     puts "Main process ID is #{Process.pid}"
+      #     exec_proc(code)
+      #
       # @param func [Proc] The proc to call.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
       #     the process is running in the background.
@@ -189,12 +377,19 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
+      # ## Example
+      #
+      # Run the "system update" tool and pass it an argument.
+      #
+      #     exec_tool(["system", "update", "--verbose"])
+      #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
       #     the process is running in the background.
@@ -229,12 +424,19 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
+      # ## Example
+      #
+      # Run the "system update" tool and pass it an argument.
+      #
+      #     exec_separate_tool(["system", "update", "--verbose"])
+      #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
       #     the process is running in the background.
@@ -257,12 +459,20 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
+      # ## Example
+      #
+      # Capture the output of an echo command
+      #
+      #     str = capture(["echo", "hello"])
+      #     assert_equal("hello\n", str)
+      #
       # @param cmd [String,Array<String>] The command to execute.
-      # @param opts [keywords] The command options. All options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [String] What was written to standard out.
       #
@@ -280,12 +490,20 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
+      # ## Example
+      #
+      # Capture the output of a ruby script.
+      #
+      #     str = capture_ruby("-e", "(1..3).each { |i| puts i }")
+      #     assert_equal "1\n2\n3\n", str
+      #
       # @param args [String,Array<String>] The arguments to ruby.
-      # @param opts [keywords] The command options. All options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [String] What was written to standard out.
       #
@@ -306,12 +524,23 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
+      # ## Example
+      #
+      # Run a proc in a forked process and capture its output:
+      #
+      #     code = proc do
+      #       puts Process.pid
+      #     end
+      #     forked_pid = capture_proc(code).chomp
+      #     puts "I forked PID #{forked_pid}"
+      #
       # @param func [Proc] The proc to call.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [String] What was written to standard out.
       #
@@ -335,12 +564,20 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
+      # ## Example
+      #
+      # Run the "system version" tool and capture its output.
+      #
+      #     str = capture_tool(["system", "version"]).chomp
+      #     puts "Version was #{str}"
+      #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [String] What was written to standard out.
       #
@@ -375,12 +612,20 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
+      # ## Example
+      #
+      # Run the "system version" tool and capture its output.
+      #
+      #     str = capture_separate_tool(["system", "version"]).chomp
+      #     puts "Version was #{str}"
+      #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [keywords] The command options. Most options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [String] What was written to standard out.
       #
@@ -397,12 +642,20 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
+      # ## Example
+      #
+      # Run a shell script
+      #
+      #     exit_code = sh("cd mydir && git init")
+      #     puts exit_code == 0 ? "Success!" : "Failed!"
+      #
       # @param cmd [String] The shell command to execute.
-      # @param opts [keywords] The command options. All options listed in the
-      #     {Toys::Utils::Exec} documentation are supported, plus the
-      #     `exit_on_nonzero_status` option.
-      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
-      #     for the subprocess streams.
+      # @param opts [keywords] The command options. See the section on
+      #     Configuration Options in the {Toys::StandardMixins::Exec} module
+      #     documentation.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess. See the section on Controlling Processes in the
+      #     {Toys::StandardMixins::Exec} module documentation.
       #
       # @return [Integer] The exit code
       #
@@ -432,42 +685,50 @@ module Toys
 
       ## @private
       def self._setup_exec_opts(opts, context)
+        count = 0
+        result_callback = nil
         if opts.key?(:result_callback)
-          opts = _setup_result_callback_option(opts, context)
+          result_callback = _interpret_result_callback(opts[:result_callback], context)
+          count += 1
+        end
+        [:exit_on_nonzero_status, :e].each do |sym|
+          if opts.key?(sym)
+            result_callback = _interpret_e(opts[sym], context)
+            count += 1
+            opts = opts.reject { |k, _v| k == sym }
+          end
         end
-        if opts.key?(:exit_on_nonzero_status) || opts.key?(:e)
-          opts = _setup_e_option(opts, context)
+        if count > 1
+          raise ::ArgumentError,
+                "You can provide at most one of: result_callback, exit_on_nonzero_status, e"
         end
+        opts = opts.merge(result_callback: result_callback) if count == 1
         opts
       end
 
       ## @private
-      def self._setup_e_option(opts, context)
-        e_options = [:exit_on_nonzero_status, :e]
-        if e_options.any? { |k| opts[k] }
-          result_callback = proc { |r| context.exit(r.exit_code) if r.error? }
-          opts = opts.merge(result_callback: result_callback)
-        end
-        opts.reject { |k, _v| e_options.include?(k) }
+      def self._interpret_e(value, context)
+        value ? proc { |r| context.exit(r.exit_code) if r.error? } : nil
       end
 
       ## @private
-      def self._setup_result_callback_option(opts, context)
-        orig_callback = opts[:result_callback]
-        result_callback =
-          if orig_callback.is_a?(::Symbol)
-            context.method(orig_callback)
-          elsif orig_callback.respond_to?(:call)
-            proc { |r| orig_callback.call(r, context) }
-          end
-        opts.merge(result_callback: result_callback)
+      def self._interpret_result_callback(value, context)
+        if value.is_a?(::Symbol)
+          context.method(value)
+        elsif value.respond_to?(:call)
+          proc { |r| context.instance_eval { value.call(r, context) } }
+        elsif value.nil?
+          nil
+        else
+          raise ::ArgumentError, "Bad value for result_callback"
+        end
       end
 
       ## @private
       def self._setup_clean_process(cmd)
         raise ::ArgumentError, "Toys process is unknown" unless ::Toys.executable_path
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-        cmd = Array(::Toys.executable_path) + cmd
+        cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
         if defined?(::Bundler)
           if ::Bundler.respond_to?(:with_unbundled_env)
             ::Bundler.with_unbundled_env { yield(cmd) }