toys-core 0.7.0 → 0.8.0

data/lib/toys/context.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+# Copyright 2019 Daniel Azuma
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+;
+
+require "logger"
+
+module Toys
+  ##
+  # This is the base class for tool execution. It represents `self` when your
+  # tool's methods (such as `run`) are called, and it defines the methods that
+  # can be called by your tool (such as {#logger} and {#exit}.)
+  #
+  # This class also manages the "data" available to your tool when it runs.
+  # This data is a hash of key-value pairs. It consists of values set by flags
+  # and arguments defined by the tool, plus some "well-known" values such as
+  # the logger and verbosity level.
+  #
+  # You can obtain a value from the data using the {Toys::Context#get} method.
+  # Additionally, convenience methods are provided for many of the well-known
+  # keys. For instance, you can call {Toys::Context#verbosity} to obtain the
+  # value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
+  # positional arguments that store their data here will also typically
+  # generate convenience methods. For example, an argument with key `:abc` will
+  # add a method called `abc` that you can call to get the value.
+  #
+  # By convention, flags and arguments defined by your tool should use strings
+  # or symbols as keys. Keys that are not strings or symbols should either be
+  # well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
+  # for internal private information needed by middleware and mixins. The
+  # module {Toys::Context::Key} defines a number of well-known keys as
+  # constants.
+  #
+  class Context
+    ##
+    # Well-known context keys.
+    #
+    # This module is mixed into the runtime context. This means you can
+    # reference any of these constants directly from your run method.
+    #
+    # ## Example
+    #
+    #     tool "my-name" do
+    #       def run
+    #         # TOOL_NAME is available here.
+    #         puts "My name is #{get(TOOL_NAME)}"
+    #       end
+    #     end
+    #
+    module Key
+      ##
+      # Context key for the argument list passed to the current tool. Value is
+      # an array of strings.
+      # @return [Object]
+      #
+      ARGS = ::Object.new.freeze
+
+      ##
+      # Context key for the currently running {Toys::CLI}. You can use the
+      # value to run other tools from your tool by calling {Toys::CLI#run}.
+      # @return [Object]
+      #
+      CLI = ::Object.new.freeze
+
+      ##
+      # Context key for the context directory path. The value is a string
+      # @return [Object]
+      #
+      CONTEXT_DIRECTORY = ::Object.new.freeze
+
+      ##
+      # Context key for the active `Logger` object.
+      # @return [Object]
+      #
+      LOGGER = ::Object.new.freeze
+
+      ##
+      # Context key for the {Toys::Tool} object being executed.
+      # @return [Object]
+      #
+      TOOL = ::Object.new.freeze
+
+      ##
+      # Context key for the full name of the tool being executed. Value is an
+      # array of strings.
+      # @return [Object]
+      #
+      TOOL_NAME = ::Object.new.freeze
+
+      ##
+      # Context key for the {Toys::SourceInfo} describing the source of this
+      # tool.
+      # @return [Object]
+      #
+      TOOL_SOURCE = ::Object.new.freeze
+
+      ##
+      # Context key for all unmatched args in order. The value is an array of
+      # strings.
+      # @return [Object]
+      #
+      UNMATCHED_ARGS = ::Object.new.freeze
+
+      ##
+      # Context key for unmatched flags. The value is an array of strings.
+      # @return [Object]
+      #
+      UNMATCHED_FLAGS = ::Object.new.freeze
+
+      ##
+      # Context key for unmatched positional args. The value is an array of
+      # strings.
+      # @return [Object]
+      #
+      UNMATCHED_POSITIONAL = ::Object.new.freeze
+
+      ##
+      # Context key for the list of usage errors raised. The value is an array
+      # of {Toys::ArgParser::UsageError}.
+      # @return [Object]
+      #
+      USAGE_ERRORS = ::Object.new.freeze
+
+      ##
+      # Context key for the verbosity value. The value is an integer defaulting
+      # to 0, with higher values meaning more verbose and lower meaning more
+      # quiet.
+      # @return [Object]
+      #
+      VERBOSITY = ::Object.new.freeze
+    end
+
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    #
+    # @private
+    #
+    # @param data [Hash]
+    #
+    def initialize(data)
+      @__data = data
+    end
+
+    ##
+    # The raw arguments passed to the tool, as an array of strings.
+    # This does not include the tool name itself.
+    #
+    # This is a convenience getter for {Toys::Context::Key::ARGS}.
+    #
+    # @return [Array<String>]
+    #
+    def args
+      @__data[Key::ARGS]
+    end
+
+    ##
+    # The currently running CLI.
+    #
+    # This is a convenience getter for {Toys::Context::Key::CLI}.
+    #
+    # @return [Toys::CLI]
+    #
+    def cli
+      @__data[Key::CLI]
+    end
+
+    ##
+    # Return the context directory for this tool. Generally, this defaults
+    # 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.
+    #
+    # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
+    #
+    # @return [String] Context directory path
+    # @return [nil] if there is no context.
+    #
+    def context_directory
+      @__data[Key::CONTEXT_DIRECTORY]
+    end
+
+    ##
+    # The logger for this execution.
+    #
+    # This is a convenience getter for {Toys::Context::Key::LOGGER}.
+    #
+    # @return [Logger]
+    #
+    def logger
+      @__data[Key::LOGGER]
+    end
+
+    ##
+    # The full name of the tool being executed, as an array of strings.
+    #
+    # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
+    #
+    # @return [Array<String>]
+    #
+    def tool_name
+      @__data[Key::TOOL_NAME]
+    end
+
+    ##
+    # The source of the tool being executed.
+    #
+    # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
+    #
+    # @return [Toys::SourceInfo]
+    #
+    def tool_source
+      @__data[Key::TOOL_SOURCE]
+    end
+
+    ##
+    # The (possibly empty) array of errors detected during argument parsing.
+    #
+    # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
+    #
+    # @return [Array<Toys::ArgParser::UsageError>]
+    #
+    def usage_errors
+      @__data[Key::USAGE_ERRORS]
+    end
+
+    ##
+    # The current verbosity setting as an integer.
+    #
+    # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
+    #
+    # @return [Integer]
+    #
+    def verbosity
+      @__data[Key::VERBOSITY]
+    end
+
+    ##
+    # Fetch an option or other piece of data by key.
+    #
+    # @param key [Symbol]
+    # @return [Object]
+    #
+    def [](key)
+      @__data[key]
+    end
+    alias get []
+    alias __get []
+
+    ##
+    # Set an option or other piece of context data by key.
+    #
+    # @param key [Symbol]
+    # @param value [Object]
+    #
+    def []=(key, value)
+      @__data[key] = value
+    end
+
+    ##
+    # Set one or more options or other context data by key.
+    #
+    # @return [self]
+    #
+    # @overload set(key, value)
+    #   Set an option or other piece of context data by key.
+    #   @param key [Symbol]
+    #   @param value [Object]
+    #   @return [self]
+    #
+    # @overload set(hash)
+    #   Set multiple content data keys and values
+    #   @param hash [Hash] The keys and values to set
+    #   @return [self]
+    #
+    def set(key, value = nil)
+      if key.is_a?(::Hash)
+        @__data.merge!(key)
+      else
+        @__data[key] = value
+      end
+      self
+    end
+
+    ##
+    # The subset of the context that uses string or symbol keys. By convention,
+    # this includes keys that are set by tool flags and arguments, but does not
+    # include well-known context values such as verbosity or private context
+    # values used by middleware or mixins.
+    #
+    # @return [Hash]
+    #
+    def options
+      @__data.select do |k, _v|
+        k.is_a?(::Symbol) || k.is_a?(::String)
+      end
+    end
+
+    ##
+    # Find the given data file or directory in this tool's search path.
+    #
+    # @param path [String] The path to find
+    # @param type [nil,:file,:directory] Type of file system object to find,
+    #     or nil to return any type.
+    #
+    # @return [String] Absolute path of the result
+    # @return [nil] if the data was not found.
+    #
+    def find_data(path, type: nil)
+      @__data[Key::TOOL_SOURCE].find_data(path, type: type)
+    end
+
+    ##
+    # Exit immediately with the given status code
+    #
+    # @param code [Integer] The status code, which should be 0 for no error,
+    #     or nonzero for an error condition. Default is 0.
+    # @return [void]
+    #
+    def exit(code = 0)
+      throw :result, code
+    end
+
+    ##
+    # Exit immediately with the given status code
+    #
+    # @param code [Integer] The status code, which should be 0 for no error,
+    #     or nonzero for an error condition. Default is 0.
+    # @return [void]
+    #
+    def self.exit(code = 0)
+      throw :result, code
+    end
+  end
+end

