toys-core 0.7.0 → 0.8.0

data/lib/toys/dsl/tool.rb

@@ -1,32 +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.
 ;
 
 module Toys
@@ -69,121 +61,251 @@ module Toys
       end
 
       ##
-      # Create an acceptor that can be passed into a flag or arg. An acceptor
-      # validates and/or converts a string parameter to a Ruby object. This
-      # acceptor may, for the current tool, be referenced by the name you provide
-      # when you create a flag or arg.
+      # Create a named acceptor that can be referenced by name from any flag or
+      # positional argument in this tool or its subtools.
+      #
+      # An acceptor validates the string parameter passed to a flag or
+      # positional argument. It also optionally converts the string to a
+      # different object before storing it in your tool's data.
+      #
+      # Acceptors can be defined in one of four ways.
+      #
+      #  *  You can provide a **regular expression**. This acceptor validates
+      #     only if the regex matches the *entire string parameter*.
+      #
+      #     You can also provide an optional conversion function as a block. If
+      #     provided, function must take a variable number of arguments, the
+      #     first being the matched string and the remainder being the captures
+      #     from the regular expression. It should return the converted object
+      #     that will be stored in the context data. If you do not provide a
+      #     block, the original string will be used.
+      #
+      #  *  You can provide an **array** of possible values. The acceptor
+      #     validates if the string parameter matches the *string form* of one
+      #     of the array elements (i.e. the results of calling `to_s` on the
+      #     array elements.)
+      #
+      #     An array acceptor automatically converts the string parameter to
+      #     the actual array element that it matched. For example, if the
+      #     symbol `:foo` is in the array, it will match the string `"foo"`,
+      #     and then store the symbol `:foo` in the tool data.
+      #
+      #  *  You can provide a **range** of possible values, along with a
+      #     conversion function that converts a string parameter to a type
+      #     comparable by the range. (See the "function" spec below for a
+      #     detailed description of conversion functions.) If the range has
+      #     numeric endpoints, the conversion function is optional because a
+      #     default will be provided.
+      #
+      #  *  You can provide a **function** by passing it as a proc or a block.
+      #     This function performs *both* validation and conversion. It should
+      #     take the string parameter as its argument, and it must either
+      #     return the object that should be stored in the tool data, or raise
+      #     an exception (descended from `StandardError`) to indicate that the
+      #     string parameter is invalid.
+      #
+      # ## Example
+      #
+      # The following example creates an acceptor named "hex" that is defined
+      # via a regular expression. It then uses it to validate values passed to
+      # a flag.
+      #
+      #     tool "example" do
+      #       acceptor "hex", /[0-9a-fA-F]+/, type_desc: "hex numbers"
+      #       flag :number, accept: "hex"
+      #       def run
+      #         puts "number was #{number}"
+      #       end
+      #     end
+      #
+      # @param name [String] The acceptor name.
+      # @param spec [Object] See the description for recognized values.
+      # @param type_desc [String] Type description string, shown in help.
+      #     Defaults to the acceptor name.
+      # @param block [Proc] See the description for recognized forms.
+      # @return [self]
+      #
+      def acceptor(name, spec = nil, type_desc: nil, &block)
+        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool&.add_acceptor(name, spec, type_desc: type_desc || name.to_s, &block)
+        self
+      end
+
+      ##
+      # Create a named mixin module that can be included by name from this tool
+      # or its subtools.
       #
-      # An acceptor contains a validator, which parses and validates the string
-      # syntax of an argument, and a converter, which takes the validation
-      # results and returns a final value for the context data.
+      # A mixin is a module that defines methods that can be called from a
+      # tool. It is commonly used to provide "utility" methods, implementing
+      # common functionality and allowing tools to share code.
       #
-      # The validator may be either a regular expression or a list of valid
-      # inputs.
+      # Normally you provide a block and define the mixin's methods in that
+      # block. Alternatively, you can create a module separately and pass it
+      # directly to this directive.
       #
-      # If the validator is a regular expression, it is matched against the
-      # argument string and succeeds only if the expression covers the *entire*
-      # string. The elements of the MatchData (i.e. the string matched, plus any
-      # captures) are then passed into the conversion function.
+      # ## Example
       #
-      # If the validator is an array, the *string form* of the array elements
-      # (i.e. the results of calling to_s on each element) are considered the
-      # valid values for the argument. This is useful for enums, for example.
-      # In this case, the input is converted to the original array element, and
-      # any converter function you provide is ignored.
+      # The following example creates a named mixin and uses it in a tool.
       #
-      # If you provide no validator, then no validation takes place and all
-      # argument strings are considered valid. The string itself is passed on to
-      # the converter.
+      #     mixin "error-reporter" do
+      #       def error message
+      #         logger.error "An error occurred: #{message}"
+      #         exit 1
+      #       end
+      #     end
       #
-      # The converter should be a proc that takes as its arguments the results
-      # of validation. For example, if you use a regular expression validator,
-      # the converter should take a series of strings arguments, the first of
-      # which is the full input string, and the rest of which are captures.
-      # If you provide no converter, no conversion is done and the input string
-      # is considered the final value. You may also provide the converter as a
-      # block.
+      #     tool "build" do
+      #       include "error-reporter"
+      #       def run
+      #         puts "Building..."
+      #         error "Build failed!"
+      #       end
+      #     end
       #
-      # @param [String] name The acceptor name.
-      # @param [Regexp,Array,nil] validator The validator.
-      # @param [Proc,nil] converter The validator.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param name [String] Name of the mixin
+      # @param mixin_module [Module] Module to use as the mixin. Optional.
+      #     Either pass a module here, *or* provide a block and define the
+      #     mixin within the block.
+      # @param block [Proc] Defines the mixin module.
+      # @return [self]
       #
