toys 0.9.4 → 0.10.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61f79d9f7f044f396ffee09be4d6c3b9e4c758528b2fbc217c951d73e15f8750
-  data.tar.gz: 454e1c492241769432ac58782d52cc5c87b106ee18a16fc083c6ebd09f97a0e5
+  metadata.gz: 2df55870f3530617a4961bb0cfa09d0752bb13e99f7642a4156ab4b7ffea3a8c
+  data.tar.gz: 74131a75411c11703347193f167c916e351fa3582401d0505036cd74dbb9911c
 SHA512:
-  metadata.gz: 9dadef613e97d409603869f8c812c7a690e467c7719dcd9893d7d0efff627954f07ff237cae99742efbef5e1988e55c288a1fc26d265fa15ac1b0b2b485a12c9
-  data.tar.gz: 5194bb826ca09d62f4a48eb78122dcf8d3653bfa97107e8042748357226a4e37d5c8fd06970d714c29a053a61a312ef3461dc9c7ea5ba63140fe730a884d6faf
+  metadata.gz: ff5a5e3e2c2fea1bebdcfbeef064bd51d5a587a48077b7ee6c6b4befe926433d0318ce5c4b8c63a067e8b4e6dbd21f191c86b11844e8e1ff9d8c6096cffad996
+  data.tar.gz: 464d5d87896965c77182d6f7f3793b23bbf9797439619c01b9142516bb71077f44a5c53e81492017890e8fd9db1cb7d5c9e83bed1ea68741f716d94833e7e3b6

data/.yardopts

@@ -3,7 +3,8 @@
 --markup=markdown
 --markup-provider redcarpet
 --main=README.md
-./lib/**/*.rb
+./lib/toys/**/*.rb
+./lib/toys.rb
 -
 README.md
 LICENSE.md

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Release History
 
+### 0.10.4 / 2020-07-11
+
+* IMPROVED: Bundler integration can now handle Toys itself being in the bundle, as long as the version requirements cover the running Toys version.
+* IMPROVED: Passing `static: true` to the `:bundler` mixin installs the bundle at definition rather than execution time.
+
+### 0.10.3 / 2020-07-04
+
+* FIXED: The `exec_separate_tool` method in the `:exec` mixin no longer throws ENOEXEC on Windows.
+
+### 0.10.2 / 2020-07-03
+
+* FIXED: The load path no longer loses the toys and toys-core directories after a bundle install.
+
+### 0.10.1 / 2020-03-07
+
+* FIXED: Setting `:exit_on_nonzero_status` explicitly to false now works as expected.
+
+### 0.10.0 / 2020-02-24
+
+* ADDED: `:bundler` mixin that installs and sets up a bundle for the tool
+* ADDED: `bundler` options in the standard templates, to run those tools in a bundle
+* ADDED: `subtool_apply` directive which applies a block to all subtools.
+* ADDED: Add `.lib` directories to the Ruby load path when executing a tool.
+* ADDED: `toys_version?` and `toys_version!` directives that check against version requirements.
+* ADDED: `exec_separate_tool` and `capture_separate_tool` methods in the `:exec` mixin, to support executing tools in a separate process without forking
+* IMPROVED: `long_desc` directive can now read the description from a text file.
+* IMPROVED: The `tool` directive can take delimited strings as tool names.
+* IMPROVED: Subtool blocks aren't actually executed unless the tool is needed.
+* CHANGED: Added `on_missing` and `on_conflict` arguments to `Toys::Utils::Gems` constructor (which also affects the `:gems` mixin), and deprecated `suppress_confirm` and `default_confirm`.
+* CHANGED: Tightened `rdoc` template's default gem version to `~> 6.1.0`.
+* FIXED: `rdoc` template crashed if any nonstandard options were given.
+* FIXED: `rubocop` template would abort prematurely if standard streams were redirected.
+
 ### 0.9.4 / 2020-01-26
 
 * FIXED: Crash in the loader when a non-ruby file appears in a toys directory

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2019 Daniel Azuma
+Copyright 2019-2020 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

