toys-core 0.8.1 → 0.9.0

data/lib/toys/positional_arg.rb

@@ -37,7 +37,7 @@ module Toys
       @type = type
       @acceptor = Acceptor.create(acceptor)
       @default = default
-      @completion = Completion.create(completion)
+      @completion = Completion.create(completion, **{})
       @desc = WrappableString.make(desc)
       @long_desc = WrappableString.make_array(long_desc)
       @display_name = display_name || key.to_s.tr("-", "_").gsub(/\W/, "").upcase

data/lib/toys/standard_middleware/set_default_descriptions.rb

@@ -40,6 +40,12 @@ module Toys
       #
       DEFAULT_TOOL_DESC = "(No tool description available)"
 
+      ##
+      # The default description for delegating tools.
+      # @return [String]
+      #
+      DEFAULT_DELEGATE_DESC = '(Delegates to "%<target>s")'
+
       ##
       # The default description for namespaces.
       # @return [String]
@@ -58,7 +64,7 @@ module Toys
       #
       DEFAULT_ROOT_LONG_DESC = [
         "This command line tool was built using the toys-core gem. See" \
-          " https://www.rubydoc.info/gems/toys-core for more info.",
+          " https://dazuma.github.io/toys/gems/toys-core for more info.",
         "To replace this message, set the description and long description" \
           " of the root tool, or configure the SetDefaultDescriptions" \
           " middleware.",
@@ -70,33 +76,39 @@ module Toys
       # @param default_tool_desc [String,nil] The default short description for
       #     runnable tools, or `nil` not to set one. Defaults to
       #     {DEFAULT_TOOL_DESC}.
-      # @param default_tool_long_desc [String,nil] The default long description
-      #     for runnable tools, or `nil` not to set one. Defaults to `nil`.
+      # @param default_tool_long_desc [Array<String>,nil] The default long
+      #     description for runnable tools, or `nil` not to set one. Defaults
+      #     to `nil`.
       # @param default_namespace_desc [String,nil] The default short
       #     description for non-runnable tools, or `nil` not to set one.
       #     Defaults to {DEFAULT_TOOL_DESC}.
-      # @param default_namespace_long_desc [String,nil] The default long
+      # @param default_namespace_long_desc [Array<String>,nil] The default long
       #     description for non-runnable tools, or `nil` not to set one.
       #     Defaults to `nil`.
       # @param default_root_desc [String,nil] The default short description for
       #     the root tool, or `nil` not to set one. Defaults to
       #     {DEFAULT_ROOT_DESC}.
-      # @param default_root_long_desc [String,nil] The default long description
-      #     for the root tool, or `nil` not to set one. Defaults to
+      # @param default_root_long_desc [Array<String>,nil] The default long
+      #     description for the root tool, or `nil` not to set one. Defaults to
       #     {DEFAULT_ROOT_LONG_DESC}.
+      # @param default_delegate_desc [String,nil] The default short description
+      #     for delegate tools, or `nil` not to set one. May include an sprintf
+      #     field for the `target` name. Defaults to {DEFAULT_DELEGATE_DESC}.
       #
       def initialize(default_tool_desc: DEFAULT_TOOL_DESC,
                      default_tool_long_desc: nil,
                      default_namespace_desc: DEFAULT_NAMESPACE_DESC,
                      default_namespace_long_desc: nil,
                      default_root_desc: DEFAULT_ROOT_DESC,
-                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC)
+                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
+                     default_delegate_desc: DEFAULT_DELEGATE_DESC)
         @default_tool_desc = default_tool_desc
         @default_tool_long_desc = default_tool_long_desc
         @default_namespace_desc = default_namespace_desc
         @default_namespace_long_desc = default_namespace_long_desc
         @default_root_desc = default_root_desc
         @default_root_long_desc = default_root_long_desc
+        @default_delegate_desc = default_delegate_desc
       end
 
       ##
@@ -137,6 +149,9 @@ module Toys
       def generate_tool_desc(tool, data)
         if tool.root?
           @default_root_desc
