toys-core 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2805bf71091b4ea8bf6f6a670281171dc6a5df4edec5196d80d64124ce2a199
-  data.tar.gz: b5c860449af3a0566e9b1fe8dc527cba4df6750ccc3b259365faf99fa79682fb
+  metadata.gz: 72758c7ebe4c70a841bd76672f81e206a6de66c2a1104c81a3eb5b6b8c0b3c1f
+  data.tar.gz: 8c5b44be27ba6721dbb1dda109b6f4c46c4b1fc45dcba5b2b295d9082d19582e
 SHA512:
-  metadata.gz: 95490a978d1a3ae04be668a2fd318de2499e9610bb6072a053776fb47214d2444c0d93a73fa690b46a6d4706e2fec1f20b76f8d111100ec65216f0c274efe77a
-  data.tar.gz: b9421ebfa989c45444024222cc3576a166d5797d7c982033265a11aa149c71ef0ab069441c70da490819e5bbafe95eb017c92289d6b46d7917c19634ee3eaf64
+  metadata.gz: f9cb82ec77824ca0d5ca3e220559498c717aeef15e0a66b60b96f51e087a5313e6c8b2a9c547fd3cb84d41e1fd0f70dab2d416ddcce3e28559f7438437e532d8
+  data.tar.gz: f3216d320f1feb0edd4b5e65cf3adc453adc97e8865b332182350bb27c65bc9580469cd55f06b3fda42c0e6b75d98180eb48e17ec10baa4eaa15e8524787b10d

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Release History
 
+### v0.22.0 / 2026-05-05
+
+Toys-core 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.
+
+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.
+* 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

@@ -29,7 +29,9 @@ need to be modified if you're running on Windows.
 
 Install the **toys-core** gem using:
 
-    $ gem install toys-core
+```
+$ gem install toys-core
+```
 
 You can also install the **toys** gem, which brings in **toys-core** as a
 dependency.
@@ -39,22 +41,28 @@ dependency.
 We'll start by creating an executable Ruby script. Using your favorite text
 editor, create a new file called `mycmd` with the following contents:
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    exit(cli.run(*ARGV))
+exit(cli.run(*ARGV))
+```
 
 Make sure the file's executable bit is set:
 
-    $ chmod a+x mycmd
+```
+$ chmod a+x mycmd
+```
 
 That's it! This is a fully-functional Toys-based executable! Let's see what
 happens when you run it:
 
-    $ ./mycmd
+```
+$ ./mycmd
+```
 
 Just as with Toys itself, you get a help screen by default (since we haven't
 yet actually implemented any behavior.) As you can see, some of the same
@@ -71,30 +79,34 @@ information to the Toys CLI object in a block.
 
 Let's add some functionality to `mycmd`.
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    #### Insert the following block ...
-    cli.add_config_block do
-      desc "My first executable!"
-      flag :whom, default: "world"
-      def run
-        puts "Hello, #{whom}!"
-      end
-    end
+#### Insert the following block ...
+cli.add_config_block do
+  desc "My first executable!"
+  flag :whom, default: "world"
+  def run
+    puts "Hello, #{whom}!"
+  end
+end
 
-    exit(cli.run(*ARGV))
+exit(cli.run(*ARGV))
+```
 
 If you went through the tutorial in the README for the Toys gem, this should
 look familiar. Let's run it now, and experiment with passing flags to it.
 
-    $ ./mycmd
-    $ ./mycmd --whom=ruby
-    $ ./mycmd --bye
-    $ ./mycmd --help
+```
+$ ./mycmd
+$ ./mycmd --whom=ruby
+$ ./mycmd --bye
+$ ./mycmd --help
+```
 
 Notice that we did not create a `tool` block, but instead set up description,
 flags, and functionality directly in the configuration block. This configures
