toys 0.3.11 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e808d6aa4a3e6a57484c458c7c2633ce1dc248991327c69d3c728b3eb502f135
-  data.tar.gz: 5092670abd0a8cdf65d6d62dc1d34455229022e9780384ec2d91dd34553a8615
+  metadata.gz: ba4429bb2ffdb0b3022575052f06f6278cb2b44a65da21fe9b93d2e8df56ee11
+  data.tar.gz: af08f4cc228545c39b7829ea650b7f70a621a002b177163e6561c41e1a887de8
 SHA512:
-  metadata.gz: 932274290953fe6bbcc60f58c87b808b2f0ebec867ca6a8d21c9342ca49788131fbad9f1d7755147c4f5635177da7615e51d22f88fe91d9fe617a499b20b2748
-  data.tar.gz: 5d4f9b1651d79c9cbb71cedc014cbf1af5c63f22817a1f7a87f588316ee5080b8afb0a0437275428d15a15ac4bce188cd021d94f594703e165237a6dadf90fd4
+  metadata.gz: a887876d4fec040313fa6e6f9b40de1a98add4fb7f2d33f6ffb92b4dadc1f9be68f1551fe9ac1bd07751acb227c57e69453e60993f71e407418d0e298a11a8da
+  data.tar.gz: 7a453bbefbd8b729561f3a27559434cbbad6b46aeda5f065cf4a07f75787eecc0f8e96f70db7043dc3462419c91d111523153e4fc922e7cdc276073f69139dc5

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 0.4.0 / 2018-07-03
+
+Now declaring this alpha quality. Backward-incompatible changes are still
+possible from this point, but I'll try to avoid them.
+
+* CHANGED: Utils::Terminal#confirm default is now unset by default
+* CHANGED: Moved gem install/activation methods into a mixin
+* IMPROVED: Toys::Utils::Gems can suppress the confirmation prompt
+* IMPROVED: Magic comments are now honored in toys files.
+
 ### 0.3.11 / 2018-07-02
 
 * CHANGED: Require Ruby 2.3 or later

data/README.md

@@ -1,34 +1,13 @@
 # Toys
 
-Toys is a command line binary that lets you build your own personal suite of
-command line tools using a Ruby DSL. Toys handles argument parsing, error
-reporting, logging, help text, and many other details for you. Toys is designed
-for software developers, IT specialists, and other power users who want to
-write and organize scripts to automate their workflows.
+Toys is a configurable command line tool. Write commands in config files using
+a simple DSL, and Toys will provide the command line binary and take care of
+all the details such as argument parsing, online help, and error reporting.
 
-I wrote Toys because I was accumulating dozens of ad hoc Ruby scripts that I
-had written to automate various tasks in my workflow, everything from
-refreshing credentials, to displaying git history in my favorite format, to
-running builds and tests of complex multi-component projects. It was becoming
-difficult to remember which scripts did what, and what arguments each required,
-and I was constantly digging back into their source just to remember how to use
-them. Furthermore, when writing new scripts, I was repeating the same
-OptionParser boilerplate and common functionality.
-
-Toys was designed to address those problems by providing a framework for
-writing and organizing your own command line scripts. You provide the actual
-functionality, and Toys takes care of all the other details expected from a
-good command line tool. It provides a streamlined interface for defining and
-handling command line flags and positional arguments, and sensible ways to
-organize shared code. It automatically generates help text, so you can see
-usage information at a glance, and it also provides a search feature to help
-you find the script you need.
-
-Toys can also be used to share scripts. For example, it can be used instead of
-Rake to provide build and test scripts for a project—tools that, unlike Rake
-tasks, can be invoked and passed arguments using familiar unix command line
-arguments and flags. The Toys github repo itself comes with Toys configs
-instead of Rakefiles.
+Toys is designed for software developers, IT professionals, and other power
+users who want to write and organize scripts to automate their workflows. It
+can also be used as a Rake replacement, providing a more natural command line
+interface for your project's build tasks.
 
 Unlike most command line frameworks, Toys is *not primarily* designed to help
 you build and ship a custom command line binary written in Ruby. However, you
@@ -88,8 +67,8 @@ flags. It can also validate arguments. Try this:
 
     toys greet --bye
 
-Notice that Toys automatically generated a usage summary for your tool. It can
-also automatically generate a full help screen, which you can view using the
+Notice that Toys automatically generated a usage summary for your tool. It also
+automatically generates a full help screen, which you can view using the
 `--help` flag:
 
     toys greet --help
@@ -101,7 +80,7 @@ also that the tools you create in the config file are available only in this
 directory and its subdirectories. If you move into a different directory tree,
 Toys will instead look for a config file in that directory. Thus, you can
 define tools scoped to particular projects. You can also define "global" tools
-by creating a `.toys.rb` config in your home directory.
+by creating a `.toys.rb` file in your home directory.
 
 Toys provides a rich set of useful libraries for writing tools and subtools. It
 gives you a logger and automatically provides flags to control verbosity of log
