toys-core 0.11.2 → 0.12.0

data/lib/toys/dsl/flag.rb

@@ -9,7 +9,7 @@ module Toys
     # These directives are available inside a block passed to
     # {Toys::DSL::Tool#flag}.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "mytool" do
     #       flag :value do
@@ -212,7 +212,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:
@@ -243,7 +243,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.",

data/lib/toys/dsl/flag_group.rb

@@ -10,7 +10,7 @@ module Toys
     # {Toys::DSL::Tool#at_most_one}, {Toys::DSL::Tool#at_least_one}, or
     # {Toys::DSL::Tool#exactly_one}.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "login" do
     #       all_required do
@@ -43,7 +43,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.
@@ -98,7 +98,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.
@@ -123,7 +123,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:
@@ -200,7 +200,7 @@ module Toys
                                  report_collisions, @flag_group, desc, long_desc, display_name)
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(@tool, key)
-        DSL::Tool.maybe_add_getter(@tool_dsl, key)
+        DSL::Internal.maybe_add_getter(@tool_dsl, key)
         self
       end
 
@@ -221,7 +221,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:
@@ -252,7 +252,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.",

data/lib/toys/dsl/internal.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Toys
+  module DSL
+    ##
+    # Internal utility calls used by the DSL.
+    #
+    # @private
+    #
+    module Internal
+      class << self
+        ##
+        # Called by the Loader and InputFile to prepare a tool class for running
+        # the DSL.
+        #
+        # @private
+        #
+        def prepare(tool_class, words, priority, remaining_words, source, loader)
+          unless tool_class.is_a?(DSL::Tool)
+            class << tool_class
+              alias_method :super_include, :include
+            end
+            tool_class.extend(DSL::Tool)
+          end
+          unless tool_class.instance_variable_defined?(:@__words)
+            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(:@__source, [])
+          end
+          tool_class.instance_variable_set(:@__remaining_words, remaining_words)
+          tool_class.instance_variable_get(:@__source).push(source)
+          old_source = ::Thread.current[:__toys_current_source]
+          begin
+            ::Thread.current[:__toys_current_source] = source
+            yield
+          ensure
+            tool_class.instance_variable_get(:@__source).pop
+            ::Thread.current[:__toys_current_source] = old_source
+          end
+        end
+
+        ##
+        # Called by the DSL implementation to get, and optionally activate, the
+        # current tool.
+        #
+        # @private
+        #
+        def 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
+
+        ##
+        # Called by the DSL implementation to add a getter to the tool class.
+        #
+        # @private
+        #
+        def 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
+
+        ##
+        # Called by the DSL implementation to find a named mixin.
+        #
+        # @private
+        #
+        def resolve_mixin(mixin, cur_tool, loader)
+          mod =
+            case mixin
+            when ::String
+              cur_tool.lookup_mixin(mixin)
+            when ::Symbol
+              loader.resolve_standard_mixin(mixin.to_s)
+            when ::Module
+              mixin
+            end
+          raise ToolDefinitionError, "Mixin not found: #{mixin.inspect}" unless mod
+          mod
+        end
+
+        ##
+        # Called by the DSL implementation to load a long description from a
+        # file.
+        #
+        # @private
+        #
+        def 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
+        end
+
+        ##
+        # Called by the Tool base class to set config values for a subclass.
+        #
+        # @private
+        #
+        def configure_class(tool_class, given_name = nil)
+          return if tool_class.name.nil? || tool_class.instance_variable_defined?(:@__loader)
+
+          mod_names = tool_class.name.split("::")
+          class_name = mod_names.pop
+          parent = parent_from_mod_name_segments(mod_names)
+          loader = parent.instance_variable_get(:@__loader)
+          name = given_name ? loader.split_path(given_name) : class_name_to_tool_name(class_name)
+
+          priority = parent.instance_variable_get(:@__priority)
+          words = parent.instance_variable_get(:@__words) + name
+          subtool = loader.get_tool(words, priority, tool_class)
+
+          remaining_words = parent.instance_variable_get(:@__remaining_words)
+          next_remaining = name.reduce(remaining_words) do |running_words, word|
+            Loader.next_remaining_words(running_words, word)
+          end
+
+          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(:@__source, [current_source_from_context])
+          tool_class.instance_variable_set(:@__remaining_words, next_remaining)
+          tool_class.instance_variable_set(:@__cur_tool, subtool)
+        end
+
+        ##
+        # Called by the Tool base class to add the DSL to a subclass.
+        #
+        # @private
+        #
+        def setup_class_dsl(tool_class)
+          return if tool_class.name.nil? || tool_class.is_a?(DSL::Tool)
+          class << tool_class
+            alias_method :super_include, :include
+          end
+          tool_class.extend(DSL::Tool)
+        end
+
+        private
+
+        def class_name_to_tool_name(class_name)
+          name = class_name.to_s.sub(/^_+/, "").sub(/_+$/, "").gsub(/_+/, "-")
+          while name.sub!(/([^-])([A-Z])/, "\\1-\\2") do end
+          [name.downcase!]
+        end
+
+        def parent_from_mod_name_segments(mod_names)
+          parent = mod_names.reduce(::Object) do |running_mod, seg|
+            running_mod.const_get(seg)
+          end
+          if !parent.is_a?(::Toys::Tool) && parent.instance_variable_defined?(:@__tool_class)
+            parent = parent.instance_variable_get(:@__tool_class)
+          end
+          unless parent.ancestors.include?(::Toys::Context)
+            raise ToolDefinitionError, "Toys::Tool can be subclassed only from the Toys DSL"
+          end
+          parent
+        end
+
+        def current_source_from_context
+          source = ::Thread.current[:__toys_current_source]
+          if source.nil?
+            raise ToolDefinitionError, "Toys::Tool can be subclassed only from a Toys config file"
+          end
+          unless source.source_type == :file
+            raise ToolDefinitionError, "Toys::Tool cannot be subclassed inside a tool block"
+          end
+          source
+        end
+      end
+    end
+  end
+end