@@ -109,40 +121,46 @@ But perhaps you want your executable to have multiple "tools", similar to other
 familiar executables like git or kubectl. You can define tools, including
 nested tools, by writing `tool` blocks in your config. Here's an example:
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    cli = Toys::CLI.new
+cli = Toys::CLI.new
 
-    #### Change the config block as follows ...
-    cli.add_config_block do
-      # Things outside any tool block still apply to the root
-      desc "My first executable with several tools"
+#### Change the config block as follows ...
+cli.add_config_block do
+  # Things outside any tool block still apply to the root
+  desc "My first executable with several tools"
 
-      # We'll put the greet function here
-      tool "greet" do
-        desc "My first tool!"
-        flag :whom, default: "world"
-        def run
-          puts "Hello, #{whom}!"
-        end
-      end
-
-      # Try writing a second tool here. You could use the "new-repo"
-      # example from the Toys tutorial.
+  # We'll put the greet function here
+  tool "greet" do
+    desc "My first tool!"
+    flag :whom, default: "world"
+    def run
+      puts "Hello, #{whom}!"
     end
+  end
+
+  # Try writing a second tool here. You could use the "new-repo"
+  # example from the Toys tutorial.
+end
 
-    exit(cli.run(*ARGV))
+exit(cli.run(*ARGV))
+```
 
 Now you can run `greet` as a tool:
 
-    $ ./mycmd greet
+```
+$ ./mycmd greet
+```
 
 The "root" functionality once again shows global help, including a list of the
 available tools.
 
-    $ ./mycmd
+```
+$ ./mycmd
+```
 
 Notice that the description set at the "root" of the config block (outside the
 tool blocks) shows up here.
@@ -157,43 +175,47 @@ These and many more aspects of the behavior of our executable can be customized
 by passing options to the `Toys::CLI` constructor. Here's an example that
 modifies error handling and delimiter parsing.
 
-    #!/usr/bin/env ruby
-
-    require "toys-core"
-
-    #### Pass some additional options to the CLI constructor ...
-    cli = Toys::CLI.new(
-      extra_delimiters: ":",
-      error_handler: ->(err) {
-        puts "Aww shucks, an error happened: #{err.message}"
-        return 1
-      }
-    )
-
-    #### Change the config block as follows ...
-    cli.add_config_block do
-      tool "example" do
-        tool "greet" do
-          def run
-            puts "Hello, world!"
-          end
-        end
-        tool "error" do
-          def run
-            raise "Whoops!"
-          end
-        end
+```ruby
+#!/usr/bin/env ruby
+
+require "toys-core"
+
+#### Pass some additional options to the CLI constructor ...
+cli = Toys::CLI.new(
+  extra_delimiters: ":",
+  error_handler: ->(err) {
+    puts "Aww shucks, an error happened: #{err.message}"
+    return 1
+  }
+)
+
+#### Change the config block as follows ...
+cli.add_config_block do
+  tool "example" do
+    tool "greet" do
+      def run
+        puts "Hello, world!"
       end
     end
+    tool "error" do
+      def run
+        raise "Whoops!"
+      end
+    end
+  end
+end
 
-    exit(cli.run(*ARGV))
+exit(cli.run(*ARGV))
+```
 
 Try these runs. Do they behave as you expected?
 
-    $ ./mycmd example greet
-    $ ./mycmd example:greet
-    $ ./mycmd example.greet
-    $ ./mycmd example error
+```
+$ ./mycmd example greet
+$ ./mycmd example:greet
+$ ./mycmd example.greet
+$ ./mycmd example error
+```
 
 ### Configuring middleware
 
@@ -204,32 +226,36 @@ your tools by default.
 The next example provides a custom middleware stack, resulting in a different
 set of common tool functionality.
 
-    #!/usr/bin/env ruby
+```ruby
+#!/usr/bin/env ruby
 
-    require "toys-core"
+require "toys-core"
 