+        elsif tool.delegate_target
+          params = {target: tool.delegate_target.join(" ")}
+          format(@default_delegate_desc, params)
         elsif !tool.runnable? && data[:loader].has_subtools?(tool.full_name)
           @default_namespace_desc
         else

data/lib/toys/standard_middleware/show_help.rb

@@ -216,7 +216,7 @@ module Toys
         @show_source_path = show_source_path
         @stream = stream
         @styled_output = styled_output
-        @use_less = use_less
+        @use_less = use_less && !Compat::IS_JRUBY
       end
 
       ##
@@ -294,7 +294,7 @@ module Toys
           include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], show_source_path: @show_source_path,
           wrap_width: terminal.width
         )
-        if RUBY_PLATFORM != "java" && less_path
+        if less_path
           require "toys/utils/exec"
           Utils::Exec.new.exec([less_path, "-R"], in: [:string, str])
         else
@@ -333,7 +333,7 @@ module Toys
         dict = loader.list_subtools(tool_name).map(&:simple_name)
         suggestions = Compat.suggestions(next_word, dict)
         tool_name = (tool_name + [next_word]).join(" ")
-        message = "Tool not found: \"#{tool_name}\"."
+        message = "Tool not found: \"#{tool_name}\""
         unless suggestions.empty?
           suggestions_str = suggestions.join("\n                 ")
           message = "#{message}\nDid you mean...  #{suggestions_str}"

data/lib/toys/standard_mixins/exec.rb

@@ -82,6 +82,10 @@ module Toys
     #
     #         include :exec, exit_on_nonzero_status: true
     #
+    #     **:e** can be used as a shortcut for **:exit_on_nonzero_status**
+    #
+    #         include :exec, e: true
+    #
     module Exec
       include Mixin
 
@@ -343,25 +347,38 @@ module Toys
 
       ## @private
       def self._setup_exec_opts(opts, context)
-        if opts.key?(:exit_on_nonzero_status)
-          result_callback =
-            if opts[:exit_on_nonzero_status]
-              proc { |r| context.exit(r.exit_code) if r.error? }
-            end
-          opts = opts.merge(result_callback: result_callback)
-          opts.delete(:exit_on_nonzero_status)
-        elsif opts.key?(:result_callback)
-          orig_callback = opts[:result_callback]
-          result_callback =
-            if orig_callback.is_a?(::Symbol)
-              context.method(orig_callback)
-            elsif orig_callback.respond_to?(:call)
-              proc { |r| orig_callback.call(r, context) }
-            end
-          opts = opts.merge(result_callback: result_callback)
+        if opts.key?(:result_callback)
+          opts = _setup_result_callback_option(opts, context)
+        end
+        if opts.key?(:exit_on_nonzero_status) || opts.key?(:e)
+          opts = _setup_e_option(opts, context)
         end
         opts
       end
+
+      ## @private
+      def self._setup_e_option(opts, context)
+        result_callback =
+          if opts[:exit_on_nonzero_status] || opts[:e]
+            proc { |r| context.exit(r.exit_code) if r.error? }
+          end
+        opts = opts.merge(result_callback: result_callback)
+        opts.delete(:exit_on_nonzero_status)
+        opts.delete(:e)
+        opts
+      end
+
+      ## @private
+      def self._setup_result_callback_option(opts, context)
+        orig_callback = opts[:result_callback]
+        result_callback =
+          if orig_callback.is_a?(::Symbol)
+            context.method(orig_callback)
+          elsif orig_callback.respond_to?(:call)
+            proc { |r| orig_callback.call(r, context) }
+          end
+        opts.merge(result_callback: result_callback)
+      end
     end
   end
 end

data/lib/toys/standard_mixins/gems.rb

@@ -54,7 +54,7 @@ module Toys
         def self.gems
           require "toys/utils/gems"
           # rubocop:disable Naming/MemoizedInstanceVariableName
