toys 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91bb0564850a2dc5b0742038d542cbb1239b2bcdef5db7f256c8deceac580e82
-  data.tar.gz: 894bdc6c036528a156fecdd79ee65ec4d099281552c5fe3f6ec6488627985fb2
+  metadata.gz: 87582d55a2f60738d19c3c4d717f93910c5cc677f5e210c8418366baf2e91921
+  data.tar.gz: f82f165fa06113b1ad398c5cb2d5e62217d860924f00e5b0d3b6172824d4a116
 SHA512:
-  metadata.gz: 576e41a7ffda908b16b696158bf7baa00b0a9fe065425847e24ee5db01082dbbc61119362de0e14a98f00d5a0edb727ec42f5428ab110b3be5a0cf318041d628
-  data.tar.gz: 56e9a65cbc25bd8c40b30885a61399fc7927b047b2f2edffbea0533a642b969734d52303a01637efc9a38e1300d1f6ed3697fa61515a6522d54148511b1d2a1d
+  metadata.gz: 5a9dad0dcdd8c83d678dfe23522faaa38b62bb765e16f7b6aafce2ce014920d13addce0d32a619f4c5d80e21f8e79b40ff8c0936381169df17d080d3d2500aec
+  data.tar.gz: 0f2b4c0cc5cf87ed070d7f21d57f8a9b2051277c5651f5e4d210b9ebb2a9498df93dde3203cb54437c19f8991ed348ab3b9d59c5a944c3070aa22e09a7cdd14e

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 0.20 is a major release with several new features and a number of fixes, including a few minor breaking changes.

data/builtins/system/bash-completion.rb

@@ -60,7 +60,7 @@ tool "install" do
     require "shellwords"
     path = ::File.join(::File.dirname(::File.dirname(__dir__)), "share", "bash-completion.sh")
     exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
-    puts Shellwords.join(["source", path] + exes)
+    puts ::Shellwords.join(["source", path] + exes)
   end
 end
 
@@ -84,6 +84,6 @@ tool "remove" do
     require "shellwords"
     path = ::File.join(::File.dirname(::File.dirname(__dir__)), "share", "bash-completion-remove.sh")
     exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
-    puts Shellwords.join(["source", path] + exes)
+    puts ::Shellwords.join(["source", path] + exes)
   end
 end

data/builtins/system/zsh-completion.rb

@@ -40,7 +40,7 @@ tool "install" do
     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)
+    puts ::Shellwords.join(["source", path] + exes)
   end
 end
 
@@ -64,7 +64,7 @@ tool "remove" do
     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)
+    puts ::Shellwords.join(["source", path] + exes)
   end
 end
 

data/core-docs/toys/core.rb

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

data/core-docs/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
+
     ##
     # **_Defined in the toys-core gem_**
     #

data/core-docs/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.

data/core-docs/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/core-docs/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:

data/core-docs/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

data/core-docs/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
     #

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

@@ -33,36 +33,6 @@ module Toys
     # to processes it spawns. You can set these defaults when constructing the
     # service class, or at any time by calling {#configure_defaults}.
     #
-    # ### 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_service.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_service.exec(["git", "init"], background: true)
-    #
     # ### Stream handling
     #
     # By default, subprocess streams are connected to the corresponding streams
@@ -82,7 +52,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
@@ -134,7 +104,7 @@ module Toys
     #     the setting `:controller`. You can then manipulate the stream via the
     #     controller. If you pass a block to {Toys::Utils::Exec#exec}, it
     #     yields the {Toys::Utils::Exec::Controller}, giving you access to
-    #     streams.
+    #     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
@@ -154,6 +124,70 @@ 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_service.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_service.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_service.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_service.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}
@@ -188,6 +222,12 @@ module Toys
     #     end
     #     exec_service.exec(["git", "init"], result_callback: my_callback)
     #
+    # 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.
+    #
     # ### Configuration options
     #
     # A variety of options can be used to control subprocesses. These can be
