toys-core 0.19.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 815f546de5a0da65099cf1fdce70527fb42aafd3793bf8a99e35f63d77c4e66b
-  data.tar.gz: 79bd650fb1bdc5d04a2b1e1d235864e39313b4320518b9ac6296a8e1892aa8b1
+  metadata.gz: f2805bf71091b4ea8bf6f6a670281171dc6a5df4edec5196d80d64124ce2a199
+  data.tar.gz: b5c860449af3a0566e9b1fe8dc527cba4df6750ccc3b259365faf99fa79682fb
 SHA512:
-  metadata.gz: e696b9c3921aec0c56796bdd7b93a09d056f6d46347a5936bbf6a0ce9bc7b2811f90d4b9553c54bdf69b62d74289e4608da98473e9b62e34f155accbf665f7a1
-  data.tar.gz: 675e01b73df268ceda5cfd5bd62f4a21b164c2fce0b37e88f3397bc12f76ba8baa4b2969df5d82901ffbb78440dd1156374cc6642792d81a4ec9c149a800148a
+  metadata.gz: 95490a978d1a3ae04be668a2fd318de2499e9610bb6072a053776fb47214d2444c0d93a73fa690b46a6d4706e2fec1f20b76f8d111100ec65216f0c274efe77a
+  data.tar.gz: b9421ebfa989c45444024222cc3576a166d5797d7c982033265a11aa149c71ef0ab069441c70da490819e5bbafe95eb017c92289d6b46d7917c19634ee3eaf64

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Release History
 
+### v0.21.0 / 2026-03-23
+
+This release includes a variety of small fixes and updates toward improving product polish in preparation for a 1.0 release. It focuses on the following areas:
+
+* Updates to the help system
+    * FIXED / BREAKING CHANGE: The help middleware omits the subtool filter flags on runnable tools that have subtools
+* Updates to bundler integration
+    * FIXED: Fixed some cleanup issues when bundler setup fails
+* Updates to the exec utility
+    * ADDED: Support for the `:unbundle` option which removes any existing bundle for a subprocess
+    * FIXED: Fixed several thread-safety issues with the controller
+    * FIXED: The result callback is now called in background mode if the result is never explicitly obtained from the controller
+* Updates to the git_cache utility
+    * ADDED: Support for filtering lookups of ref and source info
+    * ADDED: Support for SHA-256 repos
+    * FIXED: Fixed failure to get a parent directory after previously getting a descendant object
+    * FIXED: GitCache no longer unnecessarily sets the write bit on files copied into a specified directory
+    * FIXED: GitCache no longer cleans out existing files when writing to a shared source, which should reduce issues with concurrent clients
+* Updates to the XDG utility
+    * FIXED / BREAKING CHANGE: The XDG utility returns an empty array (instead of the system defaults) from the corresponding methods if `XDG_DATA_DIRS` or `XDG_CONFIG_DIRS` is nonempty but contains only relative paths
+    * ADDED: Provided `lookup_state` and `lookup_cache` methods on the XDG utility
+* Updates to the settings system:
+    * FIXED: Block certain reserved names from being used as Settings field names
+    * FIXED: Fixed `Settings#load_data!` when subclassing another settings class
+    * FIXED: Reject non-String values in Settings regexp type spec
+    * FIXED: Settings guards against unknown classes when loading YAML on older Ruby versions
+    * FIXED: Settings guards against `ILLEGAL_VALUE` being passed to `range.member?`
+    * FIXED: Settings does a better job choosing exact-match values when using a union type
+    * FIXED: Settings reject non-numeric strings in Integer and Float converters
+    * FIXED: Settings propagates nested group errors in `Settings#load_data!`
+
+### 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.21.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/settings.rb

@@ -35,8 +35,12 @@ module Toys
   # Attribute names must start with an ascii letter, and may contain only ascii
   # letters, digits, and underscores. Unlike method names, they may not include
   # non-ascii unicode characters, nor may they end with `!` or `?`.
