toys-core 0.7.0 → 0.8.0

data/lib/toys/source_info.rb

@@ -0,0 +1,192 @@
+# 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.
+;
+
+module Toys
+  ##
+  # Information about source toys directories and files.
+  #
+  class SourceInfo
+    ##
+    # Create a SourceInfo.
+    # @private
+    #
+    def initialize(parent, context_directory, source, source_type, source_name, data_dir_name)
+      @parent = parent
+      @context_directory = context_directory
+      @source = source
+      @source_type = source_type
+      @source_path = source if source.is_a?(::String)
+      @source_proc = source if source.is_a?(::Proc)
+      @source_name = source_name
+      @data_dir =
+        if data_dir_name && @source_path
+          dir = ::File.join(::File.dirname(@source_path), data_dir_name)
+          dir if ::File.directory?(dir) && ::File.readable?(dir)
+        end
+    end
+
+    ##
+    # The parent of this SourceInfo.
+    #
+    # @return [Toys::SourceInfo] The parent.
+    # @return [nil] if this SourceInfo is the root.
+    #
+    attr_reader :parent
+
+    ##
+    # The context directory path (normally the directory containing the
+    # toplevel toys file or directory).
+    #
+    # @return [String] The context directory path.
+    # @return [nil] if there is no context directory (perhaps because the tool
+    #     is being defined from a block)
+    #
+    attr_reader :context_directory
+
+    ##
+    # The source, which may be a path or a proc.
+    #
+    # @return [String] Path to the source file or directory.
+    # @return [Proc] The block serving as the source.
+    #
+    attr_reader :source
+
+    ##
+    # Return the type of source.
+    #
+    # @return [:file,:directory,:proc]
+    #
+    attr_reader :source_type
+
+    ##
+    # The path of the current source file or directory.
+    #
+    # @return [String] The source path
+    # @return [nil] if this source is not a file system path.
+    #
+    attr_reader :source_path
+
+    ##
+    # The source proc.
+    #
+    # @return [Proc] The source proc
+    # @return [nil] if this source is not a proc.
+    #
+    attr_reader :source_proc
+
+    ##
+    # The user-visible name of this source.
+    #
+    # @return [String]
+    #
+    attr_reader :source_name
+    alias to_s source_name
+
+    ##
+    # Locate the given data file or directory and return an absolute path.
+    #
+    # @param path [String] The relative path to find
+    # @param type [nil,:file,:directory] Type of file system object to find,
+    #     or nil (the default) to return any type.
+    # @return [String] Absolute path of the resulting data.
+    # @return [nil] if the data was not found.
+    #
+    def find_data(path, type: nil)
+      if @data_dir
+        full_path = ::File.join(@data_dir, path)
+        case type
+        when :file
+          return full_path if ::File.file?(full_path)
+        when :directory
+          return full_path if ::File.directory?(full_path)
+        else
+          return full_path if ::File.readable?(full_path)
+        end
+      end
+      parent&.find_data(path, type: type)
+    end
+
+    ##
+    # Create a child SourceInfo relative to the parent path.
+    # @private
+    #
+    def relative_child(filename, data_dir_name)
+      raise "Cannot create relative child of a proc" unless source_path
+      child_path = ::File.join(source_path, filename)
+      child_path, type = SourceInfo.check_path(child_path, true)
+      return nil unless child_path
+      SourceInfo.new(self, context_directory, child_path, type, child_path, data_dir_name)
+    end
+
+    ##
+    # Create a child SourceInfo with an absolute path.
+    # @private
+    #
+    def absolute_child(child_path)
+      child_path, type = SourceInfo.check_path(child_path, false)
+      SourceInfo.new(self, context_directory, child_path, type, child_path, nil)
+    end
+
+    ##
+    # Create a root source info for a file path.
+    # @private
+    #
+    def self.create_path_root(source_path)
+      source_path, type = check_path(source_path, false)
+      context_directory = ::File.dirname(source_path)
+      new(nil, context_directory, source_path, type, source_path, nil)
+    end
+
+    ##
+    # Create a root source info for a proc.
+    # @private
+    #
+    def self.create_proc_root(source_proc, source_name)
+      new(nil, nil, source_proc, :proc, source_name, nil)
+    end
+
+    ##
+    # Check a path and determine the canonical path and type.
+    # @private
+    #
+    def self.check_path(path, lenient)
+      path = ::File.expand_path(path)
+      unless ::File.readable?(path)
+        raise LoaderError, "Cannot read: #{path}" unless lenient
+        return [nil, nil]
+      end
+      if ::File.file?(path)
+        unless ::File.extname(path) == ".rb"
+          raise LoaderError, "File is not a ruby file: #{path}" unless lenient
+          return [nil, nil]
+        end
+        [path, :file]
+      elsif ::File.directory?(path)
+        [path, :directory]
+      else
+        raise LoaderError, "Unknown type: #{path}" unless lenient
+        [nil, nil]
+      end
+    end
+  end
+end

