toys-core 0.8.1 → 0.9.0

data/lib/toys/dsl/positional_arg.rb

@@ -49,8 +49,8 @@ module Toys
         @display_name = display_name
         @desc = desc
         @long_desc = long_desc || []
-        accept(acceptor)
-        complete(completion)
+        accept(acceptor, **{})
+        complete(completion, **{})
       end
 
       ##
@@ -65,9 +65,7 @@ module Toys
       # @return [self]
       #
       def accept(spec = nil, **options, &block)
-        @acceptor_spec = spec
-        @acceptor_options = options
-        @acceptor_block = block
+        @acceptor = Acceptor.scalarize_spec(spec, options, block)
         self
       end
 
@@ -94,9 +92,7 @@ module Toys
       # @return [self]
       #
       def complete(spec = nil, **options, &block)
-        @completion_spec = spec
-        @completion_options = options
-        @completion_block = block
+        @completion = Completion.scalarize_spec(spec, options, block)
         self
       end
 
@@ -178,31 +174,22 @@ module Toys
 
       ## @private
       def _add_required_to(tool, key)
-        acceptor = tool.scalar_acceptor(@acceptor_spec, @acceptor_options, &@acceptor_block)
-        completion = tool.scalar_completion(@completion_spec, @completion_options,
-                                            &@completion_block)
         tool.add_required_arg(key,
-                              accept: acceptor, complete: completion,
+                              accept: @acceptor, complete: @completion,
                               display_name: @display_name, desc: @desc, long_desc: @long_desc)
       end
 
       ## @private
       def _add_optional_to(tool, key)
-        acceptor = tool.scalar_acceptor(@acceptor_spec, @acceptor_options, &@acceptor_block)
-        completion = tool.scalar_completion(@completion_spec, @completion_options,
-                                            &@completion_block)
         tool.add_optional_arg(key,
-                              accept: acceptor, default: @default, complete: completion,
+                              accept: @acceptor, default: @default, complete: @completion,
                               display_name: @display_name, desc: @desc, long_desc: @long_desc)
       end
 
       ## @private
       def _set_remaining_on(tool, key)
-        acceptor = tool.scalar_acceptor(@acceptor_spec, @acceptor_options, &@acceptor_block)
-        completion = tool.scalar_completion(@completion_spec, @completion_options,
-                                            &@completion_block)
         tool.set_remaining_args(key,
-                                accept: acceptor, default: @default, complete: completion,
+                                accept: @acceptor, default: @default, complete: @completion,
                                 display_name: @display_name, desc: @desc, long_desc: @long_desc)
       end
     end

data/lib/toys/dsl/tool.rb

@@ -57,7 +57,7 @@ module Toys
     module Tool
       ## @private
       def method_added(_meth)
-        DSL::Tool.current_tool(self, true)&.check_definition_state
+        DSL::Tool.current_tool(self, true)&.check_definition_state(is_method: true)
       end
 
       ##
@@ -273,7 +273,7 @@ module Toys
       #
       def completion(name, spec = nil, **options, &block)
         cur_tool = DSL::Tool.current_tool(self, false)
-        cur_tool&.add_completion(name, spec, options, &block)
+        cur_tool&.add_completion(name, spec, **options, &block)
         self
       end
 
@@ -297,6 +297,16 @@ module Toys
       #       end
       #     end
       #
+      # The following example defines a tool that runs one of its subtools.
+      #
+      #     tool "test", runs: ["test", "unit"] do
+      #       tool "unit" do
+      #         def run
+      #           puts "Running unit tests"
+      #         end
+      #       end
+      #     end
+      #
       # @param words [String,Array<String>] The name of the subtool
       # @param if_defined [:combine,:reset,:ignore] What to do if a definition
       #     already exists for this tool. Possible values are `:combine` (the
@@ -304,10 +314,14 @@ module Toys
       #     existing definition, `:reset` indicating the earlier definition
       #     should be reset and the new definition applied instead, or
       #     `:ignore` indicating the new definition should be ignored.
