toys-core 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd26e85c431cf630dda5d6c7f49f43a13b917880169d47ca8d2df84df94a4b90
-  data.tar.gz: 87338976eafafd543f1b66c83c3c675739bddcffe1db8a2c595b3353c558d716
+  metadata.gz: 3e7a8292d7e4fb6fc31e4f308159f50050c455055a5333d89cebe448f8a2d472
+  data.tar.gz: 9e96d5f69ca1d072e64f0e2b012479ed1602b73ec94315a13dd6902f9ac5c189
 SHA512:
-  metadata.gz: 3d6e67e2800287709a3a09ddff87145999e4712db5a69b96ae479c58a586ab14596e42ad52ce8c9aca08146163ff6113318d70f426c08e8e18f6f2842b679f8e
-  data.tar.gz: e45bda72586ad53fa0b3ed51bb7b1a1b67f0da3a91a3c83344af61d616692f3bc435911cd5ab9fd8b2d086894ca03d976617213573c50c44b85454d7a0c4728b
+  metadata.gz: d8bd19a911524c3a776c947e8dfed37466c877a03f475f472c1082b7287f446e9881cbe666bee87663fcc9d966e76a6426ef9db072c07d47946d5a0a9cd2f7ce
+  data.tar.gz: 909d606e1bb8864264ee25e175b9422b5754071788bd2dcb590d617dd00aa7041f30a788380717a18d3242230939feff69e7a167d5b45096e22d29d6ae613f2f

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Release History
 
+### 0.9.2 / 2020-01-03
+
+* IMPROVED: Mixins can now take real keyword arguments, and will pass them on properly to `on_initialize` and `on_include` blocks.
+* CHANGED: `Toys::Utils::Exec` and the `:exec` mixin methods now take real keyword arguments rather than an `opts` hash. This means you should use keywords (or the double-splat operator) to avoid a deprecation warning on Ruby 2.7.
+* IMPROVED: `Toys::CLI#clone` can be passed keyword arguments to modify the configuration.
+* IMPROVED: `Toys::Loader` is now thread-safe. This means it is now possible for a single `Toys::CLI` to run multiple tools in different threads.
+* IMPROVED: There is now a class for middleware specs, making possible a nicer syntax for building a middleware stack.
+
 ### 0.9.1 / 2019-12-22
 
 * IMPROVED: `delegate_to` and `alias_tool` can take symbols as well as strings.
@@ -15,7 +23,7 @@ Functional changes:
 * IMPROVED: `alias_tool` is now just shorthand for delegating. This means, aliases can now point to namespaces and will resolve subtools of their targets, and they now support tab completion and online help.
 * IMPROVED: This release of Toys is now compatible with Ruby 2.7.0-preview3. It fixes some Ruby 2.7 specific bugs, and sanitizes keyword argument usage to eliminate Ruby 2.7 warnings.
 * IMPROVED: JRuby is now supported for most operations. However, JRuby is generally not recommended because of JVM boot latency, lack of Kernel#fork support, and other issues.
-* FIXED: The the `tool` directive no longer crashes if not passed a block.
+* FIXED: The `tool` directive no longer crashes if no block is provided.
 
 Internal interface changes:
 

data/README.md

@@ -64,8 +64,8 @@ happens when you run it:
 Just as with Toys itself, you get a help screen by default (since we haven't
 yet actually implemented any behavior.) As you can see, some of the same
 features from Toys are present already: online help, and `--verbose` and
-`--quiet` flags. These features can of course all be customized, but they're
-useful to have to start off.
+`--quiet` flags. These features can of course all be customized or disabled,
+but they're often useful to have to start off.
 
 ### Add some functionality
 
