toys 0.23.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee5fe663d934949887ff7ce01289453e7b59efcc553331e2efb8a8ae949b626b
-  data.tar.gz: c34a38d893789bdb14fc159f211ac83b09a39b2d897601c961755876be2b6d28
+  metadata.gz: 1a607f5cce147c21bdd90781026767b310054e69bbbff8c9a1103fdbd3d77b6b
+  data.tar.gz: ab0b2ff711816c75e2a50206e93ae19673c21f88618a3332e0642387b7baa6f3
 SHA512:
-  metadata.gz: 0fd0c5c2edfe80ede91db110a513bfe176766b4d3c8a75e378721296b8fe4c7c5681e07695fa249f9efede159ffb9feff43524d3ad085f98ca7498af9433c3d1
-  data.tar.gz: 5345ecacee610f36dd439f7adf8b1118a1cc0ecb858f19a5f3c938a5e86a33fb19be94fff5173e3170d1bac6b8ed4309fc54192f5542573e15a7109ddeaba9e2
+  metadata.gz: a99af47c6944f33da01db83f1aeb9d77021424cf2ef3b739c7f34caeaffac8dfbcfa25fff7e6ce73d742c4d4d44cabd1ab2b6521d3b64aeaf7d9adb5aeff0ffa
+  data.tar.gz: 3d853bf3958d6894a5388830c5f4c2595f3631a13280741d93cc70410d43374c690273a23314bd1758b558a523b0d3d4372446f3054a2d616cf9b78db0d526bd

data/.yardopts

@@ -1,7 +1,6 @@
 --no-private
 --title=Toys
 --markup=markdown
---markup-provider redcarpet
 --main=README.md
 ./core-docs/toys/**/*.rb
 ./core-docs/toys-core.rb

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+### v0.24.0 / 2026-09-11
+
+* Feature: The `toys do` builtin provides an `--on-missing-gem` flag that governs how the `--gem` flag handles gems that are not installed.
+* BREAKING CHANGE: Removed deprecated `gem_version:` argument from `:rspec` and `:minitest` templates.
+
 ### v0.23.0 / 2026-09-09
 
 This is a major release, with several new features. It also includes a significant refactor of some of the underlying layers, which should be mostly invisible. It is a release candidate for the upcoming version 1.0.

data/builtins/do.rb

@@ -17,16 +17,10 @@ long_desc \
   "The --delim flag must appear first before the tools to run. Any flags that appear later in" \
     " the command line will be passed to the tools themselves.",
   "",
-  "You may also make additional tools available to the tools you run, by passing the --gem," \
-    " --git, and --path flags. Each adds a source of tools, which takes priority over the" \
-    " tools that would otherwise be found. The three flags may be repeated and interleaved," \
-    " and the source added by the leftmost flag takes priority over the sources added by the" \
-    " flags to its right. For example:",
-  ["    toys do --gem=my-tools --git=https://github.com/dazuma/example deploy --migrate"],
-  "Here, a tool defined by both sources is taken from the gem. See the descriptions of the" \
-    " individual flags below for the syntax of their values. Note that the commas within those" \
-    " values are part of the flag value, and are unrelated to the delimiter that separates the" \
-    " tools to run."
+  "You may also load tools from additional sources, by passing the --gem, --git, and --path" \
+    " flags. Any number of these flags can be added; each adds a source of tools, with earlier" \
+    " flags taking priority over later. For example:",
+  ["    toys do --gem=my-tools --git=https://github.com/dazuma/example deploy --migrate"]
 
 flag :delim do
   flags "-d", "--delim=VALUE"
@@ -49,7 +43,9 @@ flag :sources do
   default []
   desc "Make the tools from the given gem available"
   long_desc \
-    "Adds the tools from the given gem, prompting to install the gem if it is not present.",
+    "Adds the tools from the given gem. If the specified gem is not currently installed," \
+      " follows the policy set by the --on-missing-gem flag, which is normally to prompt" \
+      " whether to install.",
     "",
     "The value is the gem name, optionally followed by any number of version requirements," \
       " all separated by commas. Whitespace surrounding each element is ignored. The version" \
