toys 0.7.0 → 0.8.0

data/bin/toys

@@ -1,33 +1,25 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# 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:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# 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__)
@@ -35,4 +27,4 @@
 $LOAD_PATH.unshift(::File.absolute_path(::File.join(::File.dirname(__dir__), "lib")))
 require "toys"
 
-exit(::Toys::StandardCLI.create.run(::ARGV))
+exit(::Toys::StandardCLI.new.run(::ARGV))

data/builtins/do.rb

@@ -1,33 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# 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:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
-;
+# 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"
 
@@ -39,25 +30,34 @@ long_desc \
   "",
   "Example: Suppose you have a \"rails build\" tool and a \"deploy\" tool. You could run them" \
     " in order like this:",
-  ["    toys do rails build , deploy"],
-  "",
-  "However, if you want to pass flags to the tools to run, you need to preface the arguments" \
-    " with \"--\" in order to prevent \"do\" from trying to use them as its own flags. That" \
-    " might look something like this:",
-  ["    toys do -- rails build --staging , deploy --migrate"],
+  ["    toys do rails build --staging , deploy --migrate"],
   "",
   "You may change the delimiter using the --delim flag. For example:",
-  ["    toys do --delim=/ -- rails build --staging / deploy --migrate"]
+  ["    toys do --delim=/ rails build --staging / deploy --migrate"],
+  "The --delim flag must appear first before the tools to run. Any flags that appear later in" \
+    " the command line will be passed to the tools themselves."
 
-flag :delim, "-d", "--delim=VALUE",
-     default: ",",
-     desc: "Set the delimiter",
-     long_desc: "Sets the delimiter that separates tool invocations. The default value is \",\"."
+flag :delim do
+  flags "-d", "--delim=VALUE"
+  default ","
+  desc "Set the delimiter"
+  long_desc "Sets the delimiter that separates tool invocations. The default value is \",\"."
+end
+
+remaining_args :commands do
+  complete do |context|
+    commands = context.arg_parser.data[:commands]
+    last_command = commands.inject([]) { |acc, arg| arg == "," ? [] : (acc << arg) }
+    new_context = context.with(previous_words: last_command, disable_flags: commands.empty?)
+    new_context.tool.completion.call(new_context)
+  end
+  desc "A series of tools to run, separated by the delimiter"
+end
 
-remaining_args :args, desc: "A series of tools to run, separated by the delimiter"
+enforce_flags_before_args
 
 def run
-  args
+  commands
     .chunk { |arg| arg == delim ? :_separator : true }
     .each do |_, action|
       code = cli.run(action)

data/builtins/system.rb

@@ -1,33 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# 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:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
-;
+# 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"
 
@@ -54,18 +45,18 @@ tool "update" do
 
   def run
     configure_exec(exit_on_nonzero_status: true)
-    version_info = terminal.spinner(leading_text: "Checking rubygems for the latest release... ",
-                                    final_text: "Done.\n") do
+    version_info = spinner(leading_text: "Checking rubygems for the latest release... ",
+                           final_text: "Done.\n") do
       capture(["gem", "query", "-q", "-r", "-e", "toys"])
     end
     if version_info =~ /toys\s\((.+)\)/
-      latest_version = ::Gem::Version.new($1)
+      latest_version = ::Gem::Version.new(::Regexp.last_match(1))
       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, default: true)
-        result = terminal.spinner(leading_text: "Installing Toys version #{latest_version}... ",
-                                  final_text: "Done.\n") do
+        result = spinner(leading_text: "Installing Toys version #{latest_version}... ",
+                         final_text: "Done.\n") do
           exec(["gem", "install", "toys", "--version", latest_version.to_s],
                out: :capture, err: :capture)
         end
@@ -88,3 +79,93 @@ tool "update" do
     end
   end
 end
+
+tool "bash-completion" do
+  desc "Bash tab completion for Toys"
+
+  long_desc \
+    "Tools that manage tab completion for Toys in the bash shell.",
+    "",
+    "To install tab completion for Toys, execute the following line in a bash shell, or" \
+      " include it in an init file such as your .bashrc:",
+    ["  $(toys system bash-completion install)"],
+    "",
+    "To remove tab completion, execute:",
+    ["  $(toys system bash-completion remove)"],
+    "",
+    "It is also possible to install completions for different executable names if you have" \
+      " aliases for Toys. See the help for the \"install\" and \"remove\" tools for details.",
+    "",
+    "The \"eval\" tool is the actual completion command invoked by bash when it needs to" \
+      " complete a toys command line. You shouldn't need to invoke it directly."
+
+  tool "eval" do
+    desc "Tab completion command (executed by bash)"
+
+    long_desc \
+      "Completion command invoked by bash to compete a toys command line. Generally you do not" \
+        " need to invoke this directly. It reads the command line context from the COMP_LINE" \
+        " and COMP_POINT environment variables, and outputs completion candidates to stdout."
+
+    disable_argument_parsing
+
+    def run
+      require "toys/utils/completion_engine"
+      result = ::Toys::Utils::CompletionEngine::Bash.new(cli).run
+      if result > 1
+        logger.fatal("This tool must be invoked as a bash completion command.")
+      end
+      exit(result)
+    end
+  end
+
+  tool "install" do
+    desc "Install bash tab completion"
+
+    long_desc \
+      "Outputs a command to set up Toys tab completion in the current bash shell.",
+      "",
+      "To use, execute the following line in a bash shell, or include it in an init file" \
+        " such as your .bashrc:",
+      ["  $(toys system bash-completion install)"],
+      "",
+      "This will associate the toys tab completion logic with the `toys` executable by default." \
+        " If you have aliases for the toys executable, pass them as arguments. e.g.",
+      ["  $(toys system bash-completion install my-toys-alias another-alias)"]
+
+    remaining_args :executable_names,
+                   desc: "Names of executables for which to set up tab completion" \
+                         " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
+
+    def run
+      require "shellwords"
+      path = ::File.join(::File.dirname(__dir__), "share", "bash-completion.sh")
+      exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
+      puts Shellwords.join(["source", path] + exes)
+    end
+  end
+
+  tool "remove" do
+    desc "Remove bash tab completion"
+
+    long_desc \
+      "Outputs a command to remove Toys tab completion from the current bash shell.",
+      "",
+      "To use, execute the following line in a bash shell:",
+      ["  $(toys system bash-completion remove)"],
+      "",
+      "If you have other names or aliases for the toys executable, pass them as arguments. e.g.",
+      ["  $(toys system bash-completion remove my-toys-alias another-alias)"]
+
+    remaining_args :executable_names,
+                   desc: "Names of executables for which to set up tab completion" \
+                         " (default: #{::Toys::StandardCLI::EXECUTABLE_NAME})"
+
+    def run
+      require "shellwords"
+      path = ::File.join(::File.dirname(__dir__), "share", "bash-completion-remove.sh")
+      exes = executable_names.empty? ? [::Toys::StandardCLI::EXECUTABLE_NAME] : executable_names
+      puts Shellwords.join(["source", path] + exes)
+    end
+  end
+end

data/docs/guide.md

@@ -3,8 +3,8 @@
 # Toys User Guide
 
 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.
+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 is designed for software developers, IT professionals, and other power
 users who want to write and organize scripts to automate their workflows. It
@@ -12,23 +12,33 @@ 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
-provides a single binary called `toys`. You define the commands recognized by
-the Toys binary by writing configuration files. (You can, however, build your
-own custom command line binary using the related **toys-core** library.)
-
-This user's guide covers everything you need to know to use Toys effectively.
-
-## Conceptual Overview
-
-Toys is a command line *framework*. It provides a binary called `toys` along
+you build and ship a custom command line executable written in Ruby. Rather, it
+provides a single executable called `toys`. You define the commands recognized
+by the Toys executable by writing configuration files. (You can, however, build
+your own custom command line executable using the related **toys-core**
+library.)
+
+If this is your first time using Toys, we recommend starting with the
+[README](https://www.rubydoc.info/gems/toys/file/README.md), which includes a
+tutorial that introduces how to install Toys, write and execute tools, and even
+use Toys to replace Rake. The tutorial will likely give you enough information
+to start using Toys effectively.
+
+This user's guide is also structured like an extended tutorial, but it is much
+longer and covers all the features of Toys in much more depth. Read it when
+you're ready to unlock all the capabilities of Toys to create sophisticated
+command line tools.
+
+## Conceptual overview
+
+Toys is a command line *framework*. It provides an executable called `toys`
 with basic functions such as argument parsing and online help. You provide the
-actual behavior of the Toys binary by writing **Toys files**.
+actual behavior of the Toys executable 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; you may define **namespaces**
-that have **subtools**.
+Toys is a multi-command executable. You may define any number of commands,
+called **tools**, which can be invoked by passing the tool name as an argument
+to the `toys` executable. 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
@@ -42,12 +52,12 @@ tool's **online help** screen. Descriptions come in **long** and **short**
 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, its ancestors,
-and in the Toys **search path**.
+directories**. It searches for these in the current directory, in its
+ancestors, and in the Toys **search path**.
 
 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
-call (such as controlling subprocesses and styling output), and **templates**
+call (such as to control subprocesses and style output), and **templates**
 which are prefabricated tools that you can configure for your needs.
 
 Finally, Toys provides useful **built-in behavior**, including automatically
@@ -55,7 +65,7 @@ providing flags to display help screens and set verbosity. It also includes a
 built-in namespace of **system tools** that let you inspect and configure the
 Toys system itself.
 
-## The Toys Command Line
+## The Toys command line
 
 In this section, you will learn how Toys parses its command line, identifies a
 tool to run, and interprets flags and other command line arguments.
@@ -73,8 +83,8 @@ first **positional argument**), or until there are no more arguments.
 
 For example, in the following command:
 