-  # Additionally, the name `method_missing` is not allowed because of its
-  # special behavior in Ruby.
+  # Additionally, some names are reserved because they would shadow critical
+  # Ruby methods or interfere with Settings' internal behavior (see
+  # {Toys::Settings::RESERVED_FIELD_NAMES} for the complete list, which
+  # currently includes names such as `class`, `clone`, `dup`, `freeze`, `hash`,
+  # `initialize`, `method_missing`, `object_id`, `public_send`, `raise`,
+  # `require`, and `send`).
   #
   # Each attribute defines four methods: a getter, a setter, an unsetter, and a
   # set detector. In the above example, the attribute named `:endpoint` creates
@@ -297,12 +301,27 @@ module Toys
   #     grandchild_settings.str        # => "value_from_root"
   #
   class Settings
+    ##
     # A special value indicating a type check failure.
+    #
     ILLEGAL_VALUE = ::Object.new.freeze
 
+    ##
     # A special type specification indicating infer from the default value.
+    #
     DEFAULT_TYPE = ::Object.new.freeze
 
+    ##
+    # Field names that are not allowed because they would shadow critical Ruby
+    # methods or break Settings' own internal method calls.
+    #
+    # @return [Array<String>]
+    #
+    RESERVED_FIELD_NAMES = [
+      "class", "clone", "dup", "freeze", "hash", "initialize",
+      "method_missing", "object_id", "public_send", "raise", "require", "send"
+    ].freeze
+
     ##
     # Error raised when a value does not match the type constraint.
     #
@@ -447,15 +466,14 @@ module Toys
           range_class = (range.begin || range.end).class
           new("(#{range})") do |val|
             converted = convert(val, range_class)
-            range.member?(converted) ? converted : ILLEGAL_VALUE
+            converted != ILLEGAL_VALUE && range.member?(converted) ? converted : ILLEGAL_VALUE
           end
         end
 
         def for_regexp(regexp)
           regexp_str = regexp.source.gsub("/", "\\/")
           new("/#{regexp_str}/") do |val|
-            str = val.to_s
-            regexp.match(str) ? str : ILLEGAL_VALUE
+            val.is_a?(::String) && regexp.match(val) ? val : ILLEGAL_VALUE
           end
         end
 
@@ -466,7 +484,7 @@ module Toys
             result = ILLEGAL_VALUE
             types.each do |type|
               converted = type.call(val)
-              if converted == val
+              if converted.eql?(val)
                 result = val
                 break
               elsif result == ILLEGAL_VALUE
@@ -518,7 +536,7 @@ module Toys
       float_converter = proc do |val|
         case val
         when ::String
-          val.to_f
+          Float(val)
         when ::Numeric
           converted = val.to_f
           converted == val ? converted : ILLEGAL_VALUE
@@ -530,7 +548,7 @@ module Toys
       integer_converter = proc do |val|
         case val
         when ::String
-          val.to_i
+          Integer(val)
         when ::Numeric
           converted = val.to_i
           converted == val ? converted : ILLEGAL_VALUE
@@ -605,7 +623,7 @@ module Toys
           raise FieldError.new(value, self.class, name, nil) unless field
           if field.group?
             raise FieldError.new(value, self.class, name, "Hash") unless value.is_a?(::Hash)
-            get!(field).load_data!(value)
+            errors.concat(get!(field).load_data!(value, raise_on_failure: raise_on_failure))
           else
             set!(field, value)
           end
@@ -628,7 +646,7 @@ module Toys
     #
     def load_yaml!(str, raise_on_failure: false)
       require "psych"
-      load_data!(::Psych.load(str), raise_on_failure: raise_on_failure)
+      load_data!(::Psych.safe_load(str, permitted_classes: [::Symbol]), raise_on_failure: raise_on_failure)
     end
 
     ##
@@ -641,7 +659,7 @@ module Toys
     # @return [Array<FieldError>] An array of errors.
     #
     def load_yaml_file!(filename, raise_on_failure: false)
-      load_yaml!(File.read(filename), raise_on_failure: raise_on_failure)
+      load_yaml!(::File.read(filename), raise_on_failure: raise_on_failure)
     end
 
     ##
@@ -668,7 +686,7 @@ module Toys
     # @return [Array<FieldError>] An array of errors.
     #
     def load_json_file!(filename, raise_on_failure: false, **json_opts)
