toys-core 0.9.1 → 0.9.2

data/lib/toys/middleware.rb

@@ -40,9 +40,10 @@ module Toys
   # 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}. A
-  # middleware can include this module to get default implementations that do
-  # nothing, but this is not required.
+  # 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.
   #
   module Middleware
     ##
@@ -89,5 +90,186 @@ module Toys
     def run(context) # rubocop:disable Lint/UnusedMethodArgument
       yield
     end
+
+    class << self
+      ##
+      # 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.
+      #
+      #   @param name [String,Symbol,Class] The middleware name or class
+      #   @param args [Array] The arguments to pass to the constructor
+      #   @param kwargs [Hash] The keyword arguments to pass to the constructor
+      #   @param block [Proc,nil] The block to pass to the constructor
+      #   @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)
+          Spec.new(nil, middleware, args, kwargs, block)
+        else
+          Spec.new(middleware, nil, nil, nil, nil)
+        end
+      end
+
+      ##
+      # 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
+      #
+      def spec_from_array(array)
+        middleware = array.first
+        if !middleware.is_a?(::String) && !middleware.is_a?(::Symbol) && !middleware.is_a?(::Class)
+          raise ::ArgumentError, "Bad middleware name: #{middleware.inspect}"
+        end
+        args = []
+        kwargs = {}
+        block = nil
+        array.slice(1..-1).each do |param|
+          case param
+          when ::Array
+            args += param
+          when ::Hash
+            kwargs = kwargs.merge(param)
+          when ::Proc
+            block = param
+          else
+            raise ::ArgumentError, "Bad param: #{param.inspect}"
+          end
+        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
+
+    ##
+    # A base class that provides default NOP implementations of the middleware
+    # interface. This base class may optionally be subclassed by a middleware
+    # implementation.
+    #
+    class Base
+      include Middleware
+    end
+
+    ##
+    # A middleware specification, including the middleware class and the
+    # arguments to pass to the constructor.
+    #
+    # Use {Toys::Middleware.spec} to create a middleware spec.
+    #
+    class Spec
+      ##
+      # Builds a middleware for this spec, given a ModuleLookup for middleware.
+      #
+      # If this spec wraps an existing middleware object, returns that object.
+      # Otherwise, constructs a middleware object from the spec.
+      #
+      # @param lookup [Toys::ModuleLookup] A module lookup to resolve
+      #     middleware names
+      # @return [Toys::Middleware] The middleware
+      #
+      def build(lookup)
+        return @object unless @object.nil?
+        if @name.is_a?(::String) || @name.is_a?(::Symbol)
+          klass = lookup&.lookup(@name)
+          raise ::NameError, "Unknown middleware name #{@name.inspect}" if klass.nil?
+        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
+      end
+
+      ##
+      # @return [Toys::Middleware] if this spec wraps a middleware object
+      # @return [nil] if this spec represents a class to instantiate
+      #
+      attr_reader :object
+
+      ##
+      # @return [String,Symbol] if this spec represents a middleware name
+      # @return [Class] if this spec represents a middleware class
+      # @return [nil] if this spec wraps a middleware object
+      #
+      attr_reader :name
+
+      ##
+      # @return [Array] the positional arguments to be passed to a middleware
+      #     class constructor, or the empty array if there are no positional
+      #     arguments
+      # @return [nil] if this spec wraps a middleware object
+      #
+      attr_reader :args
+
+      ##
+      # @return [Hash] the keyword arguments to be passed to a middleware class
+      #     constructor, or the empty hash if there are no keyword arguments
+      # @return [nil] if this spec wraps a middleware object
+      #
+      attr_reader :kwargs
+
+      ##
+      # @return [Proc] if there is a block argument to be passed to a
+      #     middleware class constructor
+      # @return [nil] if there is no block argument, or this spec wraps a
+      #     middleware object
+      #
+      attr_reader :block
+
+      ## @private
+      def initialize(object, name, args, kwargs, block)
+        @object = object
+        @name = name
+        @args = args
+        @kwargs = kwargs
+        @block = block
+      end
+    end
   end
 end

data/lib/toys/module_lookup.rb