-         |----TOOL----|
-    toys system version
+           |----TOOL----|
+    $ toys system version
 
 The tool name is `system version`. Notice that the tool name may have multiple
 words. Tools are arranged hierarchically. In this case, `system` is a
@@ -85,13 +95,13 @@ The words in a tool name can be delimited with spaces as shown above, or
 alternately periods or colons. The following commands also invoke the tool
 `system version`:
 
-    toys system.version
-    toys system:version
+    $ toys system.version
+    $ toys system:version
 
 In the following command:
 
-         |TOOL| |ARG|
-    toys system frodo
+           |TOOL| |ARG|
+    $ toys system frodo
 
 There is no subtool `frodo` under the `system` namespace, so Toys works
 backward until it finds an existing tool. In this case, the `system` namespace
@@ -103,7 +113,7 @@ other tool. In the above case, it takes the argument `frodo`, determines it has
 no subtool of that name, and prints an error message. More commonly, though,
 you might execute a namespace without arguments:
 
-    toys system
+    $ toys system
 
 This displays the **online help screen** for the `system` namespace, which
 includes a list of all its subtools and what they do.
@@ -111,14 +121,14 @@ includes a list of all its subtools and what they do.
 It is also legitimate for the tool name to be empty. This invokes the **root
 tool**, the toplevel namespace:
 
-    toys
+    $ toys
 
 Like any namespace, invoking the root tool displays its help screen, including
 showing the list of all its subtools.
 
 One last example:
 
-    toys frodo
+    $ toys frodo
 
 If there is no tool called `frodo` in the toplevel namespace, then once again,
 `frodo` is interpreted as an argument to the root tool. The root tool responds
@@ -134,38 +144,51 @@ tool, the tool will generally display an error message.
 
 Toys follows the typical unix conventions for flags, specifically those covered
 by Ruby's OptionParser library. You can provide short (single-character) flags
-with a single hyphen, or long flags with a double hyphen. You can also provide
-optional **values** for flags. Following are a few examples.
+with a single hyphen, or long flags with a double hyphen. Some flags can also
+take **values**. Following are a few examples.
+
+Here we pass a single short flag (for verbose output).
+
+    $ toys system -v
 
-Pass a single short flag (for verbose output).
+Here we pass multiple long flags (for verbose output and recursive subtool
+search).
 
-    toys system -v
+    $ toys system --verbose --recursive
 
-Pass multiple long flags (for verbose output and recursive subtool search).
+You can combine short flags. The following passes both the `-v` and `-r` flags
+(i.e. it has the same effect as the previous example.)
 
-    toys system --verbose --recursive
+    $ toys system -vr
 
-You can combine short flags. This does the same as the previous example.
+Long flags can be abbreviated, as long as the abbreviation is not ambiguous.
+For example, there is only one flag (`--recursive`) beginning with the string
+`--rec`, so you can use the shortened form.
 
-    toys system -rv
+    $ toys --rec
 
-Pass a value using a long flag. The root tool supports the `--search` flag to
-search for tools that have the given keyword.
+However, there are two flags (`--version` and `--verbose`) beginning with
+`--ver`, so it cannot be used as an abbreviation. This will cause an error:
 
-    toys --search=build
-    toys --search build
+    $ toys --ver
 
-Pass a value using a short flag.
+Some flags take values. The root tool supports the `--search` flag to search
+for tools that have the given keyword.
 
-    toys -s build
-    toys -sbuild
+    $ toys --search=build
+    $ toys --search build
+
+The short form of the search flag `-s` also takes a value.
+
+    $ toys -s build
+    $ toys -sbuild
 
 If a double hyphen `--` appears by itself in the arguments, it disables flag
 parsing from that point. Any further arguments are treated as positional
 arguments, even if they begin with hyphens. For example:
 
-         |--FLAG--|   |---ARG---|
-    toys --verbose -- --recursive
+           |--FLAG--|   |---ARG---|
+    $ toys --verbose -- --recursive
 
 That will cause `--recursive` to be treated as a positional argument. (In this
 case, as we saw earlier, the root tool will respond by printing an error
@@ -174,7 +197,7 @@ message that no tool named `--recursive` exists.)
 Note that a single hyphen by itself `-` is not considered a flag, nor does it
 disable flag parsing. It is treated as a normal positional argument.
 