data/lib/toys/core_version.rb

@@ -1,38 +1,30 @@
 # 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
   ##
-  # Current version of Toys core
+  # Current version of Toys core.
   # @return [String]
   #
-  CORE_VERSION = "0.7.0"
+  CORE_VERSION = "0.8.0"
 end

data/lib/toys/dsl/flag.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
@@ -38,12 +30,23 @@ module Toys
     # These directives are available inside a block passed to
     # {Toys::DSL::Tool#flag}.
     #
+    # ## Example
+    #
+    #     tool "mytool" do
+    #       flag :value do
+    #         # The directives in here are defined by this class
+    #         flags "--value=VAL"
+    #         accept Integer
+    #         desc "An integer value"
+    #       end
+    #       # ...
+    #     end
+    #
     class Flag
       ## @private
-      def initialize(flags, accept, default, handler, report_collisions,
-                     group, desc, long_desc, display_name)
+      def initialize(flags, acceptor, default, handler, flag_completion, value_completion,
+                     report_collisions, group, desc, long_desc, display_name)
         @flags = flags
-        @accept = accept
         @default = default
         @handler = handler
         @report_collisions = report_collisions
@@ -51,36 +54,98 @@ module Toys
         @desc = desc
         @long_desc = long_desc || []
         @display_name = display_name
