toys 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87582d55a2f60738d19c3c4d717f93910c5cc677f5e210c8418366baf2e91921
-  data.tar.gz: f82f165fa06113b1ad398c5cb2d5e62217d860924f00e5b0d3b6172824d4a116
+  metadata.gz: 7c91d8f8914503e8d8baf7eae17725fa3eee2470273311917561c0c1dfa9b341
+  data.tar.gz: 01a7b93c64123371a1f82afbb708c15377efc9b63b0bd2c52fd5dd0e9acee8c7
 SHA512:
-  metadata.gz: 5a9dad0dcdd8c83d678dfe23522faaa38b62bb765e16f7b6aafce2ce014920d13addce0d32a619f4c5d80e21f8e79b40ff8c0936381169df17d080d3d2500aec
-  data.tar.gz: 0f2b4c0cc5cf87ed070d7f21d57f8a9b2051277c5651f5e4d210b9ebb2a9498df93dde3203cb54437c19f8991ed348ab3b9d59c5a944c3070aa22e09a7cdd14e
+  metadata.gz: f888f8e2b005d13c943a7856add1ae37d56739dc0553612fa09b13472a4b43b002a594b11b8d77723f4ddafdf05170a99c2ade023ed247136cd946d7345784fa
+  data.tar.gz: a8e90f01ab91878bf4175bde290c39d1d126985a77d23779134aa008ba217801f1f2b2e876733b4bf1ef61336506758b7fb4f9dab0bd3a5da7c03ae9aba9d141

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Release History
 
