toys-core 0.11.5 → 0.13.0

data/lib/toys/dsl/tool.rb

@@ -10,7 +10,7 @@ module Toys
     # how to execute the tool, and requesting mixin modules and other services.
     # It also lets you define subtools, nested arbitrarily deep, using blocks.
     #
-    # ## Simple example
+    # ### Simple example
     #
     # Create a file called `.toys.rb` in the current directory, with the
     # following contents:
@@ -34,11 +34,6 @@ module Toys
     #     toys greet rubyists
     #
     module Tool
-      ## @private
-      def method_added(_meth)
-        DSL::Tool.current_tool(self, true)&.check_definition_state(is_method: true)
-      end
-
       ##
       # Create a named acceptor that can be referenced by name from any flag or
       # positional argument in this tool or its subtools.
@@ -83,7 +78,7 @@ module Toys
       #     an exception (descended from `StandardError`) to indicate that the
       #     string parameter is invalid.
       #
-      # ## Example
+      # ### 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
@@ -105,7 +100,7 @@ module Toys
       # @return [self]
       #
       def acceptor(name, spec = nil, type_desc: nil, &block)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         cur_tool&.add_acceptor(name, spec, type_desc: type_desc || name.to_s, &block)
         self
       end
@@ -122,7 +117,7 @@ module Toys
       # block. Alternatively, you can create a module separately and pass it
       # directly to this directive.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates a named mixin and uses it in a tool.
       #
@@ -149,7 +144,7 @@ module Toys
       # @return [self]
       #
       def mixin(name, mixin_module = nil, &block)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         cur_tool&.add_mixin(name, mixin_module, &block)
         self
       end
@@ -175,7 +170,7 @@ module Toys
       # directly. See {Toys::Template} for details on creating a template
       # class.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates and uses a simple template.
       #
@@ -204,7 +199,7 @@ module Toys
       # @return [self]
       #
       def template(name, template_class = nil, &block)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
         cur_tool.add_template(name, template_class, &block)
         self
@@ -228,7 +223,7 @@ module Toys
       #  *  The symbol `:file_system` which indicates that paths in the file
       #     system should serve as completion candidates.
       #
-      # ## Example
+      # ### Example
       #
       # The following example defines a completion that uses only the immediate
       # files in the current directory as candidates. (This is different from
@@ -252,7 +247,7 @@ module Toys
       # @return [self]
       #
       def completion(name, spec = nil, **options, &block)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
         cur_tool.add_completion(name, spec, **options, &block)
         self
@@ -261,7 +256,7 @@ module Toys
       ##
       # Create a subtool. You must provide a block defining the subtool.
       #
-      # ## Example
+      # ### Example
       #
       # The following example defines a tool and two subtools within it.
       #
@@ -280,7 +275,7 @@ module Toys
       #
       # The following example defines a tool that runs one of its subtools.
       #
-      #     tool "test", runs: ["test", "unit"] do
+      #     tool "test", delegate_to: ["test", "unit"] do
       #       tool "unit" do
       #         def run
       #           puts "Running unit tests"
@@ -316,7 +311,7 @@ module Toys
           when :ignore
             return self
           when :reset
-            subtool.reset_definition(@__loader)
+            subtool.reset_definition
           end
         end
         if delegate_to
@@ -328,7 +323,6 @@ module Toys
         end
         self
       end
-      alias name tool
 
       ##
       # Create an alias, representing an "alternate name" for a tool.
@@ -337,7 +331,7 @@ module Toys
       # `delegate_to` option, except that `alias_tool` takes a _relative_ name
       # for the delegate.
       #
-      # ## Example
+      # ### 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.
@@ -364,7 +358,7 @@ module Toys
       # Causes the current tool to delegate to another tool. When run, it
       # simply invokes the target tool with the same arguments.
       #
-      # ## Example
+      # ### Example
       #
       # This example defines a tool that runs one of its subtools. Running the
       # `test` tool will have the same effect (and recognize the same args) as
@@ -386,7 +380,7 @@ module Toys
       # @return [self]
       #
       def delegate_to(target)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.delegate_to(@__loader.split_path(target))
         self
@@ -397,20 +391,64 @@ module Toys
       # at the current location.
       #
       # @param path [String] The file or directory to load.
+      # @param as [String] Load into the given tool/namespace. If omitted,
+      #     configuration will be loaded into the current namespace.
+      #
       # @return [self]
       #
