toys-core 0.18.0 → 0.19.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd5a5658f6cecd3721768123c8125b9f8d0459f9f6812aede164c3207c30da3
-  data.tar.gz: 2576dc86d5ea42e516bc2b812809ad653b3c7302a3d30a9bc28be3490de749e8
+  metadata.gz: 815f546de5a0da65099cf1fdce70527fb42aafd3793bf8a99e35f63d77c4e66b
+  data.tar.gz: 79bd650fb1bdc5d04a2b1e1d235864e39313b4320518b9ac6296a8e1892aa8b1
 SHA512:
-  metadata.gz: 6795ecfbda46c2259164fcef70089882c07c087e40cb378ee2726691fde2c3e89888bb13323dc974260ce79211f0ad603a67bb73de09319eca8c57a9fb3006cd
-  data.tar.gz: 9d2f4b8da60d7470d4bc3a0759841ed705d194025556bde61efa084ec7d5a8f400acece16ef289c41c3cc0c8e98229a34035cc075d59798626347c53621d90a4
+  metadata.gz: e696b9c3921aec0c56796bdd7b93a09d056f6d46347a5936bbf6a0ce9bc7b2811f90d4b9553c54bdf69b62d74289e4608da98473e9b62e34f155accbf665f7a1
+  data.tar.gz: 675e01b73df268ceda5cfd5bd62f4a21b164c2fce0b37e88f3397bc12f76ba8baa4b2969df5d82901ffbb78440dd1156374cc6642792d81a4ec9c149a800148a

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release History
 
+### v0.19.1 / 2026-01-06
+
+* DOCS: Some formatting fixes in the user guide
+
+### 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

@@ -99,9 +99,9 @@ look familiar. Let's run it now, and experiment with passing flags to it.
 Notice that we did not create a `tool` block, but instead set up description,
 flags, and functionality directly in the configuration block. This configures
 the "root tool", i.e. what happens when you run the executable without passing