+### v0.22.0 / 2026-05-05
+
+Toys 0.22 is a major release focused on polish and cleanup in preparation for version 1.0. It includes a number of small breaking changes where needed to clean up the interfaces. (Note that many of the changes listed below are actually in the `toys-core` gem.)
+
+Breaking interface changes:
+
+* The `static` directive no longer "forces" creating of helper methods, instead using the same logic as the flag and argument directives. In particular, by default it will not create a method starting with underscore.
+* Removed `Toys::Settings` and moved inheritable_helper_methods to a dedicated tool attribute. Use the `basic_settings` gem if you need the old settings class.
+* `Toys::Acceptor#create` no longer takes a hash as the spec. (This was undocumented but worked previously.) To construct an object, pass the class as the main spec object, and the keyword arguments in the options.
+* `Toys::Acceptor::Enum#values` now returns the values themselves instead of a zipped array that includes strings.
+* `Toys::FlagGroup::Base` is no longer instantiable; use `Toys::FlagGroup::Optional` instead.
+* The `acceptor` and `display_name` attributes of `Toys::PositionalArg` are no longer writable and must be set in the constructor.
+* `Toys::Completion#create` no longer takes a hash as the spec. (This was undocumented but worked previously.) To construct an object, pass the class as the main spec object, and the keyword arguments in the options.
+* The `delegation_target` attribute of `Toys::ToolDefinition::DefaultCompletion` is no longer writable and must be set in the constructor.
+* You can no longer override a completion class using the `:""` key. (This was undocumented but worked previously.) Just pass a fully constructed completion object if you need a custom object.
+* The original `Module#include` method is now available in the DSL as `include_module` instead of `super_include`.
+* Template classes no longer automatically include `Toys::Context::Key`. This behavior was undocumented and inconsistent between different ways of defining templates.
+* Made `Toys::CLI#load_tool` return the block value rather than the exit_code.
+* Made `Toys::Testing#toys_load_tool` return the block value rather than the exit_code
+* Dropped undocumented `Loader#add_path_set` option to include individual source names in the relative_paths argument.
+* Renamed `use_less` in the `Toys::StandardMiddleware::ShowHelp` constructor to `use_pager`, and added support for custom pagers.
+* Renamed many of the methods in `StandardUI` to reduce confusion.
+* Removed `LoaderError` and used `ToolDefinitionError` for those cases, as it was decided that the distinction was ambiguous and dependent on internal details.
+* Removed `ContextualError#underlying_error` as it was synonymous with `cause`.
+* Consolidated `ContextualError` public interface into a single `capture` method.
+* `ArgParser::ExtraArgumentsError` now takes `:arguments` instead of `:values`, and provides an accessor for the same.
+* `ArgParser::ToolUnrecognizedError` now takes `:full_name` instead of `:values`, and provides an accessor for the same.
+* Renamed `ArgParser::UsageError#full_message` to `message_with_suggestions` to avoid overriding `Exception#full_message`.
+
+New features:
+
+* The range acceptor supports beginless and endless ranges.
+* A custom source_name can be provided to `Loader#add_path_set`, `Loader#add_git`, and `Loader#add_gem`.
+* The `:gems` mixin provides a context key for retrieving the underlying `Toys::Utils::Gems` service object.
+* The `:gems` mixin provides an explicit `Toys::Utils::Gems::ClassMethods` module defining the directives added to the tool class.
+* The `activate` and `bundle` methods in the Gems utility now return useful results.
+
+Other fixes:
+
+* The `:update` argument to the `load_git` directive had no effect if the `:as` argument was provided.
+* `FlagValueUnacceptableError` and `ArgValueUnacceptableError` have their value set correctly.
+* If a CLI has a static (shared) logger, creating a child with `logger: nil` actually clears it.
+* Removed unused `Toys::StandardMiddleware::ShowHelp::TOOL_NAME_KEY`.
+* ShowHelp middleware displays an error message instead of raising an exception when help cannot be generated due to a bad search regex.
+* `ArgParser::UsageError` is now a proper exception.
+* `ContextualError` does a better job of capturing relevant syntax errors.
+* Various minor completion system fixes.
+
+Several libraries under `toys/utils` were extracted into their own gems. The current code remains under `Toys::Utils` as a vendored copy of the external gem, so the extracted gems are not actually dependencies of Toys. The affected libraries are:
+
+* `Toys::Utils::Exec` which was extracted to the gem `exec_service`.
+* `Toys::Utils::XDG` which was extracted to the gem `simple_xdg`.
+* `Toys::Utils::GitCache` which was extracted to the gem `git_cache`.
+
+Finally, a variety of clarifications and fixes were made to the reference documentation, readme, and user's guide.
+
 ### 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:

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2019-2023 Daniel Azuma and the Toys contributors
+Copyright 2019-2026 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -23,12 +23,16 @@ Here's a tutorial to help you get a feel of what Toys can do.
 
 Install the **toys** gem using:
 
-    $ gem install toys
+```
+$ gem install toys
+```
 
 This installs the `toys` executable, along with some built-in tools and
 libraries. You can run the executable immediately:
 
-    $ toys
+```
+$ toys
+```
 
 This displays overall help for Toys. If you have `less` installed, Toys will
 use it to display the help screen. Press `q` to exit.
@@ -36,19 +40,25 @@ use it to display the help screen. Press `q` to exit.
 You may notice that the help screen lists some tools that are pre-installed.
 Let's run one of them:
 
-    $ toys system version
+```
+$ toys system version
+```
 
 The `system version` tool displays the current version of the toys gem.
 
-Toys also provides optional tab completion for bash. To install it, execute the
-following command in your shell, or add it to your bash configuration file
-(e.g. `~/.bashrc`).
+Toys also provides optional tab completion for bash and zsh. To install for
+bash, execute the following command in your shell, or add it to your bash
+configuration file (e.g. `~/.bashrc`).
 
-    $(toys system bash-completion install)
+```
+$(toys system bash-completion install)
+```
 
-Toys does not yet specially implement tab completion for zsh or other shells.
-However, if you are using zsh, installing bash completion using `bashcompinit`
-*mostly* works.
+To install for zsh, execute this or add to your `~/.zshrc`.
+
+```
+$(toys system zsh-completion install)
+```
 
 ### Write your first tool
 
