toys 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1219a7aaa39a426ad3df4a1206620094d8f23a0080a6f021fdfc008b3bac57e0
-  data.tar.gz: 481a4b1ff80f776d04093a74f3e0b0b3946148c584793a5c8258aa9681f11bf8
+  metadata.gz: 5866812d1c711bf0870e0608fa2f8758de52f659bcda167d13590f5d6ad9d5c1
+  data.tar.gz: b68fc387ce5a624101b384e1c62b1f1229936a8dd2474bc61b15e58fb578917f
 SHA512:
-  metadata.gz: 545e3b289191f13b001e5ba0c1e36c23d69b81e533413b3680b672daf9f99a05e944721abc6fcb82a5456588969451ac14f44b833ae610b7eef0abd2de6a805f
-  data.tar.gz: '0480a435d1730c3ea06148a7f8d991454b7c5ee96e8732eb30291a0a14637650574ce53ad07e051b6d324193396369e351bf9ee1a6d7ab814c9be5c16f6be798'
+  metadata.gz: a0637d7bad711309be05fbc443127fb5e6545db4e20ca4d60eb466fba971ed7c5490d2c81d5d07e0b4c059305e0bcaeb5cd03c68048487298756c2bbdfe5173e
+  data.tar.gz: d0f8a09727f39aeec544e78334db551bf8c94ed0b681eb2201de8445e12341fd2249e5be7748ba4e905c0ade5a3f497c468c5b1487cd3429d8b89502d5941f71

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### v0.19.0 / 2025-12-22
+
+Compatibility update for Ruby 4.0, including:
+
+* The logger gem is now an explicit dependency
+* Calling a tool via exec no longer disables rubygems
+* Bundler integration does a better job of cleaning up temporary lockfiles under bundler 4
+
+Additionally, this release includes updates to readmes and users guides
+
 ### v0.18.0 / 2025-12-05
 
 * ADDED: The load_gem directive can now take version requirements as positional arguments

data/README.md

@@ -9,10 +9,10 @@ users who want to write and organize scripts to automate their workflows. It
 can also be used as a replacement for Rake, providing a more natural command
 line interface for your project's build tasks.
 