@@ -200,10 +240,16 @@ module Toys
     #     Keys represent variable names and should be strings. Values should be
     #     either strings or `nil`, which unsets the variable.
     #
-    #  *  `:background` (Boolean) Runs the process in the background if `true`.
+    #  *  `:background` (boolean) Runs the process in the background if `true`.
     #
     #  *  `:result_callback` (Proc) Called and passed the result object when
-    #     the subprocess exits.
+    #     the subprocess exits. If the process was run in the background, this
+    #     callback is executed in a separate thread. If the process was run in
+    #     the foreground, this callback is executed in the calling thread.
+    #
+    #  *  `: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 for connecting input and output streams. See the section above on
     # stream handling for info on the values that can be passed.
@@ -238,16 +284,16 @@ module Toys
     #
     #  *  `:chdir` (String) Set the working directory for the command.
     #
-    #  *  `:close_others` (Boolean) Whether to close non-redirected
+    #  *  `:close_others` (boolean) Whether to close non-redirected
     #     non-standard file descriptors.
     #
-    #  *  `:new_pgroup` (Boolean) Create new process group (Windows only).
+    #  *  `:new_pgroup` (boolean) Create new process group (Windows only).
     #
     #  *  `:pgroup` (Integer,true,nil) The process group setting.
     #
     #  *  `:umask` (Integer) Umask setting for the new process.
     #
-    #  *  `:unsetenv_others` (Boolean) Clear environment variables except those
+    #  *  `:unsetenv_others` (boolean) Clear environment variables except those
     #     explicitly set.
     #
     # Any other option key will result in an `ArgumentError`.
@@ -494,7 +540,10 @@ module Toys
         # After calling this, do not read directly from the stream.
         #
         # @param which [:out,:err] Which stream to capture
-        # @return [self]
+        #
+        # @return [self] if the stream was captured
+        # @return [nil] if the stream was not captured because the process has
+        #     completed or did not start successfully
         #
         def capture(which)
           # Source available in the toys-core gem
@@ -538,7 +587,10 @@ module Toys
         # @param io [IO,StringIO,String,:null] Where to redirect the stream
         # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to/from a file.
-        # @return [self]
+        #
+        # @return [self] if the stream was redirected
+        # @return [nil] if the stream was not redirected because the process
+        #     has completed or did not start successfully
         #
         def redirect(which, io, *io_args)
           # Source available in the toys-core gem
@@ -557,7 +609,10 @@ module Toys
         # @param io [IO,StringIO,String,:null] Where to redirect the stream
         # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting from a file.
-        # @return [self]
+        #
+        # @return [self] if the stream was redirected
+        # @return [nil] if the stream was not redirected because the process
+        #     has completed or did not start successfully
         #
         def redirect_in(io, *io_args)
           # Source available in the toys-core gem
@@ -576,7 +631,10 @@ module Toys
         # @param io [IO,StringIO,String,:null] Where to redirect the stream
         # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to a file.
-        # @return [self]
+        #
+        # @return [self] if the stream was redirected
+        # @return [nil] if the stream was not redirected because the process
+        #     has completed or did not start successfully
         #
         def redirect_out(io, *io_args)
           # Source available in the toys-core gem
@@ -587,14 +645,18 @@ module Toys
         #
         # You can specify the stream as an IO or IO-like object, or as a file
         # specified by its path. If specifying a file, you can optionally
-        # provide the mode and permissions for the call to `File#open`.
+        # provide the mode and permissions for the call to `File#open`. You can
+        # also specify the value `:null` to indicate the null file.
         #
         # After calling this, do not interact directly with the stream.
         #
-        # @param io [IO,StringIO,String] Where to redirect the stream
+        # @param io [IO,StringIO,String,:null] Where to redirect the stream
         # @param io_args [Object...] The mode and permissions for opening the
         #     file, if redirecting to a file.