@@ -21,6 +21,8 @@
 # IN THE SOFTWARE.
 ;
 
+require "monitor"
+
 module Toys
   ##
   # A helper module that provides methods to do module lookups. This is
@@ -71,11 +73,15 @@ module Toys
       end
     end
 
+    include ::MonitorMixin
+
     ##
     # Create an empty ModuleLookup
     #
     def initialize
+      super()
       @paths = []
+      @paths_locked = false
     end
 
     ##
@@ -90,10 +96,13 @@ module Toys
     #
     def add_path(path_base, module_base: nil, high_priority: false)
       module_base ||= ModuleLookup.path_to_module(path_base)
-      if high_priority
-        @paths.unshift([path_base, module_base])
-      else
-        @paths << [path_base, module_base]
+      synchronize do
+        raise "You cannot add a path after a lookup has already occurred." if @paths_locked
+        if high_priority
+          @paths.unshift([path_base, module_base])
+        else
+          @paths << [path_base, module_base]
+        end
       end
       self
     end
@@ -105,19 +114,22 @@ module Toys
     # @return [Module] The specified module
     #
     def lookup(name)
-      @paths.each do |path_base, module_base|
-        path = "#{path_base}/#{ModuleLookup.to_path_name(name)}"
-        begin
-          require path
-        rescue ::LoadError
-          next
-        end
-        mod_name = ModuleLookup.to_module_name(name)
-        unless module_base.constants.include?(mod_name)
-          raise ::NameError,
-                "File #{path.inspect} did not define #{module_base.name}::#{mod_name}"
+      synchronize do
+        @paths_locked = true
+        @paths.each do |path_base, module_base|
+          path = "#{path_base}/#{ModuleLookup.to_path_name(name)}"
+          begin
+            require path
+          rescue ::LoadError
+            next
+          end
+          mod_name = ModuleLookup.to_module_name(name)
+          unless module_base.constants.include?(mod_name)
+            raise ::NameError,
+                  "File #{path.inspect} did not define #{module_base.name}::#{mod_name}"
+          end
+          return module_base.const_get(mod_name)
         end
-        return module_base.const_get(mod_name)
       end
       nil
     end

data/lib/toys/standard_mixins/exec.rb

@@ -95,11 +95,11 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      on_initialize do |opts = {}|
+      on_initialize do |**opts|
         require "toys/utils/exec"
         context = self
         opts = Exec._setup_exec_opts(opts, context)
-        context[KEY] = Utils::Exec.new(opts) do |k|
+        context[KEY] = Utils::Exec.new(**opts) do |k|
           case k
           when :logger
             context[Context::Key::LOGGER]
@@ -115,11 +115,12 @@ module Toys
       # All options listed in the {Toys::Utils::Exec} documentation are
       # supported, plus the `exit_on_nonzero_status` option.
       #
-      # @param opts [Hash] The default options.
+      # @param opts [keywords] The default options.
       # @return [self]
       #
-      def configure_exec(opts = {})
-        self[KEY].configure_defaults(Exec._setup_exec_opts(opts, self))
+      def configure_exec(**opts)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].configure_defaults(**opts)
         self
       end
 
@@ -131,7 +132,7 @@ module Toys
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
       # @param cmd [String,Array<String>] The command to execute.
-      # @param opts [Hash] The command options. All options listed in the
+      # @param opts [keywords] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
@@ -142,8 +143,9 @@ module Toys
       # @return [Toys::Utils::Exec::Result] The result, if the process ran in
       #     the foreground.
       #
-      def exec(cmd, opts = {}, &block)
-        self[KEY].exec(cmd, Exec._setup_exec_opts(opts, self), &block)
+      def exec(cmd, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].exec(cmd, **opts, &block)
       end
 
       ##
@@ -153,7 +155,7 @@ module Toys
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
       # @param args [String,Array<String>] The arguments to ruby.
-      # @param opts [Hash] The command options. All options listed in the
+      # @param opts [keywords] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
@@ -164,8 +166,9 @@ module Toys
       # @return [Toys::Utils::Exec::Result] The result, if the process ran in
       #     the foreground.
       #
