toys-core 0.19.1 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 815f546de5a0da65099cf1fdce70527fb42aafd3793bf8a99e35f63d77c4e66b
-  data.tar.gz: 79bd650fb1bdc5d04a2b1e1d235864e39313b4320518b9ac6296a8e1892aa8b1
+  metadata.gz: f391c9aad35948c882c03809a80079b592c59208547080ae68bf2e0052896f9c
+  data.tar.gz: 4aacba23fe5a5a1560b4f38c6a109e5af7b6c98b9777b0c1ce3906bd6e42810c
 SHA512:
-  metadata.gz: e696b9c3921aec0c56796bdd7b93a09d056f6d46347a5936bbf6a0ce9bc7b2811f90d4b9553c54bdf69b62d74289e4608da98473e9b62e34f155accbf665f7a1
-  data.tar.gz: 675e01b73df268ceda5cfd5bd62f4a21b164c2fce0b37e88f3397bc12f76ba8baa4b2969df5d82901ffbb78440dd1156374cc6642792d81a4ec9c149a800148a
+  metadata.gz: c8a4e6ec594002577f1e81b937c1fdd23aed6ffe9adb2535073eba4d2eabe1c0e9e1e0062ea135062e7169734f65f20d0c9a3138dceca4b514ad86a67c215016
+  data.tar.gz: c00f4cf11e0af3807cdc0559275ab79f3af4f1fe1eff83cedcda125eedabc04f7ec439d95fa65b7f3763ca86b10e30fd6a5cf8d6412f02cd2e8dae9170d9e7fd

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Release History
 
+### v0.20.0 / 2026-03-09
+
+Toys-core 0.20 is a major release with several new features and a number of fixes, including a few minor breaking changes.
+
+Major changes:
+
+* NEW: Native tab completion for zsh.
+* NEW: The `:bundler` mixin supports "manual" bundle setup, allowing bundler decisions to be deferred to execution time
+
+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.
+
+Minor fixes for TruffleRuby compatibility:
+
+* 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.
+
 ### v0.19.1 / 2026-01-06
 
 * DOCS: Some formatting fixes in the user guide

data/README.md

@@ -265,8 +265,8 @@ Navigate to the simple-gem example:
 
     $ cd toys-core/examples/simple-gem
 