-        # @return [self]
+        #
+        # @return [self] if the stream was redirected
+        # @return [nil] if the stream was not redirected because the process
+        #     has completed or did not start successfully
         #
         def redirect_err(io, *io_args)
           # Source available in the toys-core gem
@@ -615,7 +677,7 @@ module Toys
         ##
         # Determine whether the subcommand is still executing
         #
-        # @return [Boolean]
+        # @return [boolean]
         #
         def executing?
           # Source available in the toys-core gem
@@ -735,7 +797,7 @@ module Toys
         # Returns true if the subprocess failed to start, or false if the
         # process was able to execute.
         #
-        # @return [Boolean]
+        # @return [boolean]
         #
         def failed?
           # Source available in the toys-core gem
@@ -745,7 +807,7 @@ module Toys
         # Returns true if the subprocess terminated due to an unhandled signal,
         # or false if the process failed to start or exited normally.
         #
-        # @return [Boolean]
+        # @return [boolean]
         #
         def signaled?
           # Source available in the toys-core gem
@@ -756,7 +818,7 @@ module Toys
         # false if the process failed to start, terminated due to a signal, or
         # returned a nonzero status.
         #
-        # @return [Boolean]
+        # @return [boolean]
         #
         def success?
           # Source available in the toys-core gem
@@ -767,7 +829,7 @@ module Toys
         # false if the process failed to start, terminated due to a signal, or
         # returned a zero status.
         #
-        # @return [Boolean]
+        # @return [boolean]
         #
         def error?
           # Source available in the toys-core gem

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

@@ -122,11 +122,12 @@ module Toys
       #
       #     The default is `:error`.
       #
+      # @param default_confirm [Boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to true.
       # @param terminal [Toys::Utils::Terminal] Terminal to use (optional)
       # @param input [IO] Input IO (optional, defaults to STDIN)
       # @param output [IO] Output IO (optional, defaults to STDOUT)
       # @param suppress_confirm [Boolean] Deprecated. Use `on_missing` instead.