-          @__gems ||= Utils::Gems.new(@__gems_opts)
+          @__gems ||= Utils::Gems.new(**@__gems_opts)
           # rubocop:enable Naming/MemoizedInstanceVariableName
         end
 

data/lib/toys/standard_mixins/terminal.rb

@@ -58,7 +58,7 @@ module Toys
 
       on_initialize do |opts = {}|
         require "toys/utils/terminal"
-        self[KEY] = Utils::Terminal.new(opts)
+        self[KEY] = Utils::Terminal.new(**opts)
       end
 
       ##

data/lib/toys/tool.rb

@@ -87,6 +87,7 @@ module Toys
 
       @interrupt_handler = nil
       @usage_error_handler = nil
+      @delegate_target = nil
 
       @completion = DefaultCompletion.new
     end
@@ -259,6 +260,14 @@ module Toys
     #
     attr_reader :usage_error_handler
 
+    ##
+    # The full name of the delegate target, if any.
+    #
+    # @return [Array<String>] if this tool delegates
+    # @return [nil] if this tool does not delegate
+    #
+    attr_reader :delegate_target
+
     ##
     # The local name of this tool, i.e. the last element of the full name.
     #
@@ -587,7 +596,7 @@ module Toys
               "A completion named #{name.inspect} has already been defined in tool" \
               " #{display_name.inspect}."
       end
-      @completions[name] = Toys::Completion.create(completion, options, &block)
+      @completions[name] = Toys::Completion.create(completion, **options, &block)
       self
     end
 
@@ -916,7 +925,7 @@ module Toys
     # @param proc [Proc] The runnable block
     #
     def run_handler=(proc)
-      check_definition_state
+      check_definition_state(is_method: true)
       @tool_class.to_run(&proc)
     end
 
@@ -926,7 +935,7 @@ module Toys
     # @param handler [Proc,Symbol] The interrupt handler
     #
     def interrupt_handler=(handler)
-      check_definition_state
+      check_definition_state(is_method: true)
       if !handler.is_a?(::Proc) && !handler.is_a?(::Symbol) && !handler.nil?
         raise ToolDefinitionError, "Interrupt handler must be a proc or symbol"
       end
@@ -939,7 +948,7 @@ module Toys
     # @param handler [Proc,Symbol] The usage error handler
     #
     def usage_error_handler=(handler)
-      check_definition_state
+      check_definition_state(is_method: true)
       if !handler.is_a?(::Proc) && !handler.is_a?(::Symbol) && !handler.nil?
         raise ToolDefinitionError, "Usage error handler must be a proc or symbol"
       end
@@ -979,15 +988,17 @@ module Toys
     # @param spec [Object]
     #
     def completion=(spec)
-      @completion =
+      spec = resolve_completion_name(spec)
+      spec =
         case spec
         when nil, :default
-          DefaultCompletion.new
+          DefaultCompletion
         when ::Hash
-          DefaultCompletion.new(spec)
+          spec[:""].nil? ? spec.merge({"": DefaultCompletion}) : spec
         else
-          Completion.create(spec)
+          spec
         end
+      @completion = Completion.create(spec, **{})
     end
 
     ##
@@ -1005,6 +1016,35 @@ module Toys
       lookup_custom_context_directory || source_info&.context_directory
     end
 
+    ##
+    # Causes this tool to delegate to another tool.
+    #
+    # @param target [Array<String>] The full path to the delegate tool.
+    # @return [self]
+    #
+    def delegate_to(target)
+      if @delegate_target
+        raise ToolDefinitionError,
+              "Cannot delegate tool #{display_name.inspect} because" \
+              " it already delegates to \"#{@delegate_target.join(' ')}\"."
+      end
+      if includes_arguments?
+        raise ToolDefinitionError,
+              "Cannot delegate tool #{display_name.inspect} because" \
+              " arguments have already been defined."
+      end
+      if runnable?
+        raise ToolDefinitionError,
+              "Cannot delegate tool #{display_name.inspect} because" \
+              " the run method has already been defined."
+      end
+      disable_argument_parsing
+      self.run_handler = make_delegation_run_handler(target)
+      self.completion = DefaultCompletion.new(delegation_target: target)
+      @delegate_target = target
+      self
+    end
+
     ##
     # Lookup the custom context directory in this tool and its ancestors.
     # @private