@@ -91,7 +91,7 @@ automatically generates a full help screen, which you can view using the
 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
 also read multiple files if it finds them, so you can "scope" your tools more
-specifically or generally by locating them in your directory hierarchy. 
+specifically or generally by locating them in your directory hierarchy.
 
 If you want to define "global" tools that apply anywhere, write a Toys file
 either in your home directory, or in the system configuration directory
@@ -204,7 +204,7 @@ 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
 demonstrated in the example. Some other Toys features might also emit log
 entries: the `:exec` mixin, for example, by default logs every external command
-it runs (although this can be customized). 
+it runs (although this can be customized).
 
 By default, only warnings and higher severity logs are displayed, but you can
 change that by applying the `--verbose` or `--quiet` flags as we have done
@@ -318,7 +318,7 @@ Toys scripts instead of Rakefiles.
 
 ## License
 
-Copyright 2019 Daniel Azuma
+Copyright 2019-2020 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/bin/toys

@@ -1,30 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 ::ENV["TOYS_BIN_PATH"] ||= ::File.absolute_path(__FILE__)
+::ENV["TOYS_LIB_PATH"] ||= ::File.absolute_path(::File.join(::File.dirname(__dir__), "lib"))
 
-$LOAD_PATH.unshift(::File.absolute_path(::File.join(::File.dirname(__dir__), "lib")))
+$LOAD_PATH.delete(::ENV["TOYS_LIB_PATH"])
+$LOAD_PATH.unshift(::ENV["TOYS_LIB_PATH"])
 require "toys"
 
 exit(::Toys::StandardCLI.new.run(::ARGV))

data/builtins/do.rb

@@ -1,25 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-
 desc "Run multiple tools in order"
 
 long_desc \

data/builtins/system.rb

@@ -1,25 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-
 desc "A set of system commands for Toys"
 
 long_desc "Contains tools that inspect, configure, and update Toys itself."
@@ -44,6 +24,7 @@ tool "update" do
   include :terminal
 
   def run
+    require "rubygems"
     configure_exec(exit_on_nonzero_status: true)
     version_info = spinner(leading_text: "Checking rubygems for the latest release... ",
                            final_text: "Done.\n") do

data/docs/guide.md

@@ -1698,7 +1698,7 @@ the module.
 
 ### Templates
 
-One final way to share code is to expand a **template**.
+Another way to share code is to expand a **template**.
 
 A template is a class that inserts a bunch of lines into a Toys file. It is
 often used to "instantiate" prefabricated tools. For instance, Toys comes with
@@ -1841,15 +1841,102 @@ following in their Toys file:
     require "my_analysis"
     expand MyAnalysis::ToysTemplate
 
-### Preloading Ruby files
+### Loading from a lib directory
 
 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 incorporate it into your tool definitions, using "preloaded" files.