@@ -67,21 +63,18 @@ flag :sources do
       " if it is not already there.",
     "",
     "The value is the git remote (i.e. the repository URL or path), optionally followed by any" \
-      " number of \"key=value\" elements, all separated by commas. Whitespace surrounding each" \
-      " element, and surrounding each equals sign, is ignored. For example:",
+      " number of \"key=value\" elements, all separated by commas. There is no way to escape" \
+      " a comma appearing within the value. Whitespace surrounding each element, and surrounding" \
+      " each equals sign, is ignored. For example:",
     ["    --git=\"https://github.com/dazuma/example, path=toys, commit=main\""],
-    "The recognized keys are:",
-    ["    path     The file or directory within the repository to load. By default, the"],
-    ["             entire repository is loaded."],
-    ["    commit   The SHA, tag, or branch to load. By default, the repository head is used."],
-    ["    update   Whether to refresh a previously cached repository. Pass \"true\" or \"false\","],
-    ["             or a number of seconds, to refresh only if the cache is at least that old."],
-    ["             The default is \"false\"."],
-    "Unlike --gem, which takes its elements positionally, the elements here are named, because" \
-      " a git source has three independent optional fields and a positional syntax could not" \
-      " express, for example, a path with no commit.",
     "",
-    "There is no way to escape a comma appearing within the value."
+    "The recognized keys are:",
+    "* \"path\" : The file or directory within the repository to load. By default, the entire" \
+      " repository is loaded.",
+    "* \"commit\" : The SHA, tag, or branch to load. By default, the repository head is used.",
+    "* \"update\" : Whether to refresh a previously cached repository. Pass \"true\" or" \
+      " \"false\", or a number of seconds, to refresh only if the cache is at least that old." \
+      " The default is \"false\"."
 end
 
 flag :sources do
@@ -96,6 +89,22 @@ flag :sources do
     ["    --path=/path/to/my-tools"]
 end
 
+flag :on_missing_gem do
+  flags "--on-missing-gem=WHAT"
+  accept [:confirm, :install, :error]
+  complete_values ["confirm", "install", "error"]
+  desc "Specify what to do if a gem is not installed"
+  long_desc \
+    "Specifies what to do if a gem referenced by the --gem flag is not installed." \
+      " Possible values are:",
+    "* \"confirm\" : Prompt for what to do.",
+    "* \"install\" : Do not prompt, but just install the needed gem.",
+    "* \"error\" : Display an error and abort.",
+    "",
+    "Defaults to the existing CLI configuration, normally \"confirm\". Note this does not affect" \
+      " any other gem references such as via the \"gem\" or \"load_gem\" directives."
+end
+
 remaining_args :commands do
   complete do |context|
     commands = context.arg_parser.data[:commands]
@@ -119,24 +128,19 @@ def run
 end
 
 # Returns the CLI used to run the requested tools. Normally this is simply the
-# current CLI, but if any sources were requested, we need a new CLI because
-# sources cannot be added to a CLI that has already started loading tools. The
-# new CLI copies the current sources and adds the requested ones on top of
-# them. The requested sources are added in reverse order so that the first flag
-# on the command line ends up with the highest priority.
+# current CLI, but if any sources were requested, we need a new CLI with those
+# sources added. Any new sources are added in reverse order so that the first
+# flag on the command line ends up with the highest priority.
 #
 # All the flag values are parsed up front, in command line order, so that a
 # malformed value is reported before any source is added, and is reported
-# against the first offending flag rather than the last.
-#
-# All added sources are then proactively resolved and failures reported.
+# against the first offending flag rather than the last. All added sources are
+# then proactively resolved and failures reported.
 def build_cli
   specs = sources.map { |kind, value| parse_source_request(kind, value) }
   return cli if specs.empty?
