toys-core 0.3.7.1 → 0.3.8

data/lib/toys/runner.rb

@@ -31,15 +31,32 @@ require "optparse"
 
 module Toys
   ##
-  # An internal class that manages execution of a tool
-  # @private
+  # An internal class that orchestrates execution of a tool.
+  #
+  # Generaly, you should not need to use this class directly. Instead, run a
+  # tool using {Toys::CLI#run}.
   #
   class Runner
+    ##
+    # Create a runner for a particular tool in a particular CLI.
+    #
+    # @param [Toys::CLI] cli The CLI that is running the tool. This will
+    #     provide needed context information.
+    # @param [Toys::Definition::Tool] tool_definition The tool to run.
+    #
     def initialize(cli, tool_definition)
       @cli = cli
       @tool_definition = tool_definition
     end
 
+    ##
+    # Run the tool, provided given arguments.
+    #
+    # @param [Array<String>] args Command line arguments passed to the tool.
+    # @param [Integer] verbosity Initial verbosity. Default is 0.
+    #
+    # @return [Integer] The resulting status code
+    #
     def run(args, verbosity: 0)
       data = create_data(args, verbosity)
       parse_args(args, data)

data/lib/toys/{middleware → standard_middleware}/add_verbosity_flags.rb

@@ -27,10 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/middleware/base"
-
 module Toys
-  module Middleware
+  module StandardMiddleware
     ##
     # A middleware that provides flags for editing the verbosity.
     #
@@ -38,7 +36,9 @@ module Toys
     # not already defined by the tool. These flags affect the setting of
     # {Toys::Tool::Keys::VERBOSITY}, and, thus, the logger level.
     #
-    class AddVerbosityFlags < Base
+    class AddVerbosityFlags
+      include Middleware
+
       ##
       # Default verbose flags
       # @return [Array<String>]
@@ -56,12 +56,15 @@ module Toys
       #
       # @param [Boolean,Array<String>,Proc] verbose_flags Specify flags
       #     to increase verbosity. The value may be any of the following:
+      #
       #     *  An array of flags that increase verbosity.
       #     *  The `true` value to use {DEFAULT_VERBOSE_FLAGS}. (Default)
       #     *  The `false` value to disable verbose flags.
       #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean,Array<String>,Proc] quiet_flags Specify flags
       #     to decrease verbosity. The value may be any of the following:
+      #
       #     *  An array of flags that decrease verbosity.
       #     *  The `true` value to use {DEFAULT_QUIET_FLAGS}. (Default)
       #     *  The `false` value to disable quiet flags.
@@ -84,8 +87,8 @@ module Toys
       private
 
       def add_verbose_flags(tool_definition)