-This example wraps the simple "greet" executable that we
-[covered earlier](#Add_some_functionality) in a gem. You can see the
+This example wraps the simple "greet" executable that we covered earlier, in a
+gem. You can see the
 [executable file](https://github.com/dazuma/toys/tree/main/toys-core/examples/simple-gem/bin/toys-core-simple-example)
 in the bin directory.
 
@@ -348,7 +348,7 @@ recommended because it has a few known bugs that affect Toys.
 
 ## License
 
-Copyright 2019-2025 Daniel Azuma and the Toys contributors
+Copyright 2019-2026 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/toys/cli.rb

@@ -552,7 +552,7 @@ module Toys
       #
       def default_error_handler
         proc do |error|
-          cause = error.cause
+          cause = error.respond_to?(:underlying_error) ? error.underlying_error : error.cause
           raise cause.is_a?(::SignalException) ? cause : error
         end
       end

data/lib/toys/compat.rb

@@ -13,35 +13,72 @@ module Toys
     parts = ::RUBY_VERSION.split(".")
     ruby_version = (parts[0].to_i * 10000) + (parts[1].to_i * 100) + parts[2].to_i
 
+    ##
     # @private
+    # An integer representation of the Ruby version, guaranteed to have the
+    # correct ordering. Currently, this is `major*10000 + minor*100 + patch`.
+    #
+    # @return [Integer]
+    #
     RUBY_VERSION_CODE = ruby_version
 
+    ##
     # @private
+    # Whether the current Ruby implementation is JRuby
+    #
+    # @return [boolean]
+    #
     def self.jruby?
       ::RUBY_ENGINE == "jruby"
     end
 
+    ##
     # @private
+    # Whether the current Ruby implementation is TruffleRuby
+    #
+    # @return [boolean]
+    #
     def self.truffleruby?
       ::RUBY_ENGINE == "truffleruby"
     end
 
+    ##
     # @private
+    # Whether we are running on Windows
+    #
+    # @return [boolean]
+    #
     def self.windows?
       ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
     end
 
+    ##
     # @private
+    # Whether we are running on Mac OS
+    #
+    # @return [boolean]
+    #
     def self.macos?
       ::RbConfig::CONFIG["host_os"] =~ /darwin/
     end
 
+    ##
     # @private
+    # Whether fork is supported on the current Ruby and OS
+    #
+    # @return [boolean]
+    #
     def self.allow_fork?
       !jruby? && !truffleruby? && !windows?
     end
 
+    ##
     # @private
+    # Whether it is possible to get suggestions from DidYouMean. If this
+    # returns false, {Compat.suggestions} will always return the empty array.
+    #
+    # @return [boolean]
+    #
     def self.supports_suggestions?
       unless defined?(@supports_suggestions)
         begin
@@ -59,7 +96,16 @@ module Toys
       @supports_suggestions
     end
 
+    ##
     # @private
+    # A list of suggestions from DidYouMean.
+    #
+    # @param word [String] A value that seems wrong
+    # @param list [Array<String>] A list of valid values
+    #
+    # @return [Array<String>] A possibly empty array of suggestions from the
+    #     valid list that could match the given word.
+    #
     def self.suggestions(word, list)
       if supports_suggestions?
         ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
@@ -67,5 +113,22 @@ module Toys
         []
       end
     end
+
+    ##
+    # @private
+    # A list of gems that should generally not be included in a bundle, usually
+    # because the Ruby implementation handles the library specially and cannot
+    # install the real gem. Currently, this includes the `pathname` gem for
+    # TruffleRuby, since TruffleRuby includes a special version of it.
+    #
+    # @return [Array<String>]
+    #
+    def self.gems_to_omit_from_bundles
+      if truffleruby?
+        ["pathname"]
+      else
+        []
+      end
+    end
   end
 end

data/lib/toys/core.rb

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

data/lib/toys/errors.rb

@@ -51,24 +51,25 @@ 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)
-      super("#{banner} : #{cause.message} (#{cause.class})")
-      @cause = cause
+      super("#{banner} : #{underlying_error.message} (#{underlying_error.class})")
+      @underlying_error = underlying_error
       @banner = banner
       @config_path = config_path
       @config_line = config_line
       @tool_name = tool_name
       @tool_args = tool_args
-      set_backtrace(cause.backtrace)
+      set_backtrace(underlying_error.backtrace)
     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
@@ -141,10 +142,10 @@ module Toys
         end
         raise e
       rescue ::ScriptError, ::StandardError, ::SignalException => e
-        e = ContextualError.new(e, banner)
-        add_fields_if_missing(e, opts)
-        add_config_path_if_missing(e, path)
-        raise e
+        ce = ContextualError.new(e, banner)
+        add_fields_if_missing(ce, opts)
+        add_config_path_if_missing(ce, path)
+        raise ce
       end
 
       ##
@@ -172,7 +173,7 @@ module Toys
 
       def add_config_path_if_missing(error, path)
         if error.config_path.nil? && error.config_line.nil?
-          l = (error.cause.backtrace_locations || []).find do |b|
+          l = (error.underlying_error.backtrace_locations || []).find do |b|
             b.absolute_path == path || b.path == path
           end
           if l

data/lib/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
@@ -94,6 +108,14 @@ module Toys
       #
       DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
 
+      ##
+      # @private
+      # Context key for the mixin parameters when using manual setup. The value
+      # will be a hash of parameters if the bundle has not been set up yet, or
+      # nil if the bundle has already been set up.
+      #
+      SETUP_PARAMS_KEY = Object.new.freeze
+
       ##
       # @private
       #
@@ -121,17 +143,43 @@ module Toys
         gems.bundle(groups: groups, gemfile_path: gemfile_path, retries: retries)
       end
 
-      on_initialize do |static: false, **kwargs|
-        unless static
+      on_initialize do |static: false, setup: nil, **kwargs|
+        setup ||= (static ? :static : :auto)
+        case setup
+        when :auto
           context_directory = self[::Toys::Context::Key::CONTEXT_DIRECTORY]
           source_info = self[::Toys::Context::Key::TOOL_SOURCE]
           ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        when :manual
+          self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY] = kwargs
         end
       end
 