-a tool name to it. (In fact, it's legal to do this in Toys as well, by setting
-functionality at the "top level" of a `.toys.rb` file without including any
-`tool` block.)
+a tool name to it. (In fact, it's technically legal to do this in Toys as well,
+by setting functionality at the "top level" of a `.toys.rb` file without any
+`tool` block, although you probably won't actually want to do so.)
 
 ### Tool-based executables
 

data/docs/guide.md

@@ -59,8 +59,8 @@ An executable can customize many aspects of its behavior, such as the
 **logging output**, **error handling**, and even shell **tab completion**.
 
 Finally, Toys-Core can also be used to publish **Toys extensions**, collections
-of mixins, templates, and predefined tools that can be distributed as gems to
-enhance Toys for other users.
+of mixins, templates, and/or predefined tools that can be distributed as gems
+to enhance Toys for other users.
 
 ## Using the CLI object
 
@@ -80,27 +80,29 @@ to ensure that the `toys-core` gem is loaded, and `require "toys-core"`.
 
 Following is a simple "hello world" example using the CLI:
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    # Instantiate a CLI with the default options
-    cli = Toys::CLI.new
+# Instantiate a CLI with the default options
+cli = Toys::CLI.new
 
-    # Define the functionality
-    cli.add_config_block do
-      desc "My first executable!"
-      flag :whom, default: "world"
-      def run
-        puts "Hello, #{whom}!"
-      end
-    end
+# Define the functionality
+cli.add_config_block do
+  desc "My first executable!"
+  flag :whom, default: "world"
+  def run
+    puts "Hello, #{whom}!"
+  end
+end
 
-    # Run the CLI, passing the command line arguments
-    result = cli.run(*ARGV)
+# Run the CLI, passing the command line arguments
+result = cli.run(*ARGV)
 
-    # Handle the result code.
-    exit(result)
+# Handle the result code.
+exit(result)
+```
 
 ### CLI execution
 
@@ -123,10 +125,10 @@ When you call {Toys::CLI#run}, the CLI runs through three phases:
 When the CLI needs the definition of a tool, it queries the {Toys::Loader}. The
 loader object is configured with a set of tool _sources_ representing ways to
 define a tool. These sources may be blocks passed directly to the CLI, or
-directories and files loaded from the file system or even remote git
-repositories. When a tool is requested by name, the loader is responsible for
-locating the tool definition in those sources, and constructing the tool
-definition object, represented by {Toys::ToolDefinition}.
+directories and files loaded from the file system, from gems, or even from
+remote git repositories. When a tool is requested by name, the loader is
+responsible for locating the tool definition in those sources, and constructing
+the tool definition object, represented by {Toys::ToolDefinition}.
 
 One important property of the loader is that it is _lazy_. It queries tool
 sources only when it has reason to believe that a tool it is looking for may be
@@ -141,19 +143,21 @@ when a tool is requested does the block actually execute. Furthermore, if you
 have `tool` blocks inside the block, the loader will execute only those that
 are relevant to a tool it wants. Hence:
 
-    cli.add_config_block do
-      tool "foo" do
-        def run
-          puts "foo called"
-        end
-      end
+```ruby
+cli.add_config_block do
+  tool "foo" do
+    def run
+      puts "foo called"
+    end
+  end
 
-      tool "bar" do
-        def run
-          puts "bar called"
-        end
-      end
+  tool "bar" do
+    def run
+      puts "bar called"
     end
+  end
+end
+```
 
 If only `foo` is requested, the loader will execute the `tool "foo" do` block
 to get that tool definition, but will not execute the `tool "bar" do` block.
@@ -184,7 +188,7 @@ class, but it implements a few extra features and cleans up a few ambiguities.
 
 The execution phase involves:
 
- *  Running the tool's initializers, if any, in order.
+ *  Running the tool's initializers (if any) in order.
  *  Running the tool's middleware. Each middleware "wraps" the execution of
     subsequent middleware and the final tool execution, and has the opportunity
     to inject functionality before and after the main execution, or even to
@@ -245,28 +249,30 @@ If you are writing your own command line executable using Toys-Core, often the
 easiest way to define your tools is to use a block. The "hello world" example
 at the start of this guide uses this technique:
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    # Define the functionality by passing a block to the CLI
-    cli.add_config_block do
-      desc "My first executable!"
-      flag :whom, default: "world"
-      def run
-        puts "Hello, #{whom}!"
-      end
-    end
+# Define the functionality by passing a block to the CLI
+cli.add_config_block do
+  desc "My first executable!"
+  flag :whom, default: "world"
+  def run
+    puts "Hello, #{whom}!"
+  end
+end
 
-    result = cli.run(*ARGV)
-    exit(result)
+result = cli.run(*ARGV)
+exit(result)
+```
 
 The block simply contains Toys DSL syntax. The above example configures the
 "root tool", that is, the functionality of the program if you do not pass a
 tool name on the command line. You can also include "tool" blocks to define
-named tools, just as you would in a normal Toys file.
+named tools and subtools, just as you would in a normal Toys file.
 
 The reference documentation for {Toys::CLI#add_config_block} lists several
 options that can be passed in. `:context_directory` lets you select a context
@@ -282,25 +288,29 @@ messages and documentation, can also be set explicitly.
 If you want to define tools in separate files, you can do so and pass the file
 paths to the CLI using {Toys::CLI#add_config_path}.
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    # Load a file defining the functionality
-    cli.add_config_path("/usr/local/share/my_tool.rb)
+# Load a file defining the functionality
+cli.add_config_path("/usr/local/share/my_tool.rb")
 
-    result = cli.run(*ARGV)
-    exit(result)
+result = cli.run(*ARGV)
+exit(result)
+```
 
 The contents of `/usr/local/share/my_tool.rb` could then be:
 
-    desc "My first executable!"
-    flag :whom, default: "world"
-    def run
-      puts "Hello, #{whom}!"
-    end
+```ruby
+desc "My first executable!"
+flag :whom, default: "world"
+def run
+  puts "Hello, #{whom}!"
+end
+```
 
 You can point to a specific file to load, or to a Toys directory, whose
 contents will be loaded similarly to how a `.toys` directory is loaded.
@@ -329,45 +339,49 @@ priority level than previously added sources. Thus, any tools defined in the
 new source would be overridden by tools of the same name defined in previously
 added sources.
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    # Add a block defining a tool called "hello"
-    cli.add_config_block do
-      tool "hello" do
-        def run
-          puts "Hello from the first config block!"
-        end
-      end
+# Add a block defining a tool called "hello"
+cli.add_config_block do
+  tool "hello" do
+    def run
+      puts "Hello from the first config block!"
     end
+  end
+end
 
-    # Add a lower-priority block defining a tool with the same name
-    cli.add_config_block do
-      tool "hello" do
-        def run
-          puts "Hello from the second config block!"
-        end
-      end
+# Add a lower-priority block defining a tool with the same name
+cli.add_config_block do
+  tool "hello" do
+    def run
+      puts "Hello from the second config block!"
     end
+  end
+end
 
-    # Runs the tool defined in the first block
-    result = cli.run("hello")
-    exit(result)
+# Runs the tool defined in the first block
+result = cli.run("hello")
+exit(result)
+```
 
 When defining tool blocks or loading tools from files, you can also add the new
 source at the *front* of the priority list by passing an argument:
 
-    # Add tools with the highest priority
-    cli.add_config_block high_priority: true do
-      tool "hello" do
-        def run
-          puts "Hello from the second config block!"
-        end
-      end
+```ruby
+# Add tools with the highest priority
+cli.add_config_block high_priority: true do
+  tool "hello" do
+    def run
+      puts "Hello from the second config block!"
     end
+  end
+end
+```
 
 Priorities are used by the `toys` gem when loading tools from different
 directories. Any `.toys.rb` file or `.toys` directory is added to the CLI at
@@ -375,9 +389,86 @@ the front of the list, with the highest priority. Parent directories are added
 at subsequently lower priorities, and common directories such as the home
 directory are loaded at the lowest priority.
 
-### Changing built-in mixins and templates
+### Customizing built-in mixins and templates
 
-(TODO)
+Mixins and templates are two of the most useful mechanisms for sharing code and
+generating code for tools. In the main Toys gem, a certain set of mixins are
+built-in and can be referenced via symbols. For example, the *exec* mixin that
+provides facilities for running and controlling external processes, can be
+included using `include :exec`. In this section, we see how to define your own
+"built-in" mixins and templates that can be referenced via symbol.
+
+"Built-in" mixins and templates (and middleware, which we shall cover later)
+are provided via the {Toys::ModuleLookup} mechanism. ModuleLookup lets you
+select a directory for "standard" instances. By default, Toys-Core establishes
+the `toys/standard_mixins` directory in the gem as the standard directory for
+mixins, and whenever you reference a mixin by symbol, it is used to determine
+the name of a file to open and the name of a module to load. You can, however,
+change this directory and provide a different ModuleLookup when constructing a
+CLI object.
+
+Suppose, for example, you are writing a gem `my_tools` that uses Toys-Core, and
+you have a directory in your gem's `lib` called `my_tools/mixins` where you
+want your standard mixins to live. You could define mixins there:
+
+```ruby
+# This file is my_tools/mixins/foo_mixin.rb
+
+require "toys-core"
+
+module MyTools
+  module Mixins
+    module FooMixin
+      include Toys::Mixin
+
+      def foo
+        puts "Foo was called"
+      end
+    end
+  end
+end
+```
+
+Here is how you could configure a CLI to load standard mixins from that
+directory, and then use the above mixin.
+
+```ruby
+# This file is my_tools.rb
+
+require "toys-core"
+
+my_mixin_lookup = Toys::ModuleLookup.new.add_path("my_tools/mixins")
+cli = Toys::CLI.new(mixin_lookup: my_mixin_lookup)
+
+cli.add_config_block do
+  def run
+    include :foo_mixin
+    foo
+  end
+end
+```
+
+When you configure a ModuleLookup, you provide one or more paths, which are
+path prefixes that are used in a `require` statement. In the above example,
+we used the path `my_tools/mixins` for the ModuleLookup. Now when the CLI uses
+this ModuleLookup to find a mixin called `:foo_mixin`, it will attempt to
+`require "my_tools/mixins/foo_mixin"`, which matches the file where we defined
+our mixin.
+
+Notice also that `foo_mixin.rb` above defines FooMixin within a specific module
+hierarchy, corresponding to the file name `my_tools/mixins/foo_mixin.rb`
+according to standard Ruby naming conventions. The fully-qualified module name
+for the mixin must match this expected name, constructed from the path provided
+to the ModuleLookup and the name of the mixin. You can change the way this name
+mapping occurs, by providing the `:module_base` argument to the ModuleLookup
+constructor.
+
+Template lookup happens similarly. Toys-Core does not provide a set of default
+templates, but the Toys gem does; the `StandardCLI` class used by Toys sets the
+`:template_lookup` to point to the `toys/templates` directory in that gem's
+library. If you want to customize the default template lookup for your
+Toys-based library, you can similarly provide your own ModuleLookup. This will
+let you control how templates are resolved when specified by symbol.
 
 ## Customizing diagnostic output
 
@@ -395,22 +486,24 @@ Toys provides a Logger for each tool execution. Tools can access this Logger by
 calling the `logger` method, or by getting the `Toys::Context::Key::LOGGER`
 context object.
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    cli.add_config_block do
-      tool "hello" do
-        def run
-          logger.info "This log entry is displayed in verbose mode."
-        end
-      end
+cli.add_config_block do
+  tool "hello" do
+    def run
+      logger.info "This log entry is displayed in verbose mode."
     end
+  end
+end
 
-    result = cli.run(*ARGV)
-    exit(result)
+result = cli.run(*ARGV)
+exit(result)
+```
 
 #### Log level and verbosity
 
@@ -433,15 +526,19 @@ Passing `verbosity: 1` will set the starting verbosity to 1, meaning
 the invoker then provides an extra `--verbose` flag, the verbosity will further
 increase to 2, allowing `Logger::DEBUG` entries to appear.
 
-    # ...
-    result = cli.run(*ARGV, verbosity: 1)
-    exit(result)
+```ruby
+# ...
+result = cli.run(*ARGV, verbosity: 1)
+exit(result)
+```
 
 You can also modify the log level that verbosity 0 maps to by passing the
 `base_level` argument to the CLI constructor. The following causes verbosity 0
 to map to `Logger::INFO` rather than `Logger::WARN`.
 
-    cli = Toys::CLI.new(base_level: Logger::INFO)
+```ruby
+cli = Toys::CLI.new(base_level: Logger::INFO)
+```
 
 #### Customizing the logger
 
@@ -450,8 +547,10 @@ configures it to log to STDERR. If you want to change any of these settings,
 you can provide your own logger by passing a `logger` to the CLI constructor
 constructor.
 
-    my_logger = Logger.new("my_logfile.log")
-    cli = Toys::CLI.new(logger: my_logger)
+```ruby
+my_logger = Logger.new("my_logfile.log")
+cli = Toys::CLI.new(logger: my_logger)
+```
 
 A logger passed directly to the CLI is *global*. The CLI will attempt to use it
 for every execution, even if multiple executions are happening concurrently. In
@@ -461,10 +560,12 @@ your CLI might be run multiple times concurrently, we recommend instead passing
 a `logger_factory` to the CLI constructor. This is a Proc that will be invoked
 to create a new logger for each execution.
 
-    my_logger_factory = Proc.new do
-      Logger.new("my_logfile.log")
-    end
-    cli = Toys::CLI.new(logger_factory: my_logger_factory)
+```ruby
+my_logger_factory = Proc.new do
+  Logger.new("my_logfile.log")
+end
+cli = Toys::CLI.new(logger_factory: my_logger_factory)
+```
 
 #### StandardUI logging
 
@@ -474,8 +575,10 @@ formats log entries with the severity and timestamp using ANSI coloring.
 You can use this logger by passing {Toys::Utils::StandardUI#logger_factory} to
 the CLI constructor:
 
-    standard_ui = Toys::Utils::StandardUI.new
-    cli = Toys::CLI.new(logger_factory: standard_ui.logger_factory)
+```ruby
+standard_ui = Toys::Utils::StandardUI.new
+cli = Toys::CLI.new(logger_factory: standard_ui.logger_factory)
+```
 
 You can also customize the logger by subclassing StandardUI and overriding its
 methods or adjusting its parameters. In particular, you can alter the
@@ -501,15 +604,17 @@ final handling of an unhandled exception, such as displaying the error to the
 terminal, or reraising the exception. The handler should then return the
 desired result code for the execution.
 
-    my_error_handler = Proc.new |wrapped_error| do
-      # Propagate signals out and let the Ruby VM handle them.
-      raise wrapped_error.cause if wrapped_error.cause.is_a?(SignalException)
-      # Handle any other exception types by printing a message.
-      $stderr.puts "An error occurred. Please contact your administrator."
-      # Return the result code
-      255
-    end
-    cli = Toys::CLI.new(error_handler: my_error_handler)
+```ruby
+my_error_handler = Proc.new |wrapped_error| do
+  # Propagate signals out and let the Ruby VM handle them.
+  raise wrapped_error.cause if wrapped_error.cause.is_a?(SignalException)
+  # Handle any other exception types by printing a message.
+  $stderr.puts "An error occurred. Please contact your administrator."
+  # Return the result code
+  255
+end
+cli = Toys::CLI.new(error_handler: my_error_handler)
+```
 
 If you do not set an error handler, the exception is raised out of the
 {Toys::CLI#run} call. In the case of signals, the *cause*, represented by a
@@ -530,8 +635,10 @@ conventional result code of `128 + signo` (e.g. 130 for interrupts).
 You can use this error handler by passing
 {Toys::Utils::StandardUI#error_handler} to the CLI constructor:
 
-    standard_ui = Toys::Utils::StandardUI.new
-    cli = Toys::CLI.new(error_handler: standard_ui.error_handler)
+```ruby
+standard_ui = Toys::Utils::StandardUI.new
+cli = Toys::CLI.new(error_handler: standard_ui.error_handler)
+```
 
 You can also customize the error handler by subclassing StandardUI and
 overriding its methods. In particular, you can alter what is displayed in
@@ -588,7 +695,7 @@ replace normal tool execution.
 
 Middleware is normally configured as part of the CLI object. Each CLI includes
 an ordered list, a _stack_, of middleware specifications, each represented by
-{Toys::Middleware::Spec}. A middleware spec can be a specific middleware
+{Toys::Middleware::Spec}. A middleware spec can reference a specific middleware
 object, a class to instantiate, or a name that can be looked up from a
 directory of middleware class files. You can pass an array of these specs to a
 CLI object when you instantiate it.
@@ -597,12 +704,14 @@ A useful example can be seen in the default Toys CLI behavior. If you do not
 provide a middleware stack when instantiating {Toys::CLI}, the class uses a
 default stack that looks approximately like this:
 
-    [
-      Toys::Middleware.spec(:set_default_descriptions),
-      Toys::Middleware.spec(:show_help, help_flags: true, fallback_execution: true),
-      Toys::Middleware.spec(:handle_usage_errors),
-      Toys::Middleware.spec(:add_verbosity_flags),
-    ]
+```ruby
+[
+  Toys::Middleware.spec(:set_default_descriptions),
+  Toys::Middleware.spec(:show_help, help_flags: true, fallback_execution: true),
+  Toys::Middleware.spec(:handle_usage_errors),
+  Toys::Middleware.spec(:add_verbosity_flags),
+]
+```
 
 Each of the names, e.g. `:set_default_descriptions`, is the name of a Ruby
 file in the `toys-core` gem under `toys/standard_middleware`. You can configure
@@ -659,51 +768,53 @@ following is a simple middleware that adds the `--show-timing` flag to every
 tool. When the flag is set, the middleware displays how long the tool took to
 execute.
 
-    class TimingMiddleware
-      # This is a context key that will be used to store the "--show-timing"
-      # flag state. We can use `Object.new` to ensure that the key is unique
-      # across other middlewares and tool definitions.
-      KEY = Object.new.freeze
-
-      # This method intercepts tool configuration. We use it to add a flag that
-      # enables timing display.
-      def config(tool, _loader)
-        # Add a flag to control this functionality. Suppress collisions, i.e.
-        # just silently do nothing if the tool has already added a flag called
-        # "--show-timing".
-        tool.add_flag(KEY, "--show-timing", report_collisions: false)
-
-        # Calling yield passes control to the rest of the middleware stack.
-        # Normally you should call yield, to ensure that the remaining
-        # middleware can run. If you omit this, no additional middleware will
-        # be able to run tool configuration. Note you can also perform
-        # additional processing after the yield call, i.e. after the rest of
-        # the middleware stack has run.
-        yield
-      end
-
-      # This method intercepts tool execution. We use it to collect timing
-      # information, and display it if the flag has been provided in the
-      # command line arguments.
-      def run(context)
-        # Read monotonic time at the start of execution.
-        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-        # Call yield to run the rest of the middleware stack, including the
-        # actual tool execution. If you omit this, you will prevent the rest of
-        # the middleware stack, AND the actual tool execution, from running.
-        # So you could omit the yield call if your goal is to replace tool
-        # execution with your own code.
-        yield
-
-        # Read monotonic time again after execution.
-        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-        # Display the elapsed time, if the tool was passed the "--show-timing"
-        # flag.
-        puts "Tool took #{end_time - start_time} secs" if context[KEY]
-      end
-    end
+```ruby
+class TimingMiddleware
+  # This is a context key that will be used to store the "--show-timing"
+  # flag state. We can use `Object.new` to ensure that the key is unique
+  # across other middlewares and tool definitions.
+  KEY = Object.new.freeze
+
+  # This method intercepts tool configuration. We use it to add a flag that
+  # enables timing display.
+  def config(tool, _loader)
+    # Add a flag to control this functionality. Suppress collisions, i.e.
+    # just silently do nothing if the tool has already added a flag called
+    # "--show-timing".
+    tool.add_flag(KEY, "--show-timing", report_collisions: false)
+
+    # Calling yield passes control to the rest of the middleware stack.
+    # Normally you should call yield, to ensure that the remaining
+    # middleware can run. If you omit this, no additional middleware will
+    # be able to run tool configuration. Note you can also perform
+    # additional processing after the yield call, i.e. after the rest of
+    # the middleware stack has run.
+    yield
+  end
+
+  # This method intercepts tool execution. We use it to collect timing
+  # information, and display it if the flag has been provided in the
+  # command line arguments.
+  def run(context)
+    # Read monotonic time at the start of execution.
+    start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Call yield to run the rest of the middleware stack, including the
+    # actual tool execution. If you omit this, you will prevent the rest of
+    # the middleware stack, AND the actual tool execution, from running.
+    # So you could omit the yield call if your goal is to replace tool
+    # execution with your own code.
+    yield
+
+    # Read monotonic time again after execution.
+    end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Display the elapsed time, if the tool was passed the "--show-timing"
+    # flag.
+    puts "Tool took #{end_time - start_time} secs" if context[KEY]
+  end
+end
+```
 
 We can now insert our middleware into the stack when we create a CLI. Here
 we'll take that "default" stack we saw earlier and add our timing middleware at
@@ -712,22 +823,20 @@ other middleware, and thus its timing measurement includes the latency incurred
 by other middleware (including middleware that replaces execution such as
 `:show_help`).
 
-    my_middleware_stack = [
-      Toys::Middleware.spec(TimingMiddleware),
-      Toys::Middleware.spec(:set_default_descriptions),
-      Toys::Middleware.spec(:show_help, help_flags: true, fallback_execution: true),
-      Toys::Middleware.spec(:handle_usage_errors),
-      Toys::Middleware.spec(:add_verbosity_flags),
-    ]
-    cli = Toys::CLI.new(middleware_stack: my_middleware_stack)
+```ruby
+my_middleware_stack = [
+  Toys::Middleware.spec(TimingMiddleware),
+  Toys::Middleware.spec(:set_default_descriptions),
+  Toys::Middleware.spec(:show_help, help_flags: true, fallback_execution: true),
+  Toys::Middleware.spec(:handle_usage_errors),
+  Toys::Middleware.spec(:add_verbosity_flags),
+]
+cli = Toys::CLI.new(middleware_stack: my_middleware_stack)
+```
 
 Now, every tool run by this CLI wil have the `--show-timing` flag and
 associated functionality.
 
-#### Changing built-in middleware
-
-(TODO)
-
 ## Shell and command line integration
 
 (TODO)

data/lib/toys/cli.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 module Toys
   ##
   # A Toys-based CLI.
@@ -125,7 +127,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
@@ -562,7 +564,6 @@ module Toys
       # @return [Proc]
       #
       def default_logger_factory
-        require "logger"
         proc do
           logger = ::Logger.new($stderr)
           logger.level = ::Logger::WARN

data/lib/toys/core.rb

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

data/lib/toys/standard_mixins/exec.rb

@@ -817,7 +817,7 @@ module Toys
       def self._setup_clean_process(cmd)
         raise ::ArgumentError, "Toys process is unknown" unless ::Toys.executable_path
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-        cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
+        cmd = [::RbConfig.ruby, ::Toys.executable_path] + cmd
         if defined?(::Bundler)
           if ::Bundler.respond_to?(:with_unbundled_env)
             ::Bundler.with_unbundled_env { yield(cmd) }

data/lib/toys/utils/exec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 module Toys
   module Utils
     ##
@@ -263,7 +265,6 @@ module Toys
       #
       def initialize(**opts, &block)
         require "rbconfig"
-        require "logger"
         require "stringio"
         @default_opts = Opts.new(&block).add(opts)
       end

data/lib/toys/utils/gems.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "monitor"
 
 module Toys
@@ -193,9 +194,7 @@ module Toys
         end
       end
 
-      ##
       # @private
-      #
       def self.find_gemfile(search_dir, gemfile_names: nil)
         gemfile_names ||= DEFAULT_GEMFILE_NAMES
         Array(gemfile_names).each do |file|
@@ -207,13 +206,18 @@ module Toys
 
       @global_mutex = ::Monitor.new
 
-      ##
       # @private
-      #
       def self.synchronize(&block)
         @global_mutex.synchronize(&block)
       end
 
+      # @private
+      def self.delete_at_exit(path)
+        # Call this from a class method so it doesn't hold onto the instance
+        # for the duration of the Ruby process
+        at_exit { ::FileUtils.rm_f(path) }
+      end
+
       private
 
       def terminal
@@ -344,7 +348,7 @@ module Toys
         elsif ::RUBY_VERSION < "3"
           [">= 2.2", "< 2.5"]
         else
-          ["~> 2.2"]
+          [">= 2.2", "< 5"]
         end
       end
 
@@ -421,11 +425,10 @@ module Toys
       end
 
       def delete_modified_gemfile(modified_gemfile_path)
-        # rubocop:disable Lint/NonAtomicFileOperation
-        ::File.delete(modified_gemfile_path) if ::File.exist?(modified_gemfile_path)
+        ::FileUtils.rm_f(modified_gemfile_path)
         modified_lockfile_path = find_lockfile_path(modified_gemfile_path)
-        ::File.delete(modified_lockfile_path) if ::File.exist?(modified_lockfile_path)
-        # rubocop:enable Lint/NonAtomicFileOperation
+        ::FileUtils.rm_f(modified_lockfile_path)
+        Gems.delete_at_exit(modified_lockfile_path)
       end
 
       def restore_toys_libs

data/lib/toys/utils/standard_ui.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 module Toys
   module Utils
     ##
@@ -28,7 +30,6 @@ module Toys
       #     terminal output. Default is `$stderr`.
       #
       def initialize(output: nil)
-        require "logger"
         require "toys/utils/terminal"
         @terminal = output || $stderr
         @terminal = Terminal.new(output: @terminal) unless @terminal.is_a?(Terminal)

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.1
 platform: ruby
 authors:
 - Daniel Azuma
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
 email:
@@ -78,10 +92,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.18.0/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.19.1/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.18.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.19.1
 rdoc_options: []
 require_paths:
 - lib
@@ -96,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Framework for creating command line executables
 test_files: []