@@ -56,32 +66,42 @@ You can define tools by creating a *Toys file*. Go into any directory, and,
 using your favorite editor, create a new file called `.toys.rb` (note the
 leading period). Copy the following text into the file, and save it:
 
-    tool "greet" do
-      desc "My first tool!"
-      flag :whom, default: "world"
-      def run
-        puts "Hello, #{whom}!"
-      end
-    end
+```ruby
+tool "greet" do
+  desc "My first tool!"
+  flag :whom, default: "world"
+  def run
+    puts "Hello, #{whom}!"
+  end
+end
+```
 
 This defines a tool named "greet". Try running it:
 
-    $ toys greet
+```
+$ toys greet
+```
 
 The tool also recognizes a flag on the command line. Try this:
 
-    $ toys greet --whom=ruby
+```
+$ toys greet --whom=ruby
+```
 
 Toys provides a rich set of features for defining command line arguments and
 flags. It can also validate arguments. Try this:
 
-    $ toys greet --bye
+```
+$ toys greet --bye
+```
 
 Notice that Toys automatically generated a usage summary for your tool. It also
 automatically generates a full help screen, which you can view using the
 `--help` flag:
 
-    $ toys greet --help
+```
+$ toys greet --help
+```
 
 Toys searches up the directory hierarchy for Toys files. So it will find this
 `.toys.rb` if you are located in this directory or any subdirectory. It will
@@ -99,53 +119,59 @@ likely to see in real-world usage. Add the following to your `.toys.rb` file.
 (You don't need to replace the greet tool you just wrote; just add this new
 tool to the end of the file.)
 
-    tool "new-repo" do
-      desc "Create a new git repo"
-
-      optional_arg :name, desc: "Name of the directory to create"
-
-      include :exec, exit_on_nonzero_status: true
-      include :fileutils
-      include :terminal
-
-      def run
-        if name.nil?
-          response = ask "Please enter a directory name: "
-          set :name, response
-        end
-        if File.exist? name
-          puts "Aborting because #{name} already exists", :red, :bold
-          exit 1
-        end
-        logger.info "Creating new repo in directory #{name}..."
-        mkdir name
-        cd name do
-          create_repo
-        end
-        puts "Created repo in #{name}", :green, :bold
-      end
-
-      def create_repo
-        exec "git init"
-        File.write ".gitignore", <<~CONTENT
-          tmp
-          .DS_Store
-        CONTENT
-        # You can add additional files here.
-        exec "git add ."
-        exec "git commit -m 'Initial commit'"
-      end
+```ruby
+tool "new-repo" do
+  desc "Create a new git repo"
+
+  optional_arg :name, desc: "Name of the directory to create"
+
+  include :exec, exit_on_nonzero_status: true
+  include :fileutils
+  include :terminal
+
+  def run
+    if name.nil?
+      response = ask "Please enter a directory name: "
+      set :name, response
+    end
+    if File.exist? name
+      puts "Aborting because #{name} already exists", :red, :bold
+      exit 1
+    end
+    logger.info "Creating new repo in directory #{name}..."
+    mkdir name
+    cd name do
+      create_repo
     end
+    puts "Created repo in #{name}", :green, :bold
+  end
+
+  def create_repo
+    exec "git init"
+    File.write ".gitignore", <<~CONTENT
+      tmp
+      .DS_Store
+    CONTENT
+    # You can add additional files here.
+    exec "git add ."
+    exec "git commit -m 'Initial commit'"
+  end
+end
+```
 
 Now you should have an additional tool called `new-repo` available. Type:
 
-    $ toys
+```
+$ toys
+```
 
 The help screen lists both the `greet` tool we started with, and the new
 `new-repo` tool. This new tool creates a directory containing a newly created
 git repo. (It assumes you have `git` available on your path.) Try running it:
 