-      on_include do |static: false, **kwargs|
-        if static
+      on_include do |static: false, setup: nil, **kwargs|
+        setup ||= (static ? :static : :auto)
+        case setup
+        when :static
           ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        when :manual
+          # @private
+          def bundler_setup(**kwargs)
+            original_kwargs = self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY]
+            raise ::Toys::Utils::Gems::AlreadyBundledError unless original_kwargs
+            context_directory = self[::Toys::Context::Key::CONTEXT_DIRECTORY]
+            source_info = self[::Toys::Context::Key::TOOL_SOURCE]
+            final_kwargs = original_kwargs.merge(kwargs)
+            ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **final_kwargs)
+            self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY] = nil
+          end
+
+          # @private
+          def bundler_setup?
+            self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY].nil?
+          end
+        when :auto
+          # Do nothing at this point
+        else
+          raise ::ArgumentError, "Unrecognized setup type: #{setup.inspect}"
         end
       end
 
@@ -165,7 +213,7 @@ module Toys
           when :toys
             search_toys
           else
-            raise ::ArgumentError, "Unrecognized search_dir: #{dir.inspect}"
+            raise ::ArgumentError, "Unrecognized search_dir: #{search_dir.inspect}"
           end
         end
 

data/lib/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
@@ -434,7 +435,7 @@ module Toys
       #     the foreground.
       #
       def exec_tool(cmd, **opts, &block)
-        func = Exec._make_tool_caller(cmd)
+        func = Exec._make_tool_caller(cmd, self[Context::Key::CLI])
         opts = Exec._setup_exec_opts(opts, self)
         opts = {log_cmd: "exec tool: #{cmd.inspect}"}.merge(opts)
         self[KEY].exec_proc(func, **opts, &block)
@@ -621,7 +622,7 @@ module Toys
       # @return [String] What was written to standard out.
       #
       def capture_tool(cmd, **opts, &block)
-        func = Exec._make_tool_caller(cmd)
+        func = Exec._make_tool_caller(cmd, self[Context::Key::CLI])
         opts = Exec._setup_exec_opts(opts, self)
         self[KEY].capture_proc(func, **opts, &block)
       end
@@ -750,9 +751,9 @@ module Toys
       ##
       # @private
       #
-      def self._make_tool_caller(cmd)
+      def self._make_tool_caller(cmd, cli)
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-        proc { |config| ::Kernel.exit(config[:cli].run(*cmd)) }
+        proc { ::Kernel.exit(cli.run(*cmd)) }
       end
 
       ##

data/lib/toys/utils/completion_engine.rb

@@ -10,24 +10,27 @@ module Toys
     #
     module CompletionEngine
       ##
-      # 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.
         #
         def initialize(cli)
-          require "shellwords"
           @cli = cli
         end
 
         ##
         # Perform completion in the current shell environment, which must
         # include settings for the `COMP_LINE` and `COMP_POINT` environment
-        # variables. Prints out completion candidates, one per line, and
-        # returns a status code indicating the result.
+        # variables. Prints out completion candidates and returns a status code
+        # indicating the result.
         #
         #  *  **0** for success.
         #  *  **1** if completion failed.