-      def exec_ruby(args, opts = {}, &block)
-        self[KEY].exec_ruby(args, Exec._setup_exec_opts(opts, self), &block)
+      def exec_ruby(args, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].exec_ruby(args, **opts, &block)
       end
       alias ruby exec_ruby
 
@@ -176,7 +179,7 @@ module Toys
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
       # @param func [Proc] The proc to call.
-      # @param opts [Hash] The command options. Most options listed in the
+      # @param opts [keywords] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -187,8 +190,9 @@ module Toys
       # @return [Toys::Utils::Exec::Result] The result, if the process ran in
       #     the foreground.
       #
-      def exec_proc(func, opts = {}, &block)
-        self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
+      def exec_proc(func, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].exec_proc(func, **opts, &block)
       end
 
       ##
@@ -199,7 +203,7 @@ module Toys
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [Hash] The command options. Most options listed in the
+      # @param opts [keywords] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -210,9 +214,10 @@ module Toys
       # @return [Toys::Utils::Exec::Result] The result, if the process ran in
       #     the foreground.
       #
-      def exec_tool(cmd, opts = {}, &block)
+      def exec_tool(cmd, **opts, &block)
         func = Exec._make_tool_caller(cmd)
-        self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].exec_proc(func, **opts, &block)
       end
 
       ##
@@ -226,7 +231,7 @@ module Toys
       # yielded to it.
       #
       # @param cmd [String,Array<String>] The command to execute.
-      # @param opts [Hash] The command options. All options listed in the
+      # @param opts [keywords] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -234,8 +239,9 @@ module Toys
       #
       # @return [String] What was written to standard out.
       #
-      def capture(cmd, opts = {}, &block)
-        self[KEY].capture(cmd, Exec._setup_exec_opts(opts, self), &block)
+      def capture(cmd, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].capture(cmd, **opts, &block)
       end
 
       ##
@@ -248,7 +254,7 @@ module Toys
       # yielded to it.
       #
       # @param args [String,Array<String>] The arguments to ruby.
-      # @param opts [Hash] The command options. All options listed in the
+      # @param opts [keywords] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -256,8 +262,9 @@ module Toys
       #
       # @return [String] What was written to standard out.
       #
-      def capture_ruby(args, opts = {}, &block)
-        self[KEY].capture_ruby(args, Exec._setup_exec_opts(opts, self), &block)
+      def capture_ruby(args, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].capture_ruby(args, **opts, &block)
       end
 
       ##
@@ -270,7 +277,7 @@ module Toys
       # yielded to it.
       #
       # @param func [Proc] The proc to call.
-      # @param opts [Hash] The command options. Most options listed in the
+      # @param opts [keywords] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -278,8 +285,9 @@ module Toys
       #
       # @return [String] What was written to standard out.
       #
-      def capture_proc(func, opts = {}, &block)
-        self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self), &block)
+      def capture_proc(func, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].capture_proc(func, **opts, &block)
       end
 
       ##
@@ -293,7 +301,7 @@ module Toys
       # yielded to it.
       #
       # @param cmd [String,Array<String>] The tool to execute.
-      # @param opts [Hash] The command options. Most options listed in the
+      # @param opts [keywords] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -301,9 +309,10 @@ module Toys
       #
       # @return [String] What was written to standard out.
       #
-      def capture_tool(cmd, opts = {}, &block)
+      def capture_tool(cmd, **opts, &block)
         func = Exec._make_tool_caller(cmd)
-        self[KEY].capture_proc(func, Exec._setup_exec_opts(opts, self), &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].capture_proc(func, **opts, &block)
       end
 
       ##
@@ -314,7 +323,7 @@ module Toys
       # yielded to it.
       #
       # @param cmd [String] The shell command to execute.
-      # @param opts [Hash] The command options. All options listed in the
+      # @param opts [keywords] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -322,8 +331,9 @@ module Toys
       #
       # @return [Integer] The exit code
       #
-      def sh(cmd, opts = {}, &block)
-        self[KEY].sh(cmd, Exec._setup_exec_opts(opts, self), &block)
+      def sh(cmd, **opts, &block)
+        opts = Exec._setup_exec_opts(opts, self)
+        self[KEY].sh(cmd, **opts, &block)
       end
 
       ##