+      # @param delegate_to [String,Array<String>] Optional. This tool should
+      #     delegate to another tool, specified by the full path. This path may
+      #     be given as an array of strings, or a single string possibly
+      #     delimited by path separators.
       # @param block [Proc] Defines the subtool.
       # @return [self]
       #
-      def tool(words, if_defined: :combine, &block)
+      def tool(words, if_defined: :combine, delegate_to: nil, &block)
         subtool_words = @__words
         next_remaining = @__remaining_words
         Array(words).each do |word|
@@ -326,17 +340,19 @@ module Toys
         end
         subtool_class = subtool.tool_class
         DSL::Tool.prepare(subtool_class, next_remaining, source_info) do
-          subtool_class.class_eval(&block)
+          subtool_class.delegate_to(delegate_to) if delegate_to
+          subtool_class.class_eval(&block) if block
         end
         self
       end
       alias name tool
 
       ##
-      # Create an alias in the current namespace.
+      # Create an alias, representing an "alternate name" for a tool.
       #
-      # An alias is an alternate name for a tool. The referenced tool must be
-      # in the same namespace.
+      # This is functionally equivalent to creating a subtool with the
+      # `delegate_to` option, except that `alias_tool` takes a _relative_ name
+      # for the delegate.
       #
       # ## Example
       #
@@ -351,11 +367,44 @@ module Toys
       #     alias_tool "t", "test"
       #
       # @param word [String] The name of the alias
-      # @param target [String] The target of the alias
+      # @param target [String,Array<String>] Relative path to the target of the
+      #     alias. This path may be given as an array of strings, or a single
+      #     string possibly delimited by path separators.
       # @return [self]
       #
       def alias_tool(word, target)
-        @__loader.make_alias(@__words + [word.to_s], @__words + [target.to_s], @__priority)
+        tool(word, delegate_to: @__words + @__loader.split_path(target))
+        self
+      end
+
+      ##
+      # Causes the current tool to delegate to another tool. When run, it
+      # simply invokes the target tool with the same arguments.
+      #
+      # ## 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
+      # the subtool `test unit`.
+      #
+      #     tool "test" do
+      #       tool "unit" do
+      #         flag :faster
+      #         def run
+      #           puts "running tests..."
+      #         end
+      #       end
+      #       delegate_to "test:unit"
+      #     end
+      #
+      # @param target [String,Array<String>] The full path to the delegate
+      #     tool. This path may be given as an array of strings, or a single
+      #     string possibly delimited by path separators.
+      # @return [self]
+      #
+      def delegate_to(target)
+        cur_tool = DSL::Tool.current_tool(self, true)
+        cur_tool.delegate_to(@__loader.split_path(target))
         self
       end
 
@@ -403,7 +452,7 @@ module Toys
       # @param args [Object...] Template arguments
       # @return [self]
       #
-      def expand(template_class, *args)
+      def expand(template_class, *args, **kwargs)
         cur_tool = DSL::Tool.current_tool(self, false)
         name = template_class.to_s
         if template_class.is_a?(::String)
@@ -414,7 +463,15 @@ module Toys
         if template_class.nil?
           raise ToolDefinitionError, "Template not found: #{name.inspect}"
         end
-        template = template_class.new(*args)
+        # 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 = template_class.instance_method(:initialize).parameters
+        template =
+          if kwargs.empty? && formals.all? { |(type, _name)| type != :key && type != :keyrest }
+            template_class.new(*args)
+          else
+            template_class.new(*args, **kwargs)
+          end
         yield template if block_given?
         class_exec(template, &template_class.expansion)
         self
@@ -1121,8 +1178,6 @@ module Toys
       #       end
       #     end
       #
-      # @return [self]
-      #
       # @overload static(key, value)
       #   Set a single value by key.
       #   @param key [String,Symbol] The key to use to retrieve the value from
@@ -1162,8 +1217,6 @@ module Toys
       #       end
       #     end
       #