data/lib/toys/standard_middleware/add_verbosity_flags.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
@@ -36,7 +28,7 @@ module Toys
     #
     # This middleware adds `-v`, `--verbose`, `-q`, and `--quiet` flags, if
     # not already defined by the tool. These flags affect the setting of
-    # {Toys::Tool::Keys::VERBOSITY}, and, thus, the logger level.
+    # {Toys::Context::Key::VERBOSITY}, and, thus, the logger level.
     #
     class AddVerbosityFlags
       include Middleware
@@ -56,7 +48,7 @@ module Toys
       ##
       # Create a AddVerbosityFlags middleware.
       #
-      # @param [Boolean,Array<String>,Proc] verbose_flags Specify flags
+      # @param verbose_flags [Boolean,Array<String>,Proc] Specify flags
       #     to increase verbosity. The value may be any of the following:
       #
       #     *  An array of flags that increase verbosity.
@@ -64,7 +56,7 @@ module Toys
       #     *  The `false` value to disable verbose flags.
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] quiet_flags Specify flags
+      # @param quiet_flags [Boolean,Array<String>,Proc] Specify flags
       #     to decrease verbosity. The value may be any of the following:
       #
       #     *  An array of flags that decrease verbosity.
@@ -79,26 +71,29 @@ module Toys
 
       ##
       # Configure the tool flags.
+      # @private
       #
-      def config(tool_definition, _loader)
-        unless tool_definition.argument_parsing_disabled?
-          StandardMiddleware.append_common_flag_group(tool_definition)
-          add_verbose_flags(tool_definition)
-          add_quiet_flags(tool_definition)
+      def config(tool, _loader)
+        unless tool.argument_parsing_disabled?
+          StandardMiddleware.append_common_flag_group(tool)
+          add_verbose_flags(tool)
+          add_quiet_flags(tool)
         end
         yield
       end
 
       private
 
-      def add_verbose_flags(tool_definition)
-        verbose_flags = resolve_flags_spec(@verbose_flags, tool_definition,
-                                           DEFAULT_VERBOSE_FLAGS)
+      INCREMENT_HANDLER = ->(_val, cur) { cur.to_i + 1 }
+      DECREMENT_HANDLER = ->(_val, cur) { cur.to_i - 1 }
+
+      def add_verbose_flags(tool)
+        verbose_flags = resolve_flags_spec(@verbose_flags, tool, DEFAULT_VERBOSE_FLAGS)
         unless verbose_flags.empty?