@@ -42,9 +45,9 @@ module Toys
           point = ::ENV["COMP_POINT"].to_i
           point = line.length if point.negative?
           line = line[0, point]
-          completions = run_internal(line)
-          if completions
-            completions.each { |completion| puts completion }
+          result = run_internal(line)
+          if result
+            output_completions(*result)
             0
           else
             1
@@ -53,6 +56,8 @@ module Toys
 
         ##
         # Internal completion method designed for testing.
+        # Returns `[quote_type, Array<Toys::Completion::Candidate>]`, or `nil`
+        # if the line cannot be parsed (e.g. the executable name is missing).
         #
         # @private
         #
@@ -68,39 +73,39 @@ module Toys
           end
           context = Completion::Context.new(
             cli: @cli, previous_words: words, fragment_prefix: prefix, fragment: last,
-            params: {shell: :bash, quote_type: quote_type}
+            params: { shell: shell_name, quote_type: quote_type }
           )
-          candidates = @cli.completion.call(context)
-          candidates.uniq.sort.map do |candidate|
-            CompletionEngine.format_candidate(candidate, quote_type)
-          end
+          [quote_type, @cli.completion.call(context).uniq.sort]
+        end
+
+        private
+
+        def shell_name
+          raise ::NotImplementedError
+        end
+
+        def output_completions(_quote_type, _candidates)
+          raise ::NotImplementedError
         end
       end
 
-      class << self
+      ##
+      # A completion engine for bash.
+      #
+      class Bash < Base
         ##
-        # @private
+        # Create a bash completion engine.
         #
-        def split(line)
-          words = []
-          field = ::String.new
-          quote_type = nil
-          line.scan(split_regex) do |word, sqw, dqw, esc, garbage, sep|
-            raise ArgumentError, "Didn't expect garbage: #{line.inspect}" if garbage
-            field << field_str(word, sqw, dqw, esc)
-            quote_type = update_quote_type(quote_type, sqw, dqw)
-            if sep
-              words << [quote_type, field]
-              quote_type = nil
-              field = sep.empty? ? nil : ::String.new
-            end
-          end
-          words << [quote_type, field] if field
-          words
+        # @param cli [Toys::CLI] The CLI.
+        #
+        def initialize(cli)
+          require "shellwords"
+          super
         end
 
         ##
         # @private
+        # Accessible only for testing
         #
         def format_candidate(candidate, quote_type)
           str = candidate.to_s
@@ -120,6 +125,57 @@ module Toys
 
         private
 
+        def shell_name
+          :bash
+        end
+
+        def output_completions(quote_type, candidates)
+          candidates.each { |c| puts format_candidate(c, quote_type) }
+        end
+      end
+
+      ##
+      # A completion engine for zsh.
+      #
+      class Zsh < Base
+        private
+
+        def shell_name
+          :zsh
+        end
+
+        def output_completions(_quote_type, candidates)
+          finals, partials = candidates.partition(&:final?)
+          finals.each { |c| puts c.string unless c.string.empty? }
+          puts ""
+          partials.each { |c| puts c.string unless c.string.empty? }
+        end
+      end
+
+      class << self
+        ##
+        # @private
+        #
+        def split(line)
+          words = []
+          field = ::String.new
+          quote_type = nil
+          line.scan(split_regex) do |word, sqw, dqw, esc, garbage, sep|
+            raise ArgumentError, "Didn't expect garbage: #{line.inspect}" if garbage
+            field << field_str(word, sqw, dqw, esc)
+            quote_type = update_quote_type(quote_type, sqw, dqw)
+            if sep
+              words << [quote_type, field]
+              quote_type = nil
+              field = sep.empty? ? nil : ::String.new
+            end
+          end
+          words << [quote_type, field] if field
+          words
+        end
+
+        private
+
         def split_regex
           word_re = "([^\\s\\\\\\'\\\"]+)"
           sq_re = "'([^\\']*)(?:'|\\z)"