-      # @return [self]
-      #
       # @overload set(key, value)
       #   Set a single value by key.
       #   @param key [String,Symbol] The key to use to retrieve the value from
@@ -1295,7 +1348,7 @@ module Toys
       def complete_tool_args(spec = nil, **options, &block)
         cur_tool = DSL::Tool.current_tool(self, true)
         return self if cur_tool.nil?
-        cur_tool.completion = cur_tool.scalar_completion(spec, options, &block)
+        cur_tool.completion = Completion.scalarize_spec(spec, options, block)
         self
       end
 
@@ -1505,6 +1558,16 @@ module Toys
         DSL::Tool.current_tool(self, false)&.context_directory || source_info.context_directory
       end
 
+      ##
+      # Return the current tool object. This object can be queried to determine
+      # such information as the name, but it should not be altered.
+      #
+      # @return [Toys::Tool]
+      #
+      def current_tool
+        DSL::Tool.current_tool(self, false)
+      end
+
       ##
       # Set a custom context directory for this tool.
       #
@@ -1545,10 +1608,6 @@ module Toys
             else
               loader.get_tool(words, priority)
             end
-          if cur_tool.is_a?(Alias)
-            raise ToolDefinitionError,
-                  "Cannot configure #{words.join(' ').inspect} because it is an alias"
-          end
           tool_class.instance_variable_set(memoize_var, cur_tool)
         end
         if cur_tool && activate

data/lib/toys/errors.rb

@@ -87,7 +87,7 @@ module Toys
 
     class << self
       ## @private
-      def capture_path(banner, path, opts = {})
+      def capture_path(banner, path, **opts)
         yield
       rescue ContextualError => e
         add_fields_if_missing(e, opts)
@@ -107,13 +107,13 @@ module Toys
       end
 
       ## @private
-      def capture(banner, opts = {})
+      def capture(banner, **opts)
         yield
       rescue ContextualError => e
         add_fields_if_missing(e, opts)
         raise e
       rescue ::ScriptError, ::StandardError => e
-        raise ContextualError.new(e, banner, opts)
+        raise ContextualError.new(e, banner, **opts)
       end
 
       private

data/lib/toys/flag.rb

@@ -62,7 +62,7 @@ module Toys
       @long_desc = WrappableString.make_array(long_desc)
       @default = default
       @flag_completion = create_flag_completion(flag_completion)
-      @value_completion = Completion.create(value_completion)
+      @value_completion = Completion.create(value_completion, **{})
       create_default_flag if @flag_syntax.empty?
       remove_used_flags(used_flags, report_collisions)
       canonicalize
@@ -373,14 +373,16 @@ module Toys
     end
 
     def create_flag_completion(spec)
-      case spec
-      when nil, :default
-        DefaultCompletion.new(self)
-      when ::Hash
-        DefaultCompletion.new(self, spec)
-      else
-        Completion.create(spec)
-      end
+      spec =
+        case spec
+        when nil, :default
+          {"": DefaultCompletion, flag: self}
+        when ::Hash
+          spec[:""].nil? ? spec.merge({"": DefaultCompletion, flag: self}) : spec
+        else
+          spec
+        end
+      Completion.create(spec, **{})
     end
 
     def create_default_flag
@@ -749,7 +751,7 @@ module Toys
       # @param include_long [Boolean] Whether to include long flags.
       # @param include_negative [Boolean] Whether to include `--no-*` forms.
       #
-      def initialize(flag, include_short: true, include_long: true, include_negative: true)
+      def initialize(flag:, include_short: true, include_long: true, include_negative: true)
         @flag = flag
         @include_short = include_short
         @include_long = include_long

data/lib/toys/loader.rb

@@ -134,8 +134,7 @@ module Toys
 
     ##
     # Given a list of command line arguments, find the appropriate tool to
