toys-core 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f391c9aad35948c882c03809a80079b592c59208547080ae68bf2e0052896f9c
-  data.tar.gz: 4aacba23fe5a5a1560b4f38c6a109e5af7b6c98b9777b0c1ce3906bd6e42810c
+  metadata.gz: f2805bf71091b4ea8bf6f6a670281171dc6a5df4edec5196d80d64124ce2a199
+  data.tar.gz: b5c860449af3a0566e9b1fe8dc527cba4df6750ccc3b259365faf99fa79682fb
 SHA512:
-  metadata.gz: c8a4e6ec594002577f1e81b937c1fdd23aed6ffe9adb2535073eba4d2eabe1c0e9e1e0062ea135062e7169734f65f20d0c9a3138dceca4b514ad86a67c215016
-  data.tar.gz: c00f4cf11e0af3807cdc0559275ab79f3af4f1fe1eff83cedcda125eedabc04f7ec439d95fa65b7f3763ca86b10e30fd6a5cf8d6412f02cd2e8dae9170d9e7fd
+  metadata.gz: 95490a978d1a3ae04be668a2fd318de2499e9610bb6072a053776fb47214d2444c0d93a73fa690b46a6d4706e2fec1f20b76f8d111100ec65216f0c274efe77a
+  data.tar.gz: b9421ebfa989c45444024222cc3576a166d5797d7c982033265a11aa149c71ef0ab069441c70da490819e5bbafe95eb017c92289d6b46d7917c19634ee3eaf64

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # 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.

data/lib/toys/core.rb

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

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

@@ -23,7 +23,8 @@ module Toys
     # The following parameters can be passed when including this mixin:
     #
     #  *  `:static` (Boolean) Has the same effect as passing `:static` to the
-    #     `:setup` parameter.
+    #     `: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:
@@ -114,7 +115,7 @@ module Toys
       # 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
+      SETUP_PARAMS_KEY = ::Object.new.freeze
 
       ##
       # @private
@@ -152,6 +153,8 @@ module Toys
           ::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
 
@@ -161,7 +164,7 @@ module Toys
         when :static
           ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
         when :manual
-          # @private
+          # @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
@@ -172,7 +175,7 @@ module Toys
             self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY] = nil
           end
 
-          # @private
+          # @private Defined dynamically for the tool but not visible to YARD
           def bundler_setup?
             self[::Toys::StandardMixins::Bundler::SETUP_PARAMS_KEY].nil?
           end
@@ -193,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
 

data/lib/toys/standard_mixins/exec.rb

@@ -35,36 +35,6 @@ module Toys
     # but you can also retrieve the service object itself by calling
     # {Toys::Context#get} with the key {Toys::StandardMixins::Exec::KEY}.
     #
-    # ### Controlling processes
-    #
-    # A process can be started in the *foreground* or the *background*. If you
-    # start a foreground process, it will "take over" your standard input and
-    # output streams by default, and it will keep control until it completes.
-    # If you start a background process, its streams will be redirected to null
-    # by default, and control will be returned to you immediately.
-    #
-    # While a process is running, you can control it using a
-    # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
-    # the process's input and output streams, send it signals, or wait for it
-    # to complete.
-    #
-    # When running a process in the foreground, the controller will be yielded
-    # to an optional block. For example, the following code starts a process in
-    # the foreground and passes its output stream to a controller.
-    #
-    #     exec(["git", "init"], out: :controller) do |controller|
-    #       loop do
-    #         line = controller.out.gets
-    #         break if line.nil?
-    #         puts "Got line: #{line}"
-    #       end
-    #     end
-    #
-    # When running a process in the background, the controller is returned from
-    # the method that starts the process:
-    #
-    #     controller = exec(["git", "init"], background: true)
-    #
     # ### Stream handling
     #
     # By default, subprocess streams are connected to the corresponding streams
@@ -84,7 +54,7 @@ module Toys
     #
     #  *  **Inherit parent stream:** You can inherit the corresponding stream
     #     in the parent process by passing `:inherit` as the option value. This
-    #     is the default if the subprocess is *not* run in the background.
+    #     is the default if the subprocess is run in the foreground.
     #
     #  *  **Redirect to null:** You can redirect to a null stream by passing
     #     `:null` as the option value. This connects to a stream that is not
@@ -136,7 +106,7 @@ module Toys
     #     the setting `:controller`. You can then manipulate the stream via the
     #     controller. If you pass a block to {Toys::StandardMixins::Exec#exec},
     #     it yields the {Toys::Utils::Exec::Controller}, giving you access to
-    #     streams.
+    #     streams. See the section below on controlling processes.
     #
     #  *  **Make copies of an output stream:** You can "tee," or duplicate the
     #     `:out` or `:err` stream and redirect those copies to various