@@ -169,7 +169,7 @@ modifies error handling and delimiter parsing.
     #### Pass some additional options to the CLI constructor ...
     cli = Toys::CLI.new(
       extra_delimiters: ":",
-      error_handler: ->(e) {
+      error_handler: ->(_err) {
         puts "Dude, an error happened..."
         return 1
       }

data/docs/guide.md

@@ -5,25 +5,33 @@
 Toys-Core is the command line framework underlying Toys. It implements most of
 the core functionality of Toys, including the tool DSL, argument parsing,
 loading Toys files, online help, subprocess control, and so forth. It can be
-used to create custom command line executables using the same facilities. You
-can generally write 
-
-This user's guide covers everything you need to know to build your own command
-line executables in Ruby using the Toys-Core framework.
-
-This guide assumes you are already familiar with Toys itself, including how to
-define tools by writing Toys files, parsing arguments and flags, and how tools
-are executed. For background, please see the
+used to create custom command line executables using the same facilities.
+
+If this is your first time using Toys-Core, we recommend starting with the
+[README](https://dazuma.github.io/toys/gems/toys-core/latest), which includes a
+tutorial that introduces how to create simple command line executables using
+Toys-Core, customize the behavior, and package your executable in a gem. You
+should also be familiar with Toys itself, including how to define tools by
+writing Toys files, how to interpret arguments and flags, and how to use the
+Toys execution environment. For background, please see the
+[Toys README](https://dazuma.github.io/toys/gems/toys/latest) and
 [Toys User's Guide](https://dazuma.github.io/toys/gems/toys/latest/file.guide.html).
+Together, those resources will likely give you enough information to begin
+creating your own basic command line executables.
+
+This user's guide covers all the features of Toys-Core in much more depth. Read
+it when you're ready to unlock all the capabilities of Toys-Core to create
+sophisticated command line tools.
 
 **(This user's guide is still under construction.)**
 
 ## Conceptual overview
 
 Toys-Core is a command line *framework* in the traditional sense. It is
-intended to be used to write custom command line executables in Ruby. It
-provides libraries to handle basic functions such as argumet parsing and online
-help, and you provide the actual behavior.
+intended to be used to write custom command line executables in Ruby. The
+framework provides common facilities such as argumentparsing and online help,
+while your executable chooses and configures those facilities, and implements
+the actual behavior.
 
 The entry point for Toys-Core is the **cli object**. Typically your executable
 script instantiates a CLI, configures it with the desired tool implementations,
@@ -47,10 +55,97 @@ Finally, an executable may customize many aspects of its behavior, such as the
 
 ## Using the CLI object
 
-## Writing tools
+The CLI object is the main entry point for Toys-Core. Most command line
+executables based on Toys-Core use it as follows:
+
+ *  Instantiate a CLI object, passing configuration parameters to the
+    constructor.
+ *  Define the functionality of the CLI, either inline by passing it blocks, or
+    by providing paths to tool files.
+ *  Call the {Toys::CLI#run} method, passing it the command line arguments
+    (e.g. from `ARGV`).
+ *  Handle the result code, normally by passing it to `Kernel#exit`.
+
+Following is a simple "hello world" example using the CLI:
+
+    #!/usr/bin/env ruby
+
+    require "toys-core"
+
+    # Instantiate a CLI with the default options
+    cli = Toys::CLI.new
+
+    # Define the functionality
+    cli.add_config_block do
+      desc "My first executable!"
+      flag :whom, default: "world"
+      def run
+        puts "Hello, #{whom}!"
+      end
+    end
+
+    # Run the CLI, passing the command line arguments
+    result = cli.run(*ARGV)
+
+    # Handle the result code.
+    exit(result)
+
+### CLI execution
+
+This section provides some detail on how a CLI executes your code.
+
+(TODO)
+
+### Configuring the CLI
+
+Generally, you control CLI features by passing arguments to its constructor.
+These features include:
 
-## Customizing the tool environment
+ *  How to find toys files and related code and data. See the section on
+    [writing tool files](#Writing_tool_files).
+ *  Middleware, providing common behavior for all tools. See the section on
+    [customizing the middleware stack](#Customizing_default_behavior).
+ *  Common mixins and templates available to all tools. See the section on
+    [how to define mixins and templates](#Defining_mixins_and_templates).
+ *  How logs and errors are reported. See the section on
+    [customizing tool output](#Customizing_tool_output).
+ *  How the executable interacts with the shell, including setting up tab
+    completion. See the
+    [corresponding section](#Shell_and_command_line_integration).
+
+Each of the actual parameters is covered in detail in the documentation for
+{Toys::CLI#initialize}. The configuration of a CLI cannot be changed once the
+CLI is constructed. If you need to a CLI with a modified configuration, use
+{Toys::CLI#child}.
+
+## Defining functionality
+
+### Writing tools in blocks
+
+### Writing tool files
+
+### Tool priority
+
+### Defining mixins and templates
+
+## Customizing tool output
+
+### Logging and verbosity
+
+### Handling errors
 
 ## Customizing default behavior
 
+### Introducing middleware
+
+### Built-in middlewares
+
+### Writing your own middleware
+
+## Shell and command line integration
+
+### Interpreting tool names
+
+### Tab completion
+
 ## Packaging your executable

data/lib/toys/cli.rb

@@ -117,8 +117,8 @@ module Toys
     #     {Toys::CLI::DefaultCompletion}, which delegates completion to the
     #     relevant tool.
     #
-    # @param middleware_stack [Array] An array of middleware that will be used
-    #     by default for all tools loaded by this CLI.
+    # @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
+    #     middleware that will be used by default for all tools.
     #     Optional. If not provided, uses a default set of middleware defined
     #     in {Toys::CLI.default_middleware_stack}. To include no middleware,
     #     pass the empty array explicitly.
@@ -215,32 +215,37 @@ module Toys
     end
 
     ##
-    # Make a clone with the same settings but no paths in the loader.
-    # This is sometimes useful for running sub-tools that have to be loaded
-    # from a different configuration.
+    # Make a clone with the same settings but no no config blocks and no paths
+    # in the loader. This is sometimes useful for calling another tool that has
+    # to be loaded from a different configuration.
     #
-    # @param _opts [Hash] Unused options that can be used by subclasses.
+    # @param opts [keywords] Any configuration arguments that should be
+    #     modified from the original. See {#initialize} for a list of
+    #     recognized keywords.
     # @return [Toys::CLI]
     # @yieldparam cli [Toys::CLI] If you pass a block, the new CLI is yielded
     #     to it so you can add paths and make other modifications.
     #
-    def child(**_opts)
-      cli = CLI.new(executable_name: @executable_name,
-                    config_dir_name: @config_dir_name,
-                    config_file_name: @config_file_name,
-                    index_file_name: @index_file_name,
-                    preload_dir_name: @preload_dir_name,
-                    preload_file_name: @preload_file_name,
-                    data_dir_name: @data_dir_name,
-                    middleware_stack: @middleware_stack,
-                    extra_delimiters: @extra_delimiters,
-                    mixin_lookup: @mixin_lookup,
-                    middleware_lookup: @middleware_lookup,
-                    template_lookup: @template_lookup,
-                    logger: @logger,
-                    base_level: @base_level,
-                    error_handler: @error_handler,
-                    completion: @completion)
+    def child(**opts)
+      args = {
+        executable_name: @executable_name,
+        config_dir_name: @config_dir_name,
+        config_file_name: @config_file_name,
+        index_file_name: @index_file_name,
+        preload_dir_name: @preload_dir_name,
+        preload_file_name: @preload_file_name,
+        data_dir_name: @data_dir_name,
+        middleware_stack: @middleware_stack,
+        extra_delimiters: @extra_delimiters,
+        mixin_lookup: @mixin_lookup,
+        middleware_lookup: @middleware_lookup,
+        template_lookup: @template_lookup,
+        logger: @logger,
+        base_level: @base_level,
+        error_handler: @error_handler,
+        completion: @completion,
+      }.merge(opts)
+      cli = CLI.new(**args)
       yield cli if block_given?
       cli
     end
@@ -600,14 +605,14 @@ module Toys
       # *  {Toys::StandardMiddleware::AddVerbosityFlags} adding the `--verbose`
       #    and `--quiet` flags for managing the logger level.
       #
-      # @return [Array<Toys::Middleware>]
+      # @return [Array<Toys::Middleware::Spec>]
       #
       def default_middleware_stack
         [
-          [:set_default_descriptions],
-          [:show_help, help_flags: true, fallback_execution: true],
-          [:handle_usage_errors],
-          [:add_verbosity_flags],
+          Middleware.spec(:set_default_descriptions),
+          Middleware.spec(:show_help, help_flags: true, fallback_execution: true),
+          Middleware.spec(:handle_usage_errors),
+          Middleware.spec(:add_verbosity_flags),
         ]
       end
 

data/lib/toys/core.rb

@@ -30,7 +30,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.9.1"
+    VERSION = "0.9.2"
   end
 
   ## @private deprecated

data/lib/toys/dsl/tool.rb

@@ -1464,9 +1464,10 @@ module Toys
       #
       # @param mod [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)
+      def include(mod, *args, **kwargs)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
         mod = DSL::Tool.resolve_mixin(mod, cur_tool, @__loader)
@@ -1477,11 +1478,11 @@ module Toys
         super(mod)
         if mod.respond_to?(:initializer)
           callback = mod.initializer
-          cur_tool.add_initializer(callback, *args) if callback
+          cur_tool.add_initializer(callback, *args, **kwargs) if callback
         end
         if mod.respond_to?(:inclusion)
           callback = mod.inclusion
-          class_exec(*args, &callback) if callback
+          class_exec(*args, **kwargs, &callback) if callback
         end
         self
       end

data/lib/toys/loader.rb

@@ -21,6 +21,8 @@
 # IN THE SOFTWARE.
 ;
 
+require "monitor"
+
 module Toys
   ##
   # The Loader service loads tools from configuration files, and finds the
@@ -29,18 +31,7 @@ module Toys
   # This class is not thread-safe.
   #
   class Loader
-    ## @private
-    ToolData = ::Struct.new(:definitions, :top_priority, :active_priority) do
-      ## @private
-      def top_definition
-        top_priority ? definitions[top_priority] : nil
-      end
-
-      ## @private
-      def active_definition
-        active_priority ? definitions[active_priority] : nil
-      end
-    end
+    include ::MonitorMixin
 
     ##
     # Create a Loader
@@ -59,8 +50,9 @@ module Toys
     # @param data_dir_name [String,nil] A directory with this name that appears
     #     in any configuration directory is added to the data directory search
     #     path for any tool file in that directory.
-    # @param middleware_stack [Array] An array of middleware that will be used
-    #     by default for all tools loaded by this loader.
+    # @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
+    #     middleware that will be used by default for all tools loaded by this
+    #     loader.
     # @param extra_delimiters [String] A string containing characters that can
     #     function as delimiters in a tool name. Defaults to empty. Allowed
     #     characters are period, colon, and slash.
@@ -74,21 +66,23 @@ module Toys
     def initialize(index_file_name: nil, preload_dir_name: nil, preload_file_name: nil,
                    data_dir_name: nil, middleware_stack: [], extra_delimiters: "",
                    mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil)
+      super()
       if index_file_name && ::File.extname(index_file_name) != ".rb"
         raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
       @mixin_lookup = mixin_lookup || ModuleLookup.new
-      @middleware_lookup = middleware_lookup || ModuleLookup.new
       @template_lookup = template_lookup || ModuleLookup.new
+      @middleware_lookup = middleware_lookup || ModuleLookup.new
       @index_file_name = index_file_name
       @preload_file_name = preload_file_name
       @preload_dir_name = preload_dir_name
       @data_dir_name = data_dir_name
-      @middleware_stack = middleware_stack
+      @loading_started = false
       @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
-      @extra_delimiters = process_extra_delimiters(extra_delimiters)
+      @middleware_stack = Middleware.resolve_specs(*middleware_stack)
+      @delimiter_handler = DelimiterHandler.new(extra_delimiters)
       get_tool([], -999_999)
     end
 
@@ -103,10 +97,13 @@ module Toys
     #
     def add_path(paths, high_priority: false)
       paths = Array(paths)
-      priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-      paths.each do |path|
-        source = SourceInfo.create_path_root(path)
-        @worklist << [source, [], priority]
+      synchronize do
+        raise "Cannot add a path after tool loading has started" if @loading_started
+        priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
+        paths.each do |path|
+          source = SourceInfo.create_path_root(path)
+          @worklist << [source, [], priority]
+        end
       end
       self
     end
@@ -126,9 +123,12 @@ module Toys
     #
     def add_block(high_priority: false, name: nil, &block)
       name ||= "(Code block #{block.object_id})"
-      priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-      source = SourceInfo.create_proc_root(block, name)
-      @worklist << [source, [], priority]
+      synchronize do
+        raise "Cannot add a block after tool loading has started" if @loading_started
+        priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
+        source = SourceInfo.create_proc_root(block, name)
+        @worklist << [source, [], priority]
+      end
       self
     end
 
@@ -146,7 +146,7 @@ module Toys
     # @return [Array(Toys::Tool,Array<String>)]
     #
     def lookup(args)
-      orig_prefix, args = find_orig_prefix(args)
+      orig_prefix, args = @delimiter_handler.find_orig_prefix(args)
       prefix = orig_prefix
       loop do
         tool = lookup_specific(prefix)
@@ -168,10 +168,9 @@ module Toys
     # @return [nil] if no such tool exists
     #
     def lookup_specific(words)
-      words = split_path(words.first) if words.size == 1
+      words = @delimiter_handler.split_path(words.first) if words.size == 1
       load_for_prefix(words)
-      tool_data = get_tool_data(words)
-      tool = tool_data.active_definition || tool_data.top_definition
+      tool = get_tool_data(words).cur_definition
       finish_definitions_in_tree(words) if tool
       tool
     end
@@ -191,14 +190,14 @@ module Toys
       load_for_prefix(words)
       found_tools = []
       len = words.length
-      @tool_data.each do |n, td|
+      tool_data_snapshot.each do |n, td|
         next if n.empty?
         if recursive
           next if n.length <= len || n.slice(0, len) != words
         else
           next unless n.slice(0..-2) == words
         end
-        tool = td.active_definition || td.top_definition
+        tool = td.cur_definition
         found_tools << tool unless tool.nil?
       end
       sort_tools_by_name(found_tools)
@@ -215,8 +214,8 @@ module Toys
     def has_subtools?(words) # rubocop:disable Naming/PredicateName
       load_for_prefix(words)
       len = words.length
-      @tool_data.each do |n, td|
-        if !n.empty? && n.length > len && n.slice(0, len) == words && !td.definitions.empty?
+      tool_data_snapshot.each do |n, td|
+        if !n.empty? && n.length > len && n.slice(0, len) == words && !td.empty?
           return true
         end
       end
@@ -233,8 +232,18 @@ module Toys
     #
     def split_path(str)
       return str.map(&:to_s) if str.is_a?(::Array)
-      str = str.to_s
-      @extra_delimiters ? str.split(@extra_delimiters) : [str]
+      @delimiter_handler.split_path(str.to_s)
+    end
+
+    ##
+    # Get or create the tool definition for the given name and priority.
+    #
+    # @return [Toys::Tool]
+    #
+    # @private
+    #
+    def get_tool(words, priority)
+      get_tool_data(words).get_tool(priority, self)
     end
 
     ##
@@ -253,11 +262,7 @@ module Toys
     # @private
     #
     def activate_tool(words, priority)
-      tool_data = get_tool_data(words)
-      return tool_data.active_definition if tool_data.active_priority == priority
-      return nil if tool_data.active_priority && tool_data.active_priority > priority
-      tool_data.active_priority = priority
-      get_tool(words, priority)
+      get_tool_data(words).activate_tool(priority, self)
     end
 
     ##
@@ -274,44 +279,45 @@ module Toys
     end
 
     ##
-    # Loads the subtree under the given prefix.
+    # Build a new tool.
+    # Called only from ToolData.
     #
-    # @param prefix [Array<String>] The name prefix.
-    # @return [self]
+    # @param words [Array<String>] The name of the tool.
+    # @param priority [Integer] The priority of the request.
+    #
+    # @return [Toys::Tool] A new tool object.
     #
     # @private
     #
-    def load_for_prefix(prefix)
-      cur_worklist = @worklist
-      @worklist = []
-      cur_worklist.each do |source, words, priority|
-        remaining_words = calc_remaining_words(prefix, words)
-        if source.source_proc
-          load_proc(source, words, remaining_words, priority)
-        elsif source.source_path
-          load_validated_path(source, words, remaining_words, priority)
-        end
-      end
-      self
+    def build_tool(words, priority)
+      parent = words.empty? ? nil : get_tool(words.slice(0..-2), priority)
+      built_middleware_stack = @middleware_stack.map { |m| m.build(@middleware_lookup) }
+      Tool.new(self, parent, words, priority, built_middleware_stack)
     end
 
     ##
-    # Get or create the tool definition for the given name and priority.
+    # Loads the subtree under the given prefix.
     #
-    # @return [Toys::Tool]
+    # @param prefix [Array<String>] The name prefix.
+    # @return [self]
     #
     # @private
     #
-    def get_tool(words, priority)
-      parent = words.empty? ? nil : get_tool(words.slice(0..-2), priority)
-      tool_data = get_tool_data(words)
-      if tool_data.top_priority.nil? || tool_data.top_priority < priority
-        tool_data.top_priority = priority
-      end
-      tool_data.definitions[priority] ||= begin
-        middlewares = @middleware_stack.map { |m| resolve_middleware(m) }
-        Tool.new(self, parent, words, priority, middlewares)
+    def load_for_prefix(prefix)
+      synchronize do
+        @loading_started = true
+        cur_worklist = @worklist
+        @worklist = []
+        cur_worklist.each do |source, words, priority|
+          remaining_words = calc_remaining_words(prefix, words)
+          if source.source_proc
+            load_proc(source, words, remaining_words, priority)
+          elsif source.source_path
+            load_validated_path(source, words, remaining_words, priority)
+          end
+        end
       end
+      self
     end
 
     ##
@@ -344,16 +350,28 @@ module Toys
     # Load configuration from the given path. This is called from the `load`
     # directive in the DSL.
     #
+    # @param parent_source [Toys::SourceInfo] The source of the caller.
+    # @param path [String] The file or directory to load.
+    # @param words [Array<String>] The name of the caller, i.e. the context in
+    #     which to load.
+    # @param remaining_words [Array<String>] The remaining words.
+    # @param priority [Integer] The priority.
+    #
     # @private
     #
     def load_path(parent_source, path, words, remaining_words, priority)
       source = parent_source.absolute_child(path)
-      load_validated_path(source, words, remaining_words, priority)
+      synchronize do
+        load_validated_path(source, words, remaining_words, priority)
+      end
     end
 
     ##
     # Determine the next setting for remaining_words, given a word.
     #
+    # @param remaining_words [Array<String>] The remaining words.
+    # @param word [String] The next word to parse.
+    #
     # @private
     #
     def self.next_remaining_words(remaining_words, word)
@@ -368,72 +386,12 @@ module Toys
 
     private
 
-    ALLOWED_DELIMITERS = %r{^[\./:]*$}.freeze
-    private_constant :ALLOWED_DELIMITERS
-
-    def process_extra_delimiters(input)
-      unless ALLOWED_DELIMITERS =~ input
-        raise ::ArgumentError, "Illegal delimiters in #{input.inspect}"
-      end
-      chars = ::Regexp.escape(input.chars.uniq.join)
-      chars.empty? ? nil : ::Regexp.new("[#{chars}]")
-    end
-
-    def find_orig_prefix(args)
-      if @extra_delimiters
-        first_split = (args.first || "").split(@extra_delimiters)
-        if first_split.size > 1
-          args = first_split + args.slice(1..-1)
-          return [first_split, args]
-        end
-      end
-      orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
-      [orig_prefix, args]
+    def tool_data_snapshot
+      synchronize { @tool_data.dup }
     end
 
     def get_tool_data(words)
-      @tool_data[words] ||= ToolData.new({}, nil, nil)
-    end
-
-    def resolve_middleware(input)
-      input = Array(input).dup
-      middleware = input.shift
-      if middleware.is_a?(::String) || middleware.is_a?(::Symbol)
-        middleware = @middleware_lookup.lookup(middleware)
-        if middleware.nil?
-          raise ::ArgumentError, "Unknown middleware name #{input.first.inspect}"
-        end
-      end
-      if middleware.is_a?(::Class)
-        middleware = build_middleware(middleware, input)
-      end
-      unless input.empty?
-        raise ::ArgumentError, "Unrecognized middleware arguments: #{input.inspect}"
-      end
-      middleware
-    end
-
-    def build_middleware(middleware_class, input)
-      args = input.first
-      if args.is_a?(::Array)
-        input.shift
-      else
-        args = []
-      end
-      kwargs = input.first
-      if kwargs.is_a?(::Hash)
-        input.shift
-      else
-        kwargs = {}
-      end
-      # Due to a bug in Ruby < 2.7, passing an empty **kwargs splat to
-      # initialize will fail if there are no formal keyword args.
-      formals = middleware_class.instance_method(:initialize).parameters
-      if kwargs.empty? && formals.all? { |(type, _name)| type != :key && type != :keyrest }
-        middleware_class.new(*args)
-      else
-        middleware_class.new(*args, **kwargs)
-      end
+      synchronize { @tool_data[words] ||= ToolData.new(words) }
     end
 
     ##
@@ -443,10 +401,9 @@ module Toys
     def finish_definitions_in_tree(words)
       load_for_prefix(words)
       len = words.length
-      @tool_data.each do |n, td|
+      tool_data_snapshot.each do |n, td|
         next if n.length < len || n.slice(0, len) != words
-        tool = td.active_definition || td.top_definition
-        tool.finish_definition(self) if tool.is_a?(Tool)
+        td.cur_definition&.finish_definition(self)
       end
     end
 
@@ -555,5 +512,93 @@ module Toys
         index += 1
       end
     end
+
+    ##
+    # Tool data
+    #
+    # @private
+    #
+    class ToolData
+      ## @private
+      def initialize(words)
+        @words = words
+        @definitions = {}
+        @top_priority = @active_priority = nil
+      end
+
+      ## @private
+      def cur_definition
+        active_definition || top_definition
+      end
+
+      ## @private
+      def empty?
+        @definitions.empty?
+      end
+
+      ## @private
+      def get_tool(priority, loader)
+        if @top_priority.nil? || @top_priority < priority
+          @top_priority = priority
+        end
+        @definitions[priority] ||= loader.build_tool(@words, priority)
+      end
+
+      ## @private
+      def activate_tool(priority, loader)
+        return active_definition if @active_priority == priority
+        return nil if @active_priority && @active_priority > priority
+        @active_priority = priority
+        get_tool(priority, loader)
+      end
+
+      private
+
+      def top_definition
+        @top_priority ? @definitions[@top_priority] : nil
+      end
+
+      def active_definition
+        @active_priority ? @definitions[@active_priority] : nil
+      end
+    end
+
+    ##
+    # An object that handles name delimiting.
+    #
+    # @private
+    #
+    class DelimiterHandler
+      ## @private
+      ALLOWED_DELIMITERS = %r{^[\./:]*$}.freeze
+      private_constant :ALLOWED_DELIMITERS
+
+      ## @private
+      def initialize(extra_delimiters)
+        unless ALLOWED_DELIMITERS =~ extra_delimiters
+          raise ::ArgumentError, "Illegal delimiters in #{extra_delimiters.inspect}"
+        end
+        chars = ::Regexp.escape(extra_delimiters.chars.uniq.join)
+        @extra_delimiters = chars.empty? ? nil : ::Regexp.new("[#{chars}]")
+      end
+
+      ## @private
+      def split_path(str)
+        @extra_delimiters ? str.split(@extra_delimiters) : [str]
+      end
+
+      ## @private
+      def find_orig_prefix(args)
+        if @extra_delimiters
+          first_split = (args.first || "").split(@extra_delimiters)
+          if first_split.size > 1
+            args = first_split + args.slice(1..-1)
+            return [first_split, args]
+          end
+        end
+        orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
+        [orig_prefix, args]
+      end
+    end
   end
 end