-    #### Change the CLI construction again ...
-    middlewares = [
-      [:set_default_descriptions, default_tool_desc: "Hey look, a tool!"],
-      [:show_help, help_flags: true]
-    ]
-    cli = Toys::CLI.new middleware_stack: middlewares
+#### Change the CLI construction again ...
+middlewares = [
+  [:set_default_descriptions, default_tool_desc: "Hey look, a tool!"],
+  [:show_help, help_flags: true]
+]
+cli = Toys::CLI.new middleware_stack: middlewares
 
-    #### Use this config block ...
-    cli.add_config_block do
-      tool "greet" do
-        def run
-          puts "Hello, world!"
-        end
-      end
+#### Use this config block ...
+cli.add_config_block do
+  tool "greet" do
+    def run
+      puts "Hello, world!"
     end
+  end
+end
 
-    exit(cli.run(*ARGV))
+exit(cli.run(*ARGV))
+```
 
 We've now modified the default description applied to tools that don't provide
 their own description. See the effect with:
 
-    $ ./mycmd greet --help
+```
+$ ./mycmd greet --help
+```
 
 We've also omitted some of the default middleware, including the one that adds
 the `--verbose` and `--quiet` flags to all your tools. Notice those flags are
@@ -240,7 +266,9 @@ We've also omitted the middleware that provides default execution behavior
 haven't defined a top-level `run` method in this last example, invoking the
 root tool will cause an error:
 
-    $ ./mycmd
+```
+$ ./mycmd
+```
 
 It is even possible to write your own middleware. In general, while the
 `Toys::CLI` constructor provides defaults that should work for many use cases,
@@ -258,12 +286,16 @@ includes a few simple examples that you can use as a starting point.
 
 To experiment with the examples, clone the Toys repo from GitHub:
 
-    $ git clone https://github.com/dazuma/toys.git
-    $ cd toys
+```
+$ git clone https://github.com/dazuma/toys.git
+$ cd toys
+```
 
 Navigate to the simple-gem example:
 
-    $ cd toys-core/examples/simple-gem
+```
+$ cd toys-core/examples/simple-gem
+```
 
 This example wraps the simple "greet" executable that we covered earlier, in a
 gem. You can see the
@@ -273,23 +305,31 @@ in the bin directory.
 Try it out by building and installing the gem. From the `examples/simple-gem`
 directory, run:
 
-    $ toys install
+```
+$ toys install
+```
 
 Once the gem has successfully installed, you can run the executable, which
 RubyGems should have added to your path. (Note: if you are using a ruby
 installation manager, you may need to "rehash" or "reshim" to gain access to
 the executable.)
 
-    $ toys-core-simple-example --whom=Toys
+```
+$ toys-core-simple-example --whom=Toys
+```
 
 Clean up by uninstalling the gem:
 
-    $ gem uninstall toys-core-simple-example
+```
+$ gem uninstall toys-core-simple-example
+```
 
 If the implementation of your executable is more complex, you might want to
 break it up into multiple files. The multi-file gem example demonstrates this.
 
-    $ cd ../multi-file-gem
+```
+$ cd ../multi-file-gem
+```
 
 This executable's implementation resides in its
 [lib directory](https://github.com/dazuma/toys/tree/main/toys-core/examples/multi-file-gem/lib),
@@ -305,18 +345,24 @@ as you can see in
 
 Try it out now. From the `examples/multi-file-gem` directory, run:
 
-    $ toys install
+```
+$ toys install
+```
 
 Once the gem has successfully installed, you can run the executable, which
 RubyGems should have added to your path. (Note: if you are using a ruby
 installation manager, you may need to "rehash" or "reshim" to gain access to
 the executable.)
 
-    $ toys-core-multi-file-example greet
+```
+$ toys-core-multi-file-example greet
+```
 
 Clean up by uninstalling the gem:
 
-    $ gem uninstall toys-core-multi-file-example
+```
+$ gem uninstall toys-core-multi-file-example
+```
 
 ### Learning more