@@ -156,6 +126,68 @@ module Toys
     #         the tee. Larger buffers may allow higher throughput. The default
     #         is 65536.
     #
+    # ### Controlling processes
+    #
+    # A process can be started in the *foreground* or the *background*. If you
+    # start a foreground process, it will inherit your standard input and
+    # output streams by default, and it will keep control until it completes.
+    # If you start a background process, its streams will be redirected to null
+    # by default, and control will be returned to you immediately.
+    #
+    # While a process is running, you can control it using a
+    # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
+    # the process's input and output streams, send it signals, or wait for it
+    # to complete.
+    #
+    # When running a process in the foreground, the controller will be yielded
+    # to an optional block. For example, the following code starts a process in
+    # the foreground and passes its output stream to a controller.
+    #
+    #     exec(["git", "init"], out: :controller) do |controller|
+    #       loop do
+    #         line = controller.out.gets
+    #         break if line.nil?
+    #         puts "Got line: #{line}"
+    #       end
+    #     end
+    #
+    # At the end of the block, if the controller is handling the process's
+    # input stream, that stream will automatically be closed. The following
+    # example programmatically sends data to the `wc` unix program, and
+    # captures its output. Because the controller is handling the input stream,
+    # it automatically closes the stream at the end of the block, which causes
+    # `wc` to end.
+    #
+    #     result = exec(["wc"], in: :controller, out: :capture) do |controller|
+    #       controller.in.puts "Hello, world!"
+    #     end
+    #     puts "Results: #{result.captured_out}"
+    #
+    # Otherwise, depending on the process's behavior, it may continue to run
+    # after the end of the block. Control will not be returned to the caller
+    # until the process actually terminates. Conversely, it is also possible
+    # the process could terminate by itself while the block is still executing.
+    # You can call controller methods to obtain the process's actual current
+    # state.
+    #
+    # When running a process in the background, the controller is returned
+    # immediately from the method that starts the process. In the following
+    # example, git init is kicked off in the background and the output is
+    # thrown away to /dev/null.
+    #
+    #     controller = exec(["git", "init"], background: true)
+    #
+    # In this mode, use the returned controller to query the process's state
+    # and interact with it. Streams directed to the controller are not
+    # automatically closed, so you will need to do so yourself. Following is an
+    # example of running `wc` in the background:
+    #
+    #     controller = exec(["wc"], background: true,
+    #                               in: :controller, out: :controller)
+    #     controller.in.puts "Hello, world!"
+    #     controller.in.close # Do this explicitly to cause wc to finish
+    #     puts "Results: #{controller.out.read}" # Read the entire stream
+    #
     # ### Result handling
     #
     # A subprocess result is represented by a {Toys::Utils::Exec::Result}
@@ -193,6 +225,12 @@ module Toys
     #       puts "exit code: #{result.exit_code}"
     #     end
     #
+    # In foreground mode, the callback is executed in the calling thread, after
+    # the process terminates (and after any controller block has completed) but
+    # before control is returned to the caller. In background mode, the
+    # callback is executed asynchronously in a separate thread after the
+    # process terminates.
+    #
     # Finally, you can force your tool to exit if a subprocess fails, similar
     # to setting the `set -e` option in bash, by setting the
     # `:exit_on_nonzero_status` option. This is often set as a default
@@ -216,6 +254,10 @@ module Toys
     #
     #  *  `:background` (Boolean) Runs the process in the background if `true`.
     #
+    #  *  `:unbundle` (Boolean) Disables any existing bundle when running the
+    #     subprocess. Has no effect if Bundler isn't active at the call point.
+    #     Cannot be used when executing in a fork, e.g. via {#exec_proc}.
+    #
     # Options related to handling results
     #
     #  *  `:result_callback` (Proc,Symbol) A procedure that is called, and
@@ -837,12 +879,7 @@ module Toys
         context = self
         opts = Exec._setup_exec_opts(opts, context)
         context[KEY] = Utils::Exec.new(**opts) do |k|
-          case k
-          when :logger
-            context[Context::Key::LOGGER]
-          when :cli
-            context[Context::Key::CLI]
-          end
+          k == :logger ? context[Context::Key::LOGGER] : nil
         end
       end
     end

data/lib/toys/standard_mixins/xdg.rb

@@ -10,7 +10,7 @@ module Toys
     # utility methods that locate base directories and search paths for
     # application state, configuration, caches, and other data, according to
     # the [XDG Base Directory Spec version
-    # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
+    # 0.8](https://specifications.freedesktop.org/basedir/0.8/).
     #
     # @example
     #