-      def load(path)
+      def load(path, as: nil)
+        if as
+          tool(as) do
+            load(path)
+          end
+          return self
+        end
         @__loader.load_path(source_info, path, @__words, @__remaining_words, @__priority)
         self
       end
 
+      ##
+      # Load configuration from a public git repository, as if its contents
+      # were inserted at the current location.
+      #
+      # @param remote [String] The URL of the git repository. Defaults to the
+      #     current repository if already loading from git.
+      # @param path [String] The path within the repo to the file or directory
+      #     to load. Defaults to the root of the repo.
+      # @param commit [String] The commit branch, tag, or sha. Defaults to the
+      #     current commit if already loading from git, or to `HEAD`.
+      # @param as [String] Load into the given tool/namespace. If omitted,
+      #     configuration will be loaded into the current namespace.
+      # @param update [Boolean] Force-fetch from the remote (unless the commit
+      #     is a SHA). This will ensure that symbolic commits, such as branch
+      #     names, are up to date. Default is false.
+      #
+      # @return [self]
+      #
+      def load_git(remote: nil, path: nil, commit: nil, as: nil, update: false)
+        if as
+          tool(as) do
+            load_git(remote: remote, path: path, commit: commit)
+          end
+          return self
+        end
+        remote ||= source_info.git_remote
+        raise ToolDefinitionError, "Git remote not specified" unless remote
+        path ||= ""
+        commit ||= source_info.git_commit || "HEAD"
+        @__loader.load_git(source_info, remote, path, commit,
+                           @__words, @__remaining_words, @__priority,
+                           update: update)
+        self
+      end
+
       ##
       # Expand the given template in the current location.
       #
       # The template may be specified as a class or a well-known template name.
       # You may also provide arguments to pass to the template.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates and uses a simple template.
       #
@@ -437,12 +475,13 @@ module Toys
       # @return [self]
       #
       def expand(template_class, *args, **kwargs)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
         name = template_class.to_s
-        if template_class.is_a?(::String)
+        case template_class
+        when ::String
           template_class = cur_tool.lookup_template(template_class)
-        elsif template_class.is_a?(::Symbol)
+        when ::Symbol
           template_class = @__loader.resolve_standard_template(name)
         end
         if template_class.nil?
@@ -472,7 +511,7 @@ module Toys
       #     across the strings in the array. In this case, whitespace is not
       #     compacted.
       #
-      # ## Examples
+      # ### Examples
       #
       # If you pass in a sentence as a simple string, it may be word wrapped
       # when displayed:
@@ -488,7 +527,7 @@ module Toys
       # @return [self]
       #
       def desc(str)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.desc = str
         self
@@ -506,7 +545,7 @@ module Toys
       # word-wrapped when displayed. To insert a blank line, include an empty
       # string as one of the descriptions.
       #
-      # ## Example
+      # ### Example
       #
       #     long_desc "This initial paragraph might get word wrapped.",
       #               "This next paragraph is followed by a blank line.",
@@ -524,7 +563,7 @@ module Toys
       # @return [self]
       #
       def long_desc(*strs, file: nil, data: nil)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         if file
           unless source_info.source_path
@@ -535,7 +574,7 @@ module Toys
         elsif data
           file = source_info.find_data(data, type: :file)
         end
-        strs += DSL::Tool.load_long_desc_file(file) if file
+        strs += DSL::Internal.load_long_desc_file(file) if file
         cur_tool.append_long_desc(strs)
         self
       end
@@ -545,7 +584,7 @@ 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.
@@ -562,11 +601,11 @@ module Toys
       #     `:optional`, `:exactly_one`, `:at_most_one`, `:at_least_one`.
       #     Default is `:optional`.
       # @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"`.