-  require "toys/utils/gems" if specs.any? { |spec| spec.is_a?(::Toys::SourceSpec::Gem) }
-  tool_cli = cli.child(copy_sources: true) do |child_cli|
-    specs.reverse_each { |spec| child_cli.add_source(spec, high_priority: true) }
-  end
+  tool_cli = cli.child(copy_sources: true)
+  specs.reverse_each { |spec| tool_cli.add_source(spec, high_priority: true) }
   begin
     tool_cli.loader.resolve_sources
   rescue ::Toys::ToolSourceError => e
@@ -174,7 +178,7 @@ def parse_gem_request(gem_request)
     logger.fatal("Invalid version requirement for gem #{gem_name.inspect}: #{e.message}")
     exit(1)
   end
-  ::Toys::SourceSpec.gem(gem_name, version: gem_version)
+  ::Toys::SourceSpec.gem(gem_name, version: gem_version, on_missing: on_missing_gem)
 end
 
 # Splits a --git flag value into the git remote and the options that follow it,

data/core-docs/toys/core.rb

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

data/core-docs/toys/dsl/tool.rb

@@ -308,38 +308,6 @@ module Toys
         # Source available in the toys-core gem
       end
 
-      ##
-      # Create an alias, representing an "alternate name" for a tool.
-      #
-      # Note: This is functionally equivalent to creating a tool with the
-      # `:delegate_relative` option. As such, `alias_tool` is considered
-      # deprecated.
-      #
-      # ### Example
-      #
-      # This example defines a tool and an alias pointing to it. Both the tool
-      # name `test` and the alias `t` will then refer to the same tool.
-      #
-      #     tool "test" do
-      #       def run
-      #         puts "Running tests..."
-      #       end
-      #     end
-      #     alias_tool "t", "test"
-      #     # Note: the following is preferred over alias_tool:
-      #     # tool "t", delegate_relative: "test"
-      #
-      # @param word [String] The name of the alias
-      # @param target [String,Array<String>] Relative path to the target of the
-      #     alias. This path may be given as an array of strings, or a single
-      #     string possibly delimited by path separators.
-      # @return [self]
-      # @deprecated Use {#tool} and pass `:delegate_relative` instead
-      #
-      def alias_tool(word, target)
-        # Source available in the toys-core gem
-      end
-
       ##
       # Causes the current tool to delegate to another tool, specified by the
       # full tool name. When run, it simply invokes the target tool with the
@@ -458,6 +426,18 @@ module Toys
       #     Context directory paths should generally be absolute. Relative
       #     paths will be converted to absolute, using the current working
       #     directory at the time of loading.
+      # @param on_missing [:confirm,:error,:install] What to do if the
+      #     requested gem is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     Defaults to the setting in the {Toys::Utils::Gems} utility used to
+      #     activate the gem (usually `:confirm`).
+      # @param default_confirm [boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to the setting in the
+      #     {Toys::Utils::Gems} utility used to activate the gem (usually true).
       # @param as [String] Load into the given tool/namespace, relative to the
       #     current namespace. If omitted, tools will be loaded into the
       #     current namespace.
@@ -469,6 +449,8 @@ module Toys
                    path: nil,
                    toys_dir: nil,
                    context_directory: nil,
+                   on_missing: nil,
+                   default_confirm: nil,
                    as: nil)
         # Source available in the toys-core gem
       end

data/core-docs/toys/source_spec.rb

@@ -105,10 +105,24 @@ module Toys
       # @param source_name [String,nil] The source name that will be shown in
       #     documentation for tools loaded from this source. If omitted, a
       #     default is generated at resolution time.
+      # @param on_missing [:confirm,:error,:install] What to do if the
+      #     requested gem is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     Defaults to the setting in the {Toys::Utils::Gems} utility used to
+      #     activate the gem (usually `:confirm`).
+      # @param default_confirm [boolean] The default confirmation result, if
+      #     `on_missing` is set to `:confirm`. Defaults to the setting in the
+      #     {Toys::Utils::Gems} utility used to activate the gem (usually true).
+      #
       # @return [Toys::SourceSpec::Gem]
       # @raise [ArgumentError] if an argument is not a legal value.
       #