-    # handle the command, loading it from the configuration if necessary, and
-    # following aliases.
+    # handle the command, loading it from the configuration if necessary.
     # This always returns a tool. If the specific tool path is not defined and
     # cannot be found in any configuration, it finds the nearest namespace that
     # *would* contain that tool, up to the root tool.
@@ -148,24 +147,35 @@ module Toys
     #
     def lookup(args)
       orig_prefix, args = find_orig_prefix(args)
-      cur_prefix = orig_prefix
+      prefix = orig_prefix
       loop do
-        load_for_prefix(cur_prefix)
-        prefix = orig_prefix
-        loop do
-          tool = get_active_tool(prefix, [])
-          if tool
-            finish_definitions_in_tree(tool.full_name)
-            return [tool, args.slice(prefix.length..-1)]
-          end
-          break if prefix.empty? || prefix.length <= cur_prefix.length
-          prefix = prefix.slice(0..-2)
-        end
-        raise "Unexpected error" if cur_prefix.empty?
-        cur_prefix = cur_prefix.slice(0..-2)
+        tool = lookup_specific(prefix)
+        return [tool, args.slice(prefix.length..-1)] if tool
+        prefix = prefix.slice(0..-2)
       end
     end
 
+    ##
+    # Given a tool name, looks up the specific tool, loading it from the
+    # configuration if necessary.
+    #
+    # If there is an active tool, returns it; otherwise, returns the highest
+    # priority tool that has been defined. If no tool has been defined with
+    # the given name, returns `nil`.
+    #
+    # @param words [Array<String>] The tool name
+    # @return [Toys::Tool] if the tool was found
+    # @return [nil] if no such tool exists
+    #
+    def lookup_specific(words)
+      words = 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
+      finish_definitions_in_tree(words) if tool
+      tool
+    end
+
     ##
     # Returns a list of subtools for the given path, loading from the
     # configuration if necessary.
@@ -175,8 +185,7 @@ module Toys
     #     rather than just the immediate children (the default)
     # @param include_hidden [Boolean] If true, include hidden subtools,
     #     e.g. names beginning with underscores.
-    # @return [Array<Toys::Tool,Toys::Alias>] An array of subtools, which may
-    #     be tools or aliases.
+    # @return [Array<Toys::Tool>] An array of subtools.
     #
     def list_subtools(words, recursive: false, include_hidden: false)
       load_for_prefix(words)
@@ -214,6 +223,19 @@ module Toys
       false
     end
 
+    ##
+    # Splits the given path using the delimiters configured in this Loader.
+    # You may pass in either an array of strings, or a single string possibly
+    # delimited by path separators. Always returns an array of strings.
+    #
+    # @param str [String,Array<String>] The path to split.
+    # @return [Array<String>]
+    #
+    def split_path(str)
+      return str if str.is_a?(::Array)
+      @extra_delimiters ? str.split(@extra_delimiters) : [str]
+    end
+
     ##
     # Returns the active tool specified by the given words, with the given
     # priority, without doing any loading. If the given priority matches the
@@ -225,7 +247,6 @@ module Toys
     # @param priority [Integer] The priority of the request.
     #
     # @return [Toys::Tool] The tool found.
-    # @return [Toys::Alias] The alias found.
     # @return [nil] if the given priority is insufficient.
     #
     # @private
@@ -239,53 +260,49 @@ module Toys
     end
 
     ##
-    # Sets the given name as an alias to the given target.
-    #
-    # @param words [Array<String>] The alias name
-    # @param target [Array<String>] The alias target name
-    # @param priority [Integer] The priority of the request
+    # Returns true if the given tool name currently exists in the loader.
+    # Does not load the tool if not found.
     #
-    # @return [Toys::Alias] The alias created
+    # @param words [Array<String>] The name of the tool.
+    # @return [Boolean]
     #
     # @private
     #