+and `require` the code from your tool, using `.lib` directories.
+
+To use `.lib` directories, you must define your tools inside a
+[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.
+
+For example, take the following directory structure:
+
+    (current directory)
+    |
+    +- .toys/
+       |
+       +- .lib/   <-- available when a tool is executed
+       |  |
+       |  +- greeting_helper.rb
+       |
+       +- greet.rb
+
+The `greeting_helper.rb` file can contain any Ruby code.
+
+    # .toys/.lib/greeting_helper.rb
+
+    module GreetingHelper
+      def self.make_greeting(whom)
+        "Hello, #{whom}!"
+      end
+    end
+
+Now you can `require "greeting_helper"` in your `greet` tool.
+
+    # .toys/greet.rb
+
+    tool "greet" do
+      optional_arg :whom, default: "world", desc: "Whom to greet."
+      def run
+        require "greeting_helper"
+        puts GreetingHelper.make_greeting(whom)
+      end
+    end
+
+Note that `.lib` directories are available only when your tool is being *run*,
+not when it is being defined. So any `require` statements should be located
+*inside* your `run` method.
+
+    tool "greet" do
+      # Do not try to require the file here. Toys will not find it because
+      # the tool is not yet being run.
+      # require "greeting_helper"  # ERRORS!
+
+      optional_arg :whom, default: "world", desc: "Whom to greet."
+      def run
+        # Require a helper file here, so it is loaded during tool execution.
+        require "greeting_helper"
+        # Now you can use classes defined in the helper
+        puts GreetingHelper.make_greeting(whom)
+      end
+    end
+
+If your Toys directory has subdirectories, lib directories will be prioritized
+by how close they are to the tool being executed. For example:
+
+    (current directory)
+    |
+    +- .toys/
+       |
+       +- .lib/   <-- available when any tool defined in this directory
+       |  |           is executed
+       |  |
+       |  +- helper.rb   <-- visible to "greet" but not "test unit"
+       |  |
+       |  +- helper2.rb   <-- visible to both "greet" and "test unit"
+       |
+       +- greet.rb
+       |
+       +- test/
+          |
+          +- .lib/   <-- available only when tools under "test" are executed
+          |  |
+          |  +- helper.rb   <-- overrides the other helper.rb when
+          |                     "test unit" is executed
+          |
+          +- unit.rb
+
+### Preloading Ruby files
 
-A preloaded file is loaded using the standard Ruby `require` mechanism, before
-tools are defined. You can use such files to define Ruby classes, modules, and
-other code that may be used and shared by your tools.
+You may also provide Ruby files that are "preloaded" before tools are defined.
+This is useful if those Ruby files are required by the tool definitions
+themselves. Like files in the `.lib` directory, preloaded files can define Ruby
+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
@@ -1899,58 +1986,174 @@ loaded first before the `.preload` directory contents.
 
 ## Using third-party gems
 
-The Ruby community has developed many resources for building command line
-tools, including a variety of gems that provide alternate command line parsing,
-control of the ANSI terminal, formatted output such as trees and tables, and
-effects such as hidden input, progress bars, various subprocess tools, and so
-forth.
+The toys executable itself uses only two gems: **toys** and **toys-core**. It
+has no other gem dependencies. However, the Ruby community has developed many
+resources for building command line tools, including a variety of gems that
+provide alternate command line parsing, control of the ANSI terminal, formatted
+output such as trees and tables, and effects such as hidden input, progress
+bars, various ways to spawn and control subprocesses, and so forth. You may
+find some of these gems useful when writing your tools. Additionally, if you
+are using Toys for your project's build scripts, it might be necessary to
+install your bundle when running some tools.
 
-This section describes how to use a third-party gem in your tool.
+This section describes how to manage and use external gems with Toys. Note that
+running Toys with `bundle exec` is generally *not* recommended. We'll discuss
+the reasons for this, and what you can do instead.
 
-### Activating gems
+### Why not "bundle exec toys"
 
-The toys executable itself uses only two gems: **toys** and **toys-core**. It
-has no other gem dependencies. However, if you want to use a third-party gem in
-your tool, Toys provides a convenient mechanism to ensure the gem is installed.
-
-(Note that you generally do not use bundler when running Toys; i.e. you do not
-normally run `bundle exec toys`. This is because Toys is intended as a
-general-purpose tool that can be run anywhere. It would be inconvenient to have
-to include Gemfiles in every directory where you might want to run it.)
-
-To access the gem services, include the `:gems` mixin. This mixin adds a `gem`
-directive to ensure a gem is installed and activated when you're defining a
-tool, and a `gem` method to ensure a gem is available when you're running a
-tool.
-
-Both the `gem` directive and the `gem` method take the name of the gem, and an
-optional set of version requirements. If a gem matching the given version
-requirements is installed, it is activated. If not, the gem is installed (which
-the user can confirm or abort). Or, if Toys is being run in a bundle, a message
-is printed informing the user that they need to add the gem to their Gemfile.
-
-For example, here's a way to configure a tool with flags for each of the
-HighLine styles. Because highline is needed to decide what flags to define, we
-use the `gem` directive to ensure highline is installed while the tool is being
-defined.
+[Bundler](https://bundler.io) is often used when a command-line program depends
+on external gems. You specify the gem dependencies in a `Gemfile`, use bundler
+to resolve and install those dependencies, and then run the program prefixed by
+`bundle exec` to ensure those dependencies are in the Ruby load path. When
+running a Rake task, for example, it is almost automatic for many Ruby
+developers to run `bundle exec rake my-task`.
+
+So why not simply run `bundle exec toys my-tool`?
+
+In simple cases, this will work just fine. However, Toys is a much more
+flexible tool than Rake, and it covers two cases that are not well served by
+`bundle exec`.
+
+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
+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.
+
+Second, it's possible for a variety of tools to be available together,
+including both locally and globally defined, with potentially different sets of
+dependencies. With `bundle exec`, you must choose beforehand which bundle to
+use.
+
+Although traditional `bundle exec` doesn't always work, Toys provides ways for
+individual tools to manage their own gem dependencies.
+
+### Using bundler with a tool
+
+The recommended way for a Toys tool to depend on third-party gems is for the
+tool to set up Bundler when it runs. The tool can load a bundle from an
+appropriate `Gemfile` at runtime, by including the `:bundler` mixin.
+
+Here's an example. Suppose you are writing a tool in a Rails app. It might, for
+example, load the Rails environment and populate some data into the database.
+Hence, it needs to run with your app's bundle, represented by your app's
+`Gemfile`.
+
+Simply `include :bundler` in your tool definition:
+
+    tool "populate-data" do
+      include :bundler
 
-    tool "highline-styles-demo" do
-      include :gems
-      gem "highline", "~> 2.0"
-      require "highline"
-      HighLine::BuiltinStyles::STYLES.each do |style|
-        style = style.downcase
-        flag style.to_sym, "--#{style}", "Apply #{style} to the text"
-      end
       def run
-        # ...
+        # The bundle will be set up before the tool is run,
+        # so you can now run code that depends on rails:
+        require "./config/environment.rb"
+        # ... etc.
       end
     end
 
+When the `:bundler` mixin is included in a tool, it installs a
+[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.
+
+In many cases, you might find that bundler is needed for many or most of the
+tools you write for a particular project. In this case, you might find it
+convenient to use
+[Toys::DSL::Tool#subtool_apply](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/DSL/Tool#subtool_apply-instance_method)
+to include the bundle in all your tools. For example:
+
+    # Include bundler in every tool under this one
+    subtool_apply do
+      include :bundler
+    end
+
+    tool "one-tool" do
+      # This tool will run with the bundle
+      # ...
+    end
+
+    tool "another-tool" do
+      # So will this tool
+      # ...
+    end
+
+See the section on
+[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
+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
+current working directory by passing `search_dirs: :current` as such:
+
+    tool "populate-data" do
+      include :bundler, search_dirs: :current
+      # etc...
+    end
+
+You can also pass a specific directory path to this option.
+
+If the bundle is not installed, or is out of date, Toys will ask you whether
+you want it to install the bundle first before running the tool. A tool can
+also choose to install the bundle without prompting, or simply to raise an
+error, by passing another option to the `:bundler` mixin. For example, to
+simply install the bundle without asking for confirmation:
+
+    tool "populate-data" do
+      include :bundler, on_missing: :install
+      # etc...
+    end
+
+See the documentation for
+[Toys::StandardMixins::Bundler](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
+for more information about bundler options.
+
+#### Solving bundle conflicts
+
+It is important to understand that the `:bundler` mixin installs the bundle
+when the tool *executes*, rather than when the tool is defined. Gems in the
+bundle will not be available during tool definition, so for example you
+*cannot* reference bundled gems when you are setting up the tool's flags,
+description, or other directives. This is so that Toys can define tools with
+competing bundles. Your Rails app's tools can use that app's bundle, while your
+global tools can use a different bundle. They will not conflict because Toys
+will not actually load a bundle until one or the other tool is executed. (This
+is of course different from using `bundle exec`, which chooses and loads a
+bundle before even starting Toys.)
+
+If a *different* bundle (i.e. a different `Gemfile`) is already in effect when
+a tool is run, then the `:bundler` mixin will raise an error. Ruby will not let
+you set up two different bundles at the same time. This might happen, for
+example, if you use `bundle exec` to run Toys, but the tool you are running
+asks for a different bundle---one more reason not to use `bundle exec` with
+Toys.
+
+It might also happen if one tool that uses one bundle, *calls* a tool that uses
+a different bundle. If you need to do this, use the
+[Toys::StandardMixins::Exec#exec_separate_tool](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Exec#exec_separate_tool-instance_method)
+method from the `:exec` mixin, to call the tool. This method spawns a separate
+process with a clean Bundler setup for running the tool.
+
+### Activating gems directly
+
+Although we recommend the `:bundler` mixin for most cases, it is also possible
+for a tool to install individual gems, using the `:gems` mixin. This mixin
+provides a way for a tool to install individual gems without using Bundler.
+
 Here's an example tool that just runs `rake`. Because it requires rake to be
-installed in order to *run* the tool, we call the
+installed in order to run the tool, we call the
 [Toys::StandardMixins::Gems#gem](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Gems#gem-instance_method)
-method provided by the `:gems` mixin when running.
+method (which is provided by the `:gems` mixin) at the beginning of the `run`
+method:
 
     tool "rake" do
       include :gems
@@ -1961,10 +2164,39 @@ method provided by the `:gems` mixin when running.
       end
     end
 
+The `gem` method takes the name of the gem, and an optional set of version
+requirements. If a gem matching the given version requirements is installed, it
+is activated. If not, the gem is installed (which the user can confirm or
+abort). Or, if Toys is being run in a bundle, a message is printed informing
+the user that they need to add the gem to their Gemfile.
+
 If a gem satisfying the given version constraints is already activated, it
 remains active. If a gem with a conflicting version is already activated, an
 exception is raised.
 
+The `:gems` mixin also provides a `gem` *directive* that ensures a gem is
+installed while the tool is being defined. In general, we recommend avoiding
+doing this, because it could make your tool incompatible with another tool that
+might need a competing gem during its definition. Toys would not be able to
+define both tools together. However, occasionally it might be useful.
+
+Here's an example tool with flags for each of the HighLine styles. Because
+highline is needed to decide what flags to define, we use the `gem` directive
+to ensure highline is installed while the tool is being defined.
+
+    tool "highline-styles-demo" do
+      include :gems
+      gem "highline", "~> 2.0"
+      require "highline"
+      HighLine::BuiltinStyles::STYLES.each do |style|
+        style = style.downcase
+        flag style.to_sym, "--#{style}", "Apply #{style} to the text"
+      end
+      def run
+        # ...
+      end
+    end
+
 If you are not in the Toys DSL context—for example from a class-based
 mixin—you should use
 [Toys::Utils::Gems.activate](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/Utils/Gems#activate-class_method)
@@ -1984,8 +2216,9 @@ you, whereas Rubygems will just throw an exception.
 
 ### Useful gems
 
-Now that you know how to ensure a gem is installed, let's look at some third-
-party gems that you might find useful when writing tools.
+Now that you know how to ensure a gem is installed, either individually or as
+part of a bundle, let's look at some third-party gems that you might find
+useful when writing tools.
 
 We already saw how to use the **highline** gem. Highline generally provides two
 features: terminal styling, and prompts. For these capabilities and many more,
@@ -1998,7 +2231,6 @@ To produce styled output, consider
 
     tool "fancy-output" do
       def run
-        gem "pastel", "~> 0.7"
         require "pastel"
         pastel = Pastel.new
         puts pastel.red("Rubies!")
@@ -2010,7 +2242,6 @@ To create rich user prompts, consider
 
     tool "favorite-language" do
       def run
-        gem "tty-prompt", "~> 0.16"
         require "tty-prompt"
         prompt = TTY::Prompt.new
         lang = prompt.select("What is your favorite language?",
@@ -2024,7 +2255,6 @@ To create tabular output, consider
 
     tool "matrix" do
       def run
-        gem "tty-table", "~> 0.10"
         require "tty-table"
         table = TTY::Table.new(["Language", "Creator"],
                                [["Ruby", "Matz"],
@@ -2042,7 +2272,6 @@ non-deterministic.
 
     tool "waiting" do
       def run
-        gem "tty-progressbar", "~> 0.15"
         require "tty-progressbar"
         bar = TTY::ProgressBar.new("Waiting [:bar]", total: 30)
         30.times do
@@ -2418,6 +2647,52 @@ a namespace to delegate to one of its subtools:
 
 Now `toys test` delegates to, and thus has the same effect as `toys test unit`.
 
+### Applying directives to multiple tools
+
+Sometimes a group of tools are set up similarly or share a set of flags,
+mixins, or other directives. You can apply a set of directives to all subtools
+(recursively) of the current tool, using the
+[Toys::DSL::Tool#subtool_apply](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/DSL/Tool#subtool_apply-instance_method)
+directive.
+
+For example, it is common for tools to use the `:exec` built-in mixin to invoke
+external programs. You can use `subtool_apply` to ensure that the mixin is
+included in all subtools, so that you do not need to repeat the `include`
+directive in every tool.
+
+    subtool_apply do
+      # Include the mixin only if the tool hasn't already done so
+      unless include?(:exec)
+        include :exec, exit_on_nonzero_status: true
+      end
+    end
+
+    tool "my-tool" do
+      def run
+        # This tool has access to methods defined by the :exec mixin
+        # because the above block is applied to the tool
+        sh "echo hello"
+      end
+    end
+
+Importantly, `subtool_apply` blocks are "applied" at the *end* of a tool's
+definition. Therefore, when using `subtool_apply`, you have the ability to look
+at the current definition of the tool to decide whether to apply further
+changes. The `subtool_apply` block in the above example uses this technique; it
+checks whether the `:exec` mixin has already been included before attempting to
+include it. Thus, it is possible for a tool to "override" the inclusion, say,
+to use a different configuration:
+
+    tool "another-tool" do
+      # Use a different configuration for the :exec mixin.
+      # This "overrides" the subtool_apply block above.
+      include :exec, exit_on_nonzero_status: false
+      def run
+        # This is run with exit_on_nonzero_status: false
+        sh "echo hello"
+      end
+    end
+
 ### Custom acceptors
 
 We saw earlier that flags and positional arguments can have acceptors, which
@@ -2827,8 +3102,8 @@ subdirectory:
 
 Rake handles this by actually changing the current working directory to the
 directory containing the active Rakefile. Toys, however, does not change the
-working directory unless you tell it. You can make the `list-tests` tool work
-correctly by changing the directory to the context directory (which is the
+working directory unless you tell it to. You can make the `list-tests` tool
+work correctly by changing the directory to the context directory (which is the
 directory containing the `.toys.rb` file, i.e. the `my-project` directory.)
 
     tool "list-tests" do
@@ -2856,7 +3131,7 @@ the entire toys directory structure. So if your tool definition is inside a
     |
     etc...
 
-This behavior is particularly useful for build tools. Indeed, all the build
+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
 into the context directory when they execute.