toys 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 655d198d4597ba9c37fcc968d0e8a79782ef6d54736c821d157dea3b9cb1bec1
-  data.tar.gz: 12b95827ad721652171dd6b0de05eda69ffa6fed5b823313de4626c9a8ed8f45
+  metadata.gz: e3835e01039a57776c3ae00091c53153166a723210e73e098b6af38d901c3066
+  data.tar.gz: e1efc2f269501b0a218522d929ce1d1ea50662045ab4ca03c9b4d63c8e68cdd9
 SHA512:
-  metadata.gz: b5d089ca709d0516a60d91ad8a47e92ba88aad1e761a3c78952cb3338c7146f761490baab0dd96f2cd9090179622772a04332c1eee124c85e4e86214afa67e39
-  data.tar.gz: f0b2471d424cc9da3d0570ff309f6bf2723a11b8fe0d5c2fb6e330c2e0deb768ebc13a4fa2238a30f9c602073539a2aedaf02bf4f63e3b05cb86ff6ccb5ea1a8
+  metadata.gz: 8b64f1f36da5faeebeee80456ab33247f90311f5e98bdd8ba7a68a2da8e83326e02aff9f8be877c076739c96127501b07208cec8009b4bf85bd170a328c19aa4
+  data.tar.gz: 5a178132d475dff414a6c134313412a484f6700cb5900394e5d3fe3f7ec7e6c00005d6f4471173d74b3a9a989bdacf9723934ec83b08c760ab21ee90a8f9e572

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Release History
 
+### v0.17.0 / 2025-11-07
+
+Toys 0.17 includes several significant new pieces of functionality:
+
+* Support for loading tools from Rubygems. The load_gem directive loads tools from the "toys" directory in a gem, installing the gem if necessary. This makes it easy to distribute tools, securely and versioned, as gems.
+* Flag handlers can now take an optional third argument, the entire options hash. This enables significantly more powerful behavior during flag parsing, such as letting flags affect the behavior of other flags.
+
+Additional new features:
+
+* When using the :gems mixin, you can now specify installation options such as on_missing not only when you include the mixin, but also when you declare the gem.
+* Added support for an environment variable `TOYS_GIT_CACHE_WRITABLE` to disable the read-only behavior of git cache sources. This improves compatibility with environments that want to delete caches.
+
+Other fixes and documentation:
+
+* Added the standard logger gem to the toys-core dependencies to silence Ruby 3.5 warnings.
+* Updated the user guide to cover new features and fix some internal links
+
 ### v0.16.0 / 2025-10-31
 
 * ADDED: Updated minimum Ruby version to 2.7

data/docs/guide.md

@@ -54,7 +54,8 @@ forms, which appear in different styles of help.
 
 Toys searches for tools in specifically-named **Toys files** and **Toys
 directories**. It searches for these in the current directory, in parent
-directories, and in the Toys **search path**.
+directories, and in the Toys **search path**. You can also distribute tools in
+gems or via git.
 
 Toys provides various features to help you write tools. This includes providing
 a **logger** for each tool, **mixins** that provide common functions a tool can
@@ -221,7 +222,7 @@ flag, but it has no additional effect.) Namespaces also support the following
 additional flags:
 
 *   `--all` which displays all subtools, including