@@ -113,14 +92,31 @@ third-party libraries such as Highline and TTY.
 For a more detailed look at Toys, see the
 [User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
 
-## Contributing
+## Why Toys?
+
+I wrote Toys because I was accumulating dozens of ad hoc Ruby scripts that I
+had written to automate various tasks in my workflow, everything from
+refreshing credentials, to displaying git history in my favorite format, to
+running builds and tests of complex multi-component projects. It was becoming
+difficult to remember which scripts did what, and what arguments each required,
+and I was constantly digging back into their source just to remember how to use
+them. Furthermore, when writing new scripts, I was repeating the same
+OptionParser boilerplate and common functionality.
 
-While we appreciate contributions, please note that this software is currently
-highly experimental, and the code is evolving very rapidly. Please contact the
-author before embarking on a major pull request. More detailed contribution
-guidelines will be provided when the software stabilizes further.
+Toys was designed to address those problems by providing a framework for
+writing and organizing your own command line scripts. You provide the actual
+functionality, and Toys takes care of all the other details expected from a
+good command line tool. It provides a streamlined interface for defining and
+handling command line flags and positional arguments, and sensible ways to
+organize shared code. It automatically generates help text, so you can see
+usage information at a glance, and it also provides a search feature to help
+you find the script you need.
 
-The source can be found on Github at https://github.com/dazuma/toys
+Toys can also be used to share scripts. For example, it can be used instead of
+Rake to provide build and test scripts for a project—tools that, unlike Rake
+tasks, can be invoked and passed arguments using familiar unix command line
+arguments and flags. The Toys github repo itself comes with Toys config files
+instead of Rakefiles.
 
 ## License
 
@@ -129,3 +125,5 @@ Copyright 2018 Daniel Azuma
 This software is licensed under the 3-clause BSD license.
 
 See the LICENSE.md file for more information.
+
+The source can be found on Github at https://github.com/dazuma/toys

data/builtins/system.rb

@@ -63,7 +63,7 @@ tool "update" do
       cur_version = ::Gem::Version.new(::Toys::VERSION)
       if latest_version > cur_version
         prompt = "Update toys from #{cur_version} to #{latest_version}?"
-        exit(1) unless yes || confirm(prompt)
+        exit(1) unless yes || confirm(prompt, default: true)
         result = terminal.spinner(leading_text: "Installing Toys version #{latest_version}... ",
                                   final_text: "Done.\n") do
           exec(["gem", "install", "toys", "--version", latest_version.to_s],

data/docs/guide.md

@@ -2,11 +2,14 @@
 
 # Toys User Guide
 
-Toys is a command line binary that lets you build your own personal suite of
-command line tools using a Ruby DSL. Toys handles argument parsing, error
-reporting, logging, help text, and many other details for you. Toys is designed
-for software developers, IT specialists, and other power users who want to
-write and organize scripts to automate their workflows.
+Toys is a configurable command line tool. Write commands in config files using
+a simple DSL, and Toys will provide the command line binary and take care of
+all the details such as argument parsing, online help, and error reporting.
+
+Toys is designed for software developers, IT professionals, and other power
+users who want to write and organize scripts to automate their workflows. It
+can also be used as a Rake replacement, providing a more natural command line
+interface for your project's build tasks.
 
 Unlike most command line frameworks, Toys is *not primarily* designed to help
 you build and ship a custom command line binary written in Ruby. Rather, it
@@ -24,8 +27,8 @@ actual behavior of the Toys binary by writing **Toys files**.
 
 Toys is a multi-command binary. You may define any number of commands, called
 **tools**, which can be invoked by passing the tool name as an argument to the
-`toys` binary. Tools are arranged in a hierarchy; a tool may be a **namespace**
-that has **subtools**.
+`toys` binary. Tools are arranged in a hierarchy; you may define **namespaces**
+that have **subtools**.
 
 Tools may recognize command line arguments in the form of **flags** and
 **positional arguments**. Flags can optionally take **values**, while
@@ -101,8 +104,8 @@ tool**, the toplevel namespace:
 
     toys
 
-Like any namespace, the root tool displays its help screen, including the list
-of its subtools.
+Like any namespace, invoking the root tool displays its help screen, including
+showing the list of all its subtools.
 
 One last example:
 
@@ -127,15 +130,15 @@ optional **values** for flags. Following are a few examples.
 
 Pass a single short flag (for verbose output).
 
-    toys system version -v
+    toys system -v
 
 Pass multiple long flags (for verbose output and recursive subtool search).
 
-    toys system version --verbose --recursive
+    toys system --verbose --recursive
 
 You can combine short flags. This does the same as the previous example.
 
-    toys system version -rv
+    toys system -rv
 
 Pass a value using a long flag. The root tool supports the `--search` flag to
 search for tools that have the given keyword.
@@ -230,18 +233,22 @@ Let's force `do` to treat all its arguments as positional, by starting with
                |--------ARGS--------|
     toys do -- --help , system --help
 
+Now `toys do` behaves as we intended.
+
 ## Defining Tools
 
+So far we've been experimenting only with the built-in tools provided by Toys.
 In this section, you will learn how to define tools by writing a **Toys file**.
-
-A file named `.toys.rb` (note the leading period) in the current working
-directory defines tools available in that directory and its subdirectories. We
-will cover how to write tools, including specifying the functionality of the
+We will cover how to write tools, including specifying the functionality of the
 tool, the flags and arguments it takes, and how its description appears in the
 help screen.
 
 ### Basic Toys Syntax
 
+A file named `.toys.rb` (note the leading period) in the current working
+directory is called a **Toys file**. It defines tools available in that
+directory and its subdirectories.
+
 The format of a Toys file is a Ruby DSL that includes directives, methods, and
 nested blocks. The actual DSL is specified in the
 [Toys::DSL::Tool class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Tool).
@@ -251,7 +258,7 @@ block, use directives to set the properties of the tool, including descriptions
 and the flags and arguments recognized by the tool. The actual functionality of
 the tool is set by defining a `run` method.
 
-Consider the following example:
+Let's start with an example:
 
     tool "greet" do
       desc "Print a friendly greeting."
@@ -271,19 +278,18 @@ Consider the following example:
       end
     end
 
-Its results should be mostly self-evident. We'll take a look at some of the
-details below.
+Its results should be mostly self-evident. But let's unpack a few details.
 
-### Descriptions
+### Tool Descriptions
 
 Each tool may have a **short description** and/or a **long description**. The
 short description is a generally a single string that is displayed with the
 tool name, at the top of its help page or in a subtool list. The long
-description typically includes multiple strings, which are displayed in
+description generally includes multiple strings, which are displayed in
 multiple lines in the "description" section of the tool's help page. Long
 descriptions may include blank lines to separate paragraphs visually.
 
-Each description string/line is word-wrapped by default when displayed. In the
+By default, each description string/line is word-wrapped when displayed. In the
 long description example above, the first line is a bit longer than 80
 characters, and may be word-wrapped if displayed on an 80-character terminal.
 
@@ -319,6 +325,12 @@ argument is omitted, e.g.
 
 Then the option `:whom` is set to the default value `"world"`.
 
+If the option name is a valid method name, Toys will provide a method that you
+can use to retrieve the value. In the above example, we retrieve the value for
+the option `:whom` by calling the method `whom`. If the option name cannot be
+made into a method, you can retrieve the value by calling
+[Toys::Tool#get](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get).
+
 An argument may also be **required**, which means it must be provided on the
 command line; otherwise the tool will report a usage error. You may declare a
 required argument using the directive
@@ -404,9 +416,9 @@ This sets the following option data:
 
     {arg1: "foo", arg2: nil, arg3: []}
 
-Whereas your tool can include any number of `required_arg` and `optional_arg`
-directives, declaring any number of required and optional arguments, it can
-have only at most a single `remaining_args` directive.
+Tools can include any number of `required_arg` and `optional_arg` directives,
+declaring any number of required and optional arguments, but they can have only
+at most one `remaining_args` directive.
 
 #### Descriptions and the Args DSL
 
@@ -421,11 +433,11 @@ an example:
                  long_desc: ["Long descriptions may have multiple lines.",
                              "This is the second line."]
 
-See the above section on Descriptions for more information on how descriptions
-are rendered and word wrapped.
+See the [above section on Descriptions](#descriptions) for more information on
+how descriptions are rendered and word wrapped.
 
-Long descriptions may be unwieldly to write as a hash argument in this way. So
-Toys provides an alternate syntax for defining arguments using a block.
+Because long descriptions may be unwieldly to write as a hash argument in this
+way, Toys provides an alternate syntax for defining arguments using a block.
 
     required_arg :arg do
       desc "This is a short description for the arg"
@@ -437,13 +449,12 @@ Toys provides an alternate syntax for defining arguments using a block.
 For detailed info on configuring an argument using a block, see the
 [Toys::DSL::Arg class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Arg).
 
-#### Acceptors
+#### Argument Acceptors
 
 Finally, positional arguments may use **acceptors** to define how to validate
 arguments and convert them to Ruby objects for your tool to consume. By
-default, Toys will accept an argument string in any form, and expose it to your
-tool as a raw string. However, you may provide an acceptor to change this
-behavior.
+default, Toys will accept any argument string, and expose it to your tool as a
+raw string. However, you may provide an acceptor to change this behavior.
 
 Acceptors are part of the OptionParser interface, and are described under the
 [type coercion](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#class-OptionParser-label-Type+Coercion)
@@ -451,7 +462,7 @@ section. For example, you can provide the `Integer` class as an acceptor, which
 will validate that the argument is a well-formed integer, and convert it to an
 integer during parsing:
 
-    tool "args-demo" do
+    tool "acceptor-demo" do
       required_arg :age, accept: Integer
       def run
         puts "Next year I will be #{age + 1}"  # Age is an integer
@@ -465,8 +476,8 @@ including the special types such as
 and
 [OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
 
-You may also create **custom acceptors**. See the section below on Custom
-Acceptors for more information.
+You may also create **custom acceptors**. See the
+[section below on Custom Acceptors](#custom-acceptors) for more information.
 
 ### Flags
 
@@ -478,13 +489,19 @@ we declared a flag named `:shout`:
 Like a positional argument, a flag sets an option based on the command line
 arguments passed to the tool. In the case above, the `:shout` option is set to
 `true` if either `-s` or `--shout` is provided on the command line; otherwise
-it is set to `false`. Any number of short or long flags can be declared; they
-will be synonyms and have the same effect.
+it remains falsy. The two flags `-s` and `--shout` are effectively synonyms and
+have the same effect. A flag declaration may include any number of synonyms.
+
+As with arguments, Toys will provide a method that you can call to retrieve the
+option value set by a flag. In this case, a method called `shout` will be
+available, and will return either true or false. If the option name cannot be
+made into a method, you can retrieve the value by calling
+[Toys::Tool#get](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get).
 
 #### Flag Types
 
 Toys recognizes the same syntax used by the standard OptionParser library. This
-means you can also declare a flag that can be both set and unset:
+means you can also declare a flag that can be set either to true or false:
 
     flag :shout, "--[no-]shout"
 
@@ -514,8 +531,8 @@ a value. (This is the same behavior as OptionParser.) In this example:
 
     flag :whom, "-w", "--whom=VALUE"
 
-The `-w` flag will also implicitly take a value, because it is defined as an
-alias with another flag that takes a value.
+The `-w` flag will also implicitly take a value, because it is defined as a
+synonym of another flag that takes a value.
 
 Note also that Toys will raise an error if those flags are incompatible. For
 example:
@@ -525,7 +542,7 @@ example:
 Raises an error because one flag's value is optional while the other is
 required. (Again, this is consistent with OptionParser's behavior.)
 
-#### Custom Acceptors
+#### Flag Acceptors
 
 Flags may use **acceptors** to define how to validate values and convert them
 to Ruby objects for your tool to consume. By default, Toys will accept a flag
@@ -552,13 +569,13 @@ including the special types such as
 and
 [OptionParser::OctalInteger](http://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html#OctalInteger).
 
-You may also create **custom acceptors**. See the section below on Custom
-Acceptors for more information.
+You may also create **custom acceptors**. See the
+[section below on Custom Acceptors](#custom-acceptors) for more information.
 
 #### Defaults and Handlers
 
-Currently, flags are always optional and a flag can appear in a command line
-zero, one, or any number of times. If a flag is not passed in the command line
+Currently, flags are always optional; a flag can appear in a command line zero,
+one, or any number of times. If a flag is not passed in the command line
 arguments for a tool, by default its corresponding option value will be `nil`.
 
 You may change this by providing a default value for a flag:
@@ -572,8 +589,8 @@ appearance of the flag will take effect. That is, suppose you define this flag:
 
 Now if you pass `--shout --no-shout`, then the value of the `:shout` option
 will be `false`, i.e. the last value set on the command line. This is because a
-flag *sets* its option value, replacing any previous value. You may change this
-behavior by providing a **handler**.
+flag *sets* its option value, replacing any previously set value. You may
+change this behavior by providing a **handler**.
 
 A handler is a proc that governs what a flag does to its option value. It takes
 two arguments, the new value given, and the previously set value (which might
@@ -585,15 +602,15 @@ equivalent to the following handler:
 
 For example, most tools automatically get a "--verbose" flag. This flag may
 appear any number of times, and each appearance increases the verbosity. The
-value of this verbosity is an integer. This flag is actually implemented by
-Toys, as follows:
+value of this verbosity is an integer. This flag is provided automatically by
+Toys, and its implementation looks something like this:
 
     flag Toys::Tool::Keys::VERBOSITY, "-v", "--verbose",
          default: 0,
          handler: proc { |_val, prev| prev + 1 }
 
 Similarly, the "--quiet" flag, which decreases the verbosity, is implemented
-as follows:
+like this:
 
     flag Toys::Tool::Keys::VERBOSITY, "-q", "--quiet",
          default: 0,
@@ -602,7 +619,7 @@ as follows:
 Note that both flags affect the same option value, `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 in the section on execution environment.
+you will see [below](#logging-and-verbosity).
 
 #### Descriptions and the Flags DSL
 
@@ -616,11 +633,11 @@ directive. The `desc:` argument takes a single string description, while the
          long_desc: ["Long descriptions may have multiple lines.",
                      "This is the second line."]
 
-See the above section on Descriptions for more information on how descriptions
-are rendered and word wrapped.
+See the [above section on Descriptions](#descriptions) for more information on
+how descriptions are rendered and word wrapped.
 
-Long descriptions may be unwieldly to write as a hash argument in this way. So
-Toys provides an alternate syntax for defining flags using a block.
+Because long descriptions may be unwieldly to write as a hash argument in this
+way, Toys provides an alternate syntax for defining flags using a block.
 
     flag :my_flag do
       flags "--my-flag"
@@ -642,7 +659,8 @@ 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. Most tools, however, should define `run`.
+namespaces, as we shall see [below](#namespaces-and-subtools). Most tools,
+however, should define `run`.
 
 Let's revisit the "greet" example we covered earlier.
 
@@ -732,7 +750,7 @@ Like many command line frameworks, Toys supports **subtools**. You may, for
 example create a tool called "test" that runs your tests for a particular
 project, but you might also want "test unit" and "test integration" tools to
 run specific subsets of the test suite. One way to do this, of course, is for
-the "test" tool to parse "unit" and "integration" as arguments. However, you
+the "test" tool to parse "unit" or "integration" as arguments. However, you
 could also define them as separate tools, subtools of "test".
 
 To define a subtool, create nested `tool` directives. Here's a simple example:
@@ -800,34 +818,29 @@ Now running `toys test` will run its own implementation.
 recommend doing so, because then you lose the root tool's useful default
 implementation that lists all your tools.)
 
-Toys allows subtools to be nested arbitrarily deep. Although in practice, more
+Toys allows subtools to be nested arbitrarily deep. In practice, however, more
 than two or three levels of hierarchy can be confusing to use.
 
 ## 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. In this section, we will take a
-deeper look at Toys files, including:
-
-* Defining subtools in their own files
-* Global and local Toys files
-* The `TOYS_PATH`
-* Overriding tools
+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
 
 So far we have been defining tools by writing a Toys file named `.toys.rb`
 located in the current working directory. This works great if you have a small
 number of fairly simple tools, but if you are defining many tools or tools with
-long or complex implementations, you may find it better to define some tools in
+long or complex implementations, you may find it better to split your tools in
 separate files. You can have Toys load tools from multiple files by creating a
 **Toys directory**.
 
 A Toys directory is a directory called `.toys` located in the current working
-directory. Ruby files inside a Toys directory (or any of its subdirectories)
-are loaded when Toys looks for tool definitions. Furthermore, the name of the
-Ruby file (and indeed its path relative to the Toys directory) determines which
-tool it defines.
+directory. (Again, note the leading period.) Ruby files inside a Toys directory
+(or any of its subdirectories) are loaded when Toys looks for tool definitions.
+Furthermore, the name of the Ruby file (and indeed its path relative to the
+Toys directory) determines which tool it defines.
 
 For example, one way to create a "greet" tool, as we saw before, is to write a
 `.toys.rb` file in the current directory, and populate it like this:
@@ -840,7 +853,15 @@ For example, one way to create a "greet" tool, as we saw before, is to write a
     end
 
 You could also create the same tool by creating a `.toys` directory, and then
-creating a file `greet.rb` inside that directory. The contents would be:
+creating a file `greet.rb` inside that directory.
+
+    (current directory)
+    |
+    +- .toys/
+       |
+       +- greet.rb
+
+The contents of `greet.rb` would be:
 
     optional_arg :whom, default: "world"
     def run
@@ -852,8 +873,8 @@ name of the file `greet.rb` already provides a tool context: Toys already knows
 that we are defining a "greet" tool.
 
 If you do include a `tool` block inside the `greet.rb` file, it will create a
-*subtool* of `greet`. So, inside a Toys directory, the path to each Ruby file
-defines the "starting point" namespace for the tools defined in that file.
+*subtool* of `greet`. In other words, the path to the Ruby file defines a
+"starting point" for the names of tools defined in that file.
 
 If you create subdirectories inside a Toys directory, their names also
 contribute to the namespace of created tools. For example, if you create a
@@ -879,7 +900,7 @@ will define subtools of `test unit`.
 
 The file name `.toys.rb` can also be used inside Toys directories and
 subdirectories. Such files are called **index files**, and they create tools
-with the directory as the "starting point" namespace. For example, if you
+with the *directory* as the "starting point" namespace. For example, if you
 create an index file directly underneath a `.toys` directory, it will define
 top level tools (just like a `.toys.rb` file in the current directory.) An
 index file located inside `.toys/test` will define tools with `test` as the
@@ -907,7 +928,8 @@ in the separate file `.toys/test/unit.rb`.
 
 Toys also loads index files first before other files in the directory. This
 means they are convenient places to define shared code that can be used by all
-the subtools, as we shall see later in the section on helpers.
+the subtools defined in that directory, as we shall see later in the
+[section on sharing code](#sharing-code).
 
 ### The Toys Search Path
 
@@ -921,7 +943,7 @@ When Toys runs, it looks for tools in a **search path**. Specifically:
 (1) It looks for a `.toys.rb` file and/or a `.toys` directory in the *current
     working directory*.
 (2) It does the same in the *parent directory* of the current directory, and
-    its parent, all the way up to the root of the file system.
+    then its parent, all the way up to the root of the file system.
 (3) It does the same in the current user's *home directory*.
 (4) It does the same in the system configuration directory (i.e. `/etc` on unix
     systems)
@@ -947,17 +969,17 @@ directory, and you also define it in the `.toys/greet.rb` file in the same
 current directory, Toys will also report an error, since both are defined at
 the same point (the current directory) in the search path.
 
-#### Global Toys
+#### Global Tools
 
 Note that in the search path above, steps (1) and (2) are *context-dependent*.
 That is, they may be different depending on what directory you are in. However,
 steps (3) and (4) are *not* context-dependent, and are searched regardless of
-where you are located. Toys defined here are **global**, available everywhere.
+where you are located. Tools defined here are **global**, available everywhere.
 
 By default, global tools are defined in your home directory and the system
 configuration directory. However, you can change this by defining the
 environment variable `TOYS_PATH`. This environment variable should contain a
-colon-delimited list of paths that should be searched for global toys. If you
+colon-delimited list of paths that should be searched for global tools. If you
 do define it, it replaces (3) and (4) with the paths you specify.
 
 ## The Execution Environment
@@ -991,9 +1013,10 @@ The `TOOL_NAME` constant above is a well-known key that corresponds to the full
 name (as an array of strings) of the running tool. A variety of well-known keys
 are defined in the
 [Toys::Tool::Keys module](https://www.rubydoc.info/gems/toys-core/Toys/Tool/Keys).
-They range from the tool name and the original command line arguments passed to
-it (before they were parsed), to references to some of the Toys objects that
-can be used to do things like write to the log or look up and call other tools.
+They include information about the current execution, such as the tool name and
+the original command line arguments passed to it (before they were parsed).
+They also include some internal Toys objects, which can be used to do things
+like write to the log or look up and call other tools.
 
 Most of the important context also can be accessed from convenience methods.
 For example, the `TOOL_NAME` is also available from the
@@ -1024,13 +1047,13 @@ or the
 [Toys::Tool#verbosity method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool: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, tools automatically respond to the
-`--verbose` and `--quiet` flags, (or `-v` and `-q`), which increment and
-decrement the verbosity value, respectively. If you run a tool with `-v`, the
-verbosity is incremented to 1, and the logger level is set to `INFO`. If you
-set `-q`, the verbosity is decremented to -1, and the logger level is set to
-`ERROR`. So by using the provided logger, a tool can easily provide command
-line based control of the output verbosity.
+debugs are not. However, [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
+run a tool with `-v`, the verbosity is incremented to 1, and the logger level
+is set to `INFO`. If you set `-q`, the verbosity is decremented to -1, and the
+logger level is set to `ERROR`. So by using the provided logger, a tool can
+easily provide command line based control of the output verbosity.
 
 ### Running Tools from Tools
 
@@ -1053,11 +1076,16 @@ execute, and return a process status object (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 may 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.
+
 ### Helper Methods and Mixins
 
 The methods of [Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool)
-are not the only methods available for your tool to call. We saw earlier that
-a tool can define additional methods that you can use as helpers.
+are not the only methods available for your tool 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
 helper methods. Include a mixin using the `include` directive:
@@ -1069,16 +1097,19 @@ helper methods. Include a mixin using the `include` directive:
       end
     end
 
-Th mixins may be specified by providing a module itself, or by providing a
+A mixin may be specified by providing a module itself, or by providing a
 **mixin name**. In the above example, we used `:terminal`, which is the name
 of a built-in mixin that Toys provides. Among other things, it defines a
 special `puts` method that lets you include style information such as `:bold`,
 which affects the display on ANSI-capable terminals.
 
-For details on the standard mixins provided by Toys, see the modules under
+For details on the built-in mixins provided by Toys, see the modules under
 [Toys::StandardMixins](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins).
-We will look at a few examples of the use of these mixins below. You can also
-define your own mixins, as we will see in the next section on sharing code.
+We will look at a few examples of the use of these mixins below. Built-in
+mixins have names that are symbols.
+
+You can also define your own mixins, as we will see in the
+[next section on sharing code](#defining-mixins).
 
 ### Executing Subprocesses
 
@@ -1101,6 +1132,15 @@ their output, and a powerful block-based interface for controlling streams. The
 exec mixin also lets you set a useful default option that causes the tool to
 exit automatically if one of its subprocesses exits abnormally.
 
+The exec mixin provides methods for running several different kinds of
+subprocesses:
+
+*   Normal processes started by the operating system.
+*   Another Ruby process.
+*   A shell script.
+*   Another tool run in a separate (forked) process.
+*   A block run in a separate (forked) process.
+
 For more information, see the
 [Toys::StandardMixins::Exec mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Exec)
 and the underyling library
@@ -1120,10 +1160,15 @@ and the underyling library
 [Toys::Utils::Terminal](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Terminal).
 
 If you prefer the venerable Highline library interface, Toys provides a mixin
-that makes Highline available. It also automatically installs the highline
-gem (version 2.x) if it is not available. For more information, see the
+called `:highline` that automatically installs the highline gem (version 2.x)
+if it is not available, and makes a highline object available to the tool. For
+more information, see the
 [Toys::StandardMixins::Highline mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Highline).
 
+You may 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.
+
 ## Sharing Code
 
 As you accumulate additional and more complex tools, you may find that some of
@@ -1135,20 +1180,22 @@ classes, and constants, that you might define in your tools.
 
 ### Defining Mixins
 
-We saw earlier 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` directive. A mixin defined in a tool can be
-`include`d in that tool or any of its subtools or their subtools, recursively,
-so it's a useful way to share code. Here's how that works.
-
-Define a mixin using the `mixin` directive, and give it a name and a block. In
-the block, you can define methods that will be made available to any tool that
+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`
+directive. A mixin defined in a tool can be `include`d in that tool or any of
+its subtools or their subtools, recursively, so it's a useful way to share
+code. Here's how that works.
+
+Define a mixin using the `mixin` directive, and give it a name and a block. The
+mixin name must be a string. (Symbols are reserved for built-in mixins.) In the
+block, you can define methods that will be made available to any tool that
 includes the mixin, in the same way that you can include a Ruby module.
 
-(Unlike full modules, however, mixins allow only methods to be shared. Mixins
-do not support constants. See the next section on using constants to learn how
-constants are treated by Toys.)
+(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.)
 
 Here's an example. Suppose you had common setup code that you wanted to share
 among your testing tools.
@@ -1350,8 +1397,10 @@ to your block, letting you modify its properties:
 
 Toys provides several built-in templates that are useful for project and gem
 development, including templates that generate build, test, and documentation
-tools. You can read more about these templates in the next section on using
-Toys as a Rake replacement.
+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).
 
 You may also write your own templates. Here's how...
 
@@ -1359,7 +1408,8 @@ You may also write your own templates. Here's how...
 
 One way to define a template is to use the `template` directive. Like the
 `mixin` directive, this creates a named template that you can access inside the
-current tool and any of its subtools.
+current tool and any of its subtools. Also, like mixins, your template name
+must be a string.
 
 Following is a simple template example:
 
@@ -1407,7 +1457,7 @@ those methods need access to the `template` variable, you can use
 instead of `def`.
 
 By convention, it is a good idea for configuration options for your template to
-be settable either as arguments to the constructor, or as `attr_accessor`
+be settable *both* as arguments to the constructor, *and* as `attr_accessor`
 properties. In this way, when you expand the template, options can be provided
 either as arguments to the `expand` directive, or in a block passed to the
 directive by setting properties on the template object.
@@ -1457,14 +1507,160 @@ following in their Toys file:
     require "my_analysis"
     expand MyAnalysis::ToysTemplate
 
+## 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.
+
+This section describes how to use a third-party gem in your tool.
+
+### Activating Gems
+
+The toys gem itself includes 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.
+
+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.
+
+    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
+        # ...
+
+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
+[Toys::StandardMixins::Gems#gem](https://www.rubydoc.info/gems/toys-core/Toys%2FStandardMixins%2FGems:gem)
+method provided by the `:gems` mixin when running.
+
+    tool "rake" do
+      include :gems
+      remaining_args :rake_args
+      def run
+        gem "rake", "~> 12.0"
+        Kernel.exec(["rake"] + rake_args)
+      end
+    end
+
+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.
+
+If you are not in the Toys DSL context—for example from a class-based
+mixin—you should use
+[Toys::Utils::Gems.activate](https://www.rubydoc.info/gems/toys-core/Toys%2FUtils%2FGems.activate)
+instead. For example:
+
+    Toys::Utils::Gems.activate("highline", "~> 2.0")
+
+Note these methods are a bit different from the
+[gem method](http://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Kernel.html)
+provided by Rubygems. The Toys version attempts to install a missing gem for
+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.
+
+We already saw how to use the **highline** gem. Highline generally provides two
+features: terminal styling, and prompts. For these capabilities and many more,
+you might also consider [TTY](https://github.com/piotrmurach/tty). It comprises
+a suite of gems that you can use separately or in tandem. Here are a few
+examples.
+
+To produce styled output, consider
+[Pastel](https://github.com/piotrmurach/pastel).
+
+    tool "fancy-output" do
+      def run
+        gem "pastel", "~> 0.7"
+        require "pastel"
+        pastel = Pastel.new
+        puts pastel.red("Rubies!")
+      end
+    end
+
+To create rich user prompts, consider
+[tty-prompt](https://github.com/piotrmurach/tty-prompt).
+
+    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?",
+                             %w[Elixir Java Python Ruby Rust Other])
+        prompt.say("#{lang} is awesome!")
+      end
+    end
+
+To create tabular output, consider
+[tty-table](https://github.com/piotrmurach/tty-table).
+
+    tool "matrix" do
+      def run
+        gem "tty-table", "~> 0.10"
+        require "tty-table"
+        table = TTY::Table.new(["Language", "Creator"],
+                               [["Ruby", "Matz"],
+                                ["Python", "Guido"],
+                                ["Elixir", "Jose"]])
+        puts table.render(:ascii)
+      end
+    end
+
+To show progress, consider
+[tty-progressbar](https://github.com/piotrmurach/tty-progressbar) for
+deterministic processes, or
+[tty-spinner](https://github.com/piotrmurach/tty-spinner) for
+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
+          sleep(0.1)
+          bar.advance(1)
+        end
+      end
+    end
+
+A variety of other useful gems can also be found in
+[this article](https://lab.hookops.com/ruby-cli-gems.html).
+
 ## Toys as a Rake Replacement
 
 Toys was designed to organize scripts that may be "scoped" to a project or
 directory. Rake is also commonly used for this purpose: you can write a
 "Rakefile" that defines rake tasks scoped to a directory. In many cases, Toys
-can be used as a replacement for Rake. Indeed, the Toys repository itself,
-rather than a Rakefile, contains a `.toys.rb` file that defines tools for
-running tests, builds, and so forth.
+can be used as a replacement for Rake. Indeed, the Toys repository itself
+contains a `.toys.rb` file that defines tools for running tests, builds, and so
+forth, instead of a Rakefile that is otherwise often used for this purpose.
 
 This section will explore the differences between Toys and Rake, and describe
 how to use Toys for some of the things traditionally done with Rake.
@@ -1583,7 +1779,7 @@ example:
     expand :clean, paths: ["pkg", "doc", "tmp"]
 
 See the {Toys::Templates::Clean} documentation for details on the various
-options for clean tools.
+options for clean.
 
 ### Building Documentation
 
@@ -1612,9 +1808,9 @@ all the basic tools for a Ruby gem. It includes:
   actually build) the documentation for warnings and completeness.
 
 Below is the full annotated `.toys.rb` file. For many gems, you could drop this
-into the gem source repo with minimal or no modifications. Indeed, this is
-essentially identical to the Toys files provided for the **toys** and
-**toys-core** gems themselves.
+into the gem source repo with minimal or no modifications. Indeed, it is
+nearly identical to the Toys files provided for the **toys** and **toys-core**
+gems themselves.
 
     # A "clean" tool that cleans out gem builds (from the pkg directory), and
     # documentation builds (from doc and .yardoc)
@@ -1677,144 +1873,6 @@ essentially identical to the Toys files provided for the **toys** and
       end
     end
 
-## 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.
-
-This section describes how to use a third-party gem in your tool.
-
-### Activating Gems
-
-The toys gem itself includes 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.
-
-If the gem is needed to *define* the tool, use the `gem` directive to ensure
-the gem is installed and activated. This 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.
-
-For example, here's a way to configure a tool with flags for each of the
-HighLine styles:
-
-    tool "highline-styles-demo" do
-      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
-        # ...
-
-If the gem is *not* needed to define the tool, but is needed to *run* the tool,
-then you can call
-[Toys::Tool#gem](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:gem) from
-your `run` method. Here's an example:
-
-    tool "rake" do
-      disable_argument_passing
-      def run
-        gem "rake", "~> 12.0"
-        Kernel.exec(["rake"] + args)
-      end
-    end
-
-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.
-
-If you are not in the Toys DSL context—e.g. you are writing a class-based
-mixin—you should use
-[Toys::Utils::Gems.activate](https://www.rubydoc.info/gems/toys-core/Toys%2FUtils%2FGems:activate)
-instead. For example:
-
-    Toys::Utils::Gems.activate("highline", "~> 2.0")
-
-Note these methods are a bit different from the
-[gem method](http://ruby-doc.org/stdlib/libdoc/rubygems/rdoc/Kernel.html)
-provided by Rubygems. The Toys version attempts to install a missing gem for
-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.
-
-We already saw how to use the **highline** gem. Highline generally provides two
-features: terminal styling, and prompts. For these capabilities and many more,
-you might also consider [TTY](https://github.com/piotrmurach/tty). It comprises
-a suite of gems that you can use separately or in tandem. Here are a few
-examples.
-
-To produce styled output, consider
-[Pastel](https://github.com/piotrmurach/pastel).
-
-    tool "fancy-output" do
-      def run
-        gem "pastel", "~> 0.7"
-        require "pastel"
-        pastel = Pastel.new
-        puts pastel.red("Rubies!")
-      end
-    end
-
-To create rich user prompts, consider
-[tty-prompt](https://github.com/piotrmurach/tty-prompt).
-
-    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?",
-                             %w[Elixir Java Python Ruby Rust Other])
-        prompt.say("#{lang} is awesome!")
-      end
-    end
-
-To create tabular output, consider
-[tty-table](https://github.com/piotrmurach/tty-table).
-
-    tool "matrix" do
-      def run
-        gem "tty-table", "~> 0.10"
-        require "tty-table"
-        table = TTY::Table.new(["Language", "Creator"],
-                               [["Ruby", "Matz"],
-                                ["Python", "Guido"],
-                                ["Elixir", "Jose"]])
-        puts table.render(:ascii)
-      end
-    end
-
-To show progress, consider
-[tty-progressbar](https://github.com/piotrmurach/tty-progressbar) for
-deterministic processes, or
-[tty-spinner](https://github.com/piotrmurach/tty-spinner) for
-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
-          sleep(0.1)
-          bar.advance(1)
-        end
-      end
-    end
-
-A variety of other useful gems can also be found in
-[this article](https://lab.hookops.com/ruby-cli-gems.html).
-
 ## Advanced Tool Definition Techniques
 
 This section covers some additional features that are often useful for writing
@@ -1928,11 +1986,11 @@ completely disable decreasing the verbosity, disable both `-q` and `--quiet`.
 ### Disabling Argument Parsing
 
 Normally Toys handles parsing command line arguments for you. This makes
-writing tools easier, but also allows Toys to generate documentation
+writing tools easier, and also allows Toys to generate documentation
 automatically for flags and arguments. However, occasionally you'll not want
 Toys to perform any parsing, but just to give you the command line arguments
-raw. One common case is if your tool turns around and passes its arguments to
-another subprocess.
+raw. One common case is if your tool turns around and passes its arguments
+verbatim to another subprocess.
 
 To disable argument parsing, use the `disable_argument_parsing` directive. This
 directive disables parsing and validation of flags and positional arguments.