data/lib/toys/utils/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
@@ -159,7 +160,7 @@ module Toys
     #
     # 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.
+    # streams, and any exception 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.
@@ -192,7 +193,7 @@ module Toys
     # ### Configuration options
     #
     # A variety of options can be used to control subprocesses. These can be
-    # provided to any method that starts a subprocess. Youc an also set
+    # provided to any method that starts a subprocess. You can also set
     # defaults by calling {Toys::Utils::Exec#configure_defaults}.
     #
     # Options that affect the behavior of subprocesses:
@@ -432,8 +433,8 @@ module Toys
       end
 
       ##
-      # Execute the given string in a shell. Returns the exit code.
-      # Cannot be run in the background.
+      # Execute the given string in a shell. Returns an effective exit code
+      # that is always an integer. Cannot be run in the background.
       #
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
@@ -444,11 +445,12 @@ module Toys
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Integer] The exit code
+      # @return [Integer] An effective exit code. See
+      #     {Toys::Utils::Exec::Result#effective_code}.
       #
       def sh(cmd, **opts, &block)
         opts = opts.merge(background: false)
-        exec(cmd, **opts, &block).exit_code || -1
+        exec(cmd, **opts, &block).effective_code
       end
 
       ##
@@ -523,7 +525,7 @@ module Toys
           stream = stream_for(which)
           @join_threads << ::Thread.new do
             data = stream.read
-            @mutex.synchronize do
+            @captures_mutex.synchronize do
               @captures[which] = data
             end
           ensure
@@ -560,6 +562,10 @@ module Toys
         # provide the mode and permissions for the call to `File#open`. You can
         # also specify the value `:null` to indicate the null file.
         #
+        # If the stream is redirected to an IO-like object, it is _not_ closed
+        # when the process is completed. (If it is redirected to a file
+        # specified by path, the file is closed on completion.)
+        #
         # After calling this, do not interact directly with the stream.
         #
         # @param which [:in,:out,:err] Which stream to redirect
@@ -570,9 +576,11 @@ module Toys
         #
         def redirect(which, io, *io_args)
           io = ::File::NULL if io == :null
+          close_afterward = false
           if io.is_a?(::String)
             io_args = which == :in ? ["r"] : ["w"] if io_args.empty?
             io = ::File.open(io, *io_args)
+            close_afterward = true
           end
           stream = stream_for(which, allow_in: true)
           @join_threads << ::Thread.new do
@@ -583,7 +591,7 @@ module Toys
             end
           ensure
             stream.close
-            io.close
+            io.close if close_afterward
           end
           self
         end
@@ -669,47 +677,48 @@ module Toys
         ##
         # Wait for the subcommand to complete, and return a result object.
         #
-        # Closes the control streams if present. The stdin stream is always
-        # closed, even if the call times out. The stdout and stderr streams are
-        # closed only after the command terminates.
-        #
         # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
         #     wait indefinitely.
         # @return [Toys::Utils::Exec::Result] The result object
         # @return [nil] if a timeout occurred.
         #
         def result(timeout: nil)
-          close_streams(:in)
           return nil if @wait_thread && !@wait_thread.join(timeout)
-          @result ||= begin
-            close_streams(:out)
-            @join_threads.each(&:join)
-            Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
-                  .tap { |result| @result_callback&.call(result) }
+          should_run_callback = false
+          @result_mutex.synchronize do
+            @result ||= begin
+              should_run_callback = true
+              close_streams(:both)
+              @join_threads.each(&:join)
+              Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
+            end
           end
+          @result_callback&.call(@result) if should_run_callback
+          @result
         end
 
         ##
         # @private
         #
-        def initialize(name, controller_streams, captures, pid, join_threads,
-                       result_callback, mutex)
+        def initialize(name:, controller_streams:, captures:, pid_or_exception:,
+                       join_threads:, result_callback:, captures_mutex:)
           @name = name
           @in = controller_streams[:in]
           @out = controller_streams[:out]
           @err = controller_streams[:err]
           @captures = captures
           @pid = @exception = @wait_thread = nil
