toys 0.19.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a74557d30e1049351aadf228ff90e2d81bc95c3eceb12058994f4344b7166d6a
-  data.tar.gz: 127e2bee0af281200cb10af3d3185e928d805f39c3650f2564bd4d626b499a63
+  metadata.gz: 91bb0564850a2dc5b0742038d542cbb1239b2bcdef5db7f256c8deceac580e82
+  data.tar.gz: 894bdc6c036528a156fecdd79ee65ec4d099281552c5fe3f6ec6488627985fb2
 SHA512:
-  metadata.gz: 0d0002be9a833ec73cb6b4d6051f71f6652855b8e4ea9de80c707a0e215f2de88755c625bf4d3759abb0e9a26c9ef5719ee8cd3a4f65309800f471413bdf24d3
-  data.tar.gz: 7de57d4dd7c143da7dce7316d530639859817a81cfb29b08d886380a23be9fb0fe6994bb24647c79ecdbb0d9924785665c9fb8b968a83a0fa653fb76d67889ce
+  metadata.gz: 576e41a7ffda908b16b696158bf7baa00b0a9fe065425847e24ee5db01082dbbc61119362de0e14a98f00d5a0edb727ec42f5428ab110b3be5a0cf318041d628
+  data.tar.gz: 56e9a65cbc25bd8c40b30885a61399fc7927b047b2f2edffbea0533a642b969734d52303a01637efc9a38e1300d1f6ed3697fa61515a6522d54148511b1d2a1d

data/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Release History
 
+### v0.20.0 / 2026-03-09
+
+Toys 0.20 is a major release with several new features and a number of fixes, including a few minor breaking changes.
+
+Changes in the `:minitest` template:
+
+* BREAKING CHANGE: Tools produced by the `:minitest` template default to looking for test files of the forms `*_test.rb` and `test_*.rb` instead of `test*.rb`.
+* NEW: The `:minitest` template supports installing specified gems without using bundler.
+* NEW: Tools produced by the `:minitest` template provide command line arguments for overriding the gem installation or bundler settings.
+* NEW: Tools produced by the `:minitest` template recognize `--include` as an alias for `--name`. This matches recent versions of minitest.
+* NEW: The `:minitest` template generates more comprehensive documentation.
+* NEW: The minitest tool template now requires "minitest/autorun" before loading tests, so tests don't have to do so themselves.
+* BREAKING API CHANGE: Toys::Templates::Minitest::DEFAULT_GEM_VERSION_REQUIREMENTS is now a hash that covers multiple gems rather than just the minitest gem
+* FIXED: The minitest template no longer exceeds command line length limits if the list of test files is extremely long.
+
+New functionality in the `:rspec` template:
+
+* NEW: The `:rspec` template supports installing specified gems without using bundler.
+* NEW: Tools produced by the `:rspec` template provide command line arguments for overriding the gem installation or bundler settings.
+* NEW: Tools produced by the `:rspec` template recognize the `--example-matches` flag, and can handle multiple `--example` and `--tag` flags.
+* NEW: The `:rspec` template generates more comprehensive documentation.
+* BREAKING API CHANGE: Toys::Templates::Rspec::DEFAULT_GEM_VERSION_REQUIREMENTS is now a hash that covers potentially multiple gems
+
+New functionality in the `:clean` template:
+
+* The `:clean` template supports specifying certain gitignored files to preserve.
+* The `:clean` template is more robust against concurrent modification and works better with large git repos.
+
+New functionality in the `system test` builtin tool:
+
+* BREAKING CHANGE: The `system test` builtin looks for test files of the form `*_test.rb` in addition to `test_*.rb`.
+* The `system test` builtin uses bundler to install gems if a Gemfile is present in the `.test` directory.
+* The `system test` builtin supports flags that can specify arbitrary gems to load.
+
+Updates to the Exec mixin and library:
+
+* NEW: The new `Toys::Utils::Exec::Result#effective_result` method provides a reasonable integer result code even when a process terminates via signal or fails to start at all.
+* BREAKING API CHANGE: `:cli` is no longer a legal config option.
+* BREAKING API CHANGE: An options hash is no longer passed to the proc when executing a proc using a fork.
+* BREAKING API CHANGE: Passing an IO object as an input or output stream no longer closes it afterward.
+* BREAKING API CHANGE: `Toys::Utils::Exec::Controller#result` no longer preemptively (and prematurely) closes the controller input stream
+* FIXED: The `:unsetenv_others` option now works properly when executing a proc using a fork.
+* FIXED: Environment variable values specified as nil are now correctly unset when executing a proc using a fork.
+* FIXED: Fixed a rare concurrency issue if multiple threads concurrently get the result from a controller.
+
+Other changes:
+
+* NEW: Native tab completion for zsh.
+* NEW: The `:bundler` mixin supports "manual" bundle setup, allowing bundler decisions to be deferred to execution time
+* FIXED: The `:bundler` mixin will not attempt to add the `pathname` gem to generated Gemfiles when running on TruffleRuby. This caused issues because TruffleRuby includes a special version of the gem and cannot install the one from Rubygems.
+* FIXED: `ContextualError` no longer overrides `Exception#cause`, which could confuse TruffleRuby.
+* DOCUMENTATION: Updated user guide to cover zsh completion and manual bundler setup
+* DOCUMENTATION: Some reorganization and cleanup in the user guide
+
 ### v0.19.1 / 2026-01-06
 
 * FIXED: The minitest template and the "system test" builtin now support minitest 6

