toys-core 0.21.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2805bf71091b4ea8bf6f6a670281171dc6a5df4edec5196d80d64124ce2a199
-  data.tar.gz: b5c860449af3a0566e9b1fe8dc527cba4df6750ccc3b259365faf99fa79682fb
+  metadata.gz: a09f479bfecbde001cec1076fdce57080117cbdeecfc2738879445a682b7363f
+  data.tar.gz: 277635722c80c2691759147cf7fc4b928755f0349a54fd970327c46bae443170
 SHA512:
-  metadata.gz: 95490a978d1a3ae04be668a2fd318de2499e9610bb6072a053776fb47214d2444c0d93a73fa690b46a6d4706e2fec1f20b76f8d111100ec65216f0c274efe77a
-  data.tar.gz: b9421ebfa989c45444024222cc3576a166d5797d7c982033265a11aa149c71ef0ab069441c70da490819e5bbafe95eb017c92289d6b46d7917c19634ee3eaf64
+  metadata.gz: 6cfaa55d28079f651f9eab9d8a693af1386ddc6d08e58553ab457c4c669265902da5bba6e0f336faa8113bf0a92b2fbbe2bde4b49480118fe1d63b00a38ba791
+  data.tar.gz: f8b6b6efcc6c978d1a1ce7cece9040eb5475eb7baa58c6b1527ba2dc5bb780c8401f30917e62fcc43999224ecd755b136d03d05d79c03fdc26622efc306e02d3

data/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Release History
 