-      def gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil)
+      def gem(name, version: nil, path: nil, toys_dir: nil, context_directory: nil, source_name: nil,
+              on_missing: nil, default_confirm: nil)
         # Source available in the toys-core gem
       end
 
@@ -285,6 +299,24 @@ module Toys
       #
       attr_reader :toys_dir
 
+      ##
+      # What to do if the gem is not installed.
+      #
+      # @return [nil] to use the default behavior for the Gems util
+      # @return [:error] if an error should be raised
+      # @return [:confirm] if a confirmation prompt should be presented
+      # @return [:install] if the gem should be installed without confirmation
+      #
+      attr_reader :on_missing
+
+      ##
+      # The default response for a confirmation prompt
+      #
+      # @return [nil] to use the default behavior for the Gems util
+      # @return [boolean] to provide an override
+      #
+      attr_reader :default_confirm
+
       protected
     end
 

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

@@ -126,7 +126,6 @@ module Toys
       #      *  `:install` - just install the gem
       #
       #     The default is `:confirm`.
-      #
       # @param on_conflict [:error,:warn,:ignore] What to do if bundler has
       #     already been run with a different Gemfile. Possible values:
       #
@@ -135,21 +134,30 @@ module Toys
       #      *  `:warn` - print a warning and proceed without bundling again
       #
       #     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.
       #
       def initialize(on_missing: nil,
                      on_conflict: nil,
+                     default_confirm: nil,
                      terminal: nil,
                      input: nil,
-                     output: nil,
-                     suppress_confirm: nil,
-                     default_confirm: nil)
+                     output: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Return a gem activator with the same settings as this one, except for
+      # the provided overrides. See the constructor for argument docs. If no
+      # non-nil overrides are provided, self is returned.
+      #
+      # @param overrides [Hash] Overrides. See the constructor for details.
+      # @return [Toys::Utils::Gems]
+      #
+      def with(**overrides)
         # Source available in the toys-core gem
       end
 

data/docs/guide.md

@@ -1955,7 +1955,7 @@ below.
 
 Finally, you can define and distribute tools in a Ruby gem, and load them from
 the gem. This can be more involved as it requires creating and publishing a
-gem, but it is useful for versioning and public distribution of tools.
+gem, but it is useful for versioning and distribution of tools.
 
 A Ruby gem is basically just a zip file with some metadata. By convention, it
 contains Ruby classes (usually in a top level `lib` directory), and sometimes
@@ -2012,6 +2012,14 @@ directive. This can be useful if a gem has multiple toys directories:
 load_gem "my-tools", toys_dir: "uncommon-tools"
 ```
 
+By default, if the specified gem is not currently installed, Toys will
+interactively ask whether it should install the gem for you. If you need to
+suppress this prompt, for example if you need to run in a non-interactive
+shell environment, set the `:on_missing` keyword argument. You can set
+`on_missing: :install` to attempt to install without asking, or
+`on_missing: :error` to abort with an error without asking. (The default value
+is `on_missing: :confirm` which displays the interactive prompt.)
+
 #### Loading sources from the command line
 
 If you want to run a tool from an additional source without referencing that
@@ -2037,11 +2045,13 @@ Gemfile:
 $ toys do --gem="my-tools, ~> 1.5, >= 1.5.2" greet
 ```
 
-The `--path` value is a file system path, naming either a directory of tools or
-a single Ruby file defining tools:
+You can also suppress the interactive prompt when the gem is not installed, by
+providing the `--on-missing-gem=` flag. Set `--on-missing-gem=install` to
+attempt to install the gem without asking, or `--on-missing-gem=error` to abort
+with an error. For example:
 
 ```
-$ toys do --path=/var/share/mytools greet
+$ toys do --gem=my-tools --on-missing-gem=install greet
 ```
 
 The `--git` value begins with the git remote, optionally followed by any number
@@ -2050,15 +2060,19 @@ of `key=value` elements, again separated by commas. The recognized keys are
 `load_git` directive:
 
 ```
-$ toys do --git="https://github.com/dazuma/example, path=greet.rb, update=3600" greet
+$ toys do --git="https://github.com/dazuma/example, path=toys/greet.rb, update=3600" greet
 ```
 