data/builtins/system/test.rb

@@ -9,159 +9,242 @@ flag :seed, "-s", "--seed SEED",
 flag :warnings, "-w", "--[no-]warnings",
      default: true,
      desc: "Turn on Ruby warnings (defaults to true)"
-flag :name, "-n", "--name PATTERN",
+flag :include_name, "-n", "-i", "--name PATTERN", "--include PATTERN",
      desc: "Filter run on /regexp/ or string."
-flag :exclude, "-e", "--exclude PATTERN",
+flag :exclude_name, "-e", "-x", "--exclude PATTERN",
      desc: "Exclude /regexp/ or string from run."
 flag :recursive, "--[no-]recursive", default: true,
      desc: "Recursively test subtools (default is true)"
 flag :tool, "-t TOOL", "--tool TOOL", default: "",
      desc: "Run tests only for tools under the given path"
-flag :minitest_version, "--minitest-version=VERSION", default: ">=5.0,<7",
-     desc: "Set the minitest version requirement (default is >=5.0,<7)"
+flag :minitest_version, "--minitest-version=VERSION", "--minitest=VERSION",
+     desc: "Set the minitest version requirement during runs where no Gemfile is present"
 flag :minitest_focus, "--minitest-focus[=VERSION]",
-     desc: "Make minitest-focus available during the run"
+     desc: "Make minitest-focus available during runs where no Gemfile is present"
 flag :minitest_mock, "--minitest-mock[=VERSION]",
-     desc: "Make minitest-mock available during the run"
+     desc: "Make minitest-mock available during runs where no Gemfile is present"
 flag :minitest_rg, "--minitest-rg[=VERSION]",
-     desc: "Make minitest-rg available during the run"
-flag :minitest_compat, "--[no-]minitest-compat",
+     desc: "Make minitest-rg available during runs where no Gemfile is present"
+flag :use_gems, "--use-gem=SPEC",
+     default: [], handler: :push,
+     desc: "Install the given gem with version requirements during runs where no Gemfile is present"
+flag :minitest_compat, "--[no-]minitest-compat", "--[no-]mt-compat",
      desc: "Set MT_COMPAT to retain compatibility with certain old plugins"
+flag :expand_globs, "--globs", "--expand-globs",
+     desc: "Expand globs in the test file arguments."
+
+remaining_args :tests,
+               complete: :file_system,
+               desc: "Paths to the tests to run (defaults to all tests)"
 
 include :exec
 include :gems
 include :terminal
 
 def run
-  env = ruby_env
-  ENV["MT_COMPAT"] = env["MT_COMPAT"] if env.key?("MT_COMPAT")
-  load_minitest_gems
-  result = exec_ruby(ruby_args, log_cmd: "Starting minitest...", env: env)
-  if result.error?
-    logger.error("Minitest failed!")
-    exit(result.exit_code)
-  end
-end
-
-def load_minitest_gems
-  if minitest_focus
-    set :minitest_focus, "~>1.4,>=1.4.1" if minitest_focus == true
-    gem "minitest-focus", *minitest_focus.split(",")
-    require "minitest/focus"
-  end
-  if minitest_mock
-    set :minitest_mock, "~>5.27" if minitest_mock == true
-    gem "minitest-mock", *minitest_mock.split(",")
-    require "minitest/mock"
-  end
-  if minitest_rg
-    set :minitest_rg, "~>5.4" if minitest_rg == true
-    gem "minitest-rg", *minitest_rg.split(",")
-    require "minitest/rg"
+  setup_mt_compat
+  final_code = 0
+  jobs = determine_jobs
+  if jobs.empty?
+    puts "WARNING: No test files found", :yellow, :bold
+    exit
   end