+### v0.23.0 / 2026-09-09
+
+This is a major release, with several new features, a number of fixes, and a significant refactor of the tool loading and execution layers, including several breaking interface changes. It is a release candidate for the upcoming version 1.0.
+
+Highlights include:
+
+* Major refactor of some of the larger classes that were doing too much: Extracted run logic out of `Toys::CLI` into `Toys::Runner`, extracted source configuration out of `Toys::Loader` into `Toys::SourceSpec` and `Toys::SourceList`, and extracted delimiter handling out of `Toys::Loader` into `Toys::ToolNameSplitter`. This cleaned up the architecture significantly, eliminating most back-references to the CLI object.
+* Added the ability to treat unknown flags as positional args via the `treat_unknown_flags_as_args` DSL directive and corresponding methods on `Toys::ToolDefinition`. Useful for wrapping and delegating to other commands.
+* Updates to error handling to improve the output and fix some long-standing issues related to tool delegation.
+* Several fixes to bundler integration, especially with Bundler 4.
+
+Details follow.
+
+* Changes to tool definition:
+    * BREAKING CHANGE: In a tool that delegates, `Toys::ToolDefinition#run_handler` now returns the delegate target (the target's full name as a frozen array of strings) instead of a Proc. The `run_handler=` setter still accepts only a proc, symbol, or nil, so delegation must still be configured via `delegate_to`.
+    * BREAKING CHANGE: The `validation_errors` field in `Toys::FlagGroup` classes now return strings rather than `Toys::ArgParser::FlagGroupConstraintError` objects.
+    * Added the `treat_unknown_flags_as_args` DSL directive (and the corresponding `ToolDefinition#treat_unknown_flags_as_args` setter and `ToolDefinition#unknown_flags_are_args?` query), which redirects unrecognized flags to the tool's positional arguments instead of reporting a usage error. Useful for wrapping and delegating to other commands.
+    * When two or more flags are declared using the same context key, within a flag group, the flag group's requirements now evaluate correctly.
+    * A flag or optional/remaining positional argument declared with a `nil` default no longer clears default data already set for the same key by an earlier declaration.
+    * `ToolDefinition#custom_context_directory=` and the corresponding `set_context_directory` DSL directive can take Pathname arguments and can handle relative paths (by expanding them into absolute paths).
+    * Toys now raises `Toys::ToolDefinitionError` if you attempt to "reset" a tool previously defined using a `Toys::Tool` subclass.
+    * SECURITY FIX: Toys now raises `Toys::ToolSourceError` if a tool loaded from a RubyGem attempts to load tools from the local file system.
+    * `Toys::ToolDefinition#add_flag_group` and `Toys::ToolDefinition#completion=` now properly raise ToolDefinitionError if the definition has already been finished.
+    * BREAKING CHANGE: Toys now raises `Toys::ToolDefintionError` if you attempt to create or descend into a subtool from a `subtool_apply` block or a middleware-based config.
+    * Caught additional cases of incorrectly located `Toys::Tool` subclasses and raised `Toys::ToolDefinitionError`.
+    * If `Toys::ToolDefinition#finish_definition` raises an error (e.g. due to a middleware issue), the tool now goes into an error state and refuses any operation unless it is reset.
+    * The root tool's display_name is now "(root)" instead of the empty string.
+
+* Changes to tool loading:
+    * BREAKING CHANGE: You no longer add sources to a `Toys::Loader` in place. Instead, construct a `Toys::SourceList` and add sources there, then pass it to the `Toys::Loader` constructor. (`Toys::CLI` has been modified to use this mechanism.)
+    * BREAKING CHANGE: Removed `Loader#split_path` and `Loader#split_partial_path` in favor of `Toys::ToolNameSplitter`. Use `Loader#tool_name_splitter` to get the name splitter object from a Loader. Related, `Loader.new` now takes a `tool_name_splitter` keyword argument in place of `extra_delimiters`. (`CLI.new` still takes `extra_delimiters`.)
+    * BREAKING CHANGE: `Toys::SourceInfo#apply_lib_paths` was replaced with `Toys::SourceInfo#find_lib_paths`, which returns a list of paths but does not actually `require` them. It is now the responsibility of the caller to do the `require`.
+    * BREAKING CHANGE: Removed git- and gem- specific attributes from `Toys::SourceInfo` and replaced with `Toys::SourceInfo#origin`.
+    * BREAKING CHANGE: `Toys::Loader#lookup_specific` now cannot take a tool name with delimiters. The tool name must be a string array.
+    * BREAKING CHANGE: Errors raised when the loader cannot open a tool source (e.g. a gem is missing) are now `Toys::ToolSourceError` instead of `Toys::ToolDefinitionError`.
+    * Added `Toys::SourceInfo#find_preload_files` which returns all files to preload.
+    * `Toys::Loader#list_subtools` now ensures returned tools have been finished by their middleware.
+    * The priority for the fallback root tool is now `-999_999_999` instead of `-999_999`. This value should still fit within the fixnum optimization.
+    * Directory contents are loaded in deterministic (sorted) order.
+
+* Changes to tool execution:
+    * New class `Toys::Runner` now directs tool execution (which previously was available only from `Toys::CLI`.) `Toys::Runner` provides finer-grained control over error handling, allowing independent control over `Toys::ContextualError` wrapping and error handler usage.
+    * Added `Toys::Context#runner` and `Toys::Context#loader` for easy access to those facilities from a running tool.
+    * BREAKING CHANGE: `Toys::Context#context_directory`, and `Toys::Context#get` with the associated context key, now never return nil. If no context directory is set for the tool, these now return the current working directory.
+    * Standard context keys and sentinels use the new class `Toys::UniqueKey`, which displays useful names in diagnostic output.
+    * Delegation now propagates the caller's verbosity to the delegate target, rather than resetting it to zero.
+    * When a tool delegates, a `SignalException` unhandled by the inner tool now propagates outward so each tool in the delegation chain gets a chance at its own `on_interrupt` / `on_signal` handler.
+    * A nested run that shares a logger with the run that called it now uses the base level already in effect for that logger, so verbosity no longer compounds across nested runs.
+    * BREAKING CHANGE: Several internal `Toys::ArgParser` changes: The constructor now takes the tool and loader instead of the CLI and tool, and the `default_data` keyword argument was renamed to `common_data`. It also no longer populates context keys such as `LOGGER` and `TOOL` that are not directly related to parsing; those must be passed in via `common_data`, and are generally handled by `Tool::Runner`.
+    * `Toys::ArgParser#data` now reflects the args, unmatched args, unmatched flags, unmatched positional, and usage errors accumulated so far while parsing, instead of only after `finish` is called.
+
+* Changes to the error handling system, particularly important if you provide a custom error handler:
+    * BREAKING CHANGE: `Toys::ContextualError` no longer wraps `SignalException`. Custom error handlers should be prepared to handle `SignalException` directly.
+    * BREAKING CHANGE: Custom error handlers should also be prepared to handle unwrapped `StandardError` and `ScriptError` exceptions directly, since it is now possible to disable `Toys::ContextualError` wrapping.
+    * An error raised by a delegated tool now raises nested `ContextualError` objects providing information about the inter-tool call sequence, one wrapper per tool in the chain. This might happen, for example, if a tool was delegated or if a subtool was called without an error handler. In normal runs, this displays both the delegating and original tools in the error message. It also means custom error handlers should use the new `Toys::ContextualError#root_cause` if they want the original exception.
+    * `ContextualError` now sets its backtrace from the wrapped error's backtrace locations when available (falling back to the backtrace strings), so an enclosing capture can still locate the config file line.
+    * Renamed `config_path` and `config_line` to `tool_file_path` and `tool_file_line`. The original names have been aliased for backward compatibility.
+    * `ContextualError` now captures tool names in more places, and captures the current phase (loading or running).
+    * Revamped the exception output provided by `Toys::Utils::StandardUI` so it's more compact and usable.
+
+* Changes to the shell completion system:
+    * BREAKING CHANGE: Minor simplifications to the completion internals, notably `Toys::Completion::Context#fragment_prefix` has been removed, and `prefix_constraint` has been removed from several provided completions. A completion now always receives the entire word under the cursor as its `fragment`, and every candidate must be a replacement for the entire word. (The prefix handling requirements of the Bash completion have been moved up into `Toys::Utils::CompletionEngine`.)
+    * BREAKING CHANGE: The Bash and Zsh completion engine constructors now take a completion and a loader instead of a cli, and some of the internals and override points have been reorganized.
+    * Fixed shell completion for non-flag words containing `=` or `:`: completions are now computed against the whole word, and the engine trims candidates to the span the shell will actually replace.
+    * Zsh completion now replaces the entire word rather than only the text after an `=` or `:`, matching how zsh actually handles word breaks; bash continues to break at `=` and `:`.
+    * Word-break trimming for bash now ignores `=` and `:` characters that were quoted or backslash-escaped, since the shell does not break a word at a quoted character.
+    * Subtool completion now uses the loader's configured delimiters to decide where a tool path ends, rather than a separate regex over the fragment prefix, so completing a partially typed tool path works consistently with any configured extra delimiters.
+
+* Changes to the CLI interfaces:
+    * Added `add_source` method that takes an instance of the new `Toys::SourceSpec` types that describe a tool source. This method replaces the now deprecated `add_config_*` methods (although those methods will continue to be supported for a time). In general, the "config" terminology is being retired in favor of "source" which I think better describes what is going on.
+    * BREAKING CHANGE: The `config_file_name` and `config_dir_name` arguments to CLI have been renamed to `toplevel_tool_file_name` and `toplevel_tool_dir_name`, respectively, as part of a general removal of the "config" term. The old names are not aliased.
+    * BREAKING CHANGE: It is no longer possible to configure the index file name, lib and data directory names, and preload names, via keyword arguments. This was done to simplify the CLI and Loader interfaces, and because I realized that if they ever were to be customizable, it would need to be per source directory rather than per-CLI.
+    * BREAKING CHANGE: `Toys::CLI#run` no longer accepts the `delegated_from:` keyword argument. Tool delegation is now handled internally, and its runtime is not exposed in the public interface.
+    * You can get the `Toys::Runner` for a CLI using `Toys::CLI#runner`, providing a way to customize the run process more closely than using `Toys::CLI#run`.
+    * Path parameters for the methods that add sources, such as `path` and `context_directory`, can now take Pathname objects and can handle relative paths properly (by expanding them into absolute paths).
+    * `Toys::CLI#child` accepts `copy_sources: true`, which populates the new CLI's loader with the same sources as the original. This makes it easy to create a new CLI with additional sources on top of the current.
+    * The `Toys::CLI` constructor now takes `git_cache` and `gems_util` keyword arguments letting you customize the objects used to resolve git and gem sources.
+    * Calling `Toys::CLI#add_search_path` with a nonexistent directory no longer raises.
+    * The ApplyConfig middleware now behaves correctly when configured globally in the CLI or loader.
+
+* Rubygems/Bundler integration changes:
+    * Bundler integration requires Bundler 2.4 or later. This is the default on Ruby 3.2, but requires that Bundler is updated on earlier Rubies.
+    * Bundler integration properly detects provenance attributes such as `path:` and `git:`.
+    * Calling bundler integration with a nonempty group list no longer loses gems that were already loaded.
+    * Bundler integration now honors `BUNDLE_LOCKFILE` (new in Bundler 4) and stops leaking it from the modified bundle.
+
+* Other fixes
+    * Terminal mixin now raises the correct ArgumentError (instead of NameError) if given an unknown style code.
+
+### 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,35 +79,39 @@ 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_source 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
-the "root tool", i.e. what happens when you run the executable without passing
-a tool name to it. (In fact, it's technically legal to do this in Toys as well,
+flags, and functionality directly in the source 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 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.)
 
@@ -107,44 +119,51 @@ by setting functionality at the "top level" of a `.toys.rb` file without any
 
 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:
+nested tools, by writing `tool` sub-blocks within your source block. 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 source block as follows ...
+cli.add_source 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
+Notice that the description set at the "root" of the source block (outside the
 tool blocks) shows up here.
 
 ### Configuring the CLI
@@ -157,43 +176,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 source block as follows ...
+cli.add_source 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 +227,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 source block ...
+cli.add_source 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 +267,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 +287,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 +306,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 +346,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