data/lib/toys/dsl/positional_arg.rb

@@ -10,7 +10,7 @@ module Toys
     # {Toys::DSL::Tool#required_arg}, {Toys::DSL::Tool#optional_arg}, or
     # {Toys::DSL::Tool#remaining_args}.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "mytool" do
     #       optional_arg :value do
@@ -103,7 +103,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:
@@ -134,7 +134,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.",

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:
@@ -36,7 +36,8 @@ module Toys
     module Tool
       ## @private
       def method_added(_meth)
-        DSL::Tool.current_tool(self, true)&.check_definition_state(is_method: true)
+        super
+        DSL::Internal.current_tool(self, true)&.check_definition_state(is_method: true)
       end
 
       ##
@@ -83,7 +84,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 +106,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 +123,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 +150,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 +176,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 +205,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 +229,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 +253,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 +262,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 +281,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 +317,7 @@ module Toys
           when :ignore
             return self
           when :reset
-            subtool.reset_definition(@__loader)
+            subtool.reset_definition
           end
         end
         if delegate_to
@@ -328,7 +329,6 @@ module Toys
         end
         self
       end
-      alias name tool
 
       ##
       # Create an alias, representing an "alternate name" for a tool.
@@ -337,7 +337,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 +364,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 +386,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 +397,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 +481,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 +517,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 +533,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 +551,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 +569,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 +580,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 +590,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 +607,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 +626,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 +641,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 +654,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 +682,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 +697,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 +726,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 +741,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 +770,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 +785,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 +823,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 +878,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 +903,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 +982,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 +990,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 +1008,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 +1032,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 +1051,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 +1076,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 +1093,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 +1104,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 +1123,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 +1147,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 +1176,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 +1195,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 +1213,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 +1235,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 +1252,7 @@ module Toys
       ##
       # Set a option values statically without creating helper methods.
       #
-      # ## Example
+      # ### Example
       #
       #     tool "hello" do
       #       set :greeting, "Hi there"
@@ -1229,7 +1274,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 +1296,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 +1312,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 +1327,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 +1336,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 +1353,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 +1364,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 +1391,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 +1406,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 +1419,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 +1433,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 +1450,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 +1463,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 +1482,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 +1496,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 +1511,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 +1537,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 +1559,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 +1593,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 +1613,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 +1627,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 +1652,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 +1676,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.
@@ -1672,93 +1717,6 @@ module Toys
         end
         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
-      end
     end
   end
 end