toys-core 0.9.2 → 0.10.2

data/lib/toys/errors.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # An exception indicating an error in a tool definition.
@@ -96,7 +75,7 @@ module Toys
       rescue ::SyntaxError => e
         if (match = /#{::Regexp.escape(path)}:(\d+)/.match(e.message))
           opts = opts.merge(config_path: path, config_line: match[1].to_i)
-          e = ContextualError.new(e, banner, opts)
+          e = ContextualError.new(e, banner, **opts)
         end
         raise e
       rescue ::ScriptError, ::StandardError => e

data/lib/toys/flag.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # Representation of a formal set of flags that set a particular context

data/lib/toys/flag_group.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # A FlagGroup is a group of flags with the same requirement settings.

data/lib/toys/input_file.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 ##
 # This module is a namespace for constant scopes. Whenever a configuration file
 # is parsed, a module is created under this parent for that file's constants.

data/lib/toys/loader.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 require "monitor"
 
 module Toys
@@ -28,11 +7,7 @@ module Toys
   # The Loader service loads tools from configuration files, and finds the
   # appropriate tool given a set of command line arguments.
   #
-  # This class is not thread-safe.
-  #
   class Loader
-    include ::MonitorMixin
-
     ##
     # Create a Loader
     #
@@ -50,6 +25,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 lib_dir_name [String,nil] A directory with this name that appears
+    #     in any configuration directory is added to the Ruby load path for any
+    #     tool file in that directory.
     # @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
     #     middleware that will be used by default for all tools loaded by this
     #     loader.
@@ -63,13 +41,22 @@ module Toys
     # @param template_lookup [Toys::ModuleLookup] A lookup for
     #     well-known template classes. Defaults to an empty lookup.
     #
-    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()
+    def initialize(
+      index_file_name: nil,
+      preload_dir_name: nil,
+      preload_file_name: nil,
+      data_dir_name: nil,
+      lib_dir_name: nil,
+      middleware_stack: [],
+      extra_delimiters: "",
+      mixin_lookup: nil,
+      middleware_lookup: nil,
+      template_lookup: nil
+    )
       if index_file_name && ::File.extname(index_file_name) != ".rb"
         raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
+      @mutex = ::Monitor.new
       @mixin_lookup = mixin_lookup || ModuleLookup.new
       @template_lookup = template_lookup || ModuleLookup.new
       @middleware_lookup = middleware_lookup || ModuleLookup.new
@@ -77,11 +64,12 @@ module Toys
       @preload_file_name = preload_file_name
       @preload_dir_name = preload_dir_name
       @data_dir_name = data_dir_name
+      @lib_dir_name = lib_dir_name
       @loading_started = false
       @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
-      @middleware_stack = Middleware.resolve_specs(*middleware_stack)
+      @middleware_stack = Middleware.stack(middleware_stack)
       @delimiter_handler = DelimiterHandler.new(extra_delimiters)
       get_tool([], -999_999)
     end
@@ -97,7 +85,7 @@ module Toys
     #
     def add_path(paths, high_priority: false)
       paths = Array(paths)
-      synchronize do
+      @mutex.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|
@@ -123,7 +111,7 @@ module Toys
     #
     def add_block(high_priority: false, name: nil, &block)
       name ||= "(Code block #{block.object_id})"
-      synchronize do
+      @mutex.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)
@@ -238,8 +226,6 @@ module Toys
     ##
     # Get or create the tool definition for the given name and priority.
     #
-    # @return [Toys::Tool]
-    #
     # @private
     #
     def get_tool(words, priority)
@@ -253,12 +239,6 @@ module Toys
     # the active priority, returns `nil`. If the given priority is higher than
     # the active priority, returns and activates a new tool.
     #
-    # @param words [Array<String>] The name of the tool.
-    # @param priority [Integer] The priority of the request.
-    #
-    # @return [Toys::Tool] The tool found.
-    # @return [nil] if the given priority is insufficient.
-    #
     # @private
     #
     def activate_tool(words, priority)
@@ -269,9 +249,6 @@ module Toys
     # Returns true if the given tool name currently exists in the loader.
     # Does not load the tool if not found.
     #