+      #     description for the group. See {Toys::DSL::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::Tool#long_desc=} for a description of allowed formats.
+      #     {Toys::DSL::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.
@@ -581,7 +620,7 @@ module Toys
       #
       def flag_group(type: :optional, desc: nil, long_desc: nil, name: nil,
                      report_collisions: true, prepend: false, &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.add_flag_group(type: type, desc: desc, long_desc: long_desc, name: name,
                                 report_collisions: report_collisions, prepend: prepend)
@@ -596,7 +635,7 @@ 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.
       #
@@ -609,11 +648,11 @@ module Toys
       #     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"`.
+      #     description for the group. See {Toys::DSL::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::Tool#long_desc=} for a description of allowed formats.
+      #     {Toys::DSL::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.
@@ -637,7 +676,7 @@ module Toys
       # defined in the block belong to the group. At most one flag in this
       # group must be provided on the command line.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates a group of flags in which either one or
       # none may be set, but not more than one.
@@ -652,11 +691,11 @@ module Toys
       #     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"`.
+      #     description for the group. See {Toys::DSL::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::Tool#long_desc=} for a description of allowed formats.
+      #     {Toys::DSL::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.
@@ -681,7 +720,7 @@ module Toys
       # defined in the block belong to the group. At least one flag in this
       # group must be provided on the command line.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates a group of flags in which one or more
       # may be set.
@@ -696,11 +735,11 @@ module Toys
       #     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"`.
+      #     description for the group. See {Toys::DSL::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::Tool#long_desc=} for a description of allowed formats.
+      #     {Toys::DSL::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.
@@ -725,7 +764,7 @@ module Toys
       # defined in the block belong to the group. Exactly one flag in this
       # group must be provided on the command line.
       #
-      # ## Example
+      # ### Example
       #
       # The following example creates a group of flags in which exactly one
       # must be set.
@@ -740,11 +779,11 @@ module Toys
       #     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"`.
+      #     description for the group. See {Toys::DSL::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::Tool#long_desc=} for a description of allowed formats.
+      #     {Toys::DSL::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.
@@ -778,7 +817,7 @@ module Toys
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::Flag} within the block.
       #
-      # ## Flag syntax
+      # ### Flag syntax
       #
       # The flags themselves should be provided in OptionParser form. Following
       # are examples of valid syntax.
@@ -833,7 +872,7 @@ module Toys
       #     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
+      # ### Default flag syntax
       #
       # If no flag syntax strings are provided, a default syntax will be
       # inferred based on the key and other options.
@@ -858,7 +897,7 @@ module Toys
       #     flag :number, accept: Integer
       #     flag :number, "--number=VAL", accept: Integer
       #
-      # ## More examples
+      # ### More examples
       #
       # A flag that sets its value to the number of times it appears on the
       # command line:
@@ -937,7 +976,7 @@ module Toys
                report_collisions: true, group: nil,
                desc: nil, long_desc: nil, display_name: nil,
                &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         flag_dsl = DSL::Flag.new(
           flags.flatten, accept, default, handler, complete_flags, complete_values,
@@ -945,14 +984,14 @@ module Toys
         )
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
-        DSL::Tool.maybe_add_getter(self, key)
+        DSL::Internal.maybe_add_getter(self, key)
         self
       end
 
       ##
-      # Add a required positional argument to the current tool. You must specify
-      # a key which the script may use to obtain the argument value from the
-      # context.
+      # Add a required positional argument to the current tool. You must
+      # specify a key which the script may use to obtain the argument value
+      # from the context.
       #
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
@@ -963,7 +1002,7 @@ module Toys
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::PositionalArg} within the block.
       #
-      # ## Example
+      # ### Example
       #
       # This tool "moves" something from a source to destination, and takes two
       # required arguments:
@@ -987,8 +1026,8 @@ module Toys
       #     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 display_name [String] A name to use for display (in help text
+      #     and error reports). Defaults to the key in upper case.
       # @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.
@@ -1006,21 +1045,21 @@ module Toys
                        accept: nil, complete: nil, display_name: nil,
                        desc: nil, long_desc: nil,
                        &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         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)
+        DSL::Internal.maybe_add_getter(self, key)
         self
       end
       alias required required_arg
 
       ##
-      # Add an optional positional argument to the current tool. You must specify
-      # a key which the script may use to obtain the argument value from the
-      # context. If an optional argument is not given on the command line, the
-      # value is set to the given default.
+      # Add an optional positional argument to the current tool. You must
+      # specify a key which the script may use to obtain the argument value
+      # from the context. If an optional argument is not given on the command
+      # line, the value is set to the given default.
       #
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
@@ -1031,7 +1070,7 @@ module Toys
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::PositionalArg} within the block.
       #
-      # ## Example
+      # ### 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.
@@ -1048,8 +1087,8 @@ module Toys
       # @param key [String,Symbol] The key to use to retrieve the value from
       #     the execution context.
       # @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`.
+      #     be set in the context if this argument is not provided on the
+      #     command line. Defaults to `nil`.
       # @param accept [Object] An acceptor that validates and/or converts the
       #     value. You may provide either the name of an acceptor you have
       #     defined, one of the default acceptors provided by OptionParser, or