-        verbose_flags = Middleware.resolve_flags_spec(@verbose_flags, tool_definition,
-                                                      DEFAULT_VERBOSE_FLAGS)
+        verbose_flags = resolve_flags_spec(@verbose_flags, tool_definition,
+                                           DEFAULT_VERBOSE_FLAGS)
         unless verbose_flags.empty?
           tool_definition.add_flag(
             Tool::Keys::VERBOSITY, verbose_flags,
@@ -98,8 +101,7 @@ module Toys
       end
 
       def add_quiet_flags(tool_definition)
-        quiet_flags = Middleware.resolve_flags_spec(@quiet_flags, tool_definition,
-                                                    DEFAULT_QUIET_FLAGS)
+        quiet_flags = resolve_flags_spec(@quiet_flags, tool_definition, DEFAULT_QUIET_FLAGS)
         unless quiet_flags.empty?
           tool_definition.add_flag(
             Tool::Keys::VERBOSITY, quiet_flags,
@@ -110,6 +112,20 @@ module Toys
           )
         end
       end
+
+      def resolve_flags_spec(flags, tool, defaults)
+        flags = flags.call(tool) if flags.respond_to?(:call)
+        case flags
+        when true, :default
+          Array(defaults)
+        when ::String
+          [flags]
+        when ::Array
+          flags
+        else
+          []
+        end
+      end
     end
   end
 end

data/lib/toys/{middleware → standard_middleware}/handle_usage_errors.rb

@@ -27,19 +27,17 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/middleware/base"
-require "toys/utils/help_text"
-require "toys/utils/terminal"
-
 module Toys
-  module Middleware
+  module StandardMiddleware
     ##
     # This middleware handles the case of a usage error. If a usage error, such
     # as an unrecognized flag or an unfulfilled required argument, is detected,
     # this middleware intercepts execution and displays the error along with
     # the short help string, and terminates execution with an error code.
     #
-    class HandleUsageErrors < Base
+    class HandleUsageErrors
+      include Middleware
+
       ##
       # Create a HandleUsageErrors middleware.
       #

data/lib/toys/{middleware → standard_middleware}/set_default_descriptions.rb

@@ -27,10 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/middleware/base"
-
 module Toys
-  module Middleware
+  module StandardMiddleware
     ##
     # This middleware sets default description fields for tools and command
     # line arguments and flags that do not have them set otherwise.
@@ -39,7 +37,9 @@ module Toys
     # root tool by passing parameters to this middleware. For finer control,
     # you can override methods to modify the description generation logic.
     #
-    class SetDefaultDescriptions < Base
+    class SetDefaultDescriptions
+      include Middleware
+
       ##
       # The default description for tools.
       # @return [String]

data/lib/toys/{middleware → standard_middleware}/show_help.rb

@@ -27,13 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/middleware/base"
-require "toys/utils/exec"
-require "toys/utils/help_text"
-require "toys/utils/terminal"
-
 module Toys
-  module Middleware
+  module StandardMiddleware
     ##
     # A middleware that shows help text for the tool when a flag (typically
     # `--help`) is provided. It can also be configured to show help by
@@ -44,7 +39,9 @@ module Toys
     # all subtools recursively rather than only immediate subtools. This
     # middleware can also search for keywords in its subtools.
     #
-    class ShowHelp < Base
+    class ShowHelp
+      include Middleware
+
       ##
       # Default help flags
       # @return [Array<String>]
@@ -74,30 +71,38 @@ module Toys
       #
       # @param [Boolean,Array<String>,Proc] help_flags Specify flags to
       #     display help. The value may be any of the following:
+      #
       #     *  An array of flags.
       #     *  The `true` value to use {DEFAULT_HELP_FLAGS}.
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean,Array<String>,Proc] usage_flags Specify flags to
       #     display usage. The value may be any of the following:
+      #
       #     *  An array of flags.
       #     *  The `true` value to use {DEFAULT_USAGE_FLAGS}.
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean,Array<String>,Proc] recursive_flags Specify flags
       #     to control recursive subtool search. The value may be any of the
       #     following:
+      #
       #     *  An array of flags.
       #     *  The `true` value to use {DEFAULT_RECURSIVE_FLAGS}.
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean,Array<String>,Proc] search_flags Specify flags
       #     to search subtools for a search term. The value may be any of
       #     the following:
+      #
       #     *  An array of flags.
       #     *  The `true` value to use {DEFAULT_SEARCH_FLAGS}.
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean] default_recursive Whether to search recursively for
       #     subtools by default. Default is `false`.
       # @param [Boolean] fallback_execution Cause the tool to display its own
@@ -191,7 +196,7 @@ module Toys
 
       def output_help(str)
         if less_path
-          Utils::Exec.new.exec([less_path, "-R"], in_from: str)
+          Utils::Exec.new.exec([less_path, "-R"], in: [:string, str])
         else
           terminal.puts(str)
         end
@@ -226,8 +231,7 @@ module Toys
       end
 
       def add_help_flags(tool_definition)