-    # @param words [Array<String>] The name of the tool.
-    # @return [Boolean]
-    #
     # @private
     #
     def tool_defined?(words)
@@ -282,29 +259,21 @@ module Toys
     # Build a new tool.
     # Called only from ToolData.
     #
-    # @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 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)
+      middleware_stack = parent ? parent.subtool_middleware_stack : @middleware_stack
+      Tool.new(self, parent, words, priority, middleware_stack, @middleware_lookup)
     end
 
     ##
     # Loads the subtree under the given prefix.
     #
-    # @param prefix [Array<String>] The name prefix.
-    # @return [self]
-    #
     # @private
     #
     def load_for_prefix(prefix)
-      synchronize do
+      @mutex.synchronize do
         @loading_started = true
         cur_worklist = @worklist
         @worklist = []
@@ -323,10 +292,6 @@ module Toys
     ##
     # Attempt to get a well-known mixin module for the given symbolic name.
     #
-    # @param name [Symbol] Mixin name
-    # @return [Module] The mixin
-    # @return [nil] if not found.
-    #
     # @private
     #
     def resolve_standard_mixin(name)
@@ -336,10 +301,6 @@ module Toys
     ##
     # Attempt to get a well-known template class for the given symbolic name.
     #
-    # @param name [Symbol] Template name
-    # @return [Class] The template.
-    # @return [nil] if not found.
-    #
     # @private
     #
     def resolve_standard_template(name)
@@ -350,27 +311,29 @@ 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)
-      synchronize do
+      @mutex.synchronize do
         load_validated_path(source, words, remaining_words, priority)
       end
     end
 
     ##
-    # Determine the next setting for remaining_words, given a word.
+    # Load a subtool block. Called from the `tool` directive in the DSL.
+    #
+    # @private
     #
-    # @param remaining_words [Array<String>] The remaining words.
-    # @param word [String] The next word to parse.
+    def load_block(parent_source, block, words, remaining_words, priority)
+      source = parent_source.proc_child(block)
+      @mutex.synchronize do
+        load_proc(source, words, remaining_words, priority)
+      end
+    end
+
+    ##
+    # Determine the next setting for remaining_words, given a word.
     #
     # @private
     #
@@ -387,11 +350,11 @@ module Toys
     private
 
     def tool_data_snapshot
-      synchronize { @tool_data.dup }
+      @mutex.synchronize { @tool_data.dup }
     end
 
     def get_tool_data(words)
-      synchronize { @tool_data[words] ||= ToolData.new(words) }
+      @mutex.synchronize { @tool_data[words] ||= ToolData.new(words) }
     end
 
     ##
@@ -443,15 +406,16 @@ module Toys
 
     def load_index_in(source, words, remaining_words, priority)
       return unless @index_file_name
-      index_source = source.relative_child(@index_file_name, @data_dir_name)
+      index_source = source.relative_child(@index_file_name, @data_dir_name, @lib_dir_name)
       load_relevant_path(index_source, words, remaining_words, priority) if index_source
     end
 
     def load_child_in(source, child, words, remaining_words, priority)
       return if child.start_with?(".") || child == @index_file_name ||
                 child == @preload_file_name || child == @preload_dir_name ||
-                child == @data_dir_name
-      child_source = source.relative_child(child, @data_dir_name)
+                child == @data_dir_name || child == @lib_dir_name
+      child_source = source.relative_child(child, @data_dir_name, @lib_dir_name)
+      return unless child_source
       child_word = ::File.basename(child, ".rb")
       next_words = words + [child_word]
       next_remaining = Loader.next_remaining_words(remaining_words, child_word)

data/lib/toys/middleware.rb

@@ -1,26 +1,5 @@
 # frozen_string_literal: true
 
-# Copyright 2019 Daniel Azuma
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-;
-
 module Toys
   ##
   # A middleware is an object that has the opportunity to alter the
@@ -39,15 +18,15 @@ module Toys
   # middleware, a Toys middleware can wrap execution with its own code,
   # replace it outright, or leave it unmodified.
   #