@@ -1059,8 +1098,8 @@ module Toys
       #     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 display_name [String] A name to use for display (in help text
+      #     and error reports). Defaults to the key in upper case.
       # @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.
@@ -1078,20 +1117,20 @@ module Toys
                        default: nil, accept: nil, complete: nil, display_name: nil,
                        desc: nil, long_desc: nil,
                        &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         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)
+        DSL::Internal.maybe_add_getter(self, key)
         self
       end
       alias optional optional_arg
 
       ##
-      # Specify what should be done with unmatched positional arguments. You must
-      # specify a key which the script may use to obtain the remaining args from
-      # the context.
+      # Specify what should be done with unmatched positional arguments. You
+      # must specify a key which the script may use to obtain the remaining
+      # args from the context.
       #
       # If the given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
@@ -1102,7 +1141,7 @@ module Toys
       # set in a block passed to this method. If you provide a block, you can
       # use directives in {Toys::DSL::PositionalArg} within the block.
       #
-      # ## Example
+      # ### Example
       #
       # This tool displays a "list" of the given directories. If no directories
       # ar given, lists the current directory.
@@ -1131,8 +1170,8 @@ module Toys
       #     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 display_name [String] A name to use for display (in help text
+      #     and error reports). Defaults to the key in upper case.
       # @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.
@@ -1150,12 +1189,12 @@ module Toys
                          default: [], accept: nil, complete: nil, display_name: nil,
                          desc: nil, long_desc: nil,
                          &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         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)
+        DSL::Internal.maybe_add_getter(self, key)
         self
       end
       alias remaining remaining_args
@@ -1168,7 +1207,7 @@ module Toys
       # if the key is a string or does not represent a valid method name, the
       # tool can retrieve the value by calling {Toys::Context#get}.
       #
-      # ## Example
+      # ### Example
       #
       #     tool "hello" do
       #       static :greeting, "Hi there"
@@ -1190,16 +1229,16 @@ module Toys
       #   @return [self]
       #
       def static(key, value = nil)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         if key.is_a?(::Hash)
           cur_tool.default_data.merge!(key)
           key.each_key do |k|
-            DSL::Tool.maybe_add_getter(self, k)
+            DSL::Internal.maybe_add_getter(self, k)
           end
         else
           cur_tool.default_data[key] = value
-          DSL::Tool.maybe_add_getter(self, key)
+          DSL::Internal.maybe_add_getter(self, key)
         end
         self
       end
@@ -1207,7 +1246,7 @@ module Toys
       ##
       # Set a option values statically without creating helper methods.
       #
-      # ## Example
+      # ### Example
       #
       #     tool "hello" do
       #       set :greeting, "Hi there"
@@ -1229,7 +1268,7 @@ module Toys
       #   @return [self]
       #
       def set(key, value = nil)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         if key.is_a?(::Hash)
           cur_tool.default_data.merge!(key)
@@ -1251,7 +1290,7 @@ module Toys
       # @return [self]
       #
       def enforce_flags_before_args(state = true)
-        DSL::Tool.current_tool(self, true)&.enforce_flags_before_args(state)
+        DSL::Internal.current_tool(self, true)&.enforce_flags_before_args(state)
         self
       end
 
@@ -1267,7 +1306,7 @@ module Toys
       # @return [self]
       #
       def require_exact_flag_match(state = true)
-        DSL::Tool.current_tool(self, true)&.require_exact_flag_match(state)
+        DSL::Internal.current_tool(self, true)&.require_exact_flag_match(state)
         self
       end
 
@@ -1282,7 +1321,7 @@ module Toys
       # @return [self]
       #
       def disable_argument_parsing
-        DSL::Tool.current_tool(self, true)&.disable_argument_parsing
+        DSL::Internal.current_tool(self, true)&.disable_argument_parsing
         self
       end
 
@@ -1291,7 +1330,7 @@ module Toys
       # subsequent flag definition. This can be used to prevent middleware from
       # defining a particular flag.
       #
-      # ## Example
+      # ### 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`
@@ -1308,7 +1347,7 @@ module Toys
       # @return [self]
       #
       def disable_flag(*flags)
-        DSL::Tool.current_tool(self, true)&.disable_flag(*flags)
+        DSL::Internal.current_tool(self, true)&.disable_flag(*flags)
         self
       end
 
@@ -1319,12 +1358,13 @@ module Toys
       #  *  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}.
+      #     {Toys::ToolDefinition::DefaultCompletion}.
       #  *  `nil` or `:default` to select the standard completion strategy