+        accept(acceptor)
+        complete_flags(flag_completion)
+        complete_values(value_completion)
       end
 
       ##
       # Add flags in OptionParser format. This may be called multiple times,
       # and the results are cumulative.
       #
-      # @param [String...] flags
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # 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`.
+      #
+      # @param flags [String...]
+      # @return [self]
       #
       def flags(*flags)
-        @flags += flags
+        @flags += flags.flatten
         self
       end
 
       ##
-      # Set the OptionParser acceptor.
+      # Set the acceptor for this flag's values.
+      # You can pass either the string name of an acceptor defined in this tool
+      # or any of its ancestors, or any other specification recognized by
+      # {Toys::Acceptor.create}.
       #
-      # @param [Object] accept
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param spec [Object]
+      # @param options [Hash]
+      # @param block [Proc]
+      # @return [self]
       #
-      def accept(accept)
-        @accept = accept
+      def accept(spec = nil, **options, &block)
+        @acceptor_spec = spec
+        @acceptor_options = options
+        @acceptor_block = block
         self
       end
 
       ##
       # Set the default value.
       #
-      # @param [Object] default
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param default [Object]
+      # @return [self]
       #
       def default(default)
         @default = default
@@ -94,20 +159,63 @@ module Toys
       # should be set. You may pass the handler as a Proc (or an object
       # responding to the `call` method) or you may pass a block.
       #
-      # @param [Proc] handler
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param handler [Proc]
+      # @param block [Proc]
+      # @return [self]
       #
       def handler(handler = nil, &block)
         @handler = handler || block
         self
       end
 
+      ##
+      # Set the shell completion strategy for flag names.
+      # You can pass one of the following:
+      #
+      #  *  The string name of a completion defined in this tool or any of its
+      #     ancestors.
+      #  *  A hash of options to pass to the constructor of
+      #     {Toys::Flag::DefaultCompletion}.
+      #  *  `nil` or `:default` to select the standard completion strategy
+      #     (which is {Toys::Flag::DefaultCompletion} with no extra options).
+      #  *  Any other specification recognized by {Toys::Completion.create}.
+      #
+      # @param spec [Object]
+      # @param options [Hash]
+      # @param block [Proc]
+      # @return [self]
+      #
+      def complete_flags(spec = nil, **options, &block)
+        @flag_completion_spec = spec
+        @flag_completion_options = options
+        @flag_completion_block = block
+        self
+      end
+
+      ##
+      # Set the shell completion strategy for flag values.
+      # You can pass either the string name of a completion defined in this
+      # tool or any of its ancestors, or any other specification recognized by
+      # {Toys::Completion.create}.
+      #
+      # @param spec [Object]
+      # @param options [Hash]
+      # @param block [Proc]
+      # @return [self]
+      #
+      def complete_values(spec = nil, **options, &block)
+        @value_completion_spec = spec
+        @value_completion_options = options
+        @value_completion_block = block
+        self
+      end
+
       ##
       # Set whether to raise an exception if a flag is requested that is
       # already in use or marked as disabled.
       #