-          case pid
+          case pid_or_exception
           when ::Integer
-            @pid = pid
-            @wait_thread = ::Process.detach(pid)
+            @pid = pid_or_exception
+            @wait_thread = ::Process.detach(@pid)
           when ::Exception
-            @exception = pid
+            @exception = pid_or_exception
           end
           @join_threads = join_threads
           @result_callback = result_callback
-          @mutex = mutex
+          @captures_mutex = captures_mutex
+          @result_mutex = ::Mutex.new
           @result = nil
         end
 
@@ -797,7 +806,7 @@ module Toys
         # Exactly one of {#exception} and {#status} will be non-nil.
         #
         # @return [Process::Status] The status, if the process was successfully
-        #     spanwed and terminated.
+        #     spawned and terminated.
         # @return [nil] if the process could not be started.
         #
         attr_reader :status
@@ -888,6 +897,42 @@ module Toys
           !code.nil? && !code.zero?
         end
 
+        ##
+        # Returns an "effective" exit code, which is always an integer if the
+        # process has terminated for any reason. In general, this code will be:
+        #
+        # * The same as {#exit_code} if the process terminated normally with an
+        #   exit code,
+        # * The convention of `128+signalnum` if the process terminated due to
+        #   a signal,
+        # * The convention of 126 if the process could not start due to lack of
+        #   execution permissions,
+        # * The convention of 127 if the process could not start because the
+        #   command was not recognized or could not be found, or
+        # * An undefined value between 1 and 255 for other failures.
+        #
+        # Note that the normal exit code and signal number cases are stable,
+        # but any other cases are subject to change on future releases.
+        #
+        # @return [Integer]
+        #
+        def effective_code
+          code = exit_code
+          return code unless code.nil?
+          code = signal_code
+          return code + 128 unless code.nil?
+          case exception
+          when ::Errno::ENOENT
+            127
+          else
+            # This is the intended result for ENOEXEC/EACCES.
+            # For now, any other error (e.g. EBADARCH on MacOS) will also map
+            # to this result. We can change this in the future since the
+            # documentation explicitly allows it.
+            126
+          end
+        end
+
         ##
         # @private
         #