-      #     (which is {Toys::Tool::DefaultCompletion} with no extra options).
+      #     (which is {Toys::ToolDefinition::DefaultCompletion} with no extra
+      #     options).
       #  *  Any other specification recognized by {Toys::Completion.create}.
       #
-      # ## Example
+      # ### Example
       #
       # The namespace "foo" supports completion only of subtool names. It does
       # not complete the standard flags (like --help).
@@ -1345,7 +1385,7 @@ module Toys
       # @return [self]
       #
       def complete_tool_args(spec = nil, **options, &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.completion = Completion.scalarize_spec(spec, options, block)
         self
@@ -1360,7 +1400,7 @@ module Toys
       # in the lexical scope. However, it is often more convenient to use
       # {#static} to set the value in the context.)
       #
-      # ## Example
+      # ### Example
       #
       #     tool "foo" do
       #       cur_time = Time.new
@@ -1373,7 +1413,9 @@ module Toys
       # @return [self]
       #
       def to_run(&block)
-        define_method(:run, &block)
+        cur_tool = DSL::Internal.current_tool(self, true)
+        return self if cur_tool.nil?
+        cur_tool.run_handler = block
         self
       end
       alias on_run to_run
@@ -1385,7 +1427,7 @@ module Toys
       # either case, the block or method should take one argument, the
       # Interrupt exception that was raised.
       #
-      # ## Example
+      # ### Example
       #
       #     tool "foo" do
       #       def run
@@ -1402,7 +1444,7 @@ module Toys
       # @return [self]
       #
       def on_interrupt(handler = nil, &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.interrupt_handler = handler || block
         self
@@ -1415,7 +1457,7 @@ module Toys
       # either case, the block or method should take one argument, the array of
       # usage errors reported.
       #
-      # ## Example
+      # ### Example
       #
       # This tool runs even if a usage error is encountered. You can find info
       # on the errors from {Toys::Context::Key::USAGE_ERRORS},
@@ -1434,7 +1476,7 @@ module Toys
       # @return [self]
       #
       def on_usage_error(handler = nil, &block)
-        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         cur_tool.usage_error_handler = handler || block
         self
@@ -1448,7 +1490,7 @@ module Toys
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
-      # ## Example
+      # ### Example
       #
       # Include the well-known mixin `:terminal` and perform some terminal
       # magic.
@@ -1463,28 +1505,16 @@ module Toys
       #       end
       #     end
       #
-      # @param mod [Module,Symbol,String] Module or module name.
+      # @param mixin [Module,Symbol,String] Module or module name.
       # @param args [Object...] Arguments to pass to the initializer
       # @param kwargs [keywords] Keyword arguments to pass to the initializer
       # @return [self]
       #
-      def include(mod, *args, **kwargs)
-        cur_tool = DSL::Tool.current_tool(self, true)
+      def include(mixin, *args, **kwargs)
+        cur_tool = DSL::Internal.current_tool(self, true)
         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
-        super(mod)
-        if mod.respond_to?(:initializer)
-          callback = mod.initializer
-          cur_tool.add_initializer(callback, *args, **kwargs) if callback
-        end
-        if mod.respond_to?(:inclusion)
-          callback = mod.inclusion
-          class_exec(*args, **kwargs, &callback) if callback
-        end
+        mod = DSL::Internal.resolve_mixin(mixin, cur_tool, @__loader)
+        cur_tool.include_mixin(mod, *args, **kwargs)
         self
       end
 
@@ -1501,9 +1531,9 @@ module Toys
       # @return [nil] if the current tool is not active.
       #
       def include?(mod)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return if cur_tool.nil?
-        super(DSL::Tool.resolve_mixin(mod, cur_tool, @__loader))
+        super(DSL::Internal.resolve_mixin(mod, cur_tool, @__loader))
       end
 
       ##
@@ -1523,7 +1553,7 @@ module Toys
       # in a directory called `.data` inside a Toys directory. This directive
       # locates a data file during tool definition.
       #
-      # ## Example
+      # ### Example
       #
       # This tool reads its description from a text file in the `.data`
       # directory.
@@ -1557,17 +1587,17 @@ module Toys
       # @return [nil] if there is no context.
       #
       def context_directory
-        DSL::Tool.current_tool(self, false)&.context_directory || source_info.context_directory
+        DSL::Internal.current_tool(self, false)&.context_directory || source_info.context_directory
       end
 
       ##
-      # Return the current tool object. This object can be queried to determine
+      # Return the current tool config. This object can be queried to determine
       # such information as the name, but it should not be altered.
       #
-      # @return [Toys::Tool]
+      # @return [Toys::ToolDefinition]
       #
       def current_tool
-        DSL::Tool.current_tool(self, false)
+        DSL::Internal.current_tool(self, false)
       end
 
       ##
@@ -1577,7 +1607,7 @@ module Toys
       # @return [self]
       #
       def set_context_directory(dir) # rubocop:disable Naming/AccessorMethodName
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
         cur_tool.custom_context_directory = dir
         self
@@ -1591,7 +1621,7 @@ module Toys
       # The block is applied only to subtools defined *after* the block
       # appears. Subtools defined before the block appears are not affected.
       #
-      # ## Example
+      # ### Example
       #
       # It is common for tools to use the `:exec` mixin to invoke external
       # programs. This example automatically includes the exec mixin in all
@@ -1616,7 +1646,7 @@ module Toys
       #     end
       #
       def subtool_apply(&block)
-        cur_tool = DSL::Tool.current_tool(self, false)
+        cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
         cur_tool.subtool_middleware_stack.add(:apply_config,
                                               parent_source: source_info, &block)
@@ -1640,6 +1670,15 @@ module Toys
         end
       end
 
+      ##
+      # Get the settings for this tool.
+      #
+      # @return [Toys::ToolDefinition::Settings] Tool-specific settings.
+      #
+      def settings
+        DSL::Internal.current_tool(self, false)&.settings
+      end
+
       ##
       # Determines whether the current Toys version satisfies the given
       # requirements.
@@ -1673,91 +1712,14 @@ module Toys
         self
       end
 
-      ## @private
-      def self.new_class(words, priority, loader)
-        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)
-        tool_class.instance_variable_set(:@__loader, loader)
-        tool_class.instance_variable_set(:@__remaining_words, nil)
-        tool_class.instance_variable_set(:@__source, [])
-        tool_class
-      end
-
-      ## @private
-      def self.current_tool(tool_class, activate)
-        memoize_var = activate ? :@__active_tool : :@__cur_tool
-        if tool_class.instance_variable_defined?(memoize_var)
-          tool_class.instance_variable_get(memoize_var)
-        else
-          loader = tool_class.instance_variable_get(:@__loader)
-          words = tool_class.instance_variable_get(:@__words)
-          priority = tool_class.instance_variable_get(:@__priority)
-          cur_tool =
-            if activate
-              loader.activate_tool(words, priority)
-            else
-              loader.get_tool(words, priority)
-            end
-          if cur_tool && activate
-            source = tool_class.instance_variable_get(:@__source).last
-            cur_tool.lock_source(source)
-          end
-          tool_class.instance_variable_set(memoize_var, cur_tool)
-        end
-      end
-
-      ## @private
-      def self.prepare(tool_class, remaining_words, source)
-        tool_class.instance_variable_set(:@__remaining_words, remaining_words)
-        tool_class.instance_variable_get(:@__source).push(source)
-        yield
-      ensure
-        tool_class.instance_variable_get(:@__source).pop
-      end
-
-      ## @private
-      def self.maybe_add_getter(tool_class, 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
-      end
-
-      ## @private
-      def self.resolve_mixin(mod, cur_tool, loader)
-        name = mod.to_s
-        if mod.is_a?(::String)
-          mod = cur_tool.lookup_mixin(mod)
-        elsif mod.is_a?(::Symbol)
-          mod = loader.resolve_standard_mixin(name)
-        end
-        unless mod.is_a?(::Module)
-          raise ToolDefinitionError, "Module not found: #{name.inspect}"
-        end
-        mod
-      end
-
-      ## @private
-      def self.load_long_desc_file(path)
-        if ::File.extname(path) == ".txt"
-          begin
-            ::File.readlines(path).map do |line|
-              line = line.chomp
-              line =~ /^\s/ ? [line] : line
-            end
-          rescue ::SystemCallError => e
-            raise Toys::ToolDefinitionError, e.to_s
-          end
-        else
-          raise Toys::ToolDefinitionError, "Cannot load long desc from file type: #{path}"
-        end
+      ##
+      # Notify the tool definition when a method is defined in this tool class.
+      #
+      # @private
+      #
+      def method_added(_meth)
+        super
+        DSL::Internal.current_tool(self, true)&.check_definition_state(is_method: true)
       end
     end
   end