-    def make_alias(words, target, priority)
-      tool_data = get_tool_data(words)
-      if tool_data.definitions.key?(priority)
-        raise ToolDefinitionError,
-              "Cannot make #{words.inspect} an alias because it is already defined"
-      end
-      alias_def = Alias.new(self, words, target, priority)
-      tool_data.definitions[priority] = alias_def
-      activate_tool(words, priority)
-      alias_def
+    def tool_defined?(words)
+      @tool_data.key?(words)
     end
 
     ##
-    # Returns true if the given tool name currently exists in the loader.
-    # Does not load the tool if not found.
+    # Loads the subtree under the given prefix.
     #
-    # @param words [Array<String>] The name of the tool.
-    # @return [Boolean]
+    # @param prefix [Array<String>] The name prefix.
+    # @return [self]
     #
     # @private
     #
-    def tool_defined?(words)
-      @tool_data.key?(words)
+    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
     end
 
     ##
     # Get or create the tool definition for the given name and priority.
-    # May return either a tool or alias definition.
+    #
+    # @return [Toys::Tool]
     #
     # @private
     #
     def get_tool(words, priority)
       parent = words.empty? ? nil : get_tool(words.slice(0..-2), priority)
-      if parent.is_a?(Alias)
-        raise ToolDefinitionError,
-              "Cannot create children of #{parent.display_name.inspect} because it is an alias"
-      end
       tool_data = get_tool_data(words)
       if tool_data.top_priority.nil? || tool_data.top_priority < priority
         tool_data.top_priority = priority
@@ -377,54 +394,44 @@ module Toys
       @tool_data[words] ||= ToolData.new({}, nil, nil)
     end
 
-    ##
-    # Returns the current effective tool given a name. Resolves any aliases.
-    #
-    # If there is an active tool, returns it; otherwise, returns the highest
-    # priority tool that has been defined. If no tool has been defined with
-    # the given name, returns `nil`.
-    #
-    def get_active_tool(words, looked_up = [])
-      tool_data = get_tool_data(words)
-      result = tool_data.active_definition
-      case result
-      when Alias
-        resolve_alias(result, looked_up)
-      when Tool
-        result
-      else
-        tool_data.top_definition
+    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
-    end
-
-    ##
-    # Resolves the given alias
-    #
-    def resolve_alias(alias_tool, looked_up = [])
-      words = alias_tool.target_name
-      if looked_up.include?(words)
-        raise ToolDefinitionError, "Circular alias references: #{looked_up.inspect}"
+      if middleware.is_a?(::Class)
+        middleware = build_middleware(middleware, input)
       end
-      looked_up << words
-      get_active_tool(words, looked_up)
+      unless input.empty?
+        raise ::ArgumentError, "Unrecognized middleware arguments: #{input.inspect}"
+      end
+      middleware
     end
 
-    def resolve_middleware(input)
-      input = Array(input)
-      cls = input.first
-      args = input[1..-1]
-      if cls.is_a?(::String) || cls.is_a?(::Symbol)
-        cls = @middleware_lookup.lookup(cls)
-        if cls.nil?
-          raise ::ArgumentError, "Unrecognized middleware name #{input.first.inspect}"
-        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
-      if cls.is_a?(::Class)
-        cls.new(*args)
-      elsif !args.empty?
-        raise ::ArgumentError, "Unrecognized middleware object of class #{cls.class}"
+      # 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
-        cls
+        middleware_class.new(*args, **kwargs)
       end
     end
 
@@ -442,19 +449,6 @@ module Toys
       end
     end
 
-    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
-    end
-
     def load_proc(source, words, remaining_words, priority)
       if remaining_words
         tool_class = get_tool(words, priority).tool_class
@@ -548,11 +542,6 @@ module Toys
 
     def tool_hidden?(tool, next_tool)
       return true if tool.full_name.any? { |n| n.start_with?("_") }
-      if tool.is_a?(Alias)
-        original_tool = resolve_alias(tool)
-        return true if original_tool.nil?
-        return tool_hidden?(original_tool, nil)
-      end
       !tool.runnable? && next_tool && next_tool.full_name.slice(0..-2) == tool.full_name
     end