-          tool_definition.add_flag(
-            Tool::Keys::VERBOSITY, verbose_flags,
+          tool.add_flag(
+            Context::Key::VERBOSITY, verbose_flags,
             report_collisions: false,
-            handler: ->(_val, cur) { cur + 1 },
+            handler: INCREMENT_HANDLER,
             desc: "Increase verbosity",
             long_desc: "Increase verbosity, causing additional logging levels to display.",
             group: StandardMiddleware::COMMON_FLAG_GROUP
@@ -106,13 +101,13 @@ module Toys
         end
       end
 
-      def add_quiet_flags(tool_definition)
-        quiet_flags = resolve_flags_spec(@quiet_flags, tool_definition, DEFAULT_QUIET_FLAGS)
+      def add_quiet_flags(tool)
+        quiet_flags = resolve_flags_spec(@quiet_flags, tool, DEFAULT_QUIET_FLAGS)
         unless quiet_flags.empty?
-          tool_definition.add_flag(
-            Tool::Keys::VERBOSITY, quiet_flags,
+          tool.add_flag(
+            Context::Key::VERBOSITY, quiet_flags,
             report_collisions: false,
-            handler: ->(_val, cur) { cur - 1 },
+            handler: DECREMENT_HANDLER,
             desc: "Decrease verbosity",
             long_desc: "Decrease verbosity, causing fewer logging levels to display.",
             group: StandardMiddleware::COMMON_FLAG_GROUP

data/lib/toys/standard_middleware/handle_usage_errors.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
@@ -40,34 +32,41 @@ module Toys
     class HandleUsageErrors
       include Middleware
 
+      ##
+      # Exit code for usage error. (2 by convention)
+      # @return [Integer]
+      #
+      USAGE_ERROR_EXIT_CODE = 2
+
       ##
       # Create a HandleUsageErrors middleware.
       #
-      # @param [Intgeer] exit_code The exit code to return if a usage error
-      #     occurs. Default is -1.
-      # @param [IO] stream Output stream to write to. Default is stderr.
-      # @param [Boolean,nil] styled_output Cause the tool to display help text
+      # @param exit_code [Integer] The exit code to return if a usage error
+      #     occurs. Default is {USAGE_ERROR_EXIT_CODE}.
+      # @param stream [IO] Output stream to write to. Default is stderr.
+      # @param styled_output [Boolean,nil] Cause the tool to display help text
       #     with ansi styles. If `nil`, display styles if the output stream is
       #     a tty. Default is `nil`.
       #
-      def initialize(exit_code: -1, stream: $stderr, styled_output: nil)
-        @exit_code = exit_code
+      def initialize(exit_code: nil, stream: $stderr, styled_output: nil)
+        require "toys/utils/terminal"
+        @exit_code = exit_code || USAGE_ERROR_EXIT_CODE
         @terminal = Utils::Terminal.new(output: stream, styled: styled_output)
       end
 
       ##
       # Intercept and handle usage errors during execution.
+      # @private
       #
-      def run(tool)
-        if tool[Tool::Keys::USAGE_ERROR]
-          help_text = Utils::HelpText.from_tool(tool)
-          @terminal.puts(tool[Tool::Keys::USAGE_ERROR], :bright_red, :bold)
-          @terminal.puts("")
-          @terminal.puts(help_text.usage_string(wrap_width: @terminal.width))
-          Tool.exit(@exit_code)
-        else
-          yield
-        end
+      def run(context)
+        yield
+      rescue ArgParsingError => e
+        require "toys/utils/help_text"
+        help_text = Utils::HelpText.from_context(context)
+        @terminal.puts(e.usage_errors.join("\n"), :bright_red, :bold)
+        @terminal.puts("")
+        @terminal.puts(help_text.usage_string(wrap_width: @terminal.width))
+        Context.exit(@exit_code)
       end
     end
   end

data/lib/toys/standard_middleware/set_default_descriptions.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,41 +61,27 @@ module Toys
           " https://www.rubydoc.info/gems/toys-core for more info.",
         "To replace this message, set the description and long description" \
           " of the root tool, or configure the SetDefaultDescriptions" \
-          " middleware."
+          " middleware.",
       ].freeze
 
-      ##
-      # A mapping of names for acceptable types
-      # @return [Hash]
-      #
-      ACCEPTABLE_NAMES = {
-        nil => "string",
-        ::String => "nonempty string",
-        ::TrueClass => "boolean",
-        ::FalseClass => "boolean",
-        ::OptionParser::DecimalInteger => "decimal integer",
-        ::OptionParser::OctalInteger => "octal integer",
-        ::OptionParser::DecimalNumeric => "decimal numeric"
-      }.freeze
-
       ##
       # Create a SetDefaultDescriptions middleware given default descriptions.
       #
-      # @param [String,nil] default_tool_desc The default short description for
+      # @param default_tool_desc [String,nil] The default short description for
       #     runnable tools, or `nil` not to set one. Defaults to
       #     {DEFAULT_TOOL_DESC}.
-      # @param [String,nil] default_tool_long_desc The default long description
+      # @param default_tool_long_desc [String,nil] The default long description
       #     for runnable tools, or `nil` not to set one. Defaults to `nil`.
-      # @param [String,nil] default_namespace_desc The default short
+      # @param default_namespace_desc [String,nil] The default short
       #     description for non-runnable tools, or `nil` not to set one.
       #     Defaults to {DEFAULT_TOOL_DESC}.
-      # @param [String,nil] default_namespace_long_desc The default long
+      # @param default_namespace_long_desc [String,nil] The default long
       #     description for non-runnable tools, or `nil` not to set one.
       #     Defaults to `nil`.
-      # @param [String,nil] default_root_desc The default short description for
+      # @param default_root_desc [String,nil] The default short description for
       #     the root tool, or `nil` not to set one. Defaults to
       #     {DEFAULT_ROOT_DESC}.
-      # @param [String,nil] default_root_long_desc The default long description
+      # @param default_root_long_desc [String,nil] The default long description
       #     for the root tool, or `nil` not to set one. Defaults to
       #     {DEFAULT_ROOT_LONG_DESC}.
       #
@@ -123,15 +101,20 @@ module Toys
 
       ##
       # Add default description text to tools.
+      # @private
       #
       def config(tool, loader)
         data = {tool: tool, loader: loader}
-        tool.flag_definitions.each do |flag|
+        tool.flags.each do |flag|
           config_desc(flag, generate_flag_desc(flag, data), generate_flag_long_desc(flag, data))
         end
-        tool.arg_definitions.each do |arg|
+        tool.positional_args.each do |arg|
           config_desc(arg, generate_arg_desc(arg, data), generate_arg_long_desc(arg, data))
         end
+        tool.flag_groups.each do |flag_group|
+          config_desc(flag_group, generate_flag_group_desc(flag_group, data),
+                      generate_flag_group_long_desc(flag_group, data))
+        end
         config_desc(tool, generate_tool_desc(tool, data), generate_tool_long_desc(tool, data))
         yield
       end
@@ -143,13 +126,13 @@ module Toys
       # By default, it uses the parameters given to the middleware object.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool] tool The tool to document.
-      # @param [Hash] data Additional data that might be useful. Currently,
+      # @param tool [Toys::Tool] The tool to document.
+      # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Loader} is passed with key `:loader`. Future versions
       #     of Toys may provide additional information.
-      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
-      #     default description, or `nil` not to set a default. See
-      #     {Toys::Tool#desc=} for info on the format.
+      # @return [String,Array<String>,Toys::WrappableString] The default
+      #     description. See {Toys::Tool#desc=} for info on the format.
+      # @return [nil] if this middleware should not set the description.
       #
       def generate_tool_desc(tool, data)
         if tool.root?
@@ -166,13 +149,14 @@ module Toys
       # By default, it uses the parameters given to the middleware object.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool] tool The tool to document
-      # @param [Hash] data Additional data that might be useful. Currently,
-      #     the {Toys::Loader} is passed with key `:loader`. Future versions
-      #     of Toys may provide additional information.
-      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
-      #     The default long description, or `nil` not to set a default. See
-      #     {Toys::Tool#long_desc=} for info on the format.
+      # @param tool [Toys::Tool] The tool to document
+      # @param data [Hash] Additional data that might be useful. Currently,
+      #     the {Toys::Loader} is passed with key `:loader`. Future versions of
+      #     Toys may provide additional information.
+      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
+      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     format.
+      # @return [nil] if this middleware should not set the long description.
       #
       def generate_tool_long_desc(tool, data)
         if tool.root?
@@ -188,17 +172,17 @@ module Toys
       # This method implements the logic for generating a flag description.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool::FlagDefinition] flag The flag to document
-      # @param [Hash] data Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
-      #     Toys may provide additional information.
-      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
-      #     default description, or `nil` not to set a default. See
-      #     {Toys::Tool#desc=} for info on the format.
+      # @param flag [Toys::Flag] The flag to document
+      # @param data [Hash] Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     versions of Toys may provide additional information.
+      # @return [String,Array<String>,Toys::WrappableString] The default
+      #     description. See {Toys::Tool#desc=} for info on the format.
+      # @return [nil] if this middleware should not set the description.
       #
       def generate_flag_desc(flag, data) # rubocop:disable Lint/UnusedMethodArgument
         name = flag.key.to_s.tr("_", "-").gsub(/[^\w-]/, "").downcase.inspect
-        acceptable = flag.flag_type == :value ? acceptable_name(flag.accept) : "boolean flag"
+        acceptable = flag.flag_type == :value ? flag.acceptor.type_desc : "boolean flag"
         default_clause = flag.default ? " (default is #{flag.default.inspect})" : ""
         "Sets the #{name} option as type #{acceptable}#{default_clause}."
       end
@@ -207,13 +191,14 @@ module Toys
       # This method implements logic for generating a flag long description.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool::FlagDefinition] flag The flag to document
-      # @param [Hash] data Additional data that might be useful. Currently,
+      # @param flag [Toys::Flag] The flag to document
+      # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Tool} is passed with key `:tool`. Future versions of
-      #     Toys may provide additional information.
-      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
-      #     The default long description, or `nil` not to set a default. See
-      #     {Toys::Tool#long_desc=} for info on the format.
+      #     versions of Toys may provide additional information.
+      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
+      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     format.
+      # @return [nil] if this middleware should not set the long description.
       #
       def generate_flag_long_desc(flag, data) # rubocop:disable Lint/UnusedMethodArgument
         nil
@@ -223,16 +208,16 @@ module Toys
       # This method implements the logic for generating an arg description.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool::ArgDefinition] arg The arg to document
-      # @param [Hash] data Additional data that might be useful. Currently,
+      # @param arg [Toys::PositionalArg] The arg to document
+      # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Tool} is passed with key `:tool`. Future versions of
       #     Toys may provide additional information.
-      # @return [String,Array<String>,Toys::Utils::WrappableString,nil] The
-      #     default description, or `nil` not to set a default. See
-      #     {Toys::Tool#desc=} for info on the format.
+      # @return [String,Array<String>,Toys::WrappableString] The default
+      #     description. See {Toys::Tool#desc=} for info on the format.
+      # @return [nil] if this middleware should not set the description.
       #
       def generate_arg_desc(arg, data) # rubocop:disable Lint/UnusedMethodArgument
-        acceptable = acceptable_name(arg.accept)
+        acceptable = arg.acceptor.type_desc
         default_clause = arg.default ? " (default is #{arg.default.inspect})" : ""
         case arg.type
         when :required
@@ -248,26 +233,63 @@ module Toys
       # This method implements logic for generating an arg long description.
       # Override this method to provide different logic.
       #
-      # @param [Toys::Tool::ArgDefinition] arg The arg to document
-      # @param [Hash] data Additional data that might be useful. Currently,
+      # @param arg [Toys::PositionalArg] The arg to document
+      # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Tool} is passed with key `:tool`. Future versions of
       #     Toys may provide additional information.
-      # @return [Array<Toys::Utils::WrappableString,String,Array<String>>,nil]
-      #     The default long description, or `nil` not to set a default. See
-      #     {Toys::Tool#long_desc=} for info on the format.
+      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
+      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     format.
+      # @return [nil] if this middleware should not set the long description.
       #
       def generate_arg_long_desc(arg, data) # rubocop:disable Lint/UnusedMethodArgument
         nil
       end
 
       ##
-      # Return a reasonable name for an acceptor
+      # This method implements the logic for generating a flag group
+      # description. Override this method to provide different logic.
       #
-      # @param [Object] accept An acceptor to name
-      # @return [String]
+      # @param group [Toys::FlagGroup] The flag group to document
+      # @param data [Hash] Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     versions of Toys may provide additional information.
+      # @return [String,Array<String>,Toys::WrappableString] The default
+      #     description. See {Toys::Tool#desc=} for info on the format.
+      # @return [nil] if this middleware should not set the description.
+      #
+      def generate_flag_group_desc(group, data) # rubocop:disable Lint/UnusedMethodArgument
+        if group.is_a?(FlagGroup::Required)
+          "Required Flags"
+        else
+          "Flags"
+        end
+      end
+
+      ##
+      # This method implements the logic for generating a flag group long
+      # description. Override this method to provide different logic.
       #
-      def acceptable_name(accept)
-        ACCEPTABLE_NAMES[accept] || accept.to_s.downcase
+      # @param group [Toys::FlagGroup] The flag group to document
+      # @param data [Hash] Additional data that might be useful. Currently,
+      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     versions of Toys may provide additional information.
+      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
+      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     format.
+      # @return [nil] if this middleware should not set the long description.
+      #
+      def generate_flag_group_long_desc(group, data) # rubocop:disable Lint/UnusedMethodArgument
+        case group
+        when FlagGroup::Required
+          ["These flags are required."]
+        when FlagGroup::ExactlyOne
+          ["Exactly one of these flags must be set."]
+        when FlagGroup::AtMostOne
+          ["At most one of these flags must be set."]
+        when FlagGroup::AtLeastOne
+          ["At least one of these flags must be set."]
+        end
       end
 
       private