-  gem "minitest", *minitest_version.split(",")
-  require "minitest"
-
-  @minitest_version = @minitest_focus_version = @minitest_mock_version = @minitest_rg_version = nil
-  Gem.loaded_specs.each_value do |spec|
-    @minitest_version = spec.version.to_s if spec.name == "minitest"
-    @minitest_focus_version = spec.version.to_s if spec.name == "minitest-focus"
-    @minitest_mock_version = spec.version.to_s if spec.name == "minitest-mock"
-    @minitest_rg_version = spec.version.to_s if spec.name == "minitest-rg"
+  jobs.each do |job|
+    puts "Running #{job.name}", :bold
+    result = run_job(job)
+    if result.success?
+      puts "Succeeded: #{job.name}", :green, :bold
+    else
+      puts "Failed: #{job.name} (code=#{result.effective_code})", :red, :bold
+      final_code = 1
+    end
   end
+  exit(final_code)
 end
 
-def ruby_env
+def setup_mt_compat
   case minitest_compat
   when true
-    { "MT_COMPAT" => "true" }
+    ENV["MT_COMPAT"] = "true"
   when false
-    { "MT_COMPAT" => nil }
-  else
-    {}
+    ENV.delete("MT_COMPAT")
   end
 end
 
-def ruby_args
-  args = []
-  args << "-w" if warnings
-  args << "-I#{::Toys::CORE_LIB_PATH}#{::File::PATH_SEPARATOR}#{::Toys::LIB_PATH}"
-  args << "-e" << ruby_code.join("\n")
-  args << "--"
+Job = ::Struct.new(:name, :globs, :tests, :gemfile)
+
+def run_job(job)
+  args = ["system", "test", "_internal"]
+  args.concat(verbosity_flags)
   args << "--seed" << seed if seed