-      load_json!(File.read(filename), raise_on_failure: raise_on_failure, **json_opts)
+      load_json!(::File.read(filename), raise_on_failure: raise_on_failure, **json_opts)
     end
 
     ##
@@ -848,7 +866,12 @@ module Toys
       # all its instances.
       #
       def fields
-        @fields ||= {}
+        @fields ||=
+          if superclass.respond_to?(:fields)
+            superclass.fields.dup
+          else
+            {}
+          end
       end
 
       ##
@@ -882,7 +905,7 @@ module Toys
 
       def interpret_name(name)
         name = name.to_s
-        if name !~ /^[a-zA-Z]\w*$/ || name == "method_missing"
+        if name !~ /^[a-zA-Z]\w*$/ || RESERVED_FIELD_NAMES.include?(name)
           raise ::ArgumentError, "Illegal settings field name: #{name}"
         end
         existing = public_instance_methods(false)

data/lib/toys/standard_middleware/show_help.rb

@@ -53,43 +53,43 @@ module Toys
       # Key set when the show help flag is present
       # @return [Object]
       #
-      SHOW_HELP_KEY = Object.new.freeze
+      SHOW_HELP_KEY = ::Object.new.freeze
 
       ##
       # Key set when the show usage flag is present
       # @return [Object]
       #
-      SHOW_USAGE_KEY = Object.new.freeze
+      SHOW_USAGE_KEY = ::Object.new.freeze
 
       ##
       # Key set when the show subtool list flag is present
       # @return [Object]
       #
-      SHOW_LIST_KEY = Object.new.freeze
+      SHOW_LIST_KEY = ::Object.new.freeze
 
       ##
       # Key for the recursive setting
       # @return [Object]
       #
-      RECURSIVE_SUBTOOLS_KEY = Object.new.freeze
+      RECURSIVE_SUBTOOLS_KEY = ::Object.new.freeze
 
       ##
       # Key for the search string
       # @return [Object]
       #
-      SEARCH_STRING_KEY = Object.new.freeze
+      SEARCH_STRING_KEY = ::Object.new.freeze
 
       ##
       # Key for the show-all-subtools setting
       # @return [Object]
       #
-      SHOW_ALL_SUBTOOLS_KEY = Object.new.freeze
+      SHOW_ALL_SUBTOOLS_KEY = ::Object.new.freeze
 
       ##
       # Key for the tool name
       # @return [Object]
       #
-      TOOL_NAME_KEY = Object.new.freeze
+      TOOL_NAME_KEY = ::Object.new.freeze
 
       ##
       # Create a ShowHelp middleware.
@@ -214,7 +214,7 @@ module Toys
           list_flags = has_subtools ? add_list_flags(tool) : []
           can_display_help = !help_flags.empty? || !list_flags.empty? ||
                              !usage_flags.empty? || @fallback_execution
-          if can_display_help && has_subtools
+          if can_display_help && has_subtools && !tool.runnable?
             add_recursive_flags(tool)
             add_search_flags(tool)
             add_show_all_subtools_flags(tool)

data/lib/toys/standard_middleware/show_root_version.rb

@@ -23,7 +23,7 @@ module Toys
       # Key set when the version flag is present
       # @return [Object]
       #
-      SHOW_VERSION_KEY = Object.new.freeze
+      SHOW_VERSION_KEY = ::Object.new.freeze
 
       ##
       # Create a ShowVersion middleware

data/lib/toys/standard_mixins/bundler.rb

@@ -22,9 +22,22 @@ 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. This is present largely for historical
+    #     compatibility, but it is supported and _not_ deprecated.
+    #
+    #  *  `: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 +89,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 +109,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 +144,45 @@ 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
+        when :static
+          # Already set up at include time
         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 Defined dynamically for the tool but not visible to YARD
+          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 Defined dynamically for the tool but not visible to YARD
+          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
 
@@ -145,7 +196,7 @@ module Toys
         def initialize(context_directory, source_info, gemfile_names, toys_gemfile_names)
           @context_directory = context_directory
           @source_info = source_info
-          @gemfile_names = gemfile_names
+          @gemfile_names = gemfile_names || ::Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES
           @toys_gemfile_names = toys_gemfile_names || DEFAULT_TOYS_GEMFILE_NAMES
         end
 
@@ -165,7 +216,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