@@ -1013,20 +1053,6 @@ module Toys
       custom_context_directory || @parent&.lookup_custom_context_directory
     end
 
-    ## @private
-    def scalar_acceptor(spec = nil, type_desc: nil, &block)
-      Acceptor.create(resolve_acceptor_name(spec), type_desc: type_desc, &block)
-    end
-
-    ## @private
-    def scalar_completion(spec = nil, **options, &block)
-      if spec.nil? && block.nil? || spec == :default
-        options
-      else
-        Completion.create(resolve_completion_name(spec), options, &block)
-      end
-    end
-
     ##
     # Mark this tool as having at least one module included.
     # @private
@@ -1074,7 +1100,7 @@ module Toys
     # or from the DSL only.
     # @private
     #
-    def check_definition_state(is_arg: false)
+    def check_definition_state(is_arg: false, is_method: false)
       if @definition_finished
         raise ToolDefinitionError,
               "Defintion of tool #{display_name.inspect} is already finished"
@@ -1083,6 +1109,10 @@ module Toys
         raise ToolDefinitionError,
               "Tool #{display_name.inspect} has disabled argument parsing"
       end
+      if (is_arg || is_method) && delegate_target
+        raise ToolDefinitionError,
+              "Tool #{display_name.inspect} is already delegating to another tool"
+      end
       self
     end
 
@@ -1099,14 +1129,18 @@ module Toys
       # @param complete_args [Boolean] Whether to complete positional args
       # @param complete_flags [Boolean] Whether to complete flag names
       # @param complete_flag_values [Boolean] Whether to complete flag values
+      # @param delegation_target [Array<String>,nil] Delegation target, or
+      #     `nil` if none.
       #
       def initialize(complete_subtools: true, include_hidden_subtools: false,
-                     complete_args: true, complete_flags: true, complete_flag_values: true)
+                     complete_args: true, complete_flags: true, complete_flag_values: true,
+                     delegation_target: nil)
         @complete_subtools = complete_subtools
         @include_hidden_subtools = include_hidden_subtools
         @complete_flags = complete_flags
         @complete_args = complete_args
         @complete_flag_values = complete_flag_values
+        @delegation_target = delegation_target
       end
 
       ##
@@ -1149,6 +1183,13 @@ module Toys
         @complete_flag_values
       end
 
+      ##
+      # Delegation target, or nil for none.
+      # @return [Array<String>] if there is a delegation target
+      # @return [nil] if there is no delegation target
+      #
+      attr_accessor :delegation_target
+
       ##
       # Returns candidates for the current completion.
       #
@@ -1162,6 +1203,13 @@ module Toys
         candidates = subtool_or_arg_candidates(context)
         candidates += plain_flag_candidates(context)
         candidates += flag_value_candidates(context)
+        if delegation_target
+          delegate_tool = context.cli.loader.lookup_specific(delegation_target)
+          if delegate_tool
+            context = context.with(previous_words: delegation_target)
+            candidates += delegate_tool.completion.call(context)
+          end
+        end
         candidates
       end
 
@@ -1260,6 +1308,27 @@ module Toys
       proc { middleware.config(self, loader, &next_config) }
     end
 
+    def make_delegation_run_handler(target)
+      lambda do
+        path = [target.join(" ").inspect]
+        walk_context = self
+        until walk_context.nil?
+          name = walk_context[::Toys::Context::Key::TOOL_NAME]
+          path << name.join(" ").inspect
+          if name == target
+            raise "Delegation loop: #{path.join(' <- ')}"
+          end
+          walk_context = walk_context[::Toys::Context::Key::DELEGATED_FROM]
+        end
+        cli = self[::Toys::Context::Key::CLI]
+        cli.loader.load_for_prefix(target)
+        unless cli.loader.tool_defined?(target)
+          raise "Delegate target not found: \"#{target.join(' ')}\""
+        end
+        exit(cli.run(target + self[::Toys::Context::Key::ARGS], delegated_from: self))
+      end
+    end
+
     def resolve_acceptor_name(name)
       return name unless name.is_a?(::String)
       accept = lookup_acceptor(name)