-      # @param default_confirm [Boolean] Deprecated. Use `on_missing` instead.
       #
       def initialize(on_missing: nil,
                      on_conflict: nil,
@@ -191,7 +192,12 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      @delete_at_exit_mutex = ::Mutex.new
+      @delete_at_exit_list = nil
+
       # @private
+      # This is a class method so the at_exit block doesn't hold onto an
+      # instance for the duration of the Ruby process
       def self.delete_at_exit(path)
         # Source available in the toys-core gem
       end

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

@@ -4,7 +4,7 @@ module Toys
     # **_Defined in the toys-core gem_**
     #
     # This object provides cached access to remote git data. Given a remote
-    # repository, a path, and a commit, it makes the files availble in the
+    # repository, a path, and a commit, it makes the files available in the
     # local filesystem. Access is cached, so repeated requests for the same
     # commit and path in the same repo do not hit the remote repository again.
     #
@@ -76,16 +76,27 @@ module Toys
         # A list of git refs (branches, tags, shas) that have been accessed
         # from this repo.
         #
+        # @param ref [String,nil] If provided, return only entries matching
+        #     this ref name. If omitted, return all entries.
         # @return [Array<RefInfo>]
         #
-        attr_reader :refs
+        def refs(ref: nil)
+          # Source available in the toys-core gem
+        end
 
         ##
         # A list of shared source files and directories accessed for this repo.
         #
+        # @param sha [String,nil] If provided, return only entries matching
+        #     this SHA. If omitted, entries for all SHAs are included.
+        # @param git_path [String,nil] If provided, return only entries
+        #     matching this git path. If omitted, entries for all paths are
+        #     included.
         # @return [Array<SourceInfo>]
         #
-        attr_reader :sources
+        def sources(sha: nil, git_path: nil)
+          # Source available in the toys-core gem
+        end
 
         ##
         # Convert this RepoInfo to a hash suitable for JSON output
@@ -132,14 +143,14 @@ module Toys
         ##
         # The timestamp when this ref was last accessed
         #
-        # @return [Time]
+        # @return [Time,nil]
         #
         attr_reader :last_accessed
 
         ##
         # The timestamp when this ref was last updated
         #
-        # @return [Time]
+        # @return [Time,nil]
         #
         attr_reader :last_updated
 
@@ -195,7 +206,7 @@ module Toys
         ##
         # The timestamp when this ref was last accessed
         #
-        # @return [Time]
+        # @return [Time,nil]
         #
         attr_reader :last_accessed
 
@@ -257,7 +268,7 @@ module Toys
       #
       # The resulting files are either copied into a directory you provide in
       # the `:into` parameter, or populated into a _shared_ source directory if
-      # you omit the `:info` parameter. In the latter case, it is important
+      # you omit the `:into` parameter. In the latter case, it is important
       # that you do not modify the returned files or directories, nor add or
       # remove any files from the directories returned, to avoid confusing
       # callers that could be given the same directory. If you need to make any
@@ -278,9 +289,12 @@ module Toys
       #     `false` to specify whether to update, or an integer to update if
       #     last update was done at least that many seconds ago. Default is
       #     `false`.
+      # @param timestamp [Integer,nil] The timestamp for recording the access
+      #     time and determining whether a resource is stale. Normally, you
+      #     should leave this out and it will default to the current time.
       #
       # @return [String] The full path to the cached files. The returned path
-      #     will correspod to the path given. For example, if you provide the
+      #     will correspond to the path given. For example, if you provide the
       #     path `Gemfile` representing a single file in the repository, the
       #     returned path will point directly to the cached copy of that file.
       #
@@ -320,7 +334,8 @@ module Toys
       # Be careful not to remove repos that are currently in use by other
       # GitCache clients.
       #
-      # @param remotes [Array<String>,:all] The remotes to remove.
+      # @param remotes [Array<String>,:all,nil] The remotes to remove. If set
+      #     to :all or nil, removes all repos.
       # @return [Array<String>] The remotes actually removed.
       #
       def remove_repos(remotes)

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

@@ -9,7 +9,7 @@ module Toys
     # This class provides 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/).
     #
     # Tools can use the `:xdg` mixin for convenient access to this class.
     #
@@ -19,7 +19,7 @@ module Toys
     #
     #     xdg = Toys::Utils::XDG.new
     #
-    #     # Get config file paths, in order from most to least inportant
+    #     # Get config file paths, in order from most to least important
     #     config_files = xdg.lookup_config("my-config.toml")
     #     config_files.each { |path| read_my_config(path) }
     #
@@ -41,6 +41,14 @@ module Toys
     #      use the Windows known folder paths.
     #
     class XDG
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # An error raised in certain cases when a lookup fails.
+      #
+      class Error < ::StandardError
+      end
+
       ##
       # Create an instance of XDG.
       #
@@ -63,6 +71,7 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific data files should be written.
+      #
       # Corresponds to the value of the `$XDG_DATA_HOME` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -75,6 +84,7 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific configuration files should be written.
+      #
       # Corresponds to the value of the `$XDG_CONFIG_HOME` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -87,6 +97,7 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific state files should be written.
+      #
       # Corresponds to the value of the `$XDG_STATE_HOME` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -99,6 +110,7 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific non-essential (cached) data should be written.
+      #
       # Corresponds to the value of the `$XDG_CACHE_HOME` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -111,6 +123,7 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific executable files may be written.
+      #
       # Returns the value of `$HOME/.local/bin` as specified by the XDG Base
       # Directory Spec.
       #
@@ -125,6 +138,7 @@ module Toys
       # which data files should be searched, as an array of absolute paths.
       # The array is ordered from most to least important, and does _not_
       # include the data home directory.
+      #
       # Corresponds to the value of the `$XDG_DATA_DIRS` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -139,6 +153,7 @@ module Toys
       # which configuration files should be searched, as an array of absolute
       # paths. The array is ordered from most to least important, and does
       # _not_ include the config home directory.
+      #
       # Corresponds to the value of the `$XDG_CONFIG_DIRS` environment variable
       # and its defaults according to the XDG Base Directory Spec.
       #
@@ -151,7 +166,15 @@ module Toys
       ##
       # Returns the absolute path to the single base directory relative to
       # which user-specific runtime files and other file objects should be
-      # placed. May return `nil` if no such directory could be determined.
+      # placed.
+      #
+      # Corresponds to the value of the `$XDG_RUNTIME_DIR` environment variable
+      # according to the XDG Base Directory Spec.
+      #
+      # **Important:** Returns `nil` if the `$XDG_RUNTIME_DIR` environment
+      # variable is unset or invalid. In such a case, it is the caller's
+      # responsibility to determine a fallback strategy, as this library cannot
+      # by itself implement a compliant fallback without OS help.
       #
       # @return [String,nil]
       #
@@ -159,11 +182,34 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific runtime files and other file objects should be
+      # placed.
+      #
+      # Corresponds to the value of the `$XDG_RUNTIME_DIR` environment variable
+      # according to the XDG Base Directory Spec.
+      #
+      # Raises {Toys::Utils::XDG::Error} if the `$XDG_RUNTIME_DIR` environment
+      # variable is unset or invalid. Unlike {#runtime_dir}, does not return
+      # nil.
+      #
+      # @return [String]
+      #
+      def runtime_dir!
+        # Source available in the toys-core gem
+      end
+
       ##
       # Searches the data directories for an object with the given relative
       # path, and returns an array of absolute paths to all objects found in
-      # the data directories (i.e. in {#data_dirs} or {#data_home}), in order
-      # from most to least important.
+      # all data directories (i.e. {#data_home} and {#data_dirs}), in order
+      # from most to least important. Returns the empty array if no suitable
+      # objects are found.
+      #
+      # If multiple objects are found, the caller should implement its own
+      # logic to resolve them. For example, it can select the first (most
+      # important) object, or implement logic to combine the contents.
       #
       # @param path [String] Relative path of the object to search for
       # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
@@ -181,8 +227,13 @@ module Toys
       ##
       # Searches the config directories for an object with the given relative
       # path, and returns an array of absolute paths to all objects found in
-      # the config directories (i.e. in {#config_dirs} or {#config_home}), in
-      # order from most to least important.
+      # all config directories (i.e. {#config_home} and {#config_dirs}), in
+      # order from most to least important. Returns the empty array if no
+      # suitable objects are found.
+      #
+      # If multiple objects are found, the caller should implement its own
+      # logic to resolve them. For example, it can select the first (most
+      # important) object, or implement logic to combine the contents.
       #
       # @param path [String] Relative path of the object to search for
       # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
@@ -197,6 +248,50 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      ##
+      # Searches the state directory ({#state_home}) for an object with the
+      # given relative path, and returns an array of zero or one absolute paths
+      # to any found object. Because the XDG basedir spec does not provide for
+      # a list of fallback directories for state files (i.e. there is no
+      # `XDG_STATE_DIRS` variable or list of default paths), this will return a
+      # maximum of one result. However, it returns an array for consistency
+      # with the {#lookup_data} and {#lookup_config} methods.
+      #
+      # @param path [String] Relative path of the object to search for
+      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
+      #     to find. You can specify any of the types defined by
+      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
+      #     such as `file` or `directory`, or the special type `any`. Types can
+      #     be specified as strings or the  corresponding symbols. If this
+      #     argument is not provided, the default of `file` is used.
+      # @return [Array<String>]
+      #
+      def lookup_state(path, type: :file)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Searches the cache directory ({#cache_home}) for an object with the
+      # given relative path, and returns an array of zero or one absolute paths
+      # to any found object. Because the XDG basedir spec does not provide for
+      # a list of fallback directories for cache files (i.e. there is no
+      # `XDG_CACHE_DIRS` variable or list of default paths), this will return a
+      # maximum of one result. However, it returns an array for consistency
+      # with the {#lookup_data} and {#lookup_config} methods.
+      #
+      # @param path [String] Relative path of the object to search for
+      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
+      #     to find. You can specify any of the types defined by
+      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
+      #     such as `file` or `directory`, or the special type `any`. Types can
+      #     be specified as strings or the  corresponding symbols. If this
+      #     argument is not provided, the default of `file` is used.
+      # @return [Array<String>]
+      #
+      def lookup_cache(path, type: :file)
+        # Source available in the toys-core gem
+      end
+
       ##
       # Returns the absolute path to a directory under {#data_home}, creating
       # it if it doesn't already exist.
@@ -204,7 +299,9 @@ module Toys
       # @param path [String] The relative path to the subdir within the base
       #     data directory.
       # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
+      # @raise [SystemCallError] If a non-directory already exists there. It is
+      #     unspecified which specific error will be raised; it typically could
+      #     be `Errno::EEXIST` or `Errno::ENOTDIR`.
       #
       def ensure_data_subdir(path)
         # Source available in the toys-core gem
@@ -217,7 +314,9 @@ module Toys
       # @param path [String] The relative path to the subdir within the base
       #     config directory.
       # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
+      # @raise [SystemCallError] If a non-directory already exists there. It is
+      #     unspecified which specific error will be raised; it typically could
+      #     be `Errno::EEXIST` or `Errno::ENOTDIR`.
       #
       def ensure_config_subdir(path)
         # Source available in the toys-core gem
@@ -230,7 +329,9 @@ module Toys
       # @param path [String] The relative path to the subdir within the base
       #     state directory.
       # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
+      # @raise [SystemCallError] If a non-directory already exists there. It is
+      #     unspecified which specific error will be raised; it typically could
+      #     be `Errno::EEXIST` or `Errno::ENOTDIR`.
       #
       def ensure_state_subdir(path)
         # Source available in the toys-core gem
@@ -243,7 +344,9 @@ module Toys
       # @param path [String] The relative path to the subdir within the base
       #     cache directory.
       # @return [String] The absolute path to the subdir.
-      # @raise [Errno::EEXIST] If a non-directory already exists there
+      # @raise [SystemCallError] If a non-directory already exists there. It is
+      #     unspecified which specific error will be raised; it typically could
+      #     be `Errno::EEXIST` or `Errno::ENOTDIR`.
       #
       def ensure_cache_subdir(path)
         # Source available in the toys-core gem

data/lib/toys/templates/clean.rb

@@ -152,7 +152,7 @@ module Toys
             process_globs(globs) do |path|
               until preserve_set.include?(path)
                 preserve_set << path
-                path = File.dirname(path)
+                path = ::File.dirname(path)
               end
             end
             preserve_set

data/lib/toys/version.rb

@@ -5,5 +5,5 @@ module Toys
   # Current version of the Toys command line executable.
   # @return [String]
   #
-  VERSION = "0.20.0"
+  VERSION = "0.21.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Daniel Azuma
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.21.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.20.0
+        version: 0.21.0
 description: Toys is a configurable command line tool. Write commands in Ruby using
   a simple DSL, and Toys will provide the command line executable and take care of
   all the details such as argument parsing, online help, and error reporting. Toys
@@ -123,10 +123,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.20.0/file.CHANGELOG.html
-  source_code_uri: https://github.com/dazuma/toys/tree/toys/v0.20.0/toys
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.21.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/dazuma/toys/tree/toys/v0.21.0/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.20.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.21.0
 rdoc_options: []
 require_paths:
 - lib
@@ -141,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A configurable command line tool
 test_files: []