toys-core 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd5a5658f6cecd3721768123c8125b9f8d0459f9f6812aede164c3207c30da3
-  data.tar.gz: 2576dc86d5ea42e516bc2b812809ad653b3c7302a3d30a9bc28be3490de749e8
+  metadata.gz: d4b8d67e21cd27582f76c3799f9d61127001c9b8a9f195615220873c8908ba45
+  data.tar.gz: d2987e582ec982852d1b3196c7634c60b4b113f63841c6a67e7d88b446fe4955
 SHA512:
-  metadata.gz: 6795ecfbda46c2259164fcef70089882c07c087e40cb378ee2726691fde2c3e89888bb13323dc974260ce79211f0ad603a67bb73de09319eca8c57a9fb3006cd
-  data.tar.gz: 9d2f4b8da60d7470d4bc3a0759841ed705d194025556bde61efa084ec7d5a8f400acece16ef289c41c3cc0c8e98229a34035cc075d59798626347c53621d90a4
+  metadata.gz: 4a27f6c2a6d66cb4281a4bc1bfd9a40870843f1aae249c6b11f140211263f34b99f3434013eae5ab9d13707153ca37c49d5301268c4b066da0bc573caacc601a
+  data.tar.gz: 0fb0966f58aa5c8b979d72f3f22770f1403a94992b9226e5b839f8b161d1a4481c7f504b6d432c2f2905d213c087c93ec459e3f97a3d4e81ac56b806cfa8f524

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

@@ -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
 
@@ -123,10 +123,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
@@ -184,7 +184,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
@@ -266,7 +266,7 @@ at the start of this guide uses this technique:
 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
@@ -289,7 +289,7 @@ paths to the CLI using {Toys::CLI#add_config_path}.
     cli = Toys::CLI.new
 
     # Load a file defining the functionality
-    cli.add_config_path("/usr/local/share/my_tool.rb)
+    cli.add_config_path("/usr/local/share/my_tool.rb")
 
     result = cli.run(*ARGV)
     exit(result)
@@ -375,9 +375,82 @@ 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:
+
+    # 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.
+
+    # 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
 
@@ -588,7 +661,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.
@@ -724,10 +797,6 @@ by other middleware (including middleware that replaces execution such as
 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.0"
   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.0
 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.0/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.0
 rdoc_options: []
 require_paths:
 - lib