data/lib/toys/utils/help_text.rb

@@ -53,8 +53,14 @@ module Toys
       # @return [Toys::Utils::HelpText]
       #
       def self.from_context(context)
+        orig_context = context
+        while (from = context[Context::Key::DELEGATED_FROM])
+          context = from
+        end
+        delegate_target = orig_context == context ? nil : orig_context[Context::Key::TOOL_NAME]
         cli = context[Context::Key::CLI]
-        new(context[Context::Key::TOOL], cli.loader, cli.executable_name)
+        new(context[Context::Key::TOOL], cli.loader, cli.executable_name,
+            delegate_target: delegate_target)
       end
 
       ##
@@ -64,13 +70,16 @@ module Toys
       # @param loader [Toys::Loader] A loader that can provide subcommands.
       # @param executable_name [String] The name of the executable.
       #     e.g. `"toys"`.
+      # @param delegate_target [Array<String>,nil] The full name of a tool this
+      #     tool will delegate to. Default is `nil` for no delegation.
       #
       # @return [Toys::Utils::HelpText]
       #
-      def initialize(tool, loader, executable_name)
+      def initialize(tool, loader, executable_name, delegate_target: nil)
         @tool = tool
         @loader = loader
         @executable_name = executable_name
+        @delegate_target = delegate_target
       end
 
       ##
@@ -99,8 +108,10 @@ module Toys
         left_column_width ||= DEFAULT_LEFT_COLUMN_WIDTH
         indent ||= DEFAULT_INDENT
         subtools = find_subtools(recursive, nil, include_hidden)
-        assembler = UsageStringAssembler.new(@tool, @executable_name, subtools,
-                                             indent, left_column_width, wrap_width)
+        assembler = UsageStringAssembler.new(
+          @tool, @executable_name, @delegate_target, subtools,
+          indent, left_column_width, wrap_width
+        )
         assembler.result
       end
 
@@ -130,8 +141,10 @@ module Toys
         indent ||= DEFAULT_INDENT
         indent2 ||= DEFAULT_INDENT
         subtools = find_subtools(recursive, search, include_hidden)
-        assembler = HelpStringAssembler.new(@tool, @executable_name, subtools, search,
-                                            show_source_path, indent, indent2, wrap_width, styled)
+        assembler = HelpStringAssembler.new(
+          @tool, @executable_name, @delegate_target, subtools, search, show_source_path,
+          indent, indent2, wrap_width, styled
+        )
         assembler.result
       end
 
@@ -174,10 +187,11 @@ module Toys
 
       ## @private
       class UsageStringAssembler