-#### Standard Flags
+#### Standard flags
 
 For the most part, each tool specifies which flags and arguments it recognizes.
 However, Toys adds a few standard flags globally to every tool. (It is possible
@@ -196,18 +219,19 @@ 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.
-*   `--[no-]recursive` (also `-r`) which displays all subtools recursively,
-    instead of only the immediate subtools.
+    [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
     contain the specified search term.
-*   `--tools` which displays just the list of subtools.
+*   `--tools` which displays just the list of subtools rather than the entire
+    help screen.
 
 Finally, the root tool also supports:
 
 *   `--version` which displays the current Toys version.
 
-### Positional Arguments
+### Positional arguments
 
 Any arguments not recognized as flags or flag arguments, are interpreted as
 **positional arguments**. Positional arguments are recognized in order and may
@@ -222,32 +246,70 @@ recognizes any number of positional arguments. Those arguments specify which
 tools to run and what arguments to pass to them. If, for example, you had a
 `build` tool and a `test` tool, you could run them in sequence with:
 
-            |---ARGS---|
-    toys do build , test
+              |---ARGS---|
+    $ toys do build , test
 
-The three arguments `build`, `,`, and `test` are positional arguments to the
+The three arguments `build` and `,` and `test` are positional arguments to the
 `do` tool. (The `do` tool uses `,` to delimit the tools that it should run.)
 
-Here is a more complex example illustrating the interaction between flags and
-positional arguments. Suppose we want to use `do` to display the help screens
-for the root tool and the system tool in sequence. That is, we want to run
-`toys --help` and `toys system --help` in sequence. We might start by trying:
+Most tools allow flags and positional arguments to be interspersed. A flag will
+be recognized even if it appears after some of the positional arguments.
+
+However, this approach would not work for the `do` tool because its common case
+is to pass flags down to the steps it runs. (That is, `do` wants most arguments
+to be treated as positional even if they look like flags.) So `do` stops
+recognizing flags once it encounters its first positional argument. That is,
+you could do this:
+
+              |------------ARGS-----------|
+    $ 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).
 
-            |FLAG| |-ARGS-| |FLAG|
-    toys do --help , system --help
+You can also, of course, stop recognizing flags on the command line by passing
+`--` as an argument.
 
-However, this simply displays the help for the `do` tool itself, because the
-first `--help` is interpreted as a flag for `do`. What we actually want is for
-`do` to treat it as a positional argument specifying the first tool to run. So
-Let's force `do` to treat all its arguments as positional, by starting with
-`--` like so:
+### Tab completion
 
-               |--------ARGS--------|
-    toys do -- --help , system --help
+If you are using the Bash shell, Toys provides custom tab completion. See
+[this section](#Installing_tab_completion_for_Bash) for instructions on
+installing tab completion.
 
-Now `toys do` behaves as we intended.
+Toys will complete tool and subtool names, flags, values passed to flags, and
+positional argument values, and it will respect the current context. For
+example, if you type:
 
-## Defining Tools
+    $ toys <TAB><TAB>
+
+The tab completion will show you a list of reasonable things that could appear
+next, including the defined tool names (such as `system` and `do`) as well as
+all the flags supported by the root tool (such as `--help` and `-v`). And of
+course, if you start typing something, tab completion will limit the display to
+matching completions. The following displays only flags, i.e. completions that
+begin with a hyphen:
+
+    $ toys -<TAB><TAB>
+
+And if you type the following:
+
+    $ toys sys<TAB>
+
+It is likely only one tool name starts with `sys`, so completion will
+automatically type the rest of `system` for you.
+
+The tab completion for Toys also supports values passed to flags and positional
+args. As we shall see later, when you define a flag or a positional argument,
+you can specify how completions are computed.
+
+**Note:** Because of the highly dynamic nature of Toys in which tools, flags,
+and arguments can be highly customized, the completion implementation actually
+requires *executing Toys* so it can analyze your tool configurations. This
+unfortunately means paying some upfront latency as the Ruby interpreter starts
+up. So you can expect a slight pause when evaluating tab completion for Toys,
+at least in comparison with most other tab completions.
+
+## 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**.
@@ -255,7 +317,7 @@ 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
+### 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
@@ -285,14 +347,14 @@ Let's start with an example:
 
       def run
         greeting = "Hello, #{whom}!"
-        greeting.upcase! if shout
+        greeting = greeting.upcase if shout
         puts greeting
       end
     end
 
 Its results should be mostly self-evident. But let's unpack a few details.
 
-### Tool 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
@@ -316,7 +378,7 @@ For more details, see the reference documentation for
 and
 [Toys::DSL::Tool#long_desc](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:long_desc).
 
-### Positional Arguments
+### Positional arguments
 
 Tools may recognize any number of **positional arguments**. Each argument must
 have a name, which is a key that the tool can use to obtain the argument's
@@ -328,12 +390,14 @@ The above example uses the directive
 to declare an **optional argument** named `:whom`. If the argument is provided
 on the command line e.g.
 
-    toys greet ruby
+    $ toys greet ruby
+    Hello, ruby!
 
 Then the option `:whom` is set to the string `"ruby"`. Otherwise, if the
 argument is omitted, e.g.
 
-    toys greet
+    $ toys greet
+    Hello, world!
 
 Then the option `:whom` is set to the default value `"world"`.
 
@@ -341,14 +405,14 @@ 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).
+[Toys::Context#get](https://www.rubydoc.info/gems/toys-core/Toys%2FContext: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
 [Toys::DSL::Tool#required_arg](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:required_arg).
 
-#### Parsing Required and Optional Arguments
+#### Parsing required and optional arguments
 
 When command line arguments are parsed, the required arguments are matched
 first, in order, followed by the optional arguments. For example:
@@ -356,29 +420,35 @@ first, in order, followed by the optional arguments. For example:
     tool "args-demo" do
       optional_arg :arg2
       required_arg :arg1
-      # ...
+
+      def run
+        puts "options data is #{options.inspect}"
+      end
+    end
 
 If a user runs
 
-    toys args-demo foo
+    $ toys args-demo foo
+    Options data is {arg1: "foo", arg2: nil}
 
 Then the required argument `:arg1` will be set to `"foo"`, and the optional
 argument `:arg2` will not be set (i.e. it will remain `nil`).
 
 If the user runs:
 
-    toys args-demo foo bar
+    $ toys args-demo foo bar
+    Options data is {arg1: "foo", arg2: "bar"}
 
 Then `:arg1` is set to `"foo"`, and `:arg2` is set to `"bar"`.
 
 Running the following:
 
-    toys args-demo
+    $ toys args-demo
 
 Will produce a usage error, because no value is set for the required argument
 `:arg1`. Similarly, running:
 
-    toys args-demo foo bar baz
+    $ toys args-demo foo bar baz
 
 Will also produce an error, since the tool does not define an argument to
 match `"baz"`.
@@ -389,16 +459,21 @@ not provided on the command line. For example:
     tool "args-demo" do
       required_arg :arg1
       optional_arg :arg2, default: "the-default"
-      # ...
+
+      def run
+        puts "options data is #{options.inspect}"
+      end
+    end
 
 Now running the following:
 
-    toys args-demo foo
+    $ toys args-demo foo
+    Options data is {arg1: "foo", arg2: "the-default"}
 
 Will set the required argument to `"foo"` as usual, and the optional argument,
 because it is not provided, will default to `"the-default"` instead of `nil`.
 
-#### Remaining Arguments
+#### Remaining arguments
 
 Normally, unmatched arguments will result in an error message. However, you can
 provide an "argument" to match all **remaining** unmatched arguments at the
@@ -410,29 +485,25 @@ For example:
       required_arg :arg1
       optional_arg :arg2
       remaining_args :arg3
-      # ...
 
-Now, running:
-
-    toys args-demo foo bar baz bey
-
-Sets the following option data:
-
-    {arg1: "foo", arg2: "bar", arg3: ["baz", "bey"]}
-
-If instead you run:
+      def run
+        puts "Options data is #{options.inspect}"
+      end
+    end
 
-    toys args-demo foo
+Now, we can see how the remaining arguments (if any) are collected by `:arg3`:
 
-This sets the following option data:
+    $ toys args-demo foo bar baz qux
+    Options data is {arg1: "foo", arg2: "bar", arg3: ["baz", "qux"]}
 
-    {arg1: "foo", arg2: nil, arg3: []}
+    $ toys args-demo foo
+    Options data is {arg1: "foo", arg2: nil, arg3: []}
 
 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.
+declaring any number of required and optional arguments. But tools can have at
+most only one `remaining_args` directive.
 
-#### Descriptions and the Args DSL
+#### Descriptions and the args DSL
 
 Positional arguments may also have short and long descriptions, which are
 displayed in online help. Set descriptions via the `desc:` and `long_desc:`
@@ -445,7 +516,7 @@ an example:
                  long_desc: ["Long descriptions may 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
@@ -459,9 +530,9 @@ way, Toys provides an alternate syntax for defining arguments using a block.
     end
 
 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).
+[Toys::DSL::PositionalArg class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/PositionalArg).
 
-#### Argument 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
@@ -478,7 +549,8 @@ integer during parsing:
       required_arg :age, accept: Integer
       def run
         puts "Next year I will be #{age + 1}"  # Age is an integer
-        ...
+      end
+    end
 
 If you pass a non-integer for this argument, Toys will report a usage error.
 
@@ -489,7 +561,31 @@ 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](#Custom_Acceptors) for more information.
+[section below on Custom Acceptors](#Custom_acceptors) for more information.
+
+#### Argument completions
+
+Shell tab completion supports positional arguments, and arguments can be
+configured to present a set of completion candidates for themselves.
+
+By default, an argument does not provide any completions for itself. To change
+that, set the `completion` option. Currently there are three ways to set the
+completion:
+
+*   Provide a static set of possible values, as an array of strings.
+*   Specify that values should be paths in the file system by setting the
+    symbol `:file_system`.
+*   Provide a `Proc` that returns possible values.
+
+The following are two example arguments, one that supports a static set of
+completions and the other that supports file paths.
+
+    required_arg :language, complete: ["ruby", "elixir", "rust"]
+    required_arg :path, complete: :file_system
+
+Completions are somewhat related to acceptors, and it is a common pattern to
+set both in concert. But they perform distinct functions. Acceptors affect
+argument parsing, whereas completions affect tab completion in the shell.
 
 ### Flags
 
@@ -508,21 +604,15 @@ 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).
+[Toys::Context#get](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:get).
 
-#### Flag Types
+#### Flag types
 
 Toys recognizes the same syntax used by the standard OptionParser library. This
 means you can also declare a flag that can be set either to true or false:
 
     flag :shout, "--[no-]shout"
 
-If you do not provide any actual flags, Toys will infer a long flag from the
-name of the option. Hence, the following two definitions are equivalent:
-
-    flag :shout
-    flag :shout, "--shout"
-
 You can declare that a short or long flag takes a value:
 
     flag :whom, "--whom=VALUE"
@@ -554,7 +644,106 @@ example:
 Raises an error because one flag's value is optional while the other is
 required. (Again, this is consistent with OptionParser's behavior.)
 
-#### Flag Acceptors
+#### Inferred flags
+
+If you do not provide any actual flags, Toys will attempt to infer one from the
+name of the option. A one-character name will yield a short flag, and a longer
+name a long flag. Hence, the following two definitions are equivalent:
+
+    flag :shout
+    flag :shout, "--shout"
+
+And the following two are equivalent:
+
+    flag :S
+    flag :S, "-S"
+
+Inferred flags will convert underscores to hyphens. So the following two
+definitions are also equivalent:
+
+    flag :call_out
+    flag :call_out, "--call-out
+
+#### Handling optional values
+
+There are some subtleties in how the Ruby OptionParser library treats flags
+with optional values. Although Toys does not use OptionParser interally, it
+does, for the most part, replicate OptionParser's behavior. It is thus
+important to understand that behavior if you use optional values.
+
+First, if a flag has an optional value that is not provided on the command
+line, then the option is set to `true`, as if it were a normal boolean flag
+that didn't take a value. Consider this example:
+
+    tool "flags-demo" do
+      flag :output, "--output [DIRECTORY]", default: "."
+      def run
+        puts "output is #{output.inspect}"
+      end
+    end
+
+If a user executes this without passing the `--output` flag, the default will
+be printed as we expect.
+
+    $ toys flags-demo
+    output is "."
+
+If a user executes this and provides a value for `--output`, it will show up:
+
+    $ toys flags-demo --output /etc
+    output is "/etc"
+
+If a user provides `--output` but omits the value, it displays `true`:
+
+    $ toys flags-demo --output
+    output is true
+
+Second, if the following argument looks like a flag (i.e. it begins with a
+hyphen), it is not treated as an optional value. In this example, the argument
+`--verbose` is not treated as the value of `--output` but as a separate flag.
+(If `--output` had a *required* value, then `--verbose` would have been treated
+as the value.)
+
+    $ toys flags-demo --output --verbose
+    output is true
+
+Finally, there is an important difference between the syntax
+`"--output [DIRECTORY]"` and `"--output=[DIRECTORY]"`. In the former case, the
+following argument (as long as it doesn't look like a flag) will be treated as
+the value. In the latter case, however, the following argument is *never*
+treated as the value. In that latter case, you *must* use the equals sign
+syntax to provide a value.
+
+To illustrate, consider two flags with optional values, one using space and the
+other using equals.
+
+    tool "flags-demo-space" do
+      flag :output, "--output [DIRECTORY]", default: "."
+      set_remaining_args :remaining
+      def run
+        puts "output is #{output.inspect}"
+      end
+    end
+    tool "flags-demo-equals" do
+      flag :output, "--output=[DIRECTORY]", default: "."
+      set_remaining_args :remaining
+      def run
+        puts "output is #{output.inspect}"
+      end
+    end
+
+Here is the behavior:
+
+    $ toys flags-demo-space --output=/etc
+    output is "/etc"
+    $ toys flags-demo-space --output /etc
+    output is "/etc"
+    $ toys flags-demo-equals --output=/etc
+    output is "/etc"
+    $ toys flags-demo-equals --output /etc
+    output is true
+
+#### 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
@@ -567,11 +756,12 @@ 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 "flags-demo" do
       flag :age, accept: Integer
       def run
         puts "Next year I will be #{age + 1}"  # Age is an integer
-        ...
+      end
+    end
 
 If you pass a non-integer for this flag value, Toys will report a usage error.
 
@@ -582,15 +772,16 @@ 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](#Custom_Acceptors) for more information.
+[section below on Custom Acceptors](#Custom_acceptors) for more information.
 
-#### Defaults and Handlers
+#### Defaults and handlers
 
-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`.
+Flags are usually optional; a flag can appear in a command line zero, one, or
+any number of times.
 
-You may change this by providing a default value for a flag:
+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:
 
     flag :age, accept: Integer, default: 21
 
@@ -601,39 +792,61 @@ 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 previously set value. You may
-change this behavior by providing a **handler**.
+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 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
-be the default value if this is the first appearance of the flag), and returns
-the new value that should be set. So effectively, the default behavior is
-equivalent to the following handler:
+Effectively, the default behavior (setting the value and ignoring the previous
+value) is equivalent to the following handler:
 
     flag :shout, "--[no-]shout", handler: proc { | val, _prev| val }
 
-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 provided automatically by
-Toys, and its implementation looks something like this:
+Toys gives the default handler the special name `:set`. So the above is also
+equivalent to:
 
-    flag Toys::Tool::Keys::VERBOSITY, "-v", "--verbose",
+    flag :shout, "--[no-]shout", handler: :set
+
+The `--verbose` flag, provided automatically by Toys for most tools, shows an
+example of an alternate handler. Verbosity is represented by an integer value,
+defaulting to 0. The `--verbose` flag may appear any number of times, and
+*each* appearance increases the verbosity. Its implementation is internal to
+Toys, but looks something like this:
+
+    flag Toys::Context::Key::VERBOSITY, "-v", "--verbose",
          default: 0,
          handler: proc { |_val, prev| prev + 1 }
 
 Similarly, the "--quiet" flag, which decreases the verbosity, is implemented
 like this:
 
-    flag Toys::Tool::Keys::VERBOSITY, "-q", "--quiet",
+    flag Toys::Context::Key::VERBOSITY, "-q", "--quiet",
          default: 0,
          handler: proc { |_val, prev| prev - 1 }
 
-Note that both flags affect the same option value, `VERBOSITY`. The first
+Note that both flags affect the same option name, `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).
+you will see [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
+simply omitting the `handler:` option. Another named handler is `:push`. This
+handler is intended for flags that take values and can be provided more than
+once. The final value is then an array of values.
 
-#### Descriptions and the Flags DSL
+In the following example, an invocation can provide any number of `--include`
+flags, and the `:include` option will be set to an array of the given paths.
+
+    flag :include, "-I", "--include PATH", default: [], handler: :push
+
+The `:push` handler is equivalent to
+`proc { |val, array| array.nil? ? [val] : array << val }`.
+
+#### Descriptions and the flags DSL
 
 Flags may also have short and long descriptions, which are displayed in online
 help. Set descriptions via the `desc:` and `long_desc:` arguments to the flag
@@ -645,7 +858,7 @@ 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](#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
@@ -662,7 +875,31 @@ way, Toys provides an alternate syntax for defining flags using a block.
 For detailed info on configuring an flag using a block, see the
 [Toys::DSL::Flag class](https://www.rubydoc.info/gems/toys-core/Toys/DSL/Flag).
 
-#### Flag Groups
+#### Flag completions
+
+Shell tab completion supports flag values, and flags can be configured to
+present a set of completion candidates for themselves.
+
+By default, a flag does not provide any completions for itself. To change that,
+set the `completion` option. Currently there are three ways to set the
+completion:
+
+*   Provide a static set of possible values, as an array of strings.
+*   Specify that values should be paths in the file system by setting the
+    symbol `:file_system`.
+*   Provide a `Proc` that returns possible values.
+
+The following are two example flags, one that supports a static set of
+completions and the other that supports file paths.
+
+    flag :language, "--lang=VAL", complete_values: ["ruby", "elixir", "rust"]
+    flag :path, "--path=VAL", complete_values: :file_system
+
+Completions are somewhat related to acceptors, and it is a common pattern to
+set both in concert. But they perform distinct functions. Acceptors affect
+option parsing, whereas completions affect tab completion in the shell.
+
+#### Flag groups
 
 Flags may be organized into groups. This serves two functions:
 
@@ -699,8 +936,11 @@ The `all_required` directive is actually just shorthand for passing
       flag :password, "--password=VAL", desc: "Set the password (required)"
     end
 
-There are several other types of flag groups:
+The following are the supported types of flag groups:
 
+*   The `:required` type, which you can create using the directive
+    `all_required`. All flags from the group are required and must be provided
+    on the command line to avoid an error.
 *   The `:exactly_one` type, which you can create using the directive
     `exactly_one_required`. Exactly one, and no more than one, flag from the
     group must be provided on the command line to avoid an error.
@@ -710,6 +950,9 @@ There are several other types of flag groups:
 *   The `:at_least_one` type, which you can create using the directive
     `at_least_one_required`. At least one flag from the group must be provided
     on the command line to avoid an error.
+*   The `:optional` type is the default created using the directive
+    `flag_group` when no type is specified. Flags in the group are ordinary
+    optional flags.
 
 Flag group types are useful for a variety of tools. For example, suppose you
 are writing a tool that deploys an app to one of several different kinds of
@@ -724,11 +967,12 @@ configuration for your tool with a flag group:
       end
 
       def run
-        # Now exactly one of server, vm, or container will be set.
+        # Now exactly one of server, vm, or container will be set. The other
+        # two options will be their default value, nil.
       end
     end
 
-### Tool Execution Basics
+### Tool execution basics
 
 When you run a tool from the command line, Toys will build the tool based on
 its definition in a Toys file, and then it will attempt to execute it by
@@ -737,7 +981,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.
@@ -748,7 +992,7 @@ Let's revisit the "greet" example we covered earlier.
 
       def run
         greeting = "Hello, #{whom}!"
-        greeting.upcase! if shout
+        greeting = greeting.upcase if shout
         puts greeting
       end
     end
@@ -759,12 +1003,12 @@ Ruby `$stdout`, `$stderr`, and `$stdin` streams.
 Note also how the `run` method can access values that were assigned by flags or
 positional arguments by just calling a method with that flag or argument name.
 When you declare a flag or argument, if the option name is a symbol that is a
-valid Ruby method name, Toys will provide a method of that name that you can
-call to get the value.
+valid Ruby method name, Toys will provide a method that you can call to get the
+value. In the above example, `whom` and `shout` are such methods.
 
-If you create a flag or argument whose option name is not a symbol _or_ is not
+If you create a flag or argument whose option name is not a symbol *or* is not
 a valid method name, you can still get the value by calling the
-[Toys::Tool#get](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get)
+[Toys::Context#get](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:get)
 method. For example:
 
     tool "greet" do
@@ -775,7 +1019,7 @@ method. For example:
       def run
         # We can access the "whom-to-greet" option using the "get" method.
         greeting = "Hello, #{get('whom-to-greet')}!"
-        greeting.upcase! if shout
+        greeting = greeting.upcase if shout
         puts greeting
       end
     end
@@ -783,7 +1027,7 @@ method. For example:
 If a tool's `run` method finishes normally, Toys will exit with a result code
 of 0, indicating success. You may exit immediately and/or provide a nonzero
 result by calling the
-[Toys::Tool#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:exit)
+[Toys::Context#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:exit)
 method:
 
     def run
@@ -797,7 +1041,8 @@ exit with a nonzero code.
 
 Finally, you may also define additional methods within the tool. These are
 available to be called by your `run` method, and can be used to decompose your
-tool implementation. Here's a contrived example:
+tool implementation. Indeed, a tool is actually a class under the hood, and
+you can define methods as with any other class. Here's a contrived example:
 
     tool "greet-many" do
       # Support any number of arguments on the command line
@@ -807,7 +1052,7 @@ tool implementation. Here's a contrived example:
       # You can define helper methods like this.
       def greet(name)
         greeting = "Hello, #{name}!"
-        greeting.upcase! if shout
+        greeting = greeting.upcase if shout
         puts greeting
       end
 
@@ -822,14 +1067,14 @@ This should be enough to get you started implementing tools. A variety of
 additional features are available for your tool implementation and will be
 discussed further below. But first we will cover a few important topics.
 
-### Namespaces and Subtools
+### Namespaces and subtools
 
 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" or "integration" as arguments. However, you
-could also define them as separate tools, subtools of "test".
+the "test" tool to parse "unit" or "integration" as arguments. However, it's
+often easier to define them as separate tools, subtools of "test".
 
 To define a subtool, create nested `tool` directives. Here's a simple example:
 
@@ -849,15 +1094,17 @@ To define a subtool, create nested `tool` directives. Here's a simple example:
 
 You can now invoke them like this:
 
-    toys test unit
-    toys test integration
+    $ toys test unit
+    run unit tests here...
+    $ toys test integration
+    run integration tests here...
 
 Notice in this case, the parent "test" tool itself has no `run` method. This is
 a common pattern: "test" is just a "container" for tools, a way of organizing
 your tools. In Toys terminology, it is called a **namespace**. But it is still
 a tool, and it can still be run:
 
-    toys test
+    $ toys test
 
 As discussed earlier, Toys provides a default implementation that displays the
 help screen, which includes a list of the subtools and their descriptions.
@@ -865,7 +1112,7 @@ help screen, which includes a list of the subtools and their descriptions.
 As another example, the "root" tool is also normally a namespace. If you just
 run Toys with no arguments:
 
-    toys
+    $ toys
 
 The root tool will display the overall help screen for Toys.
 
@@ -899,13 +1146,13 @@ implementation that lists all your tools.)
 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
+## 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
+### 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
@@ -947,8 +1194,8 @@ The contents of `greet.rb` would be:
     end
 
 Notice that we did not use a `tool "greet"` block here. That is because the
-name of the file `greet.rb` already provides a tool context: Toys already knows
-that we are defining a "greet" tool.
+name of the file `greet.rb` already provides a naming 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`. In other words, the path to the Ruby file defines a
@@ -974,7 +1221,7 @@ Once again, `test unit` is the "starting point" for tools defined in the
 file will define the `test unit` tool. Any `tool` blocks you add to that file
 will define subtools of `test unit`.
 
-#### Index Files
+#### Index files
 
 The file name `.toys.rb` can also be used inside Toys directories and
 subdirectories. Such files are called **index files**, and they create tools
@@ -1007,9 +1254,9 @@ 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 defined in that directory, as we shall see later in the
-[section on sharing code](#Sharing_Code).
+[section on sharing code](#Sharing_code).
 
-### The Toys Search Path
+### The Toys search path
 
 So far we have seen how to define tools by writing a `.toys.rb` file in the
 current directory, or by writing files inside a `.toys` directory in the
@@ -1018,14 +1265,16 @@ move to a different directory, they may not be available.
 
 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
+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
-    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* (but does not
-    proceed to parents of the home directory).
-(4) It does the same in the system configuration directory (i.e. `/etc` on unix
-    systems).
+2.  It does the same in the *parent directory* of the current directory, and
+    then its parent, and so on until it hits either the root of the file system
+    or one of the global directories described in (3).
+3.  It looks in a list of *global directories*, specified in the environment
+    variable `TOYS_PATH`. This variable can contain a colon-delimited list of
+    directory paths. If the variable is not set, the current user's *home
+    directory*, and the system configuration directory (`/etc` on unix systems)
+    are used by default. Toys does *not* search parents of global directories.
 
 It uses the *first* implementation that it finds for the requested tool. For
 example, if the tool `greet` is defined in the `.toys.rb` file in the current
@@ -1048,40 +1297,31 @@ 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 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. 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 tools. If you
-do define it, it replaces (3) and (4) with the paths you specify.
+step (3) is *not* context-dependent, and is searched regardless of where you
+are located. Tools defined here are **global**, available everywhere.
 
-## The Execution Environment
+## The execution environment
 
 This section describes the context and resources available to your tool when it
 is running; that is, what you can call from your tool's `run` method.
 
-Generally, your tool is executed in an object of type
-[Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool). This class
-defines a number of methods, and provides access to a variety of data and
+Each tool is defined as a class that subclasses
+[Toys::Context](https://www.rubydoc.info/gems/toys-core/Toys/Context). The base
+class defines a number of methods, and provides access to a variety of data and
 objects relevant to your tool. We have already seen earlier how to use the
-[Toys::Tool#get](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get)
+[Toys::Context#get](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:get)
 method to retrieve option values, and how to use the
-[Toys::Tool#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:exit)
+[Toys::Context#exit](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:exit)
 method to exit immediately and return an exit code. Now we will cover other
 resources available to your tool.
 
-### Built-in Context
+### Built-in context
 
-The options set by your tool's flags and command line arguments are only a
-subset of the data you can access. A variety of other data and objects are
-also accessible using the
-[Toys::Tool#get method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:get)
+In addition to the options set by your tool's flags and command line arguments,
+a variety of other data and objects are also accessible using the
+[Toys::Context#get method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:get)
 For example, you can get the full name of the tool being executed like this:
 
     def run
@@ -1091,15 +1331,15 @@ For example, you can get the full name of the tool being executed like this:
 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).
+[Toys::Context::Key module](https://www.rubydoc.info/gems/toys-core/Toys/Context/Key).
 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.
+like write to the logger 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
-[Toys::Tool#tool_name method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:tool_name):
+[Toys::Context#tool_name method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:tool_name):
 
     def run
       puts "Current tool is #{tool_name}"
@@ -1108,12 +1348,12 @@ For example, the `TOOL_NAME` is also available from the
 Let's take a look at a few things your tool can do with the objects you can
 access from built-in context.
 
-### Logging and Verbosity
+### Logging and verbosity
 
 Toys provides a Logger (a simple instance of the Ruby standard library logger
 that writes to standard error) for your tool to use to report status
 information. You can access this logger via the `LOGGER` context key, or the
-[Toys::Tool#logger method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:logger).
+[Toys::Context#logger method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:logger).
 For example:
 
     def run
@@ -1123,10 +1363,10 @@ For example:
 The current logger level is controlled by the verbosity. Verbosity is an
 integer context value that you can retrieve using the `VERBOSITY` context key
 or the
-[Toys::Tool#verbosity method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:verbosity).
+[Toys::Context#verbosity method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext: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
+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
@@ -1134,11 +1374,11 @@ 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
+### Running tools from tools
 
 A common operation a tool might want to do is "call" another tool. This can be
 done via the CLI object, which you can retrieve using the `CLI` key or the
-[Toys::Tool#cli method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:cli).
+[Toys::Context#cli method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:cli).
 These return the current instance of
 [Toys::CLI](https://www.rubydoc.info/gems/toys-core/Toys/CLI) which is the
 "main" interface to Toys. In particular, it provides the
@@ -1155,15 +1395,15 @@ 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 may also use the `exec` mixin [described below](#Executing_Subprocesses) to
+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 stream.
 
-### Helper Methods and Mixins
+### Helper methods and mixins
 
-The methods of [Toys::Tool](https://www.rubydoc.info/gems/toys-core/Toys/Tool)
+The methods of [Toys::Context](https://www.rubydoc.info/gems/toys-core/Toys/Context)
 are not the only methods available for your tool to call. We
-[saw earlier](#Tool_Execution_Basics) that a tool can define additional methods
+[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
@@ -1188,9 +1428,9 @@ 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
-[upcoming section on defining mixins](#Defining-Mixins).
+[upcoming section on defining mixins](#Defining_mixins).
 
-### Executing Subprocesses
+### Executing subprocesses
 
 Another common operation you might do in a tool is to execute other binaries.
 For example, you might write a tool that shells out to `scp` to copy files to
@@ -1199,8 +1439,8 @@ a remote server.
 Ruby itself provides a few convenient methods for simple execution, such as the
 [Kernel#system](http://ruby-doc.org/core/Kernel.html#method-i-system) method.
 However, these typically provide limited ability to control or interact with
-subprocess streams, and you need to remember to handle the exit status
-yourself. If you do want to exert any control over subprocesses, you can use
+subprocess streams, and you also need to remember to handle the exit status
+yourself. If you do want to exert more control over subprocesses, you can use
 [Process.spawn](http://ruby-doc.org/core/Process.html#method-c-spawn), or a
 higher-level wrapper such as the
 [open3 library](http://ruby-doc.org/stdlib/libdoc/open3/rdoc/index.html).
@@ -1225,7 +1465,7 @@ For more information, see the
 and the underyling library
 [Toys::Utils::Exec](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Exec).
 
-### Formatting Output
+### Formatting output
 
 Interacting with the user is a very common function of a command line tool, and
 many modern tools include intricately designed and styled output, and terminal
@@ -1236,7 +1476,7 @@ First, there is `:terminal`, which provides some basic terminal features such
 as styled output and simple spinners. For information, see the
 [Toys::StandardMixins::Terminal mixin module](https://www.rubydoc.info/gems/toys-core/Toys/StandardMixins/Terminal)
 and the underyling library
-[Toys::Utils::Terminal](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Terminal).
+[Toys::Terminal](https://www.rubydoc.info/gems/toys-core/Toys/Terminal).
 
 If you prefer the venerable Highline library interface, Toys provides a mixin
 called `:highline` that automatically installs the highline gem (version 2.x)
@@ -1246,9 +1486,9 @@ more information, see the
 
 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.
+[useful gems](#Useful_gems) provides some examples.
 
-## Sharing Code
+## Sharing code
 
 As you accumulate additional and more complex tools, you may find that some of
 your tools need to share some common configuration, data, or logic. You might,
@@ -1257,9 +1497,9 @@ authentication. This section describes several techniques for sharing code
 between tools, and describes the scope of Ruby structures, such as methods,
 classes, and constants, that you might define in your tools.
 
-### Defining Mixins
+### 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`
@@ -1274,7 +1514,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.
@@ -1312,15 +1552,15 @@ define a mixin in a file located in a `.toys` directory, it will be visible to
 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
-in a Toys directory. You can then include it from any subtools defined in other
-files in that same 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
+any subtools defined in other files in that same directory.
 
 #### Mixin initializers
 
 Sometimes a mixin will want to initialize some state before the tool executes.
 For example, the `:highline` mixin creates an instance of Highline during tool
-initialization. To do so, provide a `to_initialize` block in the mixin block.
+initialization. To do so, provide an `on_initialize` block in the mixin block.
 The initializer block is called within the context of the tool before it
 initializes, so it has access to the tool's built-in context and options.
 
@@ -1333,8 +1573,9 @@ pass a value to the mixin's initializer:
 
     tool "test" do
       mixin "common_test_code" do
-        # Initialize the mixin, and receive the argument passed to include
-        to_initialize do |type|
+        # Initialize the mixin, and receive the argument passed to the
+        # include directive
+        on_initialize do |type|
           # Initializers are called in the context of the tool, and so can
           # affect the tool's state.
           set(:test_type, type)
@@ -1363,7 +1604,7 @@ pass a value to the mixin's initializer:
       end
     end
 
-### Using Constants
+### Using constants
 
 You can define and use Ruby constants, i.e. names beginning with a capital
 letter, in a Toys file. However, they are subject to Ruby's rules regarding
@@ -1375,7 +1616,7 @@ Toys file), it is important to understand how they work.
 Constants in Toys are visible only within the Toys file in which they are
 defined. They normally behave as though they are defined at the "top level" of
 the file. Even if you define a constant lexically "inside" a tool or a mixin,
-the constant does _not_ end up connected to that tool or mixin; it is defined
+the constant does *not* end up connected to that tool or mixin; it is defined
 at the file level.
 
     tool "test" do
@@ -1397,7 +1638,8 @@ at the file level.
     end
 
 (Note it is still possible to attach constants to a tool or mixin by defining
-them with `self::`. However, this isn't very common practice in Ruby.)
+them with `self::`. However, this is uncommon Ruby practice and is mildly
+discouraged.)
 
 Because of this, it is highly recommended that you define constants only at the
 top level of a Toys file, so it doesn't "look" like it is scoped to something
@@ -1437,11 +1679,11 @@ constants, and thus follow the same rules. So you could, for example, define a
 The difference between this technique and using the `mixin` directive we saw
 earlier, is the scope. The module here is accessed via a constant, and so, like
 any constant, it is visible only in the same file it is defined in. The `mixin`
-directive creates mixins that are visible from _all_ files at the same point in
+directive creates mixins that are visible from *all* files at the same point in
 the search path.
 
 Not also, when you define a mixin in this way, you should include `Toys::Mixin`
-in the module, as illustrated above. This makes `to_initialize` available in
+in the module, as illustrated above. This makes `on_initialize` available in
 the module.
 
 ### Templates
@@ -1481,11 +1723,11 @@ 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 may also write your own templates. Here's how...
 
-#### Defining Templates
+#### Defining templates
 
 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
@@ -1502,7 +1744,7 @@ Following is a simple template example:
       attr_accessor :name
       attr_accessor :whom
 
-      to_expand do |template|
+      on_expand do |template|
         tool template.name do
           desc "A greeting tool generated from a template"
           to_run do
@@ -1521,15 +1763,15 @@ will typically have a constructor, and methods to access configuration
 properties. When the template is expanded, the class gets instantiated, and you
 can set those properties.
 
-Next, a template has a `to_expand` block. This block contains the Toys file
+Next, a template has an `on_expand` block. This block contains the Toys file
 directives that should be generated by the template. The template object is
 passed to the block, so it can access the template configuration when
 generating directives. The "greet" template in the above example generates a
 tool whose name is set by the template's `name` property.
 
-Notice that in the above example, we used `to_run do`, providing a _block_ for
+Notice that in the above example, we used `to_run do`, providing a *block* for
 the tool's execution, rather than `def run`, providing a method. Both forms are
-valid and will work in a template (as well in a normal Toys file), but the
+valid and will work in a template (as well as in a normal Toys file), but the
 block form is often useful in a template because you can access the `template`
 variable inside the block, whereas it would not be accessible if you defined a
 method. Similarly, if your template generates helper methods, and the body of
@@ -1543,7 +1785,7 @@ 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.
 
-#### Template Classes
+#### Template classes
 
 Finally, templates are classes, and you can create a template directly as a
 class by including the
@@ -1560,7 +1802,7 @@ in your class definition.
       attr_accessor :name
       attr_accessor :whom
 
-      to_expand do |template|
+      on_expand do |template|
         tool template.name do
           desc "A greeting tool generated from a template"
           to_run do
@@ -1576,7 +1818,8 @@ Remember that classes created this way are constants, and so the name
 `GreetTemplate` is available only inside the Toys file where it was defined.
 
 You must `include Toys::Template` if you define a template directly as a class,
-but you can omit it if you use the `template` directive to define the template.
+but you can omit it if you use the `template` directive to define the template
+in a block.
 
 Defining templates as classes is also a useful way for third-party gems to
 provide Toys integration. For example, suppose you are writing a code analysis
@@ -1588,7 +1831,7 @@ following in their Toys file:
     require "my_analysis"
     expand MyAnalysis::ToysTemplate
 
-### Preloading Ruby Files
+### Preloading Ruby files
 
 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
@@ -1599,7 +1842,7 @@ 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.
 
 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. Additionally, any Ruby files inside a subdirectory called `.preload`
 are also automatically required.
@@ -1641,10 +1884,10 @@ first before loading any of the tools in the `test` subdirectory. Thus, any
 additional classes needed by `test unit` can be defined in these files.
 
 Either a single `.preload.rb` file or a `.preload` directory, or both, may be
-used. If both are present, the `.preload.rb` file is loaded first before the
-`.preload` directory contents.
+used. If both are present in the same directory, the `.preload.rb` file is
+loaded first before the `.preload` directory contents.
 
-## Using Third-Party Gems
+## 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,
@@ -1654,12 +1897,17 @@ forth.
 
 This section describes how to use a third-party gem in your tool.
 
-### Activating Gems
+### Activating gems
 
-The toys binary 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
+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
@@ -1686,6 +1934,8 @@ defined.
       end
       def run
         # ...
+      end
+    end
 
 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
@@ -1708,8 +1958,13 @@ 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:
+instead. (Note that you must `require "toys/utils/gems"` explicitly before
+invoking the
+[Toys::Utils::Gems](https://www.rubydoc.info/gems/toys-core/Toys/Utils/Gems)
+class because, like all classes under `Toys::Utils`, Toys does not load it
+automatically.) For example:
 
+    require "toys/utils/gems"
     Toys::Utils::Gems.activate("highline", "~> 2.0")
 
 Note these methods are a bit different from the
@@ -1717,7 +1972,7 @@ Note these methods are a bit different from the
 provided by Rubygems. The Toys version attempts to install a missing gem for
 you, whereas Rubygems will just throw an exception.
 
-### Useful Gems
+### 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.
@@ -1790,14 +2045,14 @@ non-deterministic.
 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 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
-contains a `.toys.rb` file instead of a Rakefile for running tests, builds, and
-so forth.
+contains a `.toys.rb` file instead of a Rakefile, for running tests, builds,
+and so forth.
 
 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.
@@ -1808,7 +2063,7 @@ Although Toys and Rake serve many of the same use cases, they have very
 different design goals, and it is useful to understand them.
 
 Rake's design is based on the classic "make" tool often provided in unix
-development environments. This design focuses on _targets_ and _dependencies_,
+development environments. This design focuses on *targets* and *dependencies*,
 and is meant for a world where you invoke an external compiler tool whenever
 changes are made to an individual source file or any of its dependencies. This
 "declarative" approach expresses very well the build process for programs
@@ -1818,8 +2073,8 @@ Ruby, however, does not have an external compiler, and certainly not one that
 requires separate invocation for each source file as does the C compiler. So
 although Rake does support file dependencies, they are much less commonly used
 than in their Makefile cousins. Instead, in practice, most Rake tasks are not
-connected to a dependency at all; they are simply standalone tasks, what would
-be called "phony" targets in Makefile parlance. Such tasks are more imperative
+connected to a dependency at all; they are simply standalone scripts, what
+would be called "phony" targets in a Makefile. Such tasks are more imperative
 than declarative.
 
 The Toys approach to build tools simply embraces the fact that our build
@@ -1831,7 +2086,7 @@ For example, Rake provides a primitive mechanism for passing arguments to a
 task, but it is clumsy and quite different from most unix programs. However, to
 do otherwise would clash with Rake's design goal of treating tasks as targets
 and dependencies. Toys does not have those design goals, so it is able to
-embrace the familiar ways to pass command line arguments.
+embrace the familiar unix conventions for command line arguments.
 
 Toys actually borrows some of its design from the "mix" build tool used for
 Elixir and Erlang programs. Unlike C, the Erlang and Elixir compilers do their
@@ -1844,7 +2099,7 @@ your build tasks. Rake will continue to be your friend in those cases. However,
 for imperative tasks such as "run my tests", "build my YARD documentation", or
 "release my gem", you may find Toys easier to use.
 
-### Using Toys to Invoke Rake Tasks
+### Using Toys to invoke Rake tasks
 
 If you've already written a Rakefile for your project, Toys provides a
 convenient way to invoke your existing Rake tasks using Toys. The built-in
@@ -1857,16 +2112,16 @@ following contents:
     # In .toys.rb
     expand :rake
 
-Now within that directory, if you had a task called `test`, you can invoke it
-with:
+Now within that directory, if you had a Rake task called `test`, you can invoke
+it with:
 
-    toys test
+    $ toys test
 
-Similarly, a task named `test:integration` can be invoked with either of the
-following:
+Similarly, a Rake task named `test:integration` can be invoked with either of
+the following:
 
-    toys test integration
-    toys test:integration
+    $ toys test integration
+    $ toys test:integration
 
 Rake tasks with arguments are mapped to tool arguments, making it easier to
 invoke those tasks using Toys. For example, consider a Rake task with two
@@ -1880,12 +2135,12 @@ arguments, defined as follows:
 
 would have to be invoked as follows using rake:
 
-    rake my_task[value1,value2]
+    $ rake my_task[value1,value2]
 
 You may even need to escape the brackets if you are using a shell that treats
 them specially. Toys will let you pass them as normal command line arguments:
 
-    toys my_task value1 value2
+    $ toys my_task value1 value2
 
 The `:rake` template provides several options. If your Rakefile is named
 something other than `Rakefile` or isn't in the current directory, you can
@@ -1903,9 +2158,9 @@ arguments. Set `:use_flags` when expanding the template:
 Now with this option, to pass arguments to the tool, use the argument names as
 flags:
 
-    toys my_task --first=value1 --second=value2
+    $ toys my_task --first=value1 --second=value2
 
-### From Rakefiles to Toys Files
+### From Rakefiles to Toys files
 
 Invoking Rake tasks using Toys is an easy first step, but eventually you will
 likely want to migrate some of your project's build tasks from Rake to Toys.
@@ -1933,7 +2188,7 @@ Toys to generate common build tools.
 Note that Rakefiles and Toys files can coexist in the same directory, so you
 can use either or both tools, depending on your needs.
 
-### Running Tests
+### Running tests
 
 Toys provides a built-in template called `:minitest` for running unit tests
 with [minitest](https://github.com/seattlerb/minitest). The following example
@@ -1963,7 +2218,7 @@ tool called `rubocop`:
 See the {Toys::Templates::Rubocop} documentation for details on the available
 options.
 
-### Building and Releasing Gems
+### Building and releasing gems
 
 The `:gem_build` built-in template can generate a variety of build and release
 tools for gems, and is a useful alternative to the Rake tasks provided by
@@ -1994,7 +2249,7 @@ example:
 See the {Toys::Templates::Clean} documentation for details on the various
 options for clean.
 
-### Building Documentation
+### Building documentation
 
 Toys provides an `:rdoc` template for creating tools that generate RDoc
 documentation, and a `:yardoc` template for creating tools that generate YARD.
@@ -2006,7 +2261,7 @@ Here's an example for YARD, creating a tool called `yardoc`:
 
     expand :yardoc, protected: true, markup: "markdown"
 
-### Gem Example
+### Gem example
 
 Let's look at a complete example that combines the techniques above to provide
 all the basic tools for a Ruby gem. It includes:
@@ -2021,9 +2276,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, it is
-nearly 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 very
+similar to the Toys files provided for the **toys** and **toys-core** gems
+themselves.
 
     # This file is .toys.rb
 
@@ -2051,14 +2306,16 @@ gems themselves.
     # The normal "build" tool that just builds a gem into the pkg directory.
     expand :gem_build
 
+    # An "install" tool that builds the gem and installs it locally.
+    expand :gem_build, name: "install", install_gem: true
+
     # A full gem "release" tool that builds the gem, and pushes it to rubygems.
     # This assumes your local rubygems configuration is set up with the proper
     # credentials.
     expand :gem_build, name: "release", push_gem: true
 
     # Now we create a full CI tool. It runs the test, rubocop, and yardoc tools
-    # and checks for errors. This tool could be invoked from Travis-CI or
-    # similar CI system.
+    # and checks for errors. This tool could be invoked from a CI system.
     tool "ci" do
       # The :exec mixin provides the exec_tool() method that we will use to run
       # other tools and check their exit status.
@@ -2088,7 +2345,7 @@ gems themselves.
       end
     end
 
-## Advanced Tool Definition Techniques
+## Advanced tool definition techniques
 
 This section covers some additional features that are often useful for writing
 tools. I've labeled them "advanced", but all that really means is that this
@@ -2112,7 +2369,7 @@ To define an alias, use the `alias_tool` directive:
     alias_tool "t", "test"
 
 You may create an alias of a subtool, but the alias must have the same parent
-(namespace) tool as the target tool. For example:
+(namespace) as the target tool. For example:
 
     tool "gem" do
       tool "test" do
@@ -2123,7 +2380,7 @@ You may create an alias of a subtool, but the alias must have the same parent
       alias_tool "t", "test"
     end
 
-### Custom Acceptors
+### Custom acceptors
 
 We saw earlier that flags and positional arguments can have acceptors, which
 control the allowed format, and may also convert the string argument to a Ruby
@@ -2167,7 +2424,7 @@ A common technique, for example, would be to define an acceptor in the index
 file in a Toys directory. You can then include it from any subtools defined in
 other files in that same directory.
 
-### Controlling Built-in Flags
+### Controlling built-in flags
 
 Earlier we saw that certain flags are added automatically to every tool:
 `--verbose`, `--quiet`, `--help`, and so forth. You may occasionally want to
@@ -2178,14 +2435,14 @@ the flag as you choose. Flags explicitly defined by your tool take precedence
 over the built-ins.
 
 For example, normally two built-in flags are provided to decrease the verbosity
-level: `-q` and `--quiet`. If you define `-q` yourself—for example to activate
-a "quick" mode—then `-q` will be repurposed for your flag, but `--quiet` will
+level: `-q` and `--quiet`. If you define `-q` yourself (for example to activate
+a "quick" mode) then `-q` will be repurposed for your flag, but `--quiet` will
 still be present to decrease verbosity.
 
     # Repurposes -q to set the "quick" option instead of "quiet"
     flag :quick, "-q"
 
-You may also completely disable a flag, and _not_ repurpose it, using the
+You may also completely disable a flag, and *not* repurpose it, using the
 `disable_flag` directive. It lets you mark one or more flags as "never use".
 
 For example, if you disable the `-q` flag, then `-q` will no longer be a
@@ -2198,7 +2455,83 @@ completely disable decreasing the verbosity, disable both `-q` and `--quiet`.
     # Completely disables decreasing verbosity
     disable_flag "-q", "--quiet"
 
-### Disabling Argument Parsing
+### Enforcing flags before args
+
+By default, tools allow flags and positional arguments to be interspersed when
+command line arguments are parsed. This matches the behavior of most common
+command line binaries.
+
+However, some tools prefer to follow the convention that all flags must appear
+first, followed by positional arguments. In such a tool, once a non-flag
+argument appears on the command line, all remaining arguments are treated as
+positional, even if they look like a flag and start with a hyphen.
+
+You may configure a tool to follow this alternate parsing strategy using the
+`enforce_flags_before_args` directive.
+
+The built-in tool `toys do` is an example of a tool that does this. It
+recognizes its own flags (such as `--help` and `--delim`) but once positional
+arguments start appearing, it wants further flags to be treated as positional
+so it can pass them down to the different steps it is executing. Here is a
+simplified excerpt from the implementation that tool:
+
+    tool "do" do
+      flag :delim, default: ","
+      remaining_args :commands  # the commands to execute
+      enforce_flags_before_args
+      def run
+        # Now commands includes both the commands to run and
+        # the "flags" to pass to them.
+        commands.each do
+          # ...
+        end
+      end
+    end
+
+### Requiring exact flag matches
+
+By default, tools will recognized "shortened" forms of long flags. For example,
+most suppose you are defining a tool with long flags:
+
+    tool "my-tool" do
+      flag :long_flag_name, "--long-flag-name"
+      flag :another_long_flag, "--another-long-flag"
+      def run
+        # ...
+      end
+    end
+
+When you invoke this tool, you do not need to type the entire flag names.
+Abbreviations will also work:
+
+    $ toys my-tool --long --an
+
+As long as the abbreviation is unambiguous (i.e. there is no other flag that
+begins with the same string), the Toys argument parser will recognize the flag.
+This is consistent with the behavior of most command line tools (and is also
+the behavior of Ruby's OptionParser library.)
+
+However, it is possible to disable this behavior and require that flags be
+presented in their entirety, using the `require_exact_flag_match` directive.
+
+    tool "my-tool" do
+      require_exact_flag_match
+      flag :long_flag_name, "--long-flag-name"
+      flag :another_long_flag, "--another-long-flag"
+      def run
+        # ...
+      end
+    end
+
+Now, all flags for this tool must be presented in their entirety. Abbreviations
+are not allowed.
+
+    $ toys my-tool --long-flag-name --another-long-flag
+
+Currently you can require exact flag matches only at the tool level, applied to
+all flags for that tool. You cannot set this option for individual flags.
+
+### Disabling argument parsing
 
 Normally Toys handles parsing command line arguments for you. This makes
 writing tools easier, and also allows Toys to generate documentation
@@ -2211,7 +2544,7 @@ To disable argument parsing, use the `disable_argument_parsing` directive. This
 directive disables parsing and validation of flags and positional arguments.
 (Thus, it is incompatible with specifying any flags or arguments for the tool.)
 Instead, you can retrieve the raw arguments using the
-[Toys::Tool#args method](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:args).
+[Toys::Context#args method](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:args).
 
 Here is an example that wraps calls to git:
 
@@ -2224,24 +2557,123 @@ Here is an example that wraps calls to git:
       end
     end
 
-### Data Files
+### Handling interrupts
+
+If you interrupt a running tool, say, by hitting `CTRL`-`C`, Toys will normally
+terminate execution and display the message `INTERRUPTED` on the standard error
+stream.
+
+If your tool needs to handle interrupts itself, you have several options. You
+can rescue the `Interrupt` exception or call `Signal.trap`. Or you can provide
+an *interrupt handler* in your tool using the `on_interrupt` directive. This
+directive either provides a block to handle interrupts, or designates a named
+method as the handler. If an interrupt handler is present, Toys will handle
+interrupts as follows:
+
+1.  Toys will terminate the tool's `run` method by raising an `Interrupt`
+    exception. Any `ensure` blocks will be called.
+2.  Toys will call the interrupt handler. If this method or block takes an
+    argument, Toys will pass it the `Interrupt` exception object.
+3.  The interrupt handler is then responsible for tool execution from that
+    point. It may terminate execution by returning or calling `exit`, or it may
+    restart or resume processing (perhaps by calling the `run` method again).
+    Or it may invoke the normal Toys interrupt handling (i.e. terminating
+    execution, displaying the message `INTERRUPTED`) by re-raising *the same*
+    interrupt exception object.
+4.  If another interrupt takes place during the execution of the interrupt
+    handler, Toys will terminate it by raising a *second* `Interrupt` exception
+    (calling any `ensure` blocks). Then, the interrupt handler will be called
+    *again* and passed the new exception. Any additional interrupts will be
+    handled similarly.
+
+Because the interrupt handler is called again even if it is itself interrupted,
+you might consider detecting this case if your interrupt handler might be
+long-running. You can tell how many interrupts have taken place by looking at
+the `Exception#cause` property of the exception. The first interrupt will have
+a cause of `nil`. The second interrupt (i.e. the interrupt raised the first
+time the interrupt handler is itself interrupted) will have its cause point to
+the first interrupt (which in turn has a `nil` cause.) The third interrupt's
+cause will point to the second interrupt, and so on. So you can determine the
+interrupt "depth" by counting the length of the cause chain.
+
+Here is an example that performs a long-running task. The first two times the
+task is interrupted, it is restarted. The third time, it is terminated.
+
+    tool "long-running" do
+      def long_task(is_restart)
+        puts "task #{is_restart ? 're' : ''}starting..."
+        sleep 10
+        puts "task finished!"
+      end
+
+      def run
+        long_task(false)
+      end
+
+      on_interrupt do |ex|
+        # The third interrupt will have a non-nil ex.cause.cause.
+        # At that time, just give up and re-raise the exception, which causes
+        # it to propagate out and invoke the standard Toys interrupt handler.
+        raise ex if ex.cause&.cause
+        # Otherwise, restart the long task.
+        long_task(true)
+      end
+    end
+
+### Handling usage errors
+
+Normally, if Toys detects a usage error (such as an unrecognized flag) while
+parsing arguments, it will respond by aborting the tool and displaying the
+usage error. It is possible to override this behavior by providing your own
+usage error handler using the `on_usage_error` directive. This directive either
+provides a block to handle usage errors, or designates a named method as the
+handler.
+
+If your handler block or method takes a parameter, Toys will pass it the array
+of usage errors. Otherwise, you can get the array by calling
+[Toys::Context#usage_errors](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:usage_errors).
+This array will provide you with a list of the usage errors encountered.
+
+You can also get information about the arguments that could not be parsed from
+the context. For example, the list of unrecognized flags is available from the
+context key `UNMATCHED_FLAGS`.
+
+One common technique is to redirect usage errors back to the `run` method. In
+this way, `run` is called regardless of whether argument parsing succeeded or
+failed.
+
+    tool "lenient-parser" do
+      flag :abc
+
+      on_usage_error :run
+
+      def run
+        if usage_errors.empty?
+          puts "Usage was correct"
+        else
+          puts "Usage was not correct"
+        end
+      end
+    end
+
+### Data files
 
 If your tools require images, archives, keys, or other such static data, Toys
 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 may then "find" a data file by providing the relative path to the file from
 the `.data` directory. When defining a tool, use the
 [Toys::DSL::Tool#find_data](https://www.rubydoc.info/gems/toys-core/Toys%2FDSL%2FTool:find_data)
 directive in a Toys file. Or, at tool execution time, call
-[Toys::Tool#find_data](https://www.rubydoc.info/gems/toys-core/Toys%2FTool:find_data)
+[Toys::Context#find_data](https://www.rubydoc.info/gems/toys-core/Toys%2FContext:find_data)
 (which is a convenience method for getting the tool source object using the
 `TOOL_SOURCE` key, and calling
-[Toys::Definition::SourceInfo#find_data](https://www.rubydoc.info/gems/toys-core/Toys%2FDefinition%2FSourceInfo:find_data)
+[Toys::SourceInfo#find_data](https://www.rubydoc.info/gems/toys-core/Toys%2FSourceInfo:find_data)
 on it). In either case, `find_data` locates a matching file (or directory)
 among the data files, and returns the full path to that file system object. You
 may then read the file or perform any other operation on it.
@@ -2321,7 +2753,7 @@ If, however, you find `greeting.txt` from a tool under `test`, it will still
 find the more general `.toys/.data/greeting.txt` file because there is no
 overriding file under `.toys/test/.data`.
 
-### The Context Directory
+### The context directory
 
 The **context directory** for a tool is the directory containing the toplevel
 `.toys.rb` file or the `.toys` directory within which the tool is defined. It
@@ -2352,8 +2784,8 @@ This tool assumes it will be run from the main project directory (`my-project`
 in the above case). However, Toys lets you invoke tools even if you are in a
 subdirectory:
 
-    cd lib
-    toys list-tests  # Does not work
+    $ cd lib
+    $ toys list-tests  # Does not work
 
 Rake handles this by actually changing the current working directory to the
 directory containing the active Rakefile. Toys, however, does not change the
@@ -2388,10 +2820,10 @@ the entire toys directory structure. So if your tool definition is inside a
 
 This behavior 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
+#### Changing the context directory
 
 It is even possible to modify the context directory, causing tools that use the
 context directory (such as the standard build tools) to run in a different
@@ -2450,7 +2882,7 @@ context directory to `my-repo/gem1`. Here's what that could look like:
       # etc.
     end
 
-### Hidden Tools
+### Hidden tools
 
 Tools whose name begins with an underscore (e.g. `_foo`) are called "hidden"
 tools. They can be executed the same as any other tool, but are normally
@@ -2461,12 +2893,12 @@ the implementation of other tools.
 If you pass the `--all` flag when displaying help, the help screen will include
 hidden tools in the subtools list.
 
-## Toys Administration Using the System Tools
+## Toys administration using the system tools
 
 Toys comes with a few built-in tools, including some that let you administer
 Toys itself. These tools live in the `system` namespace.
 
-### Getting the Toys Version
+### Getting the Toys version
 
 You can get the current version of Toys by running:
 
@@ -2489,39 +2921,69 @@ installation if it is not already current.
 Normall it asks you for confirmation before downloading. To disable interactive
 confirmation, pass the `--yes` flag.
 
-A similar effect can of course be obtained simply by `gem install toys`.
+A similar effect can of course be obtained by running `gem install toys`.
+
+### Installing tab completion for Bash
+
+Toys provides tab completion for the bash shell, and lets tools customize the
+completions for their arguments. However, you need to install the Toys
+completion tool into your shell. The following command sets up tab completion
+the current shell:
+
+    $(toys system bash-completion install)
+
+Typically, you will want to include the above in your `.bashrc` or other bash
+initialization file.
+
+By default, this associates the Toys tab completion logic with the `toys`
+executable. If you have other names or aliases for the executable, pass them as
+arguments. For example, I use `t` as an alias for `toys`, and I therefore
+install Toys's completion logic for `t`:
+
+    $(toys system bash-completion install t)
+
+You can also remove the completion logic from the current shell:
+
+    $(toys system bash-completion remove)
+    $(toys system bash-completion remove t)
+
+At this time, bash is the only shell that is supported directly. If you are
+using zsh, however, you can use the `bashcompinit` function to load the toys
+bash completion (as well as other bash-based completions). This *mostly* works,
+with a few caveats. Native zsh completion is on the future roadmap.
 
-## Writing Your Own CLI Using Toys
+## Writing your own CLI using Toys
 
 Although Toys is not primarily designed to help you write a custom command-line
-binary, you can use it in that way. Toys is factored into two gems:
+executable, you can use it in that way. Toys is factored into two gems:
 **toys-core**, which includes all the underlying machinery for creating
-command-line binaries, and **toys**, which is really just a wrapper that
-provides the `toys` binary itself and its built-in commands and behavior. To
-write your own command line binary based on the Toys system, just require the
-**toys-core** gem and configure your binary the way you want.
+command-line executables, and **toys**, which is really just a wrapper that
+provides the `toys` executable itself and its built-in commands and behavior.
+To write your own command line executable based on the Toys system, just
+require the **toys-core** gem and configure your executable the way you want.
 
 Toys-Core is modular and lets you customize much of the behavior of a command
-line binary. For example:
+line executable, simply by setting options or adding plugins. For example:
 
 *   Toys itself automatically adds a number of flags, such as `--verbose` and
-    `--help`, to each tool. Toys-Core lets you customize what flags are
-    automatically added for your own command line binary.
-*   Toys itself provides a default way to run tools that have no `run` method:
-    it assumes such tools are namespaces, and displays the online help screen.
+    `--help`, to each tool. Toys-Core lets you customize what flags (if any)
+    are automatically added for your own command line executable.
+*   Toys itself provides a default way to run tools that have no `run` method.
+    It assumes such tools are namespaces, and displays the online help screen.
     Toys-Core lets you provide an alternate default run method for your own
-    command line binary.
+    command line executable.
 *   Toys itself provides several built-in tools, such as `do`, and `system`.
-    Toys-Core lets you write your own command line binary with its own built-in
-    tools.
+    Toys-Core lets you write your own command line executable with its own
+    built-in tools.
 *   Toys itself implements a particular search path for user-provided Toys
     files, and looks for specific file and directory names such as `.toys.rb`.
     Toys-Core lets you change the search path, the file/directory names, or
     disable user-provided Toys files altogether for your own command line
-    binary. Indeed, most command line binaries do not need user-customizable
-    tools, and can ship with only built-in tools.
-*   Toys itself has a particular way of displaying online help and displaying
-    errors. Toys-Core lets your own command line binary customize these.
+    executable. Indeed, most command line executables do not need
+    user-customizable tools, and can ship with only built-in tools.
+*   Toys itself has a particular way of displaying online help and reporting
+    errors. Toys-Core lets your own command line executable customize these and
+    many other features.
 
 For more information, see the
 [Toys-Core documentation](https://www.rubydoc.info/gems/toys-core/).