-  args << "--verbose" if verbosity.positive?
-  args << "--name" << name if name
-  args << "--exclude" << exclude if exclude
-  args
+  args << "--no-warnings" unless warnings
+  args << "--name" << include_name if include_name
+  args << "--exclude" << exclude_name if exclude_name
+  if job.gemfile
+    args << "--gemfile-path" << job.gemfile
+  else
+    add_gem_args(args)
+  end
+  args << "--globs" if job.globs
+  args << "--preload-code" << preload_code
+  args.concat(Array(job.globs || job.tests))
+  exec_separate_tool(args)
+end
+
+def preload_code
+  <<~RUBY
+    require "toys"
+    require "toys/testing"
+    Toys::Testing.toys_custom_paths(#{base_dir.inspect})
+    Toys::Testing.toys_include_builtins(false)
+  RUBY
 end
 
-def ruby_code
-  code = []
-  code << "gem 'minitest', '= #{@minitest_version}'"
-  code << "require 'minitest/autorun'"
-  if @minitest_focus_version
-    code << "gem 'minitest-focus', '= #{@minitest_focus_version}'"
-    code << "require 'minitest/focus'"
+def add_gem_args(args)
+  use_gems_hash = use_gems.to_h do |spec|
+    name, version = spec.strip.split(/\s*,\s*/, 2)
+    [name, version]
   end
-  if @minitest_mock_version
-    code << "gem 'minitest-mock', '= #{@minitest_mock_version}'"
-    code << "require 'minitest/mock'"
+  use_gems_hash["minitest"] = minitest_version
+  use_gems_hash["minitest-mock"] = minitest_mock if minitest_mock
+  use_gems_hash["minitest-focus"] = minitest_focus if minitest_focus
+  use_gems_hash["minitest-rg"] = minitest_rg if minitest_rg
+  if ::ENV["TOYS_DEV"] == "true"
+    args << "--libs" << ::Toys::CORE_LIB_PATH unless use_gems_hash["toys-core"]
+    args << "--libs" << ::Toys::LIB_PATH unless use_gems_hash["toys"]
+  else
+    use_gems_hash["toys"] ||= ::Toys::VERSION
   end
-  if @minitest_rg_version
-    code << "gem 'minitest-rg', '= #{@minitest_rg_version}'"
-    code << "require 'minitest/rg'"
+  use_gems_hash.each do |name, versions|
+    versions = nil if versions == true
+    args << "--use-gem" << [name, versions].compact.join(",")
   end
-  code << "require 'toys'"
-  code << "require 'toys/testing'"
-  if directory
-    code << "Toys::Testing.toys_custom_paths(#{::File.absolute_path(directory).inspect})"
-    code << "Toys::Testing.toys_include_builtins(false)"
+end
+
+def determine_jobs
+  return determine_jobs_from_tests unless tests.empty?
+  jobs = []
+  job = build_job_under(::File.join(tool_dir, ".test"))
+  jobs << job if job
+  if recursive
+    ::Dir.glob("#{tool_dir}/*/**/.test").sort.each do |test_dir|
+      job = build_job_under(test_dir)
+      jobs << job if job
+    end
+  end
+  jobs
+end
+
+def determine_jobs_from_tests
+  jobs = []
+  paths_by_test_dir = {}
+  paths_without_gemfile = []
+  preprocess_tests.each do |path|
+    test_dir = find_test_dir(path)
+    if test_dir
+      (paths_by_test_dir[test_dir] ||= []) << path
+    else
+      paths_without_gemfile << path
+    end
+  end
+  paths_by_test_dir.each do |test_dir, paths|
+    gemfile_path = ::File.join(test_dir, "Gemfile")
+    if ::File.file?(gemfile_path)
+      jobs << Job.new("specified tests under #{test_dir}", nil, paths, gemfile_path)
+    else
+      paths_without_gemfile.concat(paths)
+    end
   end
-  find_test_files.each do |file|
-    code << "load '#{file}'"
+  unless paths_without_gemfile.empty?
+    name_prefix = jobs.empty? ? "" : "remaining "
+    jobs << Job.new("#{name_prefix}specified tests", nil, paths_without_gemfile, nil)
   end
-  code
+  jobs
 end
 
-def find_test_files
-  glob = ".test/**/test_*.rb"
-  glob = "**/#{glob}" if recursive
-  glob = "#{tool_dir}/#{glob}"
-  test_files = Dir.glob(glob)
-  if test_files.empty?
-    logger.warn("No test files found")
-    exit
+def preprocess_tests
+  results = []
+  tests.each do |elem|
+    if expand_globs
+      glob_results = ::Dir.glob(elem)
+      if glob_results.empty?
+        logger.warn("Pattern did not match any test files: #{elem}")
+      else
+        glob_results.each do |path|
+          results << ::File.realpath(path)
+        end
+      end
+    else
+      begin
+        results << ::File.realpath(elem)
+      rescue ::Errno::ENOENT
+        logger.error("Unable to find file: #{elem}")
+        exit(1)
+      end
+    end
   end
-  test_files.each do |file|
-    logger.info("Loading: #{file}")
+  results
+end
+
+def find_test_dir(path)
+  dir = ::File.dirname(path)
+  while dir != path
+    return dir if ::File.basename(dir) == ".test"
+    path = dir
+    dir = ::File.dirname(dir)
   end
-  test_files
+  nil
+end
+
+def build_job_under(test_path)
+  return nil unless ::File.directory?(test_path)
+  globs = ["#{test_path}/**/test_*.rb", "#{test_path}/**/*_test.rb"]
+  globs.delete_if { |glob| ::Dir.glob(glob).empty? }
+  return nil if globs.empty?
+  gemfile_path = ::File.join(test_path, "Gemfile")
+  gemfile_path = nil unless ::File.file?(gemfile_path)
+  Job.new("tests under #{test_path}", globs, nil, gemfile_path)
 end
 
 def tool_dir
-  words = cli.loader.split_path(tool)
-  dir = base_dir
-  unless words.empty?
-    dir = ::File.join(dir, *words)
-    unless ::File.directory?(dir)
-      logger.warn("No such directory: #{dir}")
-      exit
+  @tool_dir ||= begin
+    words = cli.loader.split_path(tool)
+    dir = base_dir
+    unless words.empty?
+      dir = ::File.join(dir, *words)
+      unless ::File.directory?(dir)
+        logger.warn("No such directory: #{dir}")
+        exit
+      end
     end
+    dir
   end
-  dir
 end
 
 def base_dir
-  return ::File.absolute_path(directory) if directory
-  dir = ::Dir.getwd
-  loop do
-    candidate = ::File.join(dir, ::Toys::StandardCLI::CONFIG_DIR_NAME)
-    return candidate if ::File.directory?(candidate)
-    parent = ::File.dirname(dir)
-    if parent == dir
-      logger.error("Unable to find a Toys directory")
-      exit(1)
+  @base_dir ||=
+    if directory
+      unless ::File.directory?(directory)
+        logger.error("Directory not found: #{directory}")
+        exit(1)
+      end
+      ::File.realpath(directory)
+    else
+      dir = ::File.realpath(::Dir.getwd)
+      loop do
+        candidate = ::File.join(dir, ::Toys::StandardCLI::CONFIG_DIR_NAME)
+        break candidate if ::File.directory?(candidate)
+        parent = ::File.dirname(dir)
+        if parent == dir
+          logger.error("Unable to find a Toys directory")
+          exit(1)
+        end
+        dir = parent
+      end
     end
-    dir = parent
-  end
+end
+
+expand :minitest do |mt|
+  mt.name = "_internal"
+  mt.files = []
 end

data/builtins/system/zsh-completion.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+desc "Zsh tab completion for Toys"
+
+long_desc \
+  "Tools that manage tab completion for Toys in the zsh shell.",
+  "",
+  "To install tab completion for Toys, execute the following line in a zsh shell, or" \
+    " include it in an init file such as your .zshrc (after the line that calls compinit):",
+  ["  $(toys system zsh-completion install)"],
+  "",
+  "To remove tab completion, execute:",
+  ["  $(toys system zsh-completion remove)"],
+  "",
+  "It is also possible to install completions for different executable names if you have" \
+    " aliases for Toys. See the help for the \"install\" and \"remove\" tools for details.",
+  "",
+  "The \"eval\" tool is the actual completion command invoked by zsh when it needs to" \
+    " complete a toys command line. You shouldn't need to invoke it directly."
+
+tool "install" do
+  desc "Install zsh tab completion"
+
+  long_desc \
+    "Outputs a command to set up Toys tab completion in the current zsh shell.",
+    "",
+    "To use, execute the following line in a zsh shell, or include it in an init file" \
+      " such as your .zshrc (after the line that calls compinit):",
+    ["  $(toys system zsh-completion install)"],
+    "",
+    "This will associate the toys tab completion logic with the `toys` executable by default." \
+      " If you have aliases for the toys executable, pass them as arguments. e.g.",
+    ["  $(toys system zsh-completion install my-toys-alias another-alias)"]
+
+  remaining_args :executable_names,
+                 desc: "Names of executables for which to set up tab completion" \
+                       " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
+
+  def run
+    require "shellwords"
+    path = ::File.join(::File.dirname(::File.dirname(__dir__)), "share", "zsh-completion.sh")
+    exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
+    puts Shellwords.join(["source", path] + exes)
+  end
+end
+
+tool "remove" do
+  desc "Remove zsh tab completion"
+
+  long_desc \
+    "Outputs a command to remove Toys tab completion from the current zsh shell.",
+    "",
+    "To use, execute the following line in a zsh shell:",
+    ["  $(toys system zsh-completion remove)"],
+    "",
+    "If you have other names or aliases for the toys executable, pass them as arguments. e.g.",
+    ["  $(toys system zsh-completion remove my-toys-alias another-alias)"]
+
+  remaining_args :executable_names,
+                 desc: "Names of executables for which to remove tab completion" \
+                       " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
+
+  def run
+    require "shellwords"
+    path = ::File.join(::File.dirname(::File.dirname(__dir__)), "share", "zsh-completion-remove.sh")
+    exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
+    puts Shellwords.join(["source", path] + exes)
+  end
+end
+
+tool "eval" do
+  desc "Tab completion command (executed by zsh)"
+
+  long_desc \
+    "Completion command invoked by zsh to complete a toys command line. Generally you do not" \
+      " need to invoke this directly. It reads the command line context from the COMP_LINE" \
+      " and COMP_POINT environment variables, and outputs completion candidates to stdout in" \
+      " two sections separated by a blank line: final completions first, then partial" \
+      " completions (such as directory paths)."
+
+  disable_argument_parsing
+
+  def run
+    require "toys/utils/completion_engine"
+    result = ::Toys::Utils::CompletionEngine::Zsh.new(cli).run
+    if result > 1
+      logger.fatal("This tool must be invoked as a zsh completion command.")
+    end
+    exit(result)
+  end
+end

data/core-docs/toys/core.rb

@@ -9,6 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.19.1"
+    VERSION = "0.20.0"
   end
 end

data/core-docs/toys/errors.rb

@@ -58,17 +58,18 @@ module Toys
     #
     # @private This interface is internal and subject to change without warning.
     #
-    def initialize(cause, banner,
+    def initialize(underlying_error, banner,
                    config_path: nil, config_line: nil,
                    tool_name: nil, tool_args: nil)
       # Source available in the toys-core gem
     end
 
     ##
-    # The underlying exception
+    # The underlying exception.
+    # Generally the same as `Exception#cause`.
     # @return [::StandardError]
     #
-    attr_reader :cause
+    attr_reader :underlying_error
 
     ##
     # An overall banner message

data/core-docs/toys/standard_mixins/bundler.rb

@@ -22,9 +22,21 @@ 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.
+    #  *  `:static` (Boolean) Has the same effect as passing `:static` to the
+    #     `:setup` parameter.
+    #
+    #  *  `:setup` (:auto,:manual,:static) A symbol indicating when the bundle
+    #     should be installed. Possible values are:
+    #
+    #      *  `:auto` - (Default) Installs the bundle just before the tool runs.
+    #      *  `:static` - Installs the bundle immediately when defining the
+    #         tool.
+    #      *  `:manual` - Does not install the bundle, but defines the methods
+    #         `bundler_setup` and `bundler_setup?` in the tool. The tool can
+    #         call `bundler_setup` to install the bundle, optionally passing
+    #         any of the remaining keyword arguments below to override the
+    #         corresponding mixin parameters. The `bundler_setup?` method can
+    #         be queried to determine whether the bundle has been set up yet.
     #
     #  *  `:groups` (Array\<String\>) The groups to include in setup.
     #
@@ -76,7 +88,9 @@ module Toys
     #     (optional)
     #
     #  *  `:terminal` (Toys::Utils::Terminal) Terminal to use (optional)
+    #
     #  *  `:input` (IO) Input IO (optional, defaults to STDIN)
+    #
     #  *  `:output` (IO) Output IO (optional, defaults to STDOUT)
     #
     module Bundler

data/core-docs/toys/standard_mixins/exec.rb

@@ -109,7 +109,8 @@ module Toys
     #     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.
+    #     the IO data through to the child process. Note that the IO object
+    #     will _not_ be closed on completion.
     #
     #  *  **Redirect to a pipe:** You can redirect to a pipe created using
     #     `IO.pipe` (i.e. a two-element array of read and write IO objects) by

data/core-docs/toys/utils/completion_engine.rb

@@ -12,11 +12,15 @@ module Toys
       ##
       # **_Defined in the toys-core gem_**
       #
-      # A completion engine for bash.
+      # Base class for shell completion engines that use a
+      # `COMP_LINE` / `COMP_POINT` protocol.
+      #
+      # Subclasses must implement the private methods `#shell_name` and
+      # `#output_completions`.
       #
-      class Bash
+      class Base
         ##
-        # Create a bash completion engine.
+        # Create a completion engine.
         #
         # @param cli [Toys::CLI] The CLI.
         #
@@ -27,8 +31,8 @@ module Toys
         ##
         # 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.
+        # variables. Prints out completion candidates and returns a status code
+        # indicating the result.
         #
         #  *  **0** for success.
         #  *  **1** if completion failed.
@@ -42,6 +46,30 @@ module Toys
         end
       end
 
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # A completion engine for bash.
+      #
+      class Bash < Base
+        ##
+        # Create a bash completion engine.
+        #
+        # @param cli [Toys::CLI] The CLI.
+        #
+        def initialize(cli)
+          # Source available in the toys-core gem
+        end
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # A completion engine for zsh.
+      #
+      class Zsh < Base
+      end
+
       class << self
       end
     end