-Unlike most command line frameworks, Toys is *not primarily* designed to help
-you build and ship a custom command line executable written in Ruby. However,
-you *can* use it in that way with the "toys-core" API, available as a separate
-gem. For more info on using toys-core, see
+Unlike most command line frameworks, Toys is *not primarily* designed for
+building and shipping a custom command line executable written in Ruby.
+However, you *can* use it in that way with the "toys-core" API, available as a
+separate gem. For more info on using toys-core, see
 [its documentation](https://dazuma.github.io/toys/gems/toys-core/latest).
 
 ## Introductory tutorial

data/core-docs/toys/cli.rb

@@ -125,7 +125,7 @@ module Toys
     #     Optional. If not provided, defaults to the set of standard template
     #     classes provided by toys core, as defined by
     #     {Toys::CLI.default_template_lookup}. If you explicitly want no
-    #     standard tenokates, pass an empty instance of {Toys::ModuleLookup}.
+    #     standard templates, pass an empty instance of {Toys::ModuleLookup}.
     #
     # @param config_dir_name [String] A directory with this name that appears
     #     in the loader path, is treated as a configuration directory whose

data/core-docs/toys/core.rb

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

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

@@ -179,7 +179,22 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      # @private
+      def self.find_gemfile(search_dir, gemfile_names: nil)
+        # Source available in the toys-core gem
+      end
+
       @global_mutex = ::Monitor.new
+
+      # @private
+      def self.synchronize(&block)
+        # Source available in the toys-core gem
+      end
+
+      # @private
+      def self.delete_at_exit(path)
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/docs/guide.md

@@ -13,10 +13,10 @@ users who want to write and organize scripts to automate their workflows. It
 can also be used as a replacement for Rake, providing a more natural command
 line interface for your project's build tasks.
 
-Unlike most command line frameworks, Toys is *not primarily* designed to help
-you build and ship a custom command line executable written in Ruby. Rather, it
-provides a single executable called `toys` whose functionality you can define
-by writing configuration files. (You can, however, build your own custom
+Unlike most command line frameworks, Toys is *not primarily* designed for
+building and shipping a custom command line executable written in Ruby. Rather,
+it provides a single executable called `toys` whose functionality you can
+define by writing configuration files. (You can, however, build your own custom
 command line executable using the related **toys-core** library.)
 
 If this is your first time using Toys, we recommend starting with the
@@ -122,7 +122,7 @@ This displays the **online help screen** for the `system` namespace, which
 includes a list of all its subtools and what they do.
 
 It is also legitimate for the tool name to be empty. This invokes the **root
-tool**, the toplevel namespace:
+tool**, the top level namespace:
 
     $ toys
 
@@ -133,7 +133,7 @@ One last example:
 
     $ toys frodo
 
-If there is no tool called `frodo` in the toplevel namespace, then once again,
+If there is no tool called `frodo` in the top level namespace, then once again,
 `frodo` is interpreted as an argument to the root tool. The root tool responds
 by printing an error message that the `frodo` tool does not exist.
 
@@ -145,7 +145,7 @@ options for a tool.
 Each tool recognizes a specific set of flags. If you pass an unknown flag to a
 tool, the tool will generally display an error message.
 
-Toys follows the typical unix conventions for flags, specifically those covered
+Toys follows the typical Unix conventions for flags, specifically those covered
 by Ruby's OptionParser library. You can provide short (single-character) flags
 with a single hyphen, or long flags with a double hyphen. Some flags can also
 take **values**. Following are a few examples.
@@ -1366,7 +1366,7 @@ When Toys runs, it looks for tools in a **search path**. Specifically:
 3.  It looks in a list of *global directories*, specified in the environment
     variable `TOYS_PATH`. This variable can contain a colon-delimited list of
     directory paths. If the variable is not set, the current user's *home
-    directory*, and the system configuration directory (`/etc` on unix systems)
+    directory*, and the system configuration directory (`/etc` on Unix systems)
     are used by default. Toys does *not* search parents of global directories.
 
 It uses the *first* implementation that it finds for the requested tool. For
@@ -1608,8 +1608,8 @@ set the gem's `"toys_dir"` metadata to a different directory name. If this
 metadata is set, `load_gem` will use it as the toys top level directory for
 that gem.
 
-Additionally, you can pass a top level directory name in the `load_gem`
-directive itself. This can be useful if a gem has multiple toys directories:
+You can also specify a different toys top level directory in the `load_gem`
+directive. This can be useful if a gem has multiple toys directories:
 
     # .toys.rb
     load_gem "my-tools", toys_dir: "uncommon-tools"
@@ -1624,6 +1624,13 @@ files can be used in the tools' implementations. When `load_gem` is run, the
 gem is activated so its library directory is made available in the require
 path. This may be simpler than using `.lib` directories as described later.
 
+By default, the `load_gem` mechanism expects toys files to live inside the
+`toys` top level directory of the gem. Although this is not recommended, if you
+need to change this default, you can set the gem's `"toys_dir"` metadata to a
+different directory name. If this metadata is set, `load_gem` will use it as
+the toys top level directory for that gem. In either case, the caller of the
+`load_gem` directive can still override it by passing the `:toys_dir` argument.
+
 ## The execution environment
 
 This section describes the context and resources available to your tool when it
@@ -2672,14 +2679,14 @@ focus on a few tests.
 ## Using third-party gems
 
 The toys executable itself uses only two gems: **toys** and **toys-core**. It
-has no other gem dependencies. However, the Ruby community has developed many
-resources for building command line tools, including a variety of gems that
-provide alternate command line parsing, control of the ANSI terminal, formatted
-output such as trees and tables, and effects such as hidden input, progress
-bars, various ways to spawn and control subprocesses, and so forth. You may
-find some of these gems useful when writing your tools. Additionally, if you
-are using Toys for your project's build scripts, it might be necessary to
-install your bundle when running some tools.
+has no other gem dependencies besides standard gems bundled with Ruby. However,
+the Ruby community has developed many resources for building command line
+tools, including a variety of gems that provide alternate command line parsing,
+control of the ANSI terminal, formatted output such as trees and tables, and
+effects such as hidden input, progress bars, various ways to spawn and control
+subprocesses, and so forth. You may find some of these gems useful when writing
+your tools. Additionally, if you are using Toys for your project's build
+scripts, it might be necessary to install your bundle when running some tools.
 
 This section describes how to manage and use external gems with Toys. Note that
 running Toys with `bundle exec` is generally *not* recommended. We'll discuss
@@ -3054,7 +3061,7 @@ how to use Toys for some of the things traditionally done with Rake.
 Although Toys and Rake serve many of the same use cases, they have very
 different design goals, and it is useful to understand the differences.
 
-Rake's design is based on the classic "make" tool often provided in unix
+Rake's design is based on the classic "make" tool often provided in Unix
 development environments. This design focuses on *targets* and *dependencies*,
 and is meant for a world where you invoke an external compiler tool whenever
 changes are made to an individual source file or any of its dependencies. This
@@ -3075,10 +3082,10 @@ syntax for describing targets and dependencies, since we generally don't have
 them in Ruby programs. Instead, it is optimized for writing imperative tools.
 
 For example, Rake provides a primitive mechanism for passing arguments to a
-task, but it is clumsy and quite different from most unix programs. However, to
+task, but it is clumsy and quite different from most Unix programs. However, to
 do otherwise would clash with Rake's design goal of treating tasks as targets
 and dependencies. Toys does not have those design goals, so it is able to
-embrace the familiar unix conventions for command line arguments.
+embrace the familiar Unix conventions for command line arguments.
 
 Toys actually borrows some of its design from the "mix" build tool used for
 Elixir and Erlang programs. Unlike C, the Erlang and Elixir compilers do their
@@ -3559,7 +3566,7 @@ simplified excerpt from the implementation that tool:
 
 ### Requiring exact flag matches
 
-By default, tools will recognized "shortened" forms of long flags. For example,
+By default, tools will recognize "shortened" forms of long flags. For example,
 most suppose you are defining a tool with long flags:
 
     tool "my-tool" do
@@ -3645,8 +3652,9 @@ following takes place:
 
 1.  Ruby will terminate the tool's `run` method by raising a `SignalException`
     Any `ensure` blocks in the tool will be called.
-2.  Toys will call the signal handler, either a method or a block. If the
-    handler takes an argument, Toys will pass it the `SignalException` object.
+2.  Toys will rescue the `SignalException` and call the signal handler, either
+    a method or a block. If the handler takes an argument, Toys will pass it
+    the `SignalException` object.
 3.  The signal handler is then responsible for tool execution from that
     point. It can terminate execution by returning or calling `exit`, or it can
     restart or resume processing (perhaps by calling the `run` method again).
@@ -3902,7 +3910,7 @@ overriding file under `.toys/test/.data`.
 
 ### The context directory
 
-The **context directory** for a tool is the directory containing the toplevel
+The **context directory** for a tool is the directory containing the top level
 `.toys.rb` file or the `.toys` directory within which the tool is defined. It
 is sometimes useful for tools that expect to be run from a specific working
 directory.
@@ -3942,7 +3950,7 @@ directory containing the `.toys.rb` file, i.e. the `my-project` directory.)
 
     tool "list-tests" do
       def run
-        Dir.chdir context_directory do
+        Dir.chdir(context_directory) do
           puts Dir.glob("test/**/*.rb").join("\n")
         end
       end
@@ -4008,8 +4016,8 @@ context directory to `my-repo/gem1`. Here's what that could look like:
     # .toys.rb content
 
     require "pathname"
-    base_dir = Pathname.new context_directory
-    cur_dir = Pathname.new Dir.getwd
+    base_dir = Pathname.new(context_directory)
+    cur_dir = Pathname.new(Dir.getwd)
 
     # The gem name is the first segment of the relative path from the context
     # directory to the current directory.
@@ -4020,7 +4028,7 @@ context directory to `my-repo/gem1`. Here's what that could look like:
     if gem_name && gem_name != "." && gem_name != ".."
 
       # Now set the context directory to the gem directory.
-      set_context_directory base_dir.join(gem_name).to_s
+      set_context_directory(base_dir.join(gem_name).to_s)
 
       # Define the build tools. Each of these uses the custom context directory
       # set above, and thus runs for the selected gem.
@@ -4065,8 +4073,8 @@ To update Toys to the latest released version, run:
 This will determine the latest version from Rubygems, and update your Toys
 installation if it is not already current.
 
-Normall it asks you for confirmation before downloading. To disable interactive
-confirmation, pass the `--yes` flag.
+Normally it asks you for confirmation before downloading. To disable
+interactive confirmation, pass the `--yes` flag.
 
 A similar effect can of course be obtained by running `gem install toys`.
 
@@ -4126,6 +4134,13 @@ To display general information and a list of tools, run:
 
     toys system git-cache --help
 
+By default, files in the Git Cache are read-only. This is to prevent code that
+uses the cache from modifying those files in place and thus causing problems
+for other users of the cache. However, some environments that auto-delete cache
+directories might have a problem with this behavior, so the Git Cache supports
+an environment variable `TOYS_GIT_CACHE_WRITABLE` which, if set to a nonempty
+value, causes cache files to be writable.
+
 ## Writing your own CLI using Toys
 
 Although Toys is not primarily designed to help you write a custom command-line

data/lib/toys/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Daniel Azuma
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0
+        version: 0.19.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0
+        version: 0.19.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
@@ -120,10 +120,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.18.0/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.19.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.18.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.19.0
 rdoc_options: []
 require_paths:
 - lib