-        def initialize(tool, executable_name, subtools,
+        def initialize(tool, executable_name, delegate_target, subtools,
                        indent, left_column_width, wrap_width)
           @tool = tool
           @executable_name = executable_name
+          @delegate_target = delegate_target
           @subtools = subtools
           @indent = indent
           @left_column_width = left_column_width
@@ -201,9 +215,8 @@ module Toys
 
         def add_synopsis_section
           synopses = []
-          synopses << namespace_synopsis if !@subtools.empty? && !@tool.runnable?
-          synopses << tool_synopsis
-          synopses << namespace_synopsis if !@subtools.empty? && @tool.runnable?
+          synopses << namespace_synopsis unless @subtools.empty?
+          synopses << (@delegate_target ? delegate_synopsis : tool_synopsis)
           first = true
           synopses.each do |synopsis|
             @lines << (first ? "Usage:  #{synopsis}" : "        #{synopsis}")
@@ -220,8 +233,13 @@ module Toys
           synopsis.join(" ")
         end
 
+        def delegate_synopsis
+          target = @delegate_target.join(" ")
+          "#{@executable_name} #{@tool.display_name} [ARGUMENTS FOR \"#{target}\"...]"
+        end
+
         def namespace_synopsis
-          ([@executable_name] + @tool.full_name + ["TOOL", "[ARGUMENTS...]"]).join(" ")
+          "#{@executable_name} #{@tool.display_name} TOOL [ARGUMENTS...]"
         end
 
         def add_flag_group_sections
@@ -264,13 +282,7 @@ module Toys
           @lines << "Tools:"
           @subtools.each do |subtool|
             tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            desc =
-              if subtool.is_a?(Alias)
-                ["(Alias of #{subtool.display_target})"]
-              else
-                wrap_desc(subtool.desc)
-              end
-            add_right_column_desc(tool_name, desc)
+            add_right_column_desc(tool_name, wrap_desc(subtool.desc))
           end
         end
 
@@ -310,11 +322,12 @@ module Toys
 
       ## @private
       class HelpStringAssembler
-        def initialize(tool, executable_name, subtools, search_term, show_source_path,
-                       indent, indent2, wrap_width, styled)
+        def initialize(tool, executable_name, delegate_target, subtools, search_term,
+                       show_source_path, indent, indent2, wrap_width, styled)
           require "toys/utils/terminal"
           @tool = tool
           @executable_name = executable_name
+          @delegate_target = delegate_target
           @subtools = subtools
           @search_term = search_term
           @show_source_path = show_source_path
@@ -363,9 +376,8 @@ module Toys
         def add_synopsis_section
           @lines << ""
           @lines << bold("SYNOPSIS")
-          add_synopsis_clause(namespace_synopsis) if !@subtools.empty? && !@tool.runnable?
-          add_synopsis_clause(tool_synopsis)
-          add_synopsis_clause(namespace_synopsis) if !@subtools.empty? && @tool.runnable?
+          add_synopsis_clause(namespace_synopsis) unless @subtools.empty?
+          add_synopsis_clause(@delegate_target ? delegate_synopsis : tool_synopsis)
         end
 
         def add_synopsis_clause(synopsis)
@@ -454,6 +466,13 @@ module Toys
           wrap_indent_indent2(WrappableString.new(synopsis))
         end
 
+        def delegate_synopsis
+          target = @delegate_target.join(" ")
+          args_clause = underline("ARGUMENTS FOR \"#{target}\"")
+          synopsis = [full_executable_name, "[#{args_clause}...]"]
+          wrap_indent_indent2(WrappableString.new(synopsis))
+        end
+
         def full_executable_name
           bold(([@executable_name] + @tool.full_name).join(" "))
         end
@@ -466,7 +485,13 @@ module Toys
         end
 
         def add_description_section
-          desc = wrap_indent(@tool.long_desc)
+          desc = @tool.long_desc
+          if @delegate_target
+            delegate_clause =
+              "Passes all arguments to \"#{@delegate_target.join(' ')}\" if invoked directly."
+            desc = desc.empty? ? [delegate_clause] : desc + ["", delegate_clause]
+          end
+          desc = wrap_indent(desc)
           return if desc.empty?
           @lines << ""
           @lines << bold("DESCRIPTION")
@@ -532,13 +557,7 @@ module Toys
           name_len = @tool.full_name.length
           @subtools.each do |subtool|
             tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            desc =
-              if subtool.is_a?(Alias)
-                "(Alias of #{subtool.display_target})"
-              else
-                subtool.desc
-              end
-            add_prefix_with_desc(bold(tool_name), desc)
+            add_prefix_with_desc(bold(tool_name), subtool.desc)
           end
         end
 
@@ -642,13 +661,7 @@ module Toys
           name_len = @tool.full_name.length
           @subtools.each do |subtool|
             tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            desc =
-              if subtool.is_a?(Alias)
-                "(Alias of #{subtool.display_target})"
-              else
-                subtool.desc
-              end
-            add_prefix_with_desc(bold(tool_name), desc)
+            add_prefix_with_desc(bold(tool_name), subtool.desc)
           end
         end