-  # Generally, a middleware is a class that implements the two methods defined
-  # in this module: {Toys::Middleware#config} and {Toys::Middleware#run}. To
-  # get default implementations that do nothing, a middleware can
-  # `include Toys::Middleware` or subclass {Toys::Middleware::Base}, but this
-  # is not required.
+  # Generally, a middleware is a class that implements one or more of the
+  # methods defined in this module: {Toys::Middleware#config}, and
+  # {Toys::Middleware#run}. This module provides default implementations that
+  # do nothing, but using them is not required. Middleware objects need respond
+  # only to methods they care about.
   #
   module Middleware
     ##
-    # This method is called after a tool has been defined, and gives this
+    # This method is called *after* a tool has been defined, and gives this
     # middleware the opportunity to modify the tool definition. It is passed
     # the tool definition object and the loader, and can make any changes to
     # the tool definition. In most cases, this method should also call
@@ -95,12 +74,6 @@ module Toys
       ##
       # Create a middleware spec.
       #
-      # @overload spec(middleware_object)
-      #   Create a spec wrapping an existing middleware object
-      #
-      #   @param middleware_object [Toys::Middleware] The middleware object
-      #   @return [Toys::Middleware::Spec] A spec
-      #
       # @overload spec(name, *args, **kwargs, &block)
       #   Create a spec indicating a given middleware name should be
       #   instantiated with the given arguments.
@@ -111,27 +84,63 @@ module Toys
       #   @param block [Proc,nil] The block to pass to the constructor
       #   @return [Toys::Middleware::Spec] A spec
       #
+      # @overload spec(array)
+      #   Create a middleware spec from an array specification.
+      #
+      #   The array must be 1-4 elements long. The first element must be the
+      #   middleware name or class. The other three arguments may include any
+      #   or all of the following optional elements, in any order:
+      #    *  An array for the positional arguments to pass to the constructor
+      #    *  A hash for the keyword arguments to pass to the constructor
+      #    *  A proc for the block to pass to the constructor
+      #
+      #   @param array [Array] The array input
+      #   @return [Toys::Middleware::Spec] A spec
+      #
+      # @overload spec(middleware_object)
+      #   Create a spec wrapping an existing middleware object
+      #
+      #   @param middleware_object [Toys::Middleware] The middleware object
+      #   @return [Toys::Middleware::Spec] A spec
+      #
       def spec(middleware, *args, **kwargs, &block)
-        if middleware.is_a?(::String) || middleware.is_a?(::Symbol) || middleware.is_a?(::Class)
+        case middleware
+        when ::Array
+          spec_from_array(middleware)
+        when ::String, ::Symbol, ::Class
           Spec.new(nil, middleware, args, kwargs, block)
+        when Spec
+          middleware
         else
           Spec.new(middleware, nil, nil, nil, nil)
         end
       end
 
       ##
-      # Create a middleware spec from an array specification.
+      # Create a {Toys::Middleware::Stack} from an array of middleware specs.
+      # Each element may be one of the following:
       #
-      # The array must be 1-4 elements long. The first element must be the
-      # middleware name or class. The other three arguments may include any or
-      # all of the following optional elements, in any order:
-      #  *  An array for the positional arguments to pass to the constructor
-      #  *  A hash for the keyword arguments to pass to the constructor
-      #  *  A proc for the block to pass to the constructor
+      #  *  A {Toys::Middleware} object
+      #  *  A {Toys::Middleware::Spec}
+      #  *  An array whose first element is a middleware name or class, and the
+      #     subsequent elements are params that define what to pass to the class
+      #     constructor (see {Toys::Middleware.spec})
       #
-      # @param array [Array] The array input
-      # @return [Toys::Middleware::Spec] A spec
+      # @param input [Array<Toys::Middleware,Toys::Middleware::Spec,Array>]
+      # @return [Toys::Middleware::Stack]
       #
+      def stack(input)
+        case input
+        when Stack
+          input
+        when ::Array
+          Stack.new(default_specs: input.map { |spec| spec(spec) })
+        else
+          raise ::ArgumentError, "Illegal middleware stack: #{input.inspect}"
+        end
+      end
+
+      ## @private
       def spec_from_array(array)
         middleware = array.first
         if !middleware.is_a?(::String) && !middleware.is_a?(::Symbol) && !middleware.is_a?(::Class)