-      # @param [Boolean] setting
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param setting [Boolean]
+      # @return [self]
       #
       def report_collisions(setting)
         @report_collisions = setting
@@ -115,11 +223,36 @@ module Toys
       end
 
       ##
-      # Set the short description. See {Toys::DSL::Tool#desc} for the allowed
-      # formats.
+      # Set the short description for the current flag. The short description
+      # is displayed with the flag in online help.
+      #
+      # 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,
+      #     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.
+      #
+      # ## Examples
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString] desc
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # If you pass in a sentence as a simple string, it may be word wrapped
+      # when displayed:
+      #
+      #     desc "This sentence may be wrapped."
+      #
+      # To specify a sentence that should never be word-wrapped, pass it as the
+      # sole element of a string array:
+      #
+      #     desc ["This sentence will not be wrapped."]
+      #
+      # @param desc [String,Array<String>,Toys::WrappableString]
+      # @return [self]
       #
       def desc(desc)
         @desc = desc
@@ -127,12 +260,27 @@ module Toys
       end
 
       ##
-      # Adds to the long description. This may be called multiple times, and
-      # the results are cumulative. See {Toys::DSL::Tool#long_desc} for the
-      # allowed formats.
+      # Add to the long description for the current flag. The long description
+      # is displayed with the flag in online help. 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 {#desc} documentation, and may be
+      # word-wrapped when displayed. To insert a blank line, include an empty
+      # string as one of the descriptions.
+      #
+      # ## Example
+      #
+      #     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 indent is preserved."]
+      #     long_desc "This line is appended to the description."
       #
-      # @param [String,Array<String>,Toys::Utils::WrappableString...] long_desc
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param long_desc [String,Array<String>,Toys::WrappableString...]
+      # @return [self]
       #
       def long_desc(*long_desc)
         @long_desc += long_desc
@@ -143,8 +291,8 @@ module Toys
       # Set the group. A group may be set by name or group object. Setting
       # `nil` selects the default group.
       #
-      # @param [String,Symbol,Toys::Definition::FlagGroup,nil] group
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param group [String,Symbol,Toys::FlagGroup,nil]
+      # @return [self]
       #
       def group(group)
         @group = group
@@ -152,10 +300,11 @@ module Toys
       end
 
       ##
-      # Set the display name. This may be used in help text and error messages.
+      # Set the display name for this flag. This may be used in help text and
+      # error messages.
       #
-      # @param [String] display_name
-      # @return [Toys::DSL::Flag] self, for chaining.
+      # @param display_name [String]
+      # @return [self]
       #
       def display_name(display_name)
         @display_name = display_name
@@ -164,8 +313,16 @@ module Toys
 
       ## @private
       def _add_to(tool, key)
+        acceptor = tool.scalar_acceptor(@acceptor_spec, @acceptor_options, &@acceptor_block)
+        flag_completion = tool.scalar_completion(
+          @flag_completion_spec, @flag_completion_options, &@flag_completion_block
+        )
+        value_completion = tool.scalar_completion(
+          @value_completion_spec, @value_completion_options, &@value_completion_block
+        )
         tool.add_flag(key, @flags,
-                      accept: @accept, default: @default, handler: @handler,
+                      accept: acceptor, default: @default, handler: @handler,
+                      complete_flags: flag_completion, complete_values: value_completion,
                       report_collisions: @report_collisions, group: @group,
                       desc: @desc, long_desc: @long_desc, display_name: @display_name)
       end