-    [hidden subtools](#Hidden_tools) and namespaces.
+    [hidden subtools](#hidden-tools) and namespaces.
 *   `--no-recursive` which displays only immediate subtools, instead of the
     default behavior of showing all subtools recursively.
 *   `--search=TERM` which displays only subtools whose name or description
@@ -267,7 +268,7 @@ you could do this:
     $ toys do build --staging , test --help
 
 Each tool can choose which behavior it will support, whether or not to enforce
-[flags before positional args](#Enforcing_flags_before_args).
+[flags before positional args](#enforcing-flags-before-args).
 
 You can also, of course, stop recognizing flags on the command line by passing
 `--` as an argument.
@@ -275,7 +276,7 @@ You can also, of course, stop recognizing flags on the command line by passing
 ### Tab completion
 
 If you are using the Bash shell, Toys provides custom tab completion. See
-[this section](#Installing_tab_completion_for_Bash) for instructions on
+[this section](#installing-tab-completion-for-bash) for instructions on
 installing tab completion.
 
 Toys will complete tool and subtool names, flags, values passed to flags, and
@@ -511,7 +512,7 @@ an example:
                  long_desc: ["Long descriptions can have multiple lines.",
                              "This is the second line."]
 
-See the [above section on Descriptions](#Tool_descriptions) for more
+See the [above section on Descriptions](#tool-descriptions) for more
 information on how descriptions are rendered and word wrapped.
 
 Because long descriptions may be unwieldly to write as a hash argument in this
@@ -556,7 +557,7 @@ and
 [OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
 
 You can also create **custom acceptors**. See the
-[section below on Custom Acceptors](#Custom_acceptors) for more information.
+[section below on Custom Acceptors](#custom-acceptors) for more information.
 
 #### Argument completions
 
@@ -768,7 +769,7 @@ and
 [OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
 
 You can also create **custom acceptors**. See the
-[section below on Custom Acceptors](#Custom_acceptors) for more information.
+[section below on Custom Acceptors](#custom-acceptors) for more information.
 
 #### Defaults and handlers
 
@@ -791,15 +792,25 @@ will be `false`, i.e. the last value set on the command line. This is because a
 flag normally *sets* its option value, replacing any previously set value.
 
 You can, however, change this behavior by providing a **handler**. A handler is
-a Ruby Proc that defines what a flag does to its option value. It takes two
-arguments, the new value given, and the previously set value (which might be
-the default value if this is the first appearance of the flag), and returns the
-new value that should be set.
+a Ruby Proc that defines what a flag does to its option value. It takes up to
+three arguments:
+
+1.  The new value given
+2.  The previously set value (which might be the default value if this is the
+    first appearance of the flag)
+3.  A hash containing all the options set so far
+
+The proc must then return the new value for the option.
+
+If the proc takes three arguments, it can use the third argument to read and/or
+modify any other option. This enables powerful abilities such as flags that
+affect the behavior of other flags.
 
 Effectively, the default behavior (setting the value and ignoring the previous
-value) is equivalent to the following handler:
+value) is equivalent to the following handler that takes only the first
+argument:
 
-    flag :shout, "--[no-]shout", handler: proc { | val, _prev| val }
+    flag :shout, "--[no-]shout", handler: proc { | val| val }
 
 Toys gives the default handler the special name `:set`. So the above is also
 equivalent to:
@@ -827,7 +838,7 @@ Note that both flags affect the same option name,
 {Toys::Context::Key::VERBOSITY}. The first increments it each time it appears,
 and the second decrements it. A tool can query this option and get an integer
 telling the requested verbosity level, as you will see
-[below](#Logging_and_verbosity).
+[below](#logging-and-verbosity).
 
 Toys provides a few built-in handlers that can be specified by name. We already
 discussed the default handler that can be specified by its name `:set` or by
@@ -855,7 +866,7 @@ directive. The `desc:` argument takes a single string description, while the
          long_desc: ["Long descriptions can have multiple lines.",
                      "This is the second line."]
 
-See the [above section on Descriptions](#Tool_descriptions) for more information on
+See the [above section on Descriptions](#tool-descriptions) for more information on
 how descriptions are rendered and word wrapped.
 
 Because long descriptions may be unwieldly to write as a hash argument in this
@@ -978,7 +989,7 @@ your tools.
 
 Note: If you do not define the `run` method for a tool, Toys provides a default
 implementation that displays the tool's help screen. This is typically used for
-namespaces, as we shall see [below](#Namespaces_and_subtools). Most tools,
+namespaces, as we shall see [below](#namespaces-and-subtools). Most tools,
 however, should define `run`.
 
 Let's revisit the "greet" example we covered earlier.
@@ -1160,7 +1171,7 @@ our greet tool would look like as a class:
 Defining tools as clases is useful if you want your Toys files to look a bit
 more like normal Ruby or you want to avoid long blocks. Additionally, they can
 be useful to scope constants, which otherwise would be visible throughout the
-entire file, as noted in the [section on using constants](#Using_constants).
+entire file, as noted in the [section on using constants](#using-constants).
 
 When you define a tool as a class, Toys infers the tool name by converting the
 class name to "kebab-case". For example, the `Greet` class above would define a
@@ -1231,7 +1242,7 @@ styles. Define tools either as classes or as blocks, not both.
 ## Understanding Toys files
 
 Toys commands are defined in Toys files. We covered the basic syntax for these
-files in the [above section on defining tools](#Defining_tools). In this
+files in the [above section on defining tools](#defining-tools). In this
 section, we will take a deeper look at what you can do with Toys files.
 
 ### Toys directories
@@ -1336,7 +1347,7 @@ in the separate file `.toys/test/unit.rb`.
 Toys also loads the index file in a directory *before* any other files in that
 directory. This means they are convenient places to define shared code that can
 be used by all the subtools defined in that directory, as we shall see later in
-the [section on sharing code](#Sharing_code).
+the [section on sharing code](#sharing-code).
 
 ### The Toys search path
 
@@ -1393,7 +1404,7 @@ so, use the directive {Toys::DSL::Tool#truncate_load_path!}. This directive
 removes all directories further down the search path. It can be used, for
 example, to disable global tools when you run Toys from the current directory.
 It can also be useful if you are using
-[Bundler integration](#Using_bundler_with_a_tool) to prevent bundle conflicts
+[Bundler integration](#using-bundler-with-a-tool) to prevent bundle conflicts
 with parent directories, by disabling tools from parent directories.
 
 The `truncate_load_path!` directive works only if no tools from further down
@@ -1402,11 +1413,216 @@ if it fails to truncate the load path. In most cases, Toys is very smart about
 loading tools only when needed, but there are exceptions. To minimize the
 chance of problems, if you need to use `truncate_load_path!`, locate it as
 early as possible in your Toys files, typically at the top of the
-[index file](#Index_files).
+[index file](#index-files).
+
+### Sharing tool definitions
+
+It is a common practice to "share" tools across projects, that is, to implement
+tools in a central place and reference them from potentially multiple toys
+files. You can do this by "loading" remote tools from a toys file. You can load
+tools from a file path on your local file system, from a git repository, or
+even from a Ruby gem.
+
+#### Loading from the file system
+
+To load a tool from the file system, use the `load` directive, providing a path
+to a file or directory. This will behave as though the file or directory's
+contents were inserted in the current location.
+
+As an example, if you had a shared file `/var/share/mytools.rb` as follows:
+
+    # /var/share/mytools.rb
+    tool "foo" do
+      def run
+        puts "Running foo"
+      end
+    end
+    tool "bar" do
+      def run
+        puts "Running bar"
+      end
+    end
+
+You could instantiate it in your toys file as follows:
+
+    # .toys.rb
+    load "/var/share/mytools.rb"
+
+This has the effect of copying the _contents_ of `mytools.rb` into where it is
+being referenced. In this case, it defines the two tools "foo" and "bar" at the
+top level of your toys file.
+
+Note that when you load a file, the name of the file does not define a tool or
+a tool namespace. In the above case, the tools "foo" and "bar" are defined,
+_not_ "mytools foo" or "mytools bar". Avoid the common mistake of referencing a
+file that defines at the top level and not loading it inside a tool. For
+example, consider a shared file `/var/share/single-tool.rb`:
+
+    # /var/share/single-tool.rb
+    desc "This file defines a tool at the top level"
+    def run
+      puts "Running the top level of single-tool.rb"
+    end
+
+If you load it like follows:
+
+    # .toys.rb
+    load "/var/share/single-tool.rb"
+
+You will define the run method of the _root tool_. Instead, what you probably
+want is:
+
+    # .toys.rb
+    tool "my-single-tool" do
+      load "/var/share/single-tool.rb"
+    end
+
+Equivalently, you can say:
+
+    # .toys.rb
+    load "/var/share/single-tool.rb", as: "my-single-tool"
+
+You can also use the `load` directive to load an entire directory. Again, this
+will be have as though the directory's contents are inserted at the load point.
+The contents of any `.toys.rb` index file will be defined at the load point
+itself, and other files within the directory and subdirectories will be
+namespaced accordingly.
+
+As an example, consider this shared directory:
+
+    /var/share/mytools
+    |
+    +- .toys.rb
+    |
+    +- greet.rb
+
+Here's the contents of `.toys.rb` above:
+
+    # /var/share/mytools/.toys.rb
+    tool "foo" do
+      def run
+        puts "Running foo"
+      end
+    end
+
+Here's the contents of `greet.rb`:
+
+    # /var/share/mytools/greet.rb
+    optional_arg :whom, default: "world"
+    def run
+      puts "Hello, #{whom}"
+    end
+
+You can then define the tools "foo" and "greet" by loading this directory:
+
+    # .toys.rb
+    load "/var/share/mytools"
+
+#### Loading from a git repository
+
+You can also load tools over a network using git, by defining the tools in a
+git repository (e.g. on GitHub) and referencing it via the `load_git`
+directive. This is a simple way to distribute tools across an organization or
+over the internet.
+
+The `load_git` directive takes a repository URL, and optionally a path within
+the repository and a commit. If you do not specify the path, the entire
+repository is loaded as if you were loading a directory. (See the discussion
+above on loading from the file system.) Otherwise, if you specify a path, it
+should be a file or a directory within the repository. A commit can be a SHA,
+a branch, or a tag. If it is omitted, the default HEAD of the repository is
+used.
+
+As an example, suppose you have a repository `https://github.com/dazuma/example`
+(not a real repo...), with the file `greet.rb` at the top level. You can then
+reference that tool as follows:
+
+    # .toys.rb
+    load_git remote: "https://github.com/dazuma/example",
+             path: "greet.rb",
+             as: "greet"
+
+As discussed earlier, if you are loading a file that includes definitions at
+the top level, make sure you load it inside a tool, or use the `as:` parameter.
+
+The `load_git` directive uses the Git Cache to download and reference files in
+git repositories. This means if you omit the commit or set it to a reference
+that can float such as a branch or HEAD, it is possible you might get a stale
+commit, if the repository was previously pulled into the cache, and then
+additional commits were subsequently pushed to the remote repo. To ensure you
+get the latest data from `load_git`, you can set the `update:` parameter. If
+set to true, this forces the cache to refresh (i.e. git pull). You can also set
+it to an integer, representing a cache lifetime in seconds; the cache will
+refresh only if it has been at least that long since the last refresh.
 
-### Loading remote files
+    # .toys.rb
+    load_git remote: "https://github.com/dazuma/example",
+             path: "greet.rb",
+             as: "greet",
+             update: 3600  # Pull the latest HEAD if the cache is an hour old
 
-(TODO)
+#### Loading from a Ruby gem
+
+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.
+
+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
+executables (often in a top level `bin` directory), and sometimes a few
+documentation files. However, it's just a zip file and you can put anything in
+it, including toys files.
+
+By convention, toys tools live in the top level `toys` directory in a gem. For
+example, you could publish a gem called "my-tools" and include `toys/greet.rb`.
+Then, to reference the tool:
+
+    # .toys.rb
+    load_gem "my-tools"
+
+This will define the tool "greet". In the process, it will ensure the gem is
+installed and loaded (prompting you to confirm the install from rubygems.org if
+necessary).
+
+You can specify gem version requirements by providing the `version:` parameter.
+For example:
+
+    # .toys.rb
+    load_gem "my-tools", version: ["~> 1.5", ">= 1.5.2"]
+
+It takes version requirements in the format used by Rubygems and Bundler. You
+can pass a single requirement, multiple requirements as an array, or none.
+
+You can also specify a subpath within the gem to load. The subpath is relative
+to the "toys" root directory in the gem. For example:
+
+    # .toys.rb
+    load_gem "my-tools", path: "greet.rb", as: "greet"
+
+As before, if you are loading a file that includes definitions at the top
+level, make sure you load it inside a tool, or use the `as:` parameter.
+
+By default, `load_gem` looks inside the `toys` top level directory of a gem.
+Although this is not recommended, if you need to change this default, you can
+set the gem's `"toys_dir"` metadata to a different directory name. If this
+metadata is set, `load_gem` will use it as the toys top level directory for
+that gem.
+
+Additionally, you can pass a top level directory name in the `load_gem`
+directive itself. This can be useful if a gem has multiple toys directories:
+
+    # .toys.rb
+    load_gem "my-tools", toys_dir: "uncommon-tools"
+
+#### Publishing a tools Ruby gem
+
+Publishing a Ruby gem that includes tools is as simple as publishing a gem with
+the tool files in an extra `toys` directory.
+
+Another benefit of distributing tools via Ruby gem is that the gem's library
+files can be used in the tools' implementations. When `load_gem` is run, the
+gem is activated so its library directory is made available in the require
+path. This may be simpler than using `.lib` directories as described later.
 
 ## The execution environment
 
@@ -1465,7 +1681,7 @@ integer context value that you can retrieve using the `VERBOSITY` context key
 or {Toys::Context#verbosity}. The verbosity is set to 0 by default. This
 corresponds to a logger level of `WARN`. That is, warnings, errors, and fatals
 are displayed, while infos and debugs are not. However,
-[as we saw earlier](#Standard_flags), most tools automatically respond to the
+[as we saw earlier](#standard-flags), most tools automatically respond to the
 `--verbose` and `--quiet` flags, (or `-v` and `-q`), which increment and
 decrement the verbosity value, respectively. If you pass `-v` to a tool, the
 verbosity is incremented to 1, and the logger level is set to `INFO`. If you
@@ -1491,14 +1707,14 @@ execute, and return a process status code (i.e. 0 for success, and nonzero for
 error). Make sure you handle the exit status. For example, in most cases, you
 should probably exit if the tool you are calling returns a nonzero code.
 
-You can also use the `exec` mixin [described below](#Executing_subprocesses) to
+You can also use the `exec` mixin [described below](#executing-subprocesses) to
 run a tool in a separate process. This is particularly useful if you need to
 capture or manipulate that tool's input or output stream.
 
 ### Helper methods and mixins
 
 The methods of {Toys::Context} are not the only methods available for your tool
-to call. We [saw earlier](#Tool_execution_basics) that a tool can define
+to call. We [saw earlier](#tool-execution-basics) that a tool can define
 additional methods that you can use as helpers.
 
 You can also include **mixins**, which are modules that bring in a whole set of
@@ -1522,7 +1738,7 @@ For details on the built-in mixins provided by Toys, see the modules under
 mixins below. Built-in mixins have names that are symbols.
 
 You can also define your own mixins, as we will see in the
-[upcoming section on defining mixins](#Defining_mixins).
+[upcoming section on defining mixins](#defining-mixins).
 
 ### Executing subprocesses
 
@@ -1582,7 +1798,7 @@ underlying library {Toys::Utils::Pager}.
 
 You can also use other third-party gems such as
 [tty](https://github.com/piotrmurach/tty). The section below on
-[useful gems](#Useful_gems) provides some examples.
+[useful gems](#useful-gems) provides some examples.
 
 ### Standard base directories
 
@@ -1621,7 +1837,7 @@ classes, and constants, that you might define in your tools.
 
 ### Defining mixins
 
-We [saw earlier](#Helper_methods_and_mixins) that you can mix a module (with
+We [saw earlier](#helper-methods-and-mixins) that you can mix a module (with
 all its methods) into your tool using the `include` directive. You can specify
 a module itself, or the name of a built-in mixin such as `:exec` or
 `:terminal`. But you can also define your own mixin using the `mixin`
@@ -1636,7 +1852,7 @@ includes the mixin, in the same way that you can include a Ruby module.
 
 (Note that, unlike full modules, mixins allow only methods to be shared. Mixins
 do not support constants. See the next section on
-[using constants](#Using_constants) to learn how Toys handles constants.)
+[using constants](#using-constants) to learn how Toys handles constants.)
 
 Here's an example. Suppose you had common setup code that you wanted to share
 among your testing tools.
@@ -1675,7 +1891,7 @@ descendant tools defined in that same directory, but not in a different `.toys`
 directory.
 
 A common technique, for example, would be to define a mixin in the
-[index file](#Index_files) in a Toys directory. You can then include it from
+[index file](#index-files) in a Toys directory. You can then include it from
 any subtools defined in other files in that same directory.
 
 #### Mixin initializers
@@ -1855,7 +2071,7 @@ development, including templates that generate build, test, and documentation
 tools. The `:minitest` template illustrated above is one of these built-in
 templates. Like built-in mixins, built-in template names are always symbols.
 You can read more about them in the next section on using
-[Toys as a Rake replacement](#Toys_as_a_Rake_replacement).
+[Toys as a Rake replacement](#toys-as-a-rake-replacement).
 
 You can also write your own templates. Here's how...
 
@@ -1968,8 +2184,12 @@ For more complicated tools, you might want to write normal Ruby modules and
 classes as helpers. Toys provides a way to write Ruby code outside of its DSL
 and `require` the code from your tool, using `.lib` directories.
 
+Note: If you are writing tools for distribution in a Ruby gem as described
+[earlier](#publishing-a-tools-ruby-gem), consider simply defining your Ruby
+modules and classes in the gem's lib directory instead of using this mechanism.
+
 To use `.lib` directories, you must define your tools inside a
-[Toys directory](#Toys_directories). When a tool is executed, it looks for
+[Toys directory](#toys-directories). When a tool is executed, it looks for
 directories called `.lib` in the Toys directory, and adds them to the Ruby load
 path. Your tool can thus call `require` to load helpers from any Ruby files in
 a `.lib` directory.
@@ -2060,7 +2280,7 @@ classes, modules, and other code. But preloaded files *automatically* loaded
 (i.e. you do not `require` them explicitly) *before* your tools are defined.
 
 To use preloaded files, you must define your tools inside a
-[Toys directory](#Toys_directories). Before any tools inside a directory are
+[Toys directory](#toys-directories). Before any tools inside a directory are
 loaded, any file named `.preload.rb` in the directory is automatically
 required. Next, any Ruby files inside a subdirectory called `.preload` are also
 automatically required.
@@ -2116,7 +2336,7 @@ tests, and a set of helpers that make it easy to test tools and parts of tools.
 
 Toys integrates with [Minitest](https://github.com/seattlerb/minitest) to
 provide a testing framework for your tools. To write tests, you must define
-your tools inside a [Toys directory](#Toys_directories). Create a directory
+your tools inside a [Toys directory](#toys-directories). Create a directory
 called `.test` inside that directory. You can then write Minitest tests in
 files within that directory with names matching `test_*.rb`. You can also
 provide other files that do not match that name pattern, as fixture data or
@@ -2482,7 +2702,7 @@ flexible tool than Rake, and it covers two cases that are not well served by
 
 First, Toys lets you define *global tools* that are defined in your home
 directory or system config directory. (See the previous section on
-[the Toys search path](#The_Toys_search_path).) These tools are global, and can
+[the Toys search path](#the-toys-search-path).) These tools are global, and can
 be called from anywhere. But if they have gem dependencies, it might not be
 feasible for their Gemfiles to be present in every directory from which you
 might want to run them.
@@ -2520,7 +2740,7 @@ Simply `include :bundler` in your tool definition:
     end
 
 When the `:bundler` mixin is included in a tool, it installs a
-[mixin initializer](#Mixin_initializers) that calls `Bundler.setup` when the
+[mixin initializer](#mixin-initializers) that calls `Bundler.setup` when the
 tool is *executed*. This assumes the bundle is already installed, and brings
 the appropriate gems into the Ruby load path. That is, it's basically the same
 as `bundle exec`, but it applies only to the running tool.
@@ -2548,14 +2768,14 @@ your tools. For example:
     end
 
 See the section on
-[applying directives to multiple tools](#Applying_directives_to_multiple_tools)
+[applying directives to multiple tools](#applying-directives-to-multiple-tools)
 for more information on `subtool_apply`.
 
 #### Bundler options
 
 By default, the `:bundler` mixin will look for a `Gemfile` within the `.toys`
 directory (if your tool is defined in one), and if one is not found there,
-within the [context directory](#The_context_directory) (the directory
+within the [context directory](#the-context-directory) (the directory
 containing your `.toys` directory or `.toys.rb` file), and if one still is not
 found, in the current working directory. You can change this behavior by
 passing an option to the `:bundler` mixin. For example, you can search only the
@@ -2651,7 +2871,7 @@ tools:
 There is a big caveat to using `static: true`, which is that you are setting up
 a bundle immediately, and as a result any subsequent attempt to set up or use a
 different bundle will fail. (See the section on
-[bundle conflicts](#Solving_bundle_conflicts) for a discussion of other reasons
+[bundle conflicts](#solving-bundle-conflicts) for a discussion of other reasons
 this can happen.) As a result, it's best not to use `static: true` unless you
 *really* need it to define tools. If you do run into this problem, here are two
 things you could try:
@@ -2664,7 +2884,7 @@ things you could try:
  2. Failing that, if you need a particular gem in order to define a tool, you
     could consider activating the gem directly rather than as part of a bundle.
     See the following section on
-    [Activating gems directly](#Activating_gems_directly) for details on this
+    [Activating gems directly](#activating-gems-directly) for details on this
     technique.
 
 ### Activating gems directly
@@ -3573,7 +3793,7 @@ like we did with the test tool above.
 
 If you need to access information from enclosing scopes, consider instead
 setting options using the {Toys::DSL::Tool#static} directive, as illustrated
-earlier when we discussed [defining templates](#Defining_templates).
+earlier when we discussed [defining templates](#defining-templates).
 
     tool "def-time" do
       # Grab the time during tool definition and set it as a static option. 
@@ -3592,7 +3812,7 @@ provides a convenient place to put data files that can be looked up by tools
 either during definition or runtime.
 
 To use data files, you must define your tools inside a
-[Toys directory](#Toys_directories). Within the Toys directory, create a
+[Toys directory](#toys-directories). Within the Toys directory, create a
 directory named `.data` and copy your data files there.
 
 You mcanay then "find" a data file by providing the relative path to the file from
@@ -3747,7 +3967,7 @@ the entire toys directory structure. So if your tool definition is inside a
 
 This technique is particularly useful for build tools. Indeed, all the build
 tools described in the section on
-[Toys as a Rake Replacement](#Toys_as_a_Rake_replacement) automatically move
+[Toys as a Rake Replacement](#toys-as-a-rake-replacement) automatically move
 into the context directory when they execute.
 
 #### Changing the context directory

data/lib/toys/version.rb

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

metadata

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