@@ -154,32 +163,6 @@ module Toys
         end
         Spec.new(nil, middleware, args, kwargs, block)
       end
-
-      ##
-      # Resolve all arguments into an array of middleware specs. Each argument
-      # may be one of the following:
-      #
-      #  *  A {Toys::Middleware} object
-      #  *  A {Toys::Middleware::Spec}
-      #  *  An array whose first element is a middleware name or class, and the
-      #     subsequent elements are params that define what to pass to the class
-      #     constructor (see {Toys::Middleware.spec_from_array})
-      #
-      # @param items [Array<Toys::Middleware,Toys::Middleware::Spec,Array>]
-      # @return [Array<Toys::Middleware::Spec>]
-      #
-      def resolve_specs(*items)
-        items.map do |item|
-          case item
-          when ::Array
-            spec_from_array(item)
-          when Spec
-            item
-          else
-            spec(item)
-          end
-        end
-      end
     end
 
     ##
@@ -216,14 +199,7 @@ module Toys
         else
           klass = @name
         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 = klass.instance_method(:initialize).parameters
-        if @kwargs.empty? && formals.all? { |arg| arg.first != :key && arg.first != :keyrest }
-          klass.new(*@args, &@block)
-        else
-          klass.new(*@args, **@kwargs, &@block)
-        end
+        Compat.instantiate(klass, @args, @kwargs, @block)
       end
 
       ##
@@ -270,6 +246,99 @@ module Toys
         @kwargs = kwargs
         @block = block
       end
+
+      ## @private
+      def ==(other)
+        other.is_a?(Spec) &&
+          object.eql?(other.object) &&
+          name.eql?(other.name) &&
+          args.eql?(other.args) &&
+          kwargs.eql?(other.kwargs) &&
+          block.eql?(other.block)
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        [object, name, args, kwargs, block].hash
+      end
+    end
+
+    ##
+    # A stack of middleware specs.
+    #
+    class Stack
+      ##
+      # The middleware specs that precede the default set.
+      # @return [Array<Toys::Middleware:Spec>]
+      #
+      attr_reader :pre_specs
+
+      ##
+      # The default set of middleware specs.
+      # @return [Array<Toys::Middleware:Spec>]
+      #
+      attr_reader :default_specs
+
+      ##
+      # The middleware specs that follow the default set.
+      # @return [Array<Toys::Middleware:Spec>]
+      #
+      attr_reader :post_specs
+
+      ##
+      # Add a middleware spec to the stack, in the default location, which is
+      # at the end of pre_specs). See {Toys::Middleware.spec} for a description
+      # of the arguments you can pass.
+      #
+      # @overload add(name, *args, **kwargs, &block)
+      # @overload add(array)
+      # @overload add(middleware_object)
+      #
+      def add(middleware, *args, **kwargs, &block)
+        pre_specs.push(Middleware.spec(middleware, *args, **kwargs, &block))
+      end
+
+      ##
+      # Duplicate this stack.
+      #
+      # @return [Toys::Middleware::Stack]
+      #
+      def dup
+        Stack.new(pre_specs: pre_specs.dup,
+                  post_specs: post_specs.dup,
+                  default_specs: default_specs.dup)
+      end
+
+      ##
+      # Build the middleware in this stack.
+      #
+      # @return [Array<Toys::Middleware>]
+      #
+      def build(middleware_lookup)
+        (@pre_specs + @default_specs + @post_specs).map { |spec| spec.build(middleware_lookup) }
+      end
+
+      ## @private
+      def initialize(default_specs: nil, pre_specs: nil, post_specs: nil)
+        @pre_specs = pre_specs || []
+        @post_specs = post_specs || []
+        @default_specs = default_specs || []
+      end
+
+      ## @private
+      def ==(other)
+        other.is_a?(Stack) &&
+          pre_specs.eql?(other.pre_specs) &&
+          default_specs.eql?(other.default_specs) &&
+          post_specs.eql?(other.post_specs)
+      end
+      alias eql? ==
+
+      ## @private
+      def hash
+        [@pre_specs, @default_specs, @post_specs].hash
+      end
     end
   end
 end