-        help_flags = Middleware.resolve_flags_spec(@help_flags, tool_definition,
-                                                   DEFAULT_HELP_FLAGS)
+        help_flags = resolve_flags_spec(@help_flags, tool_definition, DEFAULT_HELP_FLAGS)
         unless help_flags.empty?
           tool_definition.add_flag(
             :_show_help, help_flags,
@@ -239,8 +243,7 @@ module Toys
       end
 
       def add_usage_flags(tool_definition)
-        usage_flags = Middleware.resolve_flags_spec(@usage_flags, tool_definition,
-                                                    DEFAULT_USAGE_FLAGS)
+        usage_flags = resolve_flags_spec(@usage_flags, tool_definition, DEFAULT_USAGE_FLAGS)
         unless usage_flags.empty?
           tool_definition.add_flag(
             :_show_usage, usage_flags,
@@ -252,8 +255,8 @@ module Toys
       end
 
       def add_recursive_flags(tool_definition)
-        recursive_flags = Middleware.resolve_flags_spec(@recursive_flags, tool_definition,
-                                                        DEFAULT_RECURSIVE_FLAGS)
+        recursive_flags = resolve_flags_spec(@recursive_flags, tool_definition,
+                                             DEFAULT_RECURSIVE_FLAGS)
         unless recursive_flags.empty?
           tool_definition.add_flag(
             :_recursive_subtools, recursive_flags,
@@ -264,8 +267,7 @@ module Toys
       end
 
       def add_search_flags(tool_definition)
-        search_flags = Middleware.resolve_flags_spec(@search_flags, tool_definition,
-                                                     DEFAULT_SEARCH_FLAGS)
+        search_flags = resolve_flags_spec(@search_flags, tool_definition, DEFAULT_SEARCH_FLAGS)
         unless search_flags.empty?
           tool_definition.add_flag(
             :_search_subtools, search_flags,
@@ -274,6 +276,20 @@ module Toys
           )
         end
       end
+
+      def resolve_flags_spec(flags, tool, defaults)
+        flags = flags.call(tool) if flags.respond_to?(:call)
+        case flags
+        when true, :default
+          Array(defaults)
+        when ::String
+          [flags]
+        when ::Array
+          flags
+        else
+          []
+        end
+      end
     end
   end
 end

data/lib/toys/{middleware → standard_middleware}/show_root_version.rb

@@ -27,16 +27,15 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/middleware/base"
-require "toys/utils/terminal"
-
 module Toys
-  module Middleware
+  module StandardMiddleware
     ##
     # A middleware that displays a version string for the root tool if the
     # `--version` flag is given.
     #
-    class ShowRootVersion < Base
+    class ShowRootVersion
+      include Middleware
+
       ##
       # Default version flags
       # @return [Array<String>]

data/lib/toys/{helpers → standard_mixins}/exec.rb

@@ -27,10 +27,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/utils/exec"
-
 module Toys
-  module Helpers
+  module StandardMixins
     ##
     # A set of helper methods for invoking subcommands. Provides shortcuts for
     # common cases such as invoking Ruby in a subprocess or capturing output
@@ -69,8 +67,8 @@ module Toys
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     the subprocess streams.
       #
-      # @return [Toys::Utils::Result] The subprocess result, including the exit
-      #     code and any captured output.
+      # @return [Toys::Utils::Exec::Result] The subprocess result, including
+      #     the exit code and any captured output.
       #
       def exec(cmd, opts = {}, &block)
         Exec._exec(self).exec(cmd, Exec._setup_exec_opts(opts, self), &block)
@@ -88,8 +86,8 @@ module Toys
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Result] The subprocess result, including the exit
-      #     code and any captured output.
+      # @return [Toys::Utils::Exec::Result] The subprocess result, including
+      #     the exit code and any captured output.
       #
       def ruby(args, opts = {}, &block)
         Exec._exec(self).ruby(args, Exec._setup_exec_opts(opts, self), &block)
@@ -150,7 +148,9 @@ module Toys
           if opts[:exit_on_nonzero_status]
             proc { |s| tool.exit(s.exitstatus) }
           end
-        opts.merge(nonzero_status_handler: nonzero_status_handler)
+        opts = opts.merge(nonzero_status_handler: nonzero_status_handler)
+        opts.delete(:exit_on_nonzero_status)
+        opts
       end
     end
   end

data/lib/toys/{helpers → standard_mixins}/fileutils.rb

@@ -30,7 +30,7 @@
 require "fileutils"
 
 module Toys
-  module Helpers
+  module StandardMixins
     ##
     # A module that provides all methods in the "fileutils" standard library.
     #

data/lib/toys/{helpers → standard_mixins}/highline.rb

@@ -27,14 +27,13 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/utils/gems"
 Toys::Utils::Gems.activate("highline", "~> 1.7")
 require "highline"
 
 module Toys
-  module Helpers
+  module StandardMixins
     ##
-    # A module that provides access to the capabilities of the highline gem.
+    # A mixin that provides access to the capabilities of the highline gem.
     #
     # You may make these methods available to your tool by including the
     # following directive in your tool configuration:

data/lib/toys/{helpers → standard_mixins}/terminal.rb

@@ -27,12 +27,10 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/utils/terminal"
-
 module Toys
-  module Helpers
+  module StandardMixins
     ##
-    # A helper that provides a simple terminal. It includes a set of methods
+    # A mixin that provides a simple terminal. It includes a set of methods
     # that produce styled output, get user input, and otherwise interact with
     # the user's terminal.
     #

data/lib/toys/tool.rb

@@ -39,6 +39,7 @@ module Toys
   #
   # Keys that are neither strings nor symbols are by convention used for other
   # context information, including:
+  #
   # *   Common information such as the {Toys::Definition::Tool} object being
   #     executed, the arguments originally passed to it, or the usage error
   #     string. These well-known keys can be accessed via constants in the
@@ -46,7 +47,7 @@ module Toys
   # *   Common settings such as the verbosity level, and whether to exit
   #     immediately if a subprocess exits with a nonzero result. These keys are
   #     also present as {Toys::Context} constants.
-  # *   Private information used internally by middleware and helpers.
+  # *   Private information used internally by middleware and mixins.
   #
   # This class provides convenience accessors for common keys and settings, and
   # you can retrieve argument-set keys using the {#options} hash.
@@ -246,7 +247,7 @@ module Toys
     # Returns the subset of the context that uses string or symbol keys. By
     # convention, this includes keys that are set by tool flags and arguments,
     # but does not include well-known context values such as verbosity or
-    # private context values used by middleware or helpers.
+    # private context values used by middleware or mixins.
     #
     # @return [Hash]
     #

data/lib/toys/utils/exec.rb

@@ -38,22 +38,6 @@ 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.
     #
-    # ## Stream handling
-    #
-    # By default, subprocess streams are connected to the corresponding streams
-    # in the parent process.
-    #
-    # Alternately, input streams may be read from a string you provide, and
-    # you may direct output streams to be captured and their contents exposed
-    # in the result object.
-    #
-    # You may also connect subprocess streams to a controller, which you can
-    # then manipulate by providing a block. Your block may read and write
-    # connected streams to interact with the process. For example, to redirect
-    # data into a subprocess you can connect its input stream to the controller
-    # using the `:in_from` option (see below). Then, in your block, you can
-    # write to that stream via the controller.
-    #
     # ## Configuration options
     #
     # A variety of options can be used to control subprocesses. These include:
@@ -63,23 +47,12 @@ module Toys
     #    If not present, the command is not logged.
     # *  **:log_level** (Integer) Log level for logging the actual command.
     #    Defaults to Logger::INFO if not present.
-    # *  **:in_from** (`:controller`,String) Connects the input stream of the
-    #    subprocess. If set to `:controller`, the controller will control the
-    #    input stream. If set to a string, that string will be written to the
-    #    input stream. If not set, the input stream will be connected to the
-    #    STDIN for the Toys process itself.
-    # *  **:out_to** (`:controller`,`:capture`) Connects the standard output
-    #    stream of the subprocess. If set to `:controller`, the controller
-    #    will control the output stream. If set to `:capture`, the output will
-    #    be captured in a string that is available in the
-    #    {Toys::Utils::Exec::Result} object. If not set, the subprocess
-    #    standard out is connected to STDOUT of the Toys process.
-    # *  **:err_to** (`:controller`,`:capture`) Connects the standard error
-    #    stream of the subprocess. If set to `:controller`, the controller
-    #    will control the output stream. If set to `:capture`, the output will
-    #    be captured in a string that is available in the
-    #    {Toys::Utils::Exec::Result} object. If not set, the subprocess
-    #    standard out is connected to STDERR of the Toys process.
+    # *  **: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.
@@ -95,7 +68,57 @@ module Toys
     #
     # Configuration options may be provided to any method that starts a
     # subprocess. You may also modify default values by calling
-    # {Toys::Utils::Exec#config_defaults}.
+    # {Toys::Utils::Exec#configure_defaults}.
+    #
+    # ## 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.
+    #
+    # *  **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.
+    # *  **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
       ##
@@ -134,17 +157,17 @@ module Toys
       #     exit code and any captured output.
       #
       def exec(cmd, opts = {}, &block)
+        exec_opts = Opts.new(@default_opts).add(opts)
         spawn_cmd =
           if cmd.is_a?(::Array)
             if cmd.size == 1 && cmd.first.is_a?(::String)
-              [[cmd.first, opts[:argv0] || cmd.first]]
+              [[cmd.first, exec_opts.config_opts[:argv0] || cmd.first]]
             else
               cmd
             end
           else
             [cmd]
           end
-        exec_opts = Opts.new(@default_opts).add(opts)
         executor = Executor.new(exec_opts, spawn_cmd)
         executor.execute(&block)
       end
@@ -161,7 +184,7 @@ module Toys
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Result] The subprocess result, including
+      # @return [Toys::Utils::Exec::Result] The subprocess result, including
       #     exit code and any captured output.
       #
       def ruby(args, opts = {}, &block)
@@ -195,7 +218,7 @@ module Toys
       # @return [String] What was written to standard out.
       #
       def capture(cmd, opts = {})
-        exec(cmd, opts.merge(out_to: :capture)).captured_out
+        exec(cmd, opts.merge(out: :capture)).captured_out
       end
 
       ##
@@ -208,13 +231,14 @@ module Toys
         # @private
         #
         CONFIG_KEYS = %i[
+          argv0
           env
-          err_to
-          in_from
+          err
+          in
           logger
           log_level
           nonzero_status_handler
-          out_to
+          out
         ].freeze
 
         ##
@@ -247,8 +271,10 @@ module Toys
           config.each do |k, v|
             if CONFIG_KEYS.include?(k)
               @config_opts[k] = v
-            elsif SPAWN_KEYS.include?(k)
+            elsif SPAWN_KEYS.include?(k) || k.to_s.start_with?("rlimit_")
               @spawn_opts[k] = v
+            else
+              raise ::ArgumentError, "Unknown key: #{k.inspect}"
             end
           end
           self
@@ -258,8 +284,10 @@ module Toys
           keys.each do |k|
             if CONFIG_KEYS.include?(k)
               @config_opts.delete(k)
-            elsif SPAWN_KEYS.include?(k)
+            elsif SPAWN_KEYS.include?(k) || k.to_s.start_with?("rlimit_")
               @spawn_opts.delete(k)
+            else
+              raise ::ArgumentError, "Unknown key: #{k.inspect}"
             end
           end
           self
@@ -285,7 +313,7 @@ module Toys
 
         ##
         # Return the subcommand's standard input stream (which can be written
-        # to), if the command was configured with `in_from: :controller`.
+        # to), if the command was configured with `in: :controller`.
         # Returns `nil` otherwise.
         # @return [IO,nil]
         #
@@ -293,7 +321,7 @@ module Toys
 
         ##
         # Return the subcommand's standard output stream (which can be read
-        # from), if the command was configured with `out_to: :controller`.
+        # from), if the command was configured with `out: :controller`.
         # Returns `nil` otherwise.
         # @return [IO,nil]
         #
@@ -301,7 +329,7 @@ module Toys
 
         ##
         # Return the subcommand's standard error stream (which can be read
-        # from), if the command was configured with `err_to: :controller`.
+        # from), if the command was configured with `err: :controller`.
         # Returns `nil` otherwise.
         # @return [IO,nil]
         #
@@ -337,14 +365,14 @@ module Toys
 
         ##
         # Returns the captured output string, if the command was configured
-        # with `out_to: :capture`. Returns `nil` otherwise.
+        # with `out: :capture`. Returns `nil` otherwise.
         # @return [String,nil]
         #
         attr_reader :captured_out
 
         ##
         # Returns the captured error string, if the command was configured
-        # with `err_to: :capture`. Returns `nil` otherwise.
+        # with `err: :capture`. Returns `nil` otherwise.
         # @return [String,nil]
         #
         attr_reader :captured_err
@@ -397,8 +425,8 @@ module Toys
 
         def execute(&block)
           setup_in_stream
-          setup_out_stream(:out, :out_to, :out)
-          setup_out_stream(:err, :err_to, :err)
+          setup_out_stream(:out)
+          setup_out_stream(:err)
           log_command
           wait_thread = start_process
           status = control_process(wait_thread, &block)
@@ -447,54 +475,199 @@ module Toys
         end
 
         def setup_in_stream
-          setting = @config_opts[:in_from]
-          if setting
-            r, w = ::IO.pipe
-            @spawn_opts[:in] = r
-            w.sync = true
-            @child_streams << r
-            case setting
-            when :controller
-              @controller_streams[:in] = w
-            when String
-              write_string_thread(w, setting)
-            else
-              raise "Unknown type for in_from"
+          setting = @config_opts[:in]
+          return unless setting
+          case setting
+          when ::Symbol
+            setup_in_stream_of_type(setting, [])
+          when ::Integer
+            setup_in_stream_of_type(:parent, [setting])
+          when ::String
+            setup_in_stream_of_type(:file, [setting])
+          when ::IO, ::StringIO
+            interpret_in_io(setting)
+          when ::Array
+            interpret_in_array(setting)
+          else
+            raise "Unknown value for in: #{setting.inspect}"
+          end
+        end
+
+        def interpret_in_io(setting)
+          if setting.fileno.is_a?(::Integer)
+            setup_in_stream_of_type(:parent, [setting.fileno])
+          else
+            setup_in_stream_of_type(:copy_io, [setting])
+          end
+        end
+
+        def interpret_in_array(setting)
+          case setting.first
+          when ::Symbol
+            setup_in_stream_of_type(setting.first, setting[1..-1])
+          when ::String
+            setup_in_stream_of_type(:file, setting)
+          else
+            raise "Unknown value for in: #{setting.inspect}"
+          end
+        end
+
+        def setup_in_stream_of_type(type, args)
+          case type
+          when :controller
+            @controller_streams[:in] = make_in_pipe
+          when :null
+            make_null_stream(:in, "r")
+          when :close
+            @spawn_opts[:in] = type
+          when :parent
+            @spawn_opts[:in] = args.first
+          when :child
+            @spawn_opts[:in] = [:child, args.first]
+          when :string
+            write_string_thread(args.first.to_s)
+          when :copy_io
+            copy_to_in_thread(args.first)
+          when :file
+            interpret_in_file(args)
+          else
+            raise "Unknown type for in: #{type.inspect}"
+          end
+        end
+
+        def interpret_in_file(args)
+          raise "Expected only file name" unless args.size == 1 && args.first.is_a?(::String)
+          @spawn_opts[:in] = args + [::File::RDONLY]
+        end
+
+        def setup_out_stream(key)
+          setting = @config_opts[key]
+          return unless setting
+          case setting
+          when ::Symbol
+            setup_out_stream_of_type(key, setting, [])
+          when ::Integer
+            setup_out_stream_of_type(key, :parent, [setting])
+          when ::String
+            setup_out_stream_of_type(key, :file, [setting])
+          when ::IO, ::StringIO
+            interpret_out_io(key, setting)
+          when ::Array
+            interpret_out_array(key, setting)
+          else
+            raise "Unknown value for #{key}: #{setting.inspect}"
+          end
+        end
+
+        def interpret_out_io(key, setting)
+          if setting.fileno.is_a?(::Integer)
+            setup_out_stream_of_type(key, :parent, [setting.fileno])
+          else
+            setup_out_stream_of_type(key, :copy_io, [setting])
+          end
+        end
+
+        def interpret_out_array(key, setting)
+          case setting.first
+          when ::Symbol
+            setup_out_stream_of_type(key, setting.first, setting[1..-1])
+          when ::String
+            setup_out_stream_of_type(key, :file, setting)
+          else
+            raise "Unknown value for #{key}: #{setting.inspect}"
+          end
+        end
+
+        def setup_out_stream_of_type(key, type, args)
+          case type
+          when :controller
+            @controller_streams[key] = make_out_pipe(key)
+          when :null
+            make_null_stream(key, "w")
+          when :close, :out, :err
+            @spawn_opts[key] = type
+          when :parent
+            @spawn_opts[key] = args.first
+          when :child
+            @spawn_opts[key] = [:child, args.first]
+          when :capture
+            capture_stream_thread(key)
+          when :copy_io
+            copy_from_out_thread(key, args.first)
+          when :file
+            interpret_out_file(key, args)
+          else
+            raise "Unknown type for #{key}: #{type.inspect}"
+          end
+        end
+
+        def interpret_out_file(key, args)
+          raise "Expected file name" if args.empty? || !args.first.is_a?(::String)
+          raise "Too many file arguments" if args.size > 3
+          @spawn_opts[key] = args.size == 1 ? args.first : args
+        end
+
+        def make_null_stream(key, mode)
+          f = ::File.open(::File::NULL, mode)
+          @spawn_opts[key] = f
+          @child_streams << f
+        end
+
+        def make_in_pipe
+          r, w = ::IO.pipe
+          @spawn_opts[:in] = r
+          @child_streams << r
+          w.sync = true
+          w
+        end
+
+        def make_out_pipe(key)
+          r, w = ::IO.pipe
+          @spawn_opts[key] = w
+          @child_streams << w
+          r
+        end
+
+        def write_string_thread(string)
+          stream = make_in_pipe
+          @join_threads << ::Thread.new do
+            begin
+              stream.write string
+            ensure
+              stream.close
             end
           end
         end
 
-        def setup_out_stream(stream_name, config_key, spawn_key)
-          setting = @config_opts[config_key]
-          if setting
-            r, w = ::IO.pipe
-            @spawn_opts[spawn_key] = w
-            @child_streams << w
-            case setting
-            when :controller
-              @controller_streams[stream_name] = r
-            when :capture
-              @join_threads << capture_stream_thread(r, stream_name)
-            else
-              raise "Unknown type for #{config_key}"
+        def copy_to_in_thread(io, close: false)
+          stream = make_in_pipe
+          @join_threads << ::Thread.new do
+            begin
+              ::IO.copy_stream(io, stream)
+            ensure
+              stream.close
+              io.close if close
             end
           end
         end
 
-        def write_string_thread(stream, string)
-          ::Thread.new do
+        def copy_from_out_thread(key, io, close: false)
+          stream = make_out_pipe(key)
+          @join_threads << ::Thread.new do
             begin
-              stream.write string
+              ::IO.copy_stream(stream, io)
             ensure
               stream.close
+              io.close if close
             end
           end
         end
 
-        def capture_stream_thread(stream, name)
-          ::Thread.new do
+        def capture_stream_thread(key)
+          stream = make_out_pipe(key)
+          @join_threads << ::Thread.new do
             begin
-              @captures[name] = stream.read
+              @captures[key] = stream.read
             ensure
               stream.close
             end