-The elements of a `--git` value are named, rather than positional as in a
-`--gem` value, because a git source has three independent optional fields, and
-a positional syntax could not express, for example, a path with no commit.
 Whitespace surrounding each element, and surrounding each equals sign, is
 ignored. There is no way to escape a comma appearing within a value.
 
+The `--path` value is a file system path, naming either a directory of tools or
+a single Ruby file defining tools:
+
+```
+$ toys do --path=/var/share/mytools greet
+```
+
 You can pass these flags multiple times, and interleave them, to make several
 sources available at once. If two sources define the same tool, the source
 whose flag appears earlier on the command line wins:
@@ -2067,7 +2081,8 @@ whose flag appears earlier on the command line wins:
 $ toys do --path=./tools --gem=my-tools --git=https://github.com/dazuma/example greet
 ```
 
-Here, a `greet` tool defined by all three sources is taken from `./tools`.
+Here, if a `greet` tool is defined by all three sources, the one from `./tools`
+wins.
 
 Remember to quote any value that includes commas or characters that are
 meaningful to the shell. The commas inside these values are part of the flag

data/lib/toys/templates/minitest.rb

@@ -49,8 +49,6 @@ module Toys
       #     the "minitest" gem, used if bundler is not enabled.
       #     Optional. If not provided, defaults to the value given in
       #     {DEFAULT_GEM_VERSION_REQUIREMENTS}.
-      # @param gem_version [String,Array<String>] Deprecated alias for the
-      #     `minitest` argument.
       # @param minitest_mock [String,Array<String>,true] Include the
       #     "minitest-mock" gem with the given version requirements. Used if
       #     bundler is not enabled. If true is passed, the value in
@@ -99,7 +97,6 @@ module Toys
                      minitest_focus: nil,
                      minitest_rg: nil,
                      gems: nil,
-                     gem_version: nil,
                      libs: nil,
                      files: nil,
                      seed: nil,
@@ -118,7 +115,7 @@ module Toys
         @mt_compat = mt_compat
         @context_directory = context_directory
         @gem_dependencies = {}
-        update_version_spec("minitest", minitest || gem_version)
+        update_version_spec("minitest", minitest)
         update_version_spec("minitest-mock", minitest_mock)
         update_version_spec("minitest-focus", minitest_focus)
         update_version_spec("minitest-rg", minitest_rg)
@@ -161,7 +158,6 @@ module Toys
       def minitest=(value)
         update_version_spec("minitest", value)
       end
-      alias gem_version= minitest=
 
       ##
       # Version requirements for the minitest-mock gem. Used if bundler is not

data/lib/toys/templates/rspec.rb

@@ -58,8 +58,6 @@ module Toys
       #     the "rspec" gem, used if bundler is not enabled.
       #     Optional. If not provided, defaults to the value given in
       #     {DEFAULT_GEM_VERSION_REQUIREMENTS}.
-      # @param gem_version [String,Array<String>] Deprecated alias for the
-      #     `rspec` argument.
       # @param gems [Hash{String=>String|Array<String>|true}] Include the given
       #     gems with the given version requirements. Used if bundler is not
       #     enabled. If the version requirement is set to `true`, then the
@@ -91,7 +89,6 @@ module Toys
       #
       def initialize(name: nil,
                      rspec: nil,
-                     gem_version: nil,
                      gems: nil,
                      libs: nil,
                      options: nil,
@@ -115,7 +112,7 @@ module Toys
         @bundler = bundler
         @context_directory = context_directory
         @gem_dependencies = {}
-        update_version_spec("rspec", rspec || gem_version)
+        update_version_spec("rspec", rspec)
         update_gems(gems) if gems
       end
 
@@ -155,7 +152,6 @@ module Toys
       def rspec=(value)
         update_version_spec("rspec", value)
       end
-      alias gem_version= rspec=
 
       ##
       # An array of directories to add to the Ruby require path.

data/lib/toys/version.rb

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

metadata

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