-      def acceptor(name, validator = nil, converter = nil, &block)
+      def mixin(name, mixin_module = nil, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        return self if cur_tool.nil?
-        accept =
-          case validator
-          when ::Regexp
-            Definition::PatternAcceptor.new(name, validator, converter, &block)
-          when ::Array
-            Definition::EnumAcceptor.new(name, validator)
-          when nil
-            Definition::Acceptor.new(name, converter, &block)
-          else
-            raise ToolDefinitionError, "Illegal validator: #{validator.inspect}"
-          end
-        cur_tool.add_acceptor(accept)
+        cur_tool&.add_mixin(name, mixin_module, &block)
         self
       end
 
       ##
-      # Create a named mixin module.
-      # This module may be included by name in this tool or any subtool.
+      # Create a named template that can be expanded by name from this tool
+      # or its subtools.
+      #
+      # A template is an object that generates DSL directives. You can use it
+      # to build "prefabricated" tools, and then instantiate them in your Toys
+      # files. Generally, a template is a class with an associated `expansion`
+      # procedure. The class defines parameters for the template expansion,
+      # and `expansion` includes DSL directives that should be run based on
+      # those parameters.
+      #
+      # Normally, you provide a block and define the template class in that
+      # block. Most templates will define an `initialize` method that takes any
+      # arguments passed into the template expansion. The template must also
+      # provide an `expansion` block showing how to use the template object to
+      # produce DSL directives.
+      #
+      # Alternately, you can create a template class separately and pass it
+      # directly. See {Toys::Template} for details on creating a template
+      # class.
+      #
+      # ## Example
+      #
+      # The following example creates and uses a simple template.
+      #
+      #     template "hello-generator" do
+      #       def initialize(name, message)
+      #         @name = name
+      #         @message = message
+      #       end
+      #       attr_reader :name, :message
+      #       expansion do |template|
+      #         tool template.name do
+      #           to_run do
+      #             puts template.message
+      #           end
+      #         end
+      #       end
+      #     end
       #
-      # You should pass a block and define methods in that block.
+      #     expand "hello-generator", "mytool", "mytool is running!"
       #
-      # @param [String] name Name of the mixin
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param name [String] Name of the template
+      # @param template_class [Class] Module to use as the mixin. Optional.
+      #     Either pass a module here, *or* provide a block and define the
+      #     mixin within the block.
+      # @param block [Proc] Defines the template class.
+      # @return [self]
       #
-      def mixin(name, &block)
+      def template(name, template_class = nil, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        if cur_tool
-          mixin_mod = ::Module.new do
-            include ::Toys::Mixin
-          end
-          mixin_mod.module_eval(&block)
-          cur_tool.add_mixin(name, mixin_mod)
-        end
+        cur_tool&.add_template(name, template_class, &block)
         self
       end
 
       ##
-      # Create a named template class.
-      # This template may be expanded by name in this tool or any subtool.
+      # Create a named completion procedure that may be used by name by any
+      # flag or positional arg in this tool or any subtool.
+      #
+      # A completion controls tab completion for the value of a flag or
+      # positional argument. In general, it is a Ruby `Proc` that takes a
+      # context object (of type {Toys::Completion::Context}) and returns an
+      # array of completion candidate strings.
+      #
+      # Completions can be specified in one of three ways.
+      #
+      #  *  A Proc object itself, either passed directly to this directive or
+      #     provided as a block.
+      #  *  A static array of strings, indicating the completion candidates
+      #     independent of context.
+      #  *  The symbol `:file_system` which indicates that paths in the file
+      #     system should serve as completion candidates.
+      #
+      # ## Example
       #
-      # You should pass a block and define the template in that block. You do
-      # not need to include `Toys::Template` in the block. Otherwise, see
-      # {Toys::Template} for information on defining a template. In general,
-      # the block should define an initialize method, and call `to_expand` to
-      # define how to expand the template.
+      # The following example defines a completion that uses only the immediate
+      # files in the current directory as candidates. (This is different from
+      # the `:file_system` completion which will descend into subdirectories
+      # similar to how bash completes most of its file system commands.)
       #
-      # @param [String] name Name of the template
-      # @return [Toys::DSL::Tool] self, for chaining.
+      #     completion "local-files" do |_context|
+      #       `/bin/ls`.split("\n")
+      #     end
+      #     tool "example" do
+      #       flag :file, complete_values: "local-files"
+      #       def run
+      #         puts "selected file #{file}"
+      #       end
+      #     end
+      #
+      # @param name [String] Name of the completion
+      # @param spec [Object] See the description for recognized values.
+      # @param options [Hash] Additional options to pass to the completion.
+      # @param block [Proc] See the description for recognized forms.
+      # @return [self]
       #
-      def template(name, &block)
+      def completion(name, spec = nil, **options, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        if cur_tool
-          template_class = ::Class.new do
-            include ::Toys::Template
-          end
-          template_class.class_eval(&block)
-          cur_tool.add_template(name, template_class)
-        end
+        cur_tool&.add_completion(name, spec, options, &block)
         self
       end
 
       ##
       # Create a subtool. You must provide a block defining the subtool.
       #
-      # @param [String,Array<String>] words The name of the subtool
-      # @param [:combine,:reset,:ignore] if_defined What to do if a definition
+      # ## Example
+      #
+      # The following example defines a tool and two subtools within it.
+      #
+      #     tool "build" do
+      #       tool "staging" do
+      #         def run
+      #           puts "Building staging"
+      #         end
+      #       end
+      #       tool "staging" do
+      #         def run
+      #           puts "Building staging"
+      #         end
+      #       end
+      #     end
+      #
+      # @param words [String,Array<String>] The name of the subtool
+      # @param if_defined [:combine,:reset,:ignore] What to do if a definition
       #     already exists for this tool. Possible values are `:combine` (the
       #     default) indicating the definition should be combined with the
       #     existing definition, `:reset` indicating the earlier definition
       #     should be reset and the new definition applied instead, or
       #     `:ignore` indicating the new definition should be ignored.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Defines the subtool.
+      # @return [self]
       #
       def tool(words, if_defined: :combine, &block)
         subtool_words = @__words
@@ -193,7 +315,7 @@ module Toys
           subtool_words += [word]
           next_remaining = Loader.next_remaining_words(next_remaining, word)
         end
-        subtool = @__loader.get_tool_definition(subtool_words, @__priority)
+        subtool = @__loader.get_tool(subtool_words, @__priority)
         if subtool.includes_definition?
           case if_defined
           when :ignore
@@ -213,9 +335,24 @@ module Toys
       ##
       # Create an alias in the current namespace.
       #
-      # @param [String] word The name of the alias
-      # @param [String] target The target of the alias
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # An alias is an alternate name for a tool. The referenced tool must be
+      # in the same namespace.
+      #
+      # ## Example
+      #
+      # This example defines a tool and an alias pointing to it. Both the tool
+      # name `test` and the alias `t` will then refer to the same tool.
+      #
+      #     tool "test" do
+      #       def run
+      #         puts "Running tests..."
+      #       end
+      #     end
+      #     alias_tool "t", "test"
+      #
+      # @param word [String] The name of the alias
+      # @param target [String] The target of the alias
+      # @return [self]
       #
       def alias_tool(word, target)
         @__loader.make_alias(@__words + [word.to_s], @__words + [target.to_s], @__priority)
@@ -226,8 +363,8 @@ module Toys
       # Load another config file or directory, as if its contents were inserted
       # at the current location.
       #
-      # @param [String] path The file or directory to load.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param path [String] The file or directory to load.
+      # @return [self]
       #
       def load(path)
         @__loader.load_path(source_info, path, @__words, @__remaining_words, @__priority)
@@ -240,16 +377,37 @@ module Toys
       # The template may be specified as a class or a well-known template name.
       # You may also provide arguments to pass to the template.
       #
-      # @param [Class,String,Symbol] template_class The template, either as a
+      # ## Example
+      #
+      # The following example creates and uses a simple template.
+      #
+      #     template "hello-generator" do
+      #       def initialize(name, message)
+      #         @name = name
+      #         @message = message
+      #       end
+      #       attr_reader :name, :message
+      #       expansion do |template|
+      #         tool template.name do
+      #           to_run do
+      #             puts template.message
+      #           end
+      #         end
+      #       end
+      #     end
+      #
+      #     expand "hello-generator", "mytool", "mytool is running!"
+      #
+      # @param template_class [Class,String,Symbol] The template, either as a
       #     class or a well-known name.
-      # @param [Object...] args Template arguments
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param args [Object...] Template arguments
+      # @return [self]
       #
       def expand(template_class, *args)
         cur_tool = DSL::Tool.current_tool(self, false)
         name = template_class.to_s
         if template_class.is_a?(::String)
-          template_class = cur_tool.resolve_template(template_class)
+          template_class = cur_tool.lookup_template(template_class)
         elsif template_class.is_a?(::Symbol)
           template_class = @__loader.resolve_standard_template(name)
         end
@@ -258,29 +416,32 @@ module Toys
         end
         template = template_class.new(*args)
         yield template if block_given?
-        class_exec(template, &template_class.expander)
+        class_exec(template, &template_class.expansion)
         self
       end
 
       ##
-      # Set the short description for the current tool. The short description is
-      # displayed with the tool in a subtool list. You may also use the
+      # Set the short description for the current tool. The short description
+      # is displayed with the tool in a subtool list. You may also use the
       # equivalent method `short_desc`.
       #
-      # The description is a {Toys::Utils::WrappableString}, which may be word-
-      # wrapped when displayed in a help screen. You may pass a
-      # {Toys::Utils::WrappableString} directly to this method, or you may pass
-      # any input that can be used to construct a wrappable string:
+      # The description is a {Toys::WrappableString}, which may be word-wrapped
+      # when displayed in a help screen. You may pass a {Toys::WrappableString}
+      # directly to this method, or you may pass any input that can be used to
+      # construct a wrappable string:
       #
-      # *   If you pass a String, its whitespace will be compacted (i.e. tabs,
+      #  *  If you pass a String, its whitespace will be compacted (i.e. tabs,
       #     newlines, and multiple consecutive whitespace will be turned into a
       #     single space), and it will be word-wrapped on whitespace.
-      # *   If you pass an Array of Strings, each string will be considered a
-      #     literal word that cannot be broken, and wrapping will be done across
-      #     the strings in the array. In this case, whitespace is not compacted.
+      #  *  If you pass an Array of Strings, each string will be considered a
+      #     literal word that cannot be broken, and wrapping will be done
+      #     across the strings in the array. In this case, whitespace is not
+      #     compacted.
       #
-      # For example, if you pass in a sentence as a simple string, it may be
-      # word wrapped when displayed:
+      # ## Examples
+      #
+      # If you pass in a sentence as a simple string, it may be word wrapped
+      # when displayed:
       #
       #     desc "This sentence may be wrapped."
       #
@@ -289,8 +450,8 @@ module Toys
       #
       #     desc ["This sentence will not be wrapped."]
       #
-      # @param [Toys::Utils::WrappableString,String,Array<String>] str
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param str [Toys::WrappableString,String,Array<String>]
+      # @return [self]
       #
       def desc(str)
         cur_tool = DSL::Tool.current_tool(self, true)
@@ -300,24 +461,27 @@ module Toys
       alias short_desc desc
 
       ##
-      # Set the long description for the current tool. The long description is
-      # displayed in the usage documentation for the tool itself.
+      # Add to the long description for the current tool. The long description
+      # is displayed in the usage documentation for the tool itself. This
+      # directive may be given multiple times, and the results are cumulative.
       #
       # A long description is a series of descriptions, which are generally
       # displayed in a series of lines/paragraphs. Each individual description
-      # uses the form described in the {Toys::DSL::Tool#desc} documentation, and
-      # may be word-wrapped when displayed. To insert a blank line, include an
-      # empty string as one of the descriptions.
+      # uses the form described in the {#desc} documentation, and may be
+      # word-wrapped when displayed. To insert a blank line, include an empty
+      # string as one of the descriptions.
       #
-      # Example:
+      # ## Example
       #
-      #     long_desc "This is an initial paragraph that might be word wrapped.",
+      #     long_desc "This initial paragraph might get word wrapped.",
       #               "This next paragraph is followed by a blank line.",
       #               "",
-      #               ["This line will not be wrapped."]
+      #               ["This line will not be wrapped."],
+      #               ["    This indent is preserved."]
+      #     long_desc "This line is appended to the description."
       #
-      # @param [Toys::Utils::WrappableString,String,Array<String>...] strs
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param strs [Toys::WrappableString,String,Array<String>...]
+      # @return [self]
       #
       def long_desc(*strs)
         DSL::Tool.current_tool(self, true)&.append_long_desc(strs)
@@ -329,33 +493,39 @@ module Toys
       # belong to the group. The flags in the group are listed together in
       # help screens.
       #
-      # Example:
+      # ## Example
+      #
+      # The following example creates a flag group in which all flags are
+      # optional.
       #
-      #     flag_group desc: "Debug Flags" do
-      #       flag :debug, "-D", desc: "Enable debugger"
-      #       flag :warnings, "-W[VAL]", desc: "Enable warnings"
+      #     tool "execute" do
+      #       flag_group desc: "Debug Flags" do
+      #         flag :debug, "-D", desc: "Enable debugger"
+      #         flag :warnings, "-W[VAL]", desc: "Enable warnings"
+      #       end
+      #       # ...
       #     end
       #
-      # @param [Symbol] type The type of group. Allowed values: `:required`,
+      # @param type [Symbol] The type of group. Allowed values: `:required`,
       #     `:optional`, `:exactly_one`, `:at_most_one`, `:at_least_one`.
       #     Default is `:optional`.
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the group. See {Toys::Definition::Tool#desc=} for a
-      #     description of  allowed formats. Defaults to `"Flags"`.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
+      #     description for the group. See {Toys::Tool#desc=} for a description
+      #     of allowed formats. Defaults to `"Flags"`.
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag group. See
-      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
-      #     formats. Defaults to the empty array.
-      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     {Toys::Tool#long_desc=} for a description of allowed formats.
+      #     Defaults to the empty array.
+      # @param name [String,Symbol,nil] The name of the group, or nil for no
       #     name.
-      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      # @param report_collisions [Boolean] If `true`, raise an exception if a
       #     the given name is already taken. If `false`, ignore. Default is
       #     `true`.
-      # @param [Boolean] prepend If `true`, prepend rather than append the
+      # @param prepend [Boolean] If `true`, prepend rather than append the
       #     group to the list. Default is `false`.
-      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
-      #     add flags to this group in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
+      #     for the directives that can be called in this block.
+      # @return [self]
       #
       def flag_group(type: :optional, desc: nil, long_desc: nil, name: nil,
                      report_collisions: true, prepend: false, &block)
@@ -374,30 +544,35 @@ module Toys
       # defined in the block belong to the group. All flags in this group are
       # required.
       #
-      # Example:
+      # ## Example
+      #
+      # The following example creates a group of required flags.
       #
-      #     all_required do
-      #       flag :username, "--username=VAL", desc: "Set the username (required)"
-      #       flag :password, "--password=VAL", desc: "Set the password (required)"
+      #     tool "login" do
+      #       all_required do
+      #         flag :username, "--username=VAL", desc: "Set username (required)"
+      #         flag :password, "--password=VAL", desc: "Set password (required)"
+      #       end
+      #       # ...
       #     end
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the group. See {Toys::Definition::Tool#desc=} for a
-      #     description of  allowed formats. Defaults to `"Flags"`.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
+      #     description for the group. See {Toys::Tool#desc=} for a description
+      #     of allowed formats. Defaults to `"Flags"`.
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag group. See
-      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
-      #     formats. Defaults to the empty array.
-      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     {Toys::Tool#long_desc=} for a description of allowed formats.
+      #     Defaults to the empty array.
+      # @param name [String,Symbol,nil] The name of the group, or nil for no
       #     name.
-      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      # @param report_collisions [Boolean] If `true`, raise an exception if a
       #     the given name is already taken. If `false`, ignore. Default is
       #     `true`.
-      # @param [Boolean] prepend If `true`, prepend rather than append the
+      # @param prepend [Boolean] If `true`, prepend rather than append the
       #     group to the list. Default is `false`.
-      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
-      #     add flags to this group in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
+      #     for the directives that can be called in this block.
+      # @return [self]
       #
       def all_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
                        prepend: false, &block)
@@ -410,87 +585,132 @@ module Toys
       # defined in the block belong to the group. At most one flag in this
       # group must be provided on the command line.
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the group. See {Toys::Definition::Tool#desc=} for a
-      #     description of  allowed formats. Defaults to `"Flags"`.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # ## Example
+      #
+      # The following example creates a group of flags in which either one or
+      # none may be set, but not more than one.
+      #
+      #     tool "provision-server" do
+      #       at_most_one do
+      #         flag :restore_from_backup, "--restore-from-backup=VAL"
+      #         flag :restore_from_image, "--restore-from-image=VAL"
+      #         flag :clone_existing, "--clone-existing=VAL"
+      #       end
+      #       # ...
+      #     end
+      #
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
+      #     description for the group. See {Toys::Tool#desc=} for a description
+      #     of allowed formats. Defaults to `"Flags"`.
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag group. See
-      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
-      #     formats. Defaults to the empty array.
-      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     {Toys::Tool#long_desc=} for a description of allowed formats.
+      #     Defaults to the empty array.
+      # @param name [String,Symbol,nil] The name of the group, or nil for no
       #     name.
-      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      # @param report_collisions [Boolean] If `true`, raise an exception if a
       #     the given name is already taken. If `false`, ignore. Default is
       #     `true`.
-      # @param [Boolean] prepend If `true`, prepend rather than append the
+      # @param prepend [Boolean] If `true`, prepend rather than append the
       #     group to the list. Default is `false`.
-      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
-      #     add flags to this group in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
+      #     for the directives that can be called in this block.
+      # @return [self]
       #
-      def at_most_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
-                               prepend: false, &block)
+      def at_most_one(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                      prepend: false, &block)
         flag_group(type: :at_most_one, desc: desc, long_desc: long_desc,
                    name: name, report_collisions: report_collisions, prepend: prepend, &block)
       end
+      alias at_most_one_required at_most_one
 
       ##
       # Create a flag group of type `:at_least_one`. If a block is given, flags
       # defined in the block belong to the group. At least one flag in this
       # group must be provided on the command line.
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the group. See {Toys::Definition::Tool#desc=} for a
-      #     description of  allowed formats. Defaults to `"Flags"`.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # ## Example
+      #
+      # The following example creates a group of flags in which one or more
+      # may be set.
+      #
+      #     tool "run-tests" do
+      #       at_least_one do
+      #         flag :unit, desc: "Run unit tests"
+      #         flag :integration, desc: "Run integration tests"
+      #         flag :performance, desc: "Run performance tests"
+      #       end
+      #       # ...
+      #     end
+      #
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
+      #     description for the group. See {Toys::Tool#desc=} for a description
+      #     of allowed formats. Defaults to `"Flags"`.
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag group. See
-      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
-      #     formats. Defaults to the empty array.
-      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     {Toys::Tool#long_desc=} for a description of allowed formats.
+      #     Defaults to the empty array.
+      # @param name [String,Symbol,nil] The name of the group, or nil for no
       #     name.
-      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      # @param report_collisions [Boolean] If `true`, raise an exception if a
       #     the given name is already taken. If `false`, ignore. Default is
       #     `true`.
-      # @param [Boolean] prepend If `true`, prepend rather than append the
+      # @param prepend [Boolean] If `true`, prepend rather than append the
       #     group to the list. Default is `false`.
-      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
-      #     add flags to this group in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
+      #     for the directives that can be called in this block.
+      # @return [self]
       #
-      def at_least_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
-                                prepend: false, &block)
+      def at_least_one(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                       prepend: false, &block)
         flag_group(type: :at_least_one, desc: desc, long_desc: long_desc,
                    name: name, report_collisions: report_collisions, prepend: prepend, &block)
       end
+      alias at_least_one_required at_least_one
 
       ##
       # Create a flag group of type `:exactly_one`. If a block is given, flags
       # defined in the block belong to the group. Exactly one flag in this
       # group must be provided on the command line.
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-      #     description for the group. See {Toys::Definition::Tool#desc=} for a
-      #     description of  allowed formats. Defaults to `"Flags"`.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # ## Example
+      #
+      # The following example creates a group of flags in which exactly one
+      # must be set.
+      #
+      #     tool "deploy" do
+      #       exactly_one do
+      #         flag :server, "--server=IP_ADDR", desc: "Deploy to server"
+      #         flag :vm, "--vm=ID", desc: "Deploy to a VM"
+      #         flag :container, "--container=ID", desc: "Deploy to a container"
+      #       end
+      #       # ...
+      #     end
+      #
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
+      #     description for the group. See {Toys::Tool#desc=} for a description
+      #     of allowed formats. Defaults to `"Flags"`.
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag group. See
-      #     {Toys::Definition::Tool#long_desc=} for a description of allowed
-      #     formats. Defaults to the empty array.
-      # @param [String,Symbol,nil] name The name of the group, or nil for no
+      #     {Toys::Tool#long_desc=} for a description of allowed formats.
+      #     Defaults to the empty array.
+      # @param name [String,Symbol,nil] The name of the group, or nil for no
       #     name.
-      # @param [Boolean] report_collisions If `true`, raise an exception if a
+      # @param report_collisions [Boolean] If `true`, raise an exception if a
       #     the given name is already taken. If `false`, ignore. Default is
       #     `true`.
-      # @param [Boolean] prepend If `true`, prepend rather than append the
+      # @param prepend [Boolean] If `true`, prepend rather than append the
       #     group to the list. Default is `false`.
-      # @yieldparam flag_group_dsl [Toys::DSL::FlagGroup] An object that lets
-      #     add flags to this group in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Adds flags to the group. See {Toys::DSL::FlagGroup}
+      #     for the directives that can be called in this block.
+      # @return [self]
       #
-      def exactly_one_required(desc: nil, long_desc: nil, name: nil, report_collisions: true,
-                               prepend: false, &block)
+      def exactly_one(desc: nil, long_desc: nil, name: nil, report_collisions: true,
+                      prepend: false, &block)
         flag_group(type: :exactly_one, desc: desc, long_desc: long_desc,
                    name: name, report_collisions: report_collisions, prepend: prepend, &block)
       end
+      alias exactly_one_required exactly_one
 
       ##
       # Add a flag to the current tool. Each flag must specify a key which
@@ -500,56 +720,176 @@ module Toys
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
       # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Tool#get}.
+      # tool can retrieve the value by calling {Toys::Context#get}.
       #
       # Attributes of the flag may be passed in as arguments to this method, or
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::Flag} within the block.
       #
-      # @param [String,Symbol] key The key to use to retrieve the value from
+      # ## Flag syntax
+      #
+      # The flags themselves should be provided in OptionParser form. Following
+      # are examples of valid syntax.
+      #
+      #  *  `-a` : A short boolean switch. When this appears as an argument,
+      #     the value is set to `true`.
+      #  *  `--abc` : A long boolean switch. When this appears as an argument,
+      #     the value is set to `true`.
+      #  *  `-aVAL` or `-a VAL` : A short flag that takes a required value.
+      #     These two forms are treated identically. If this argument appears
+      #     with a value attached (e.g. `-afoo`), the attached string (e.g.
+      #     `"foo"`) is taken as the value. Otherwise, the following argument
+      #     is taken as the value (e.g. for `-a foo`, the value is set to
+      #     `"foo"`.) The following argument is treated as the value even if it
+      #     looks like a flag (e.g. `-a -a` causes the string `"-a"` to be
+      #     taken as the value.)
+      #  *  `-a[VAL]` : A short flag that takes an optional value. If this
+      #     argument appears with a value attached (e.g. `-afoo`), the attached
+      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the value
+      #     is set to `true`. The following argument is never interpreted as
+      #     the value. (Compare with `-a [VAL]`.)
+      #  *  `-a [VAL]` : A short flag that takes an optional value. If this
+      #     argument appears with a value attached (e.g. `-afoo`), the attached
+      #     string (e.g. `"foo"`) is taken as the value. Otherwise, if the
+      #     following argument does not look like a flag (i.e. it does not
+      #     begin with a hyphen), it is taken as the value. (e.g. `-a foo`
+      #     causes the string `"foo"` to be taken as the value.). If there is
+      #     no following argument, or the following argument looks like a flag,
+      #     the value is set to `true`. (Compare with `-a[VAL]`.)
+      #  *  `--abc=VAL` or `--abc VAL` : A long flag that takes a required
+      #     value. These two forms are treated identically. If this argument
+      #     appears with a value attached (e.g. `--abc=foo`), the attached
+      #     string (e.g. `"foo"`) is taken as the value. Otherwise, the
+      #     following argument is taken as the value (e.g. for `--abc foo`, the
+      #     value is set to `"foo"`.) The following argument is treated as the
+      #     value even if it looks like a flag (e.g. `--abc --abc` causes the
+      #     string `"--abc"` to be taken as the value.)
+      #  *  `--abc[=VAL]` : A long flag that takes an optional value. If this
+      #     argument appears with a value attached (e.g. `--abc=foo`), the
+      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise,
+      #     the value is set to `true`. The following argument is never
+      #     interpreted as the value. (Compare with `--abc [VAL]`.)
+      #  *  `--abc [VAL]` : A long flag that takes an optional value. If this
+      #     argument appears with a value attached (e.g. `--abc=foo`), the
+      #     attached string (e.g. `"foo"`) is taken as the value. Otherwise, if
+      #     the following argument does not look like a flag (i.e. it does not
+      #     begin with a hyphen), it is taken as the value. (e.g. `--abc foo`
+      #     causes the string `"foo"` to be taken as the value.). If there is
+      #     no following argument, or the following argument looks like a flag,
+      #     the value is set to `true`. (Compare with `--abc=[VAL]`.)
+      #  *  `--[no-]abc` : A long boolean switch that can be turned either on
+      #     or off. This effectively creates two flags, `--abc` which sets the
+      #     value to `true`, and `--no-abc` which sets the falue to `false`.
+      #
+      # ## Default flag syntax
+      #
+      # If no flag syntax strings are provided, a default syntax will be
+      # inferred based on the key and other options.
+      #
+      # Specifically, if the key has one character, then that character will be
+      # chosen as a short flag. If the key has multiple characters, a long flag
+      # will be generated.
+      #
+      # Furthermore, if a custom completion, a non-boolean acceptor, or a
+      # non-boolean default value is provided in the options, then the flag
+      # will be considered to take a value. Otherwise, it will be considered to
+      # be a boolean switch.
+      #
+      # For example, the following pairs of flags are identical:
+      #
+      #     flag :a
+      #     flag :a, "-a"
+      #
+      #     flag :abc_def
+      #     flag :abc_def, "--abc-def"
+      #
+      #     flag :number, accept: Integer
+      #     flag :number, "--number=VAL", accept: Integer
+      #
+      # ## More examples
+      #
+      # A flag that sets its value to the number of times it appears on the
+      # command line:
+      #
+      #     flag :verbose, "-v", "--verbose",
+      #          default: 0, handler: ->(_val, count) { count + 1 }
+      #
+      # An example using block form:
+      #
+      #     flag :shout do
+      #       flags "-s", "--shout"
+      #       default false
+      #       desc "Say it louder"
+      #       long_desc "This flag says it lowder.",
+      #                 "You might use this when people can't hear you.",
+      #                 "",
+      #                 "Example:",
+      #                 ["    toys say --shout hello"]
+      #     end
+      #
+      # @param key [String,Symbol] The key to use to retrieve the value from
       #     the execution context.
-      # @param [String...] flags The flags in OptionParser format.
-      # @param [Object] accept An acceptor that validates and/or converts the
+      # @param flags [String...] The flags in OptionParser format.
+      # @param accept [Object] An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
       #     Optional. If not specified, accepts any value as a string.
-      # @param [Object] default The default value. This is the value that will
+      # @param default [Object] The default value. This is the value that will
       #     be set in the context if this flag is not provided on the command
       #     line. Defaults to `nil`.
-      # @param [Proc,nil] handler An optional handler for setting/updating the
-      #     value. If given, it should take two arguments, the new given value
-      #     and the previous value, and it should return the new value that
-      #     should be set. The default handler simply replaces the previous
-      #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
-      # @param [Boolean] report_collisions Raise an exception if a flag is
+      # @param handler [Proc,nil,:set,:push] An optional handler for
+      #     setting/updating the value. A handler is a proc taking two
+      #     arguments, the given value and the previous value, returning the
+      #     new value that should be set. You may also specify a predefined
+      #     named handler. The `:set` handler (the default) replaces the
+      #     previous value (effectively `-> (val, _prev) { val }`). The
+      #     `:push` handler expects the previous value to be an array and
+      #     pushes the given value onto it; it should be combined with setting
+      #     `default: []` and is intended for "multi-valued" flags.
+      # @param complete_flags [Object] A specifier for shell tab completion
+      #     for flag names associated with this flag. By default, a
+      #     {Toys::Flag::DefaultCompletion} is used, which provides the flag's
+      #     names as completion candidates. To customize completion, set this
+      #     to the name of a previously defined completion, a hash of options
+      #     to pass to the constructor for {Toys::Flag::DefaultCompletion}, or
+      #     any other spec recognized by {Toys::Completion.create}.
+      # @param complete_values [Object] A specifier for shell tab completion
+      #     for flag values associated with this flag. This is the empty
+      #     completion by default. To customize completion, set this to the
+      #     name of a previously defined completion, or any spec recognized by
+      #     {Toys::Completion.create}.
+      # @param report_collisions [Boolean] Raise an exception if a flag is
       #     requested that is already in use or marked as unusable. Default is
       #     true.
-      # @param [Toys::Definition::FlagGroup,String,Symbol,nil] group Group for
-      #     this flag. You may provide a group name, a FlagGroup object, or
-      #     `nil` which denotes the default group.
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      # @param group [Toys::FlagGroup,String,Symbol,nil] Group for this flag.
+      #     You may provide a group name, a FlagGroup object, or `nil` which
+      #     denotes the default group.
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
       #     description for the flag. See {Toys::DSL::Tool#desc} for a
       #     description of the allowed formats. Defaults to the empty string.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag. See {Toys::DSL::Tool#long_desc} for
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
-      # @param [String] display_name A display name for this flag, used in help
+      # @param display_name [String] A display name for this flag, used in help
       #     text and error messages.
-      # @yieldparam flag_dsl [Toys::DSL::Flag] An object that lets you
-      #     configure this flag in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
+      #     directives that can be called in this block.
+      # @return [self]
       #
       def flag(key, *flags,
                accept: nil, default: nil, handler: nil,
+               complete_flags: nil, complete_values: nil,
                report_collisions: true, group: nil,
                desc: nil, long_desc: nil, display_name: nil,
                &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        flag_dsl = DSL::Flag.new(flags, accept, default, handler, report_collisions,
-                                 group, desc, long_desc, display_name)
+        flag_dsl = DSL::Flag.new(
+          flags.flatten, accept, default, handler, complete_flags, complete_values,
+          report_collisions, group, desc, long_desc, display_name
+        )
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
         DSL::Tool.maybe_add_getter(self, key)
@@ -564,39 +904,57 @@ module Toys
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
       # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Tool#get}.
+      # tool can retrieve the value by calling {Toys::Context#get}.
       #
       # Attributes of the arg may be passed in as arguments to this method, or
       # set in a block passed to this method. If you provide a block, you can
-      # use directives in {Toys::DSL::Arg} within the block.
+      # use directives in {Toys::DSL::PositionalArg} within the block.
+      #
+      # ## Example
+      #
+      # This tool "moves" something from a source to destination, and takes two
+      # required arguments:
       #
-      # @param [String,Symbol] key The key to use to retrieve the value from
+      #     tool "mv" do
+      #       required_arg :source
+      #       required_arg :dest
+      #       def run
+      #         puts "moving from #{source} to #{dest}..."
+      #       end
+      #     end
+      #
+      # @param key [String,Symbol] The key to use to retrieve the value from
       #     the execution context.
-      # @param [Object] accept An acceptor that validates and/or converts the
+      # @param accept [Object] An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
       #     Optional. If not specified, accepts any value as a string.
-      # @param [String] display_name A name to use for display (in help text and
+      # @param complete [Object] A specifier for shell tab completion for
+      #     values of this arg. This is the empty completion by default. To
+      #     customize completion, set this to the name of a previously defined
+      #     completion, or any spec recognized by {Toys::Completion.create}.
+      # @param display_name [String] A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
       #     description for the flag. See {Toys::DSL::Tool#desc} for a
       #     description of the allowed formats. Defaults to the empty string.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag. See {Toys::DSL::Tool#long_desc} for
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
-      # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
-      #     this argument in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Configures the positional argument. See
+      #     {Toys::DSL::PositionalArg} for the directives that can be called in
+      #     this block.
+      # @return [self]
       #
       def required_arg(key,
-                       accept: nil, display_name: nil,
+                       accept: nil, complete: nil, display_name: nil,
                        desc: nil, long_desc: nil,
                        &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::Arg.new(accept, nil, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, nil, complete, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_required_to(cur_tool, key)
         DSL::Tool.maybe_add_getter(self, key)
@@ -613,42 +971,61 @@ module Toys
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
       # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Tool#get}.
+      # tool can retrieve the value by calling {Toys::Context#get}.
       #
       # Attributes of the arg may be passed in as arguments to this method, or
       # set in a block passed to this method. If you provide a block, you can
-      # use directives in {Toys::DSL::Arg} within the block.
+      # use directives in {Toys::DSL::PositionalArg} within the block.
+      #
+      # ## Example
+      #
+      # This tool creates a "link" to a given target. The link location is
+      # optional; if it is not given, it is inferred from the target.
+      #
+      #     tool "ln" do
+      #       required_arg :target
+      #       optional_arg :location
+      #       def run
+      #         loc = location || File.basename(target)
+      #         puts "linking to #{target} from #{loc}..."
+      #       end
+      #     end
       #
-      # @param [String,Symbol] key The key to use to retrieve the value from
+      # @param key [String,Symbol] The key to use to retrieve the value from
       #     the execution context.
-      # @param [Object] default The default value. This is the value that will
+      # @param default [Object] The default value. This is the value that will
       #     be set in the context if this argument is not provided on the command
       #     line. Defaults to `nil`.
-      # @param [Object] accept An acceptor that validates and/or converts the
+      # @param accept [Object] An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
       #     Optional. If not specified, accepts any value as a string.
-      # @param [String] display_name A name to use for display (in help text and
+      # @param complete [Object] A specifier for shell tab completion for
+      #     values of this arg. This is the empty completion by default. To
+      #     customize completion, set this to the name of a previously defined
+      #     completion, or any spec recognized by {Toys::Completion.create}.
+      # @param display_name [String] A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
       #     description for the flag. See {Toys::DSL::Tool#desc} for a
       #     description of the allowed formats. Defaults to the empty string.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag. See {Toys::DSL::Tool#long_desc} for
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
-      # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
-      #     this argument in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Configures the positional argument. See
+      #     {Toys::DSL::PositionalArg} for the directives that can be called in
+      #     this block.
+      # @return [self]
       #
       def optional_arg(key,
-                       default: nil, accept: nil, display_name: nil,
+                       default: nil, accept: nil, complete: nil, display_name: nil,
                        desc: nil, long_desc: nil,
                        &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_optional_to(cur_tool, key)
         DSL::Tool.maybe_add_getter(self, key)
@@ -664,42 +1041,62 @@ module Toys
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
       # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Tool#get}.
+      # tool can retrieve the value by calling {Toys::Context#get}.
       #
       # Attributes of the arg may be passed in as arguments to this method, or
       # set in a block passed to this method. If you provide a block, you can
-      # use directives in {Toys::DSL::Arg} within the block.
+      # use directives in {Toys::DSL::PositionalArg} within the block.
+      #
+      # ## Example
+      #
+      # This tool displays a "list" of the given directories. If no directories
+      # ar given, lists the current directory.
+      #
+      #     tool "ln" do
+      #       remaining_args :directories
+      #       def run
+      #         dirs = directories.empty? ? [Dir.pwd] : directories
+      #         dirs.each do |dir|
+      #           puts "Listing directory #{dir}..."
+      #         end
+      #       end
+      #     end
       #
-      # @param [String,Symbol] key The key to use to retrieve the value from
+      # @param key [String,Symbol] The key to use to retrieve the value from
       #     the execution context.
-      # @param [Object] default The default value. This is the value that will
+      # @param default [Object] The default value. This is the value that will
       #     be set in the context if no unmatched arguments are provided on the
       #     command line. Defaults to the empty array `[]`.
-      # @param [Object] accept An acceptor that validates and/or converts the
+      # @param accept [Object] An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, or one of the default acceptors provided by OptionParser.
       #     Optional. If not specified, accepts any value as a string.
-      # @param [String] display_name A name to use for display (in help text and
+      # @param complete [Object] A specifier for shell tab completion for
+      #     values of this arg. This is the empty completion by default. To
+      #     customize completion, set this to the name of a previously defined
+      #     completion, or any spec recognized by {Toys::Completion.create}.
+      # @param display_name [String] A name to use for display (in help text and
       #     error reports). Defaults to the key in upper case.
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
+      # @param desc [String,Array<String>,Toys::WrappableString] Short
       #     description for the flag. See {Toys::DSL::Tool#desc} for a
       #     description of the allowed formats. Defaults to the empty string.
-      # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
+      # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
       #     Long description for the flag. See {Toys::DSL::Tool#long_desc} for
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
-      # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
-      #     this argument in a block.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] Configures the positional argument. See
+      #     {Toys::DSL::PositionalArg} for the directives that can be called in
+      #     this block.
+      # @return [self]
       #
       def remaining_args(key,
-                         default: [], accept: nil, display_name: nil,
+                         default: [], accept: nil, complete: nil, display_name: nil,
                          desc: nil, long_desc: nil,
                          &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._set_remaining_on(cur_tool, key)
         DSL::Tool.maybe_add_getter(self, key)
@@ -708,17 +1105,35 @@ module Toys
       alias remaining remaining_args
 
       ##
-      # Set an option value statically.
+      # Set a option values statically and create a helper method.
       #
-      # If the given key is a symbol representing a valid method name, then a
+      # If any given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
       # if the key is a string or does not represent a valid method name, the
-      # tool can retrieve the value by calling {Toys::Tool#get}.
+      # tool can retrieve the value by calling {Toys::Context#get}.
       #
-      # @param [String,Symbol] key The key to use to retrieve the value from
-      #     the execution context.
-      # @param [Object] value The value to set.
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # ## Example
+      #
+      #     tool "hello" do
+      #       static :greeting, "Hi there"
+      #       def run
+      #         puts "#{greeting}, world!"
+      #       end
+      #     end
+      #
+      # @return [self]
+      #
+      # @overload static(key, value)
+      #   Set a single value by key.
+      #   @param key [String,Symbol] The key to use to retrieve the value from
+      #       the execution context.
+      #   @param value [Object] The value to set.
+      #   @return [self]
+      #
+      # @overload static(hash)
+      #   Set multiple keys and values
+      #   @param hash [Hash] The keys and values to set
+      #   @return [self]
       #
       def static(key, value = nil)
         cur_tool = DSL::Tool.current_tool(self, true)
@@ -735,15 +1150,84 @@ module Toys
         self
       end
 
+      ##
+      # Set a option values statically without creating helper methods.
+      #
+      # ## Example
+      #
+      #     tool "hello" do
+      #       set :greeting, "Hi there"
+      #       def run
+      #         puts "#{get(:greeting)}, world!"
+      #       end
+      #     end
+      #
+      # @return [self]
+      #
+      # @overload set(key, value)
+      #   Set a single value by key.
+      #   @param key [String,Symbol] The key to use to retrieve the value from
+      #       the execution context.
+      #   @param value [Object] The value to set.
+      #   @return [self]
+      #
+      # @overload set(hash)
+      #   Set multiple keys and values
+      #   @param hash [Hash] The keys and values to set
+      #   @return [self]
+      #
+      def set(key, value = nil)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        return self if cur_tool.nil?
+        if key.is_a?(::Hash)
+          cur_tool.default_data.merge!(key)
+        else
+          cur_tool.default_data[key] = value
+        end
+        self
+      end
+
+      ##
+      # Enforce that all flags must be provided before any positional args.
+      # That is, as soon as the first positional arg appears in the command
+      # line arguments, flag parsing is disabled as if `--` had appeared.
+      #
+      # Issuing this directive by itself turns on enforcement. You may turn it
+      # off by passsing `false` as the parameter.
+      #
+      # @param state [Boolean]
+      # @return [self]
+      #
+      def enforce_flags_before_args(state = true)
+        DSL::Tool.current_tool(self, true)&.enforce_flags_before_args(state)
+        self
+      end
+
+      ##
+      # Require that flags must match exactly. That is, flags must appear in
+      # their entirety on the command line. (If false, substrings of flags are
+      # accepted as long as they are unambiguous.)
+      #
+      # Issuing this directive by itself turns on exact match. You may turn it
+      # off by passsing `false` as the parameter.
+      #
+      # @param state [Boolean]
+      # @return [self]
+      #
+      def require_exact_flag_match(state = true)
+        DSL::Tool.current_tool(self, true)&.require_exact_flag_match(state)
+        self
+      end
+
       ##
       # Disable argument parsing for this tool. Arguments will not be parsed
       # and the options will not be populated. Instead, tools can retrieve the
-      # full unparsed argument list by calling {Toys::Tool#args}.
+      # full unparsed argument list by calling {Toys::Context#args}.
       #
       # This directive is mutually exclusive with any of the directives that
       # declare arguments or flags.
       #
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @return [self]
       #
       def disable_argument_parsing
         DSL::Tool.current_tool(self, true)&.disable_argument_parsing
@@ -755,26 +1239,152 @@ module Toys
       # subsequent flag definition. This can be used to prevent middleware from
       # defining a particular flag.
       #
-      # @param [String...] flags The flags to disable
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # ## Example
+      #
+      # This tool does not support the `-v` and `-q` short forms for the two
+      # verbosity flags (although it still supports the long forms `--verbose`
+      # and `--quiet`.)
+      #
+      #     tool "mytool" do
+      #       disable_flag "-v", "-q"
+      #       def run
+      #         # ...
+      #       end
+      #     end
+      #
+      # @param flags [String...] The flags to disable
+      # @return [self]
       #
       def disable_flag(*flags)
         DSL::Tool.current_tool(self, true)&.disable_flag(*flags)
         self
       end
 
+      ##
+      # Set the shell completion strategy for this tool's arguments.
+      # You can pass one of the following:
+      #
+      #  *  The string name of a completion defined in this tool or any of its
+      #     its ancestors.
+      #  *  A hash of options to pass to the constructor of
+      #     {Toys::Tool::DefaultCompletion}.
+      #  *  `nil` or `:default` to select the standard completion strategy
+      #     (which is {Toys::Tool::DefaultCompletion} with no extra options).
+      #  *  Any other specification recognized by {Toys::Completion.create}.
+      #
+      # ## Example
+      #
+      # The namespace "foo" supports completion only of subtool names. It does
+      # not complete the standard flags (like --help).
+      #
+      #     tool "foo" do
+      #       complete_tool_args complete_args: false, complete_flags: false,
+      #                          complete_flag_values: false
+      #       tool "bar" do
+      #         def run
+      #           puts "in foo bar"
+      #         end
+      #       end
+      #     end
+      #
+      # @param spec [Object]
+      # @param options [Hash]
+      # @param block [Proc]
+      # @return [self]
+      #
+      def complete_tool_args(spec = nil, **options, &block)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        return self if cur_tool.nil?
+        cur_tool.completion = cur_tool.scalar_completion(spec, options, &block)
+        self
+      end
+
       ##
       # Specify how to run this tool. Typically you do this by defining a
-      # method namd `run`. Alternatively, you can pass a block to this method.
+      # method namd `run`. Alternatively, however, you can pass a block to the
+      # `to_run` method.
+      #
       # You may want to do this if your method needs access to local variables
-      # in the lexical scope.
+      # in the lexical scope. However, it is often more convenient to use
+      # {#static} to set the value in the context.)
+      #
+      # ## Example
+      #
+      #     tool "foo" do
+      #       cur_time = Time.new
+      #       to_run do
+      #         puts "The time at tool definition was #{cur_time}"
+      #       end
+      #     end
       #
-      # @return [Toys::DSL::Tool] self, for chaining.
+      # @param block [Proc] The run method.
+      # @return [self]
       #
       def to_run(&block)
         define_method(:run, &block)
         self
       end
+      alias on_run to_run
+
+      ##
+      # Specify how to handle interrupts.
+      #
+      # You may pass a block to be called, or the name of a method to call. In
+      # either case, the block or method should take one argument, the
+      # Interrupt exception that was raised.
+      #
+      # ## Example
+      #
+      #     tool "foo" do
+      #       def run
+      #         sleep 10
+      #       end
+      #       on_interrupt do |e|
+      #         puts "I was interrupted."
+      #       end
+      #     end
+      #
+      # @param handler [Proc,Symbol,nil] The interrupt callback proc or method
+      #     name. Pass nil to disable interrupt handling.
+      # @param block [Proc] The interrupt callback as a block.
+      # @return [self]
+      #
+      def on_interrupt(handler = nil, &block)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool.interrupt_handler = handler || block unless cur_tool.nil?
+        self
+      end
+
+      ##
+      # Specify how to handle usage errors.
+      #
+      # You may pass a block to be called, or the name of a method to call. In
+      # either case, the block or method should take one argument, the array of
+      # usage errors reported.
+      #
+      # ## Example
+      #
+      # This tool runs even if a usage error is encountered. You can find info
+      # on the errors from {Toys::Context::Key::USAGE_ERRORS},
+      # {Toys::Context::Key::UNMATCHED_ARGS}, and similar keys.
+      #
+      #     tool "foo" do
+      #       def run
+      #         puts "Errors: #{usage_errors.join("\n")}"
+      #       end
+      #       on_usage_error :run
+      #     end
+      #
+      # @param handler [Proc,Symbol,nil] The interrupt callback proc or method
+      #     name. Pass nil to disable interrupt handling.
+      # @param block [Proc] The interrupt callback as a block.
+      # @return [self]
+      #
+      def on_usage_error(handler = nil, &block)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool.usage_error_handler = handler || block unless cur_tool.nil?
+        self
+      end
 
       ##
       # Specify that the given module should be mixed into this tool, and its
@@ -784,26 +1394,43 @@ module Toys
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
-      # @param [Module,Symbol,String] mod Module or module name.
-      # @param [Object...] args Arguments to pass to the initializer
+      # ## Example
+      #
+      # Include the well-known mixin `:terminal` and perform some terminal
+      # magic.
+      #
+      #     tool "spin" do
+      #       include :terminal
+      #       def run
+      #         # The spinner method is defined by the :terminal mixin.
+      #         spinner(leading_text: "Waiting...", final_text: "\n") do
+      #           sleep 5
+      #         end
+      #       end
+      #     end
+      #
+      # @param mod [Module,Symbol,String] Module or module name.
+      # @param args [Object...] Arguments to pass to the initializer
+      # @return [self]
       #
       def include(mod, *args)
         cur_tool = DSL::Tool.current_tool(self, true)
-        return if cur_tool.nil?
+        return self if cur_tool.nil?
         mod = DSL::Tool.resolve_mixin(mod, cur_tool, @__loader)
         if included_modules.include?(mod)
           raise ToolDefinitionError, "Mixin already included: #{mod.name}"
         end
         cur_tool.mark_includes_modules
-        if mod.respond_to?(:initialization_callback)
-          callback = mod.initialization_callback
+        super(mod)
+        if mod.respond_to?(:initializer)
+          callback = mod.initializer
           cur_tool.add_initializer(callback, *args) if callback
         end
-        if mod.respond_to?(:inclusion_callback)
-          callback = mod.inclusion_callback
+        if mod.respond_to?(:inclusion)
+          callback = mod.inclusion
           class_exec(*args, &callback) if callback
         end
-        super(mod)
+        self
       end
 
       ##
@@ -813,9 +1440,10 @@ module Toys
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
-      # @param [Module,Symbol,String] mod Module or module name.
-      # @return [Boolean,nil] A boolean value, or `nil` if the current tool
-      #     is not active.
+      # @param mod [Module,Symbol,String] Module or module name.
+      #
+      # @return [Boolean] Whether the mixin is included
+      # @return [nil] if the current tool is not active.
       #
       def include?(mod)
         cur_tool = DSL::Tool.current_tool(self, false)
@@ -826,19 +1454,39 @@ module Toys
       ##
       # Return the current source info object.
       #
-      # @return [Toys::Definition::SourceInfo] Source info.
+      # @return [Toys::SourceInfo] Source info.
       #
       def source_info
         @__source.last
       end
 
       ##
-      # Find the given data path (file or directory)
+      # Find the given data path (file or directory).
+      #
+      # Data directories are a convenient place to put images, archives, keys,
+      # or other such static data needed by your tools. Data files are located
+      # in a directory called `.data` inside a Toys directory. This directive
+      # locates a data file during tool definition.
+      #
+      # ## Example
+      #
+      # This tool reads its description from a text file in the `.data`
+      # directory.
+      #
+      #     tool "mytool" do
+      #       path = find_data("mytool-desc.txt", type: :file)
+      #       desc IO.read(path) if path
+      #       def run
+      #         # ...
+      #       end
+      #     end
+      #
+      # @param path [String] The path to find
+      # @param type [nil,:file,:directory] Type of file system object to find.
+      #     Default is `nil`, indicating any type.
       #
-      # @param [String] path The path to find
-      # @param [nil,:file,:directory] type Type of file system object to find,
-      #     or nil to return any type.
-      # @return [String,nil] Absolute path of the result, or nil if not found.
+      # @return [String] Absolute path of the data.
+      # @return [nil] if the given data path is not found.
       #
       def find_data(path, type: nil)
         source_info.find_data(path, type: type)
@@ -849,9 +1497,9 @@ module Toys
       # to the directory containing the toys config directory structure being
       # read, but it may be changed by setting a different context directory
       # for the tool.
-      # May return nil if there is no context.
       #
-      # @return [String,nil] Context directory
+      # @return [String] Context directory path
+      # @return [nil] if there is no context.
       #
       def context_directory
         DSL::Tool.current_tool(self, false)&.context_directory || source_info.context_directory
@@ -860,9 +1508,10 @@ module Toys
       ##
       # Set a custom context directory for this tool.
       #
-      # @param [String] dir Context directory
+      # @param dir [String] Context directory
+      # @return [self]
       #
-      def set_context_directory(dir)
+      def set_context_directory(dir) # rubocop:disable Naming/AccessorMethodName
         cur_tool = DSL::Tool.current_tool(self, false)
         return if cur_tool.nil?
         cur_tool.custom_context_directory = dir
@@ -871,7 +1520,7 @@ module Toys
 
       ## @private
       def self.new_class(words, priority, loader)
-        tool_class = ::Class.new(::Toys::Tool)
+        tool_class = ::Class.new(::Toys::Context)
         tool_class.extend(DSL::Tool)
         tool_class.instance_variable_set(:@__words, words)
         tool_class.instance_variable_set(:@__priority, priority)
@@ -892,11 +1541,11 @@ module Toys
           priority = tool_class.instance_variable_get(:@__priority)
           cur_tool =
             if activate
-              loader.activate_tool_definition(words, priority)
+              loader.activate_tool(words, priority)
             else
-              loader.get_tool_definition(words, priority)
+              loader.get_tool(words, priority)
             end
-          if cur_tool.is_a?(Definition::Alias)
+          if cur_tool.is_a?(Alias)
             raise ToolDefinitionError,
                   "Cannot configure #{words.join(' ').inspect} because it is an alias"
           end
@@ -920,10 +1569,12 @@ module Toys
 
       ## @private
       def self.maybe_add_getter(tool_class, key)
-        if key.is_a?(::Symbol) && key.to_s =~ /^[_a-zA-Z]\w*[!\?]?$/
-          tool_class.class_eval do
-            define_method(key) do
-              self[key]
+        if key.is_a?(::Symbol) && key.to_s =~ /^[_a-zA-Z]\w*[!\?]?$/ && key != :run
+          unless tool_class.public_method_defined?(key)
+            tool_class.class_eval do
+              define_method(key) do
+                self[key]
+              end
             end
           end
         end
@@ -933,7 +1584,7 @@ module Toys
       def self.resolve_mixin(mod, cur_tool, loader)
         name = mod.to_s
         if mod.is_a?(::String)
-          mod = cur_tool.resolve_mixin(mod)
+          mod = cur_tool.lookup_mixin(mod)
         elsif mod.is_a?(::Symbol)
           mod = loader.resolve_standard_mixin(name)
         end