@@ -916,7 +961,6 @@ module Toys
         CONFIG_KEYS = [
           :argv0,
           :background,
-          :cli,
           :env,
           :err,
           :in,
@@ -1012,6 +1056,10 @@ module Toys
         #
         def initialize(exec_opts, spawn_cmd, block)
           @fork_func = spawn_cmd.respond_to?(:call) ? spawn_cmd : nil
+          if @fork_func && !::Process.respond_to?(:fork)
+            raise ::NotImplementedError,
+                  "Executing a proc is not available because fork is not supported on the current Ruby platform"
+          end
           @spawn_cmd = spawn_cmd.respond_to?(:call) ? nil : spawn_cmd
           @config_opts = exec_opts.config_opts
           @spawn_opts = exec_opts.spawn_opts
@@ -1022,7 +1070,7 @@ module Toys
           @parent_streams = []
           @block = block
           @default_stream = @config_opts[:background] ? :null : :inherit
-          @mutex = ::Mutex.new
+          @captures_mutex = ::Mutex.new
         end
 
         ##
@@ -1037,6 +1085,7 @@ module Toys
           return controller if @config_opts[:background]
           begin
             @block&.call(controller)
+            controller.close_streams(:in)
             controller.result
           ensure
             controller.close_streams(:both)
@@ -1068,15 +1117,20 @@ module Toys
         end
 
         def start_with_controller
-          pid =
+          pid_or_exception =
             begin
               @fork_func ? start_fork : start_process
             rescue ::StandardError => e
               e
             end
           @child_streams.each(&:close)
-          Controller.new(@config_opts[:name], @controller_streams, @captures, pid,
-                         @join_threads, @config_opts[:result_callback], @mutex)
+          Controller.new(name: @config_opts[:name],
+                         controller_streams: @controller_streams,
+                         captures: @captures,
+                         pid_or_exception: pid_or_exception,
+                         join_threads: @join_threads,
+                         result_callback: @config_opts[:result_callback],
+                         captures_mutex: @captures_mutex)
         end
 
         def start_process
@@ -1106,21 +1160,28 @@ module Toys
         def run_fork_func
           catch(:result) do
             if @spawn_opts[:chdir]
-              ::Dir.chdir(@spawn_opts[:chdir]) { @fork_func.call(@config_opts) }
+              ::Dir.chdir(@spawn_opts[:chdir]) { @fork_func.call }
             else
-              @fork_func.call(@config_opts)
+              @fork_func.call
             end
             0
           end
         end
 
         def setup_env_within_fork
-          if @config_opts[:unsetenv_others]
+          env = @config_opts[:env] || {}
+          if @spawn_opts[:unsetenv_others]
             ::ENV.each_key do |k|
-              ::ENV.delete(k) unless @config_opts.key?(k)
+              ::ENV.delete(k) unless env.key?(k)
+            end
+          end
+          env.each do |k, v|
+            if v.nil?
+              ::ENV.delete(k.to_s)
+            else
+              ::ENV[k.to_s] = v.to_s
             end
           end
-          (@config_opts[:env] || {}).each { |k, v| ::ENV[k.to_s] = v.to_s }
         end
 
         def setup_streams_within_fork
@@ -1436,7 +1497,7 @@ module Toys
               when :close
                 io.close rescue nil # rubocop:disable Style/RescueModifier
               when :capture
-                @mutex.synchronize do
+                @captures_mutex.synchronize do
                   @captures[key] = io.string
                 end
               end
@@ -1507,7 +1568,6 @@ module Toys
             ::IO.copy_stream(io, stream)
           ensure
             stream.close
-            io.close
           end
         end
 
@@ -1517,7 +1577,6 @@ module Toys
             ::IO.copy_stream(stream, io)
           ensure
             stream.close
-            io.close
           end
         end
 
@@ -1525,7 +1584,7 @@ module Toys
           stream = make_out_pipe(key)
           @join_threads << ::Thread.new do
             data = stream.read
-            @mutex.synchronize do
+            @captures_mutex.synchronize do
               @captures[key] = data
             end
           ensure

data/lib/toys/utils/gems.rb

@@ -413,6 +413,8 @@ module Toys
         end
 
         loaded_gems = ::Gem.loaded_specs.values.sort_by(&:name)
+        omit_list = ::Toys::Compat.gems_to_omit_from_bundles
+        loaded_gems.delete_if { |spec| omit_list.include?(spec.name) } unless omit_list.empty?
         content << "toys_loaded_gems = #{loaded_gems.map(&:name).inspect}"
         content << "dependencies.delete_if { |dep| toys_loaded_gems.include?(dep.name) }"
         loaded_gems.each do |spec|

data/lib/toys/utils/pager.rb

@@ -66,7 +66,11 @@ module Toys
           result = @exec_service.exec(@command, in: :controller) do |controller|
             yield controller.in if controller.pid
           rescue ::Errno::EPIPE => e
-            raise e unless @rescue_broken_pipes
+            if @rescue_broken_pipes
+              return 1
+            else
+              raise e
+            end
           end
           return result.exit_code unless result.failed?
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.19.1
+  version: 0.20.0
 platform: ruby
 authors:
 - Daniel Azuma
@@ -92,10 +92,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.19.1/file.CHANGELOG.html
-  source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.20.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/dazuma/toys/tree/toys-core/v0.20.0/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.19.1
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.20.0
 rdoc_options: []
 require_paths:
 - lib