-    $ toys new-repo foo
+```
+$ toys new-repo foo
+```
 
 That should create a directory `foo`, initialize a git repository within it,
 and make a commit.
@@ -155,7 +181,9 @@ any combination of flags and required and optional arguments. This tool's
 argument is declared with a description string, which you can see if you view
 the tool's help:
 
-    $ toys new-repo --help
+```
+$ toys new-repo --help
+```
 
 The argument is marked as "optional" which means you can omit it. Notice that
 the tool's code detects that it has been omitted and responds by prompting you
@@ -172,7 +200,7 @@ than modules. These symbols are the names of some of Toys's built-in helper
 *mixins*, which are configurable modules that enhance your tool. They may
 provide methods your tool can call, or invoke other behavior. In our example:
 
-*   The `:exec` mixin provides a variety of methods for running external
+ *  The `:exec` mixin provides a variety of methods for running external
     commands. In this example, we use the `exec` method to run shell
     commands, but you can also signal and control these commands, capture
     and redirect streams, and so forth. Note that we pass the
@@ -181,10 +209,10 @@ provide methods your tool can call, or invoke other behavior. In our example:
     to `set -e` in bash). This is a common pattern when writing tools that
     invoke external commands. (If you want more control, the `:exec` mixin also
     provides ways to respond to result codes individually.)
-*   The `:fileutils` mixin provides the methods of the Ruby `FileUtils`
+ *  The `:fileutils` mixin provides the methods of the Ruby `FileUtils`
     library, such as `mkdir` and `cd` used in this example. It's effectively
     shorthand for `require "fileutils"; include ::FileUtils`.
-*   The `:terminal` mixin provides styled output, as you can see with the style
+ *  The `:terminal` mixin provides styled output, as you can see with the style
     codes being passed to `puts`. It also provides some user interaction
     commands such as `ask`, as well as spinners and other controls. You can see
     operation of the `:terminal` mixin in the tool's output, which is styled
@@ -193,7 +221,9 @@ provide methods your tool can call, or invoke other behavior. In our example:
 
 Now try running this:
 
-    $ toys new-repo bar --verbose
+```
+$ toys new-repo bar --verbose
+```
 
 You'll notice some diagnostic log output. Toys provides a standard Ruby Logger
 for each tool, and you can use it to emit diagnostic logs directly as
@@ -219,14 +249,18 @@ If you have a project with a Rakefile, move into that directory and create a
 new file called `.toys.rb` in that same directory (next to the Rakefile). Add
 the following line to your `.toys.rb` file:
 
-    expand :rake
+```ruby
+expand :rake
+```
 
 This syntax is called a "template expansion." It's a way to generate tools
 programmatically. In this case, Toys provides the `:rake` template, which reads
 your Rakefile and generates Toys tools corresponding to all your Rake tasks!
 Now if you run:
 
-    $ toys
+```
+$ toys
+```
 
 You'll see that you now have tools associated with each of your Rake tasks. So
 if you have a `rake test` task, you can run it using `toys test`.
@@ -326,7 +360,7 @@ because it has a few known bugs that affect Toys.
 
 ## License
 
-Copyright 2019-2025 Daniel Azuma and the Toys contributors
+Copyright 2019-2026 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/builtins/system/zsh-completion.rb

@@ -18,6 +18,28 @@ long_desc \
   "The \"eval\" tool is the actual completion command invoked by zsh when it needs to" \
     " complete a toys command line. You shouldn't need to invoke it directly."
 
+tool "eval" do
+  desc "Tab completion command (executed by zsh)"
+
+  long_desc \
+    "Completion command invoked by zsh to complete a toys command line. Generally you do not" \
+      " need to invoke this directly. It reads the command line context from the COMP_LINE" \
+      " and COMP_POINT environment variables, and outputs completion candidates to stdout in" \
+      " two sections separated by a blank line: final completions first, then partial" \
+      " completions (such as directory paths)."
+
+  disable_argument_parsing
+
+  def run
+    require "toys/utils/completion_engine"
+    result = ::Toys::Utils::CompletionEngine::Zsh.new(cli).run
+    if result > 1
+      logger.fatal("This tool must be invoked as a zsh completion command.")
+    end
+    exit(result)
+  end
+end
+
 tool "install" do
   desc "Install zsh tab completion"
 
@@ -67,25 +89,3 @@ tool "remove" do
     puts ::Shellwords.join(["source", path] + exes)
   end
 end
-
-tool "eval" do
-  desc "Tab completion command (executed by zsh)"
-
-  long_desc \
-    "Completion command invoked by zsh to complete a toys command line. Generally you do not" \
-      " need to invoke this directly. It reads the command line context from the COMP_LINE" \
-      " and COMP_POINT environment variables, and outputs completion candidates to stdout in" \
-      " two sections separated by a blank line: final completions first, then partial" \
-      " completions (such as directory paths)."
-
-  disable_argument_parsing
-
-  def run
-    require "toys/utils/completion_engine"
-    result = ::Toys::Utils::CompletionEngine::Zsh.new(cli).run
-    if result > 1
-      logger.fatal("This tool must be invoked as a zsh completion command.")
-    end
-    exit(result)
-  end
-end

data/core-docs/toys/acceptor.rb

@@ -248,7 +248,9 @@ module Toys
       # The array of enum values.
       # @return [Array<Object>]
       #
-      attr_reader :values
+      def values
+        # Source available in the toys-core gem
+      end
     end
 
     ##
@@ -312,21 +314,21 @@ module Toys
     # acceptors.
     # @return [Proc]
     #
-    INTEGER_CONVERTER = proc { |s| s.nil? ? nil : Integer(s) }
+    INTEGER_CONVERTER = proc { |s| Integer(s) }
 
     ##
     # A converter proc that handles floats. Useful in Simple and Range
     # acceptors.
     # @return [Proc]
     #
-    FLOAT_CONVERTER = proc { |s| s.nil? ? nil : Float(s) }
+    FLOAT_CONVERTER = proc { |s| Float(s) }
 
     ##
     # A converter proc that handles rationals. Useful in Simple and Range
     # acceptors.
     # @return [Proc]
     #
-    RATIONAL_CONVERTER = proc { |s| s.nil? ? nil : Rational(s) }
+    RATIONAL_CONVERTER = proc { |s| Rational(s) }
 
     ##
     # A converter proc that handles any numeric value. Useful in Simple and
@@ -405,7 +407,7 @@ module Toys
       #     and type description you provide are ignored.
       #
       #  *  Any **regular expression**. The returned acceptor validates only if
-      #     the regex matches the *entire string parameter*.
+      #     the regex matches the string parameter.
       #
       #     You can also provide an optional conversion function as a block. If
       #     provided, the block must take a variable number of arguments, the
@@ -458,17 +460,6 @@ module Toys
       def create(spec = nil, **options, &block)
         # Source available in the toys-core gem
       end
-
-      ##
-      # Take the various ways to express an acceptor spec, and convert them to
-      # a canonical form expressed as a single object. This is called from the
-      # DSL to generate a spec object that can be stored.
-      #
-      # @private This interface is internal and subject to change without warning.
-      #
-      def scalarize_spec(spec, options, block)
-        # Source available in the toys-core gem
-      end
     end
   end
 end

data/core-docs/toys/arg_parser.rb

@@ -13,10 +13,12 @@ module Toys
     #
     # Base representation of a usage error reported by the ArgParser.
     #
-    # This functions similarly to an exception, but is not raised. Rather, it
-    # is returned in the {Toys::ArgParser#errors} array.
+    # This is normally not raised directly, but returned as an element in the
+    # {Toys::ArgParser#errors} array. It will, however, have the normal
+    # message and backtrace attributes, along with additional fields as defined
+    # in this class, and it can be raised later if desired.
     #
-    class UsageError
+    class UsageError < ::StandardError
       ##
       # Create a UsageError given a message and common data
       #
@@ -28,15 +30,17 @@ module Toys
       #     applicable.
       # @param suggestions [Array<String>,nil] An array of suggestions from
       #     DidYouMean, or nil if not applicable.
+      # @param skip_frames [Integer] Number of call frames to skip when
+      #     constructing a backtrace, in addition to this initialize call
+      #     itself. Subclasses calling super from their constructor should set
+      #     this to 1 to skip their own initialize frame.
       #
-      def initialize(message, name: nil, value: nil, suggestions: nil)
+      def initialize(message, name: nil, value: nil, suggestions: nil, skip_frames: 0)
         # Source available in the toys-core gem
       end
 
       ##
-      # The basic error message. Does not include suggestions, if any.
-      #
-      # @return [String]
+      # @return [String] The error message, not including any suggestions.
       #
       attr_reader :message
 
@@ -70,10 +74,10 @@ module Toys
       #
       # @return [String]
       #
-      def full_message
+      def message_with_suggestions
         # Source available in the toys-core gem
       end
-      alias to_s full_message
+      alias to_s message_with_suggestions
     end
 
     ##
@@ -227,12 +231,16 @@ module Toys
       #
       # @param message [String,nil] A custom message. Normally omitted, in
       #     which case an appropriate default is supplied.
-      # @param value [String] The first extra argument. Normally required.
-      # @param values [Array<String>] All extra arguments. Normally required.
+      # @param arguments [Array<String>] All extra arguments. Normally required.
       #
-      def initialize(message = nil, value: nil, values: nil)
+      def initialize(message = nil, arguments: nil)
         # Source available in the toys-core gem
       end
+
+      ##
+      # @return [Array<String>] All extra arguments
+      #
+      attr_reader :arguments
     end
 
     ##
@@ -246,15 +254,19 @@ module Toys
       #
       # @param message [String,nil] A custom message. Normally omitted, in
       #     which case an appropriate default is supplied.
-      # @param value [String] The requested subtool. Normally required.
-      # @param values [Array<String>] The full path of the requested tool.
+      # @param full_name [Array<String>] The full path of the requested tool.
       #     Normally required.
       # @param suggestions [Array<String>] An array of suggestions to present
       #     to the user. Optional.
       #
-      def initialize(message = nil, value: nil, values: nil, suggestions: nil)
+      def initialize(message = nil, full_name: nil, suggestions: nil)
         # Source available in the toys-core gem
       end
+
+      ##
+      # @return [Array<String>] The full name of the tool
+      #
+      attr_reader :full_name
     end
 
     ##
@@ -268,7 +280,7 @@ module Toys
       #
       # @param message [String] The message. Required.
       #
-      def initialize(message)
+      def initialize(message = nil)
         # Source available in the toys-core gem
       end
     end
@@ -279,7 +291,7 @@ module Toys
     # @param cli [Toys::CLI] The CLI in effect.
     # @param tool [Toys::ToolDefinition] The tool defining the argument format.
     # @param default_data [Hash] Additional initial data (such as verbosity).
-    # @param require_exact_flag_match [Boolean] Whether to require flag matches
+    # @param require_exact_flag_match [boolean] Whether to require flag matches
     #     be exact (not partial). Default is false.
     #
     def initialize(cli, tool, default_data: {}, require_exact_flag_match: false)
@@ -338,7 +350,7 @@ module Toys
 
     ##
     # Whether flags are currently allowed. Returns false after `--` is received.
-    # @return [Boolean]
+    # @return [boolean]
     #
     def flags_allowed?
       # Source available in the toys-core gem
@@ -346,7 +358,7 @@ module Toys
 
     ##
     # Determine if this parser is finished
-    # @return [Boolean]
+    # @return [boolean]
     #
     def finished?
       # Source available in the toys-core gem