toys-core 0.14.6 → 0.15.0

data/lib/toys/standard_mixins/gems.rb

@@ -10,11 +10,24 @@ module Toys
     # tool DSL itself, so you can also ensure a gem is present when defining a
     # tool.
     #
-    # You may make these methods available to your tool by including the
-    # following directive in your tool configuration:
+    # ### Usage
+    #
+    # Make these methods available to your tool by including this mixin in your
+    # tool:
     #
     #     include :gems
     #
+    # You can then call the mixin method {#gem} to ensure that a gem is
+    # installed and in the load path. For example:
+    #
+    #     tool "my_tool" do
+    #       include :gems
+    #       gem "nokogiri", "~> 1.15"
+    #       def run
+    #         # Do stuff with Nokogiri
+    #       end
+    #     end
+    #
     # If you pass additional options to the include directive, those are used
     # to initialize settings for the gem install process. For example:
     #
@@ -34,7 +47,8 @@ module Toys
       end
 
       ##
-      # Activate the given gem.
+      # Activate the given gem. If it is not present, attempt to install it (or
+      # inform the user to update the bundle).
       #
       # @param name [String] Name of the gem
       # @param requirements [String...] Version requirements

data/lib/toys/standard_mixins/highline.rb

@@ -49,84 +49,84 @@ module Toys
       # Calls [HighLine#agree](https://www.rubydoc.info/gems/highline/HighLine:agree)
       #
       def agree(*args, &block)
-        highline.agree(*args, &block)
+        self[KEY].agree(*args, &block)
       end
 
       ##
       # Calls [HighLine#ask](https://www.rubydoc.info/gems/highline/HighLine:ask)
       #
       def ask(*args, &block)
-        highline.ask(*args, &block)
+        self[KEY].ask(*args, &block)
       end
 
       ##
       # Calls [HighLine#choose](https://www.rubydoc.info/gems/highline/HighLine:choose)
       #
       def choose(*args, &block)
-        highline.choose(*args, &block)
+        self[KEY].choose(*args, &block)
       end
 
       ##
       # Calls [HighLine#list](https://www.rubydoc.info/gems/highline/HighLine:list)
       #
       def list(*args, &block)
-        highline.list(*args, &block)
+        self[KEY].list(*args, &block)
       end
 
       ##
       # Calls [HighLine#say](https://www.rubydoc.info/gems/highline/HighLine:say)
       #
       def say(*args, &block)
-        highline.say(*args, &block)
+        self[KEY].say(*args, &block)
       end
 
       ##
       # Calls [HighLine#indent](https://www.rubydoc.info/gems/highline/HighLine:indent)
       #
       def indent(*args, &block)
-        highline.indent(*args, &block)
+        self[KEY].indent(*args, &block)
       end
 
       ##
       # Calls [HighLine#newline](https://www.rubydoc.info/gems/highline/HighLine:newline)
       #
       def newline
-        highline.newline
+        self[KEY].newline
       end
 
       ##
       # Calls [HighLine#puts](https://www.rubydoc.info/gems/highline/HighLine:puts)
       #
       def puts(*args)
-        highline.puts(*args)
+        self[KEY].puts(*args)
       end
 
       ##
       # Calls [HighLine#color](https://www.rubydoc.info/gems/highline/HighLine:color)
       #
       def color(*args)
-        highline.color(*args)
+        self[KEY].color(*args)
       end
 
       ##
       # Calls [HighLine#color_code](https://www.rubydoc.info/gems/highline/HighLine:color_code)
       #
       def color_code(*args)
-        highline.color_code(*args)
+        self[KEY].color_code(*args)
       end
 
       ##
       # Calls [HighLine#uncolor](https://www.rubydoc.info/gems/highline/HighLine:uncolor)
       #
       def uncolor(*args)
-        highline.uncolor(*args)
+        self[KEY].uncolor(*args)
       end
 
       ##
       # Calls [HighLine#new_scope](https://www.rubydoc.info/gems/highline/HighLine:new_scope)
       #
       def new_scope
-        highline.new_scope
+        self[KEY].new_scope
       end
 
       on_initialize do |*args|

data/lib/toys/standard_mixins/terminal.rb

@@ -54,7 +54,7 @@ module Toys
       # @return [self]
       #
       def puts(str = "", *styles)
-        terminal.puts(str, *styles)
+        self[KEY].puts(str, *styles)
         self
       end
       alias say puts
@@ -70,7 +70,7 @@ module Toys
       # @return [self]
       #
       def write(str = "", *styles)
-        terminal.write(str, *styles)
+        self[KEY].write(str, *styles)
         self
       end
 
@@ -89,7 +89,7 @@ module Toys
       # @return [String]
       #
       def ask(prompt, *styles, default: nil, trailing_text: :default)
-        terminal.ask(prompt, *styles, default: default, trailing_text: trailing_text)
+        self[KEY].ask(prompt, *styles, default: default, trailing_text: trailing_text)
       end
 
       ##
@@ -105,7 +105,7 @@ module Toys
       # @return [Boolean]
       #
       def confirm(prompt = "Proceed?", *styles, default: nil)
-        terminal.confirm(prompt, *styles, default: default)
+        self[KEY].confirm(prompt, *styles, default: default)
       end
 
       ##
@@ -130,9 +130,9 @@ module Toys
       #
       def spinner(leading_text: "", final_text: "",
                   frame_length: nil, frames: nil, style: nil, &block)
-        terminal.spinner(leading_text: leading_text, final_text: final_text,
-                         frame_length: frame_length, frames: frames, style: style,
-                         &block)
+        self[KEY].spinner(leading_text: leading_text, final_text: final_text,
+                          frame_length: frame_length, frames: frames, style: style,
+                          &block)
       end
 
       on_initialize do |**opts|

data/lib/toys/tool_definition.rb

@@ -18,12 +18,12 @@ module Toys
       ##
       # Create a completion given configuration options.
       #
-      # @param complete_subtools [Boolean] Whether to complete subtool names
-      # @param include_hidden_subtools [Boolean] Whether to include hidden
+      # @param complete_subtools [true,false] Whether to complete subtool names
+      # @param include_hidden_subtools [true,false] Whether to include hidden
       #     subtools (i.e. those beginning with an underscore)
-      # @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 complete_args [true,false] Whether to complete positional args
+      # @param complete_flags [true,false] Whether to complete flag names
+      # @param complete_flag_values [true,false] Whether to complete flag values
       # @param delegation_target [Array<String>,nil] Delegation target, or
       #     `nil` if none.
       #
@@ -41,7 +41,7 @@ module Toys
 
       ##
       # Whether to complete subtool names
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_subtools?
         @complete_subtools
@@ -49,7 +49,7 @@ module Toys
 
       ##
       # Whether to include hidden subtools
-      # @return [Boolean]
+      # @return [true,false]
       #
       def include_hidden_subtools?
         @include_hidden_subtools
@@ -57,7 +57,7 @@ module Toys
 
       ##
       # Whether to complete flags
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flags?
         @complete_flags
@@ -65,7 +65,7 @@ module Toys
 
       ##
       # Whether to complete positional args
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_args?
         @complete_args
@@ -73,7 +73,7 @@ module Toys
 
       ##
       # Whether to complete flag values
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flag_values?
         @complete_flag_values
@@ -205,7 +205,7 @@ module Toys
     #
     # The following settings are supported:
     #
-    #  *  `propagate_helper_methods` (_Boolean_) - Whether subtools should
+    #  *  `propagate_helper_methods` (_boolean_) - Whether subtools should
     #     inherit methods defined by parent tools. Defaults to `false`.
     #
     class Settings < ::Toys::Settings
@@ -273,7 +273,8 @@ module Toys
       @includes_modules = false
       @custom_context_directory = nil
 
-      @interrupt_handler = nil
+      @run_handler = :run
+      @signal_handlers = {}
       @usage_error_handler = nil
       @delegate_target = nil
 
@@ -454,19 +455,33 @@ module Toys
     attr_reader :completion
 
     ##
-    # The interrupt handler.
+    # The run handler.
     #
-    # @return [Proc] The interrupt handler proc
-    # @return [Symbol] The name of a method to call
-    # @return [nil] if there is no interrupt handler
+    # This handler is called to run the tool. Normally it is a method name,
+    # represented by a symbol. (The default is `:run`.) It can be set to a
+    # different method name, or to a proc that will be called with `self` set
+    # to the tool context. Either way, it takes no arguments. The run handler
+    # can also be explicitly set to `nil` indicating a non-runnable tool;
+    # however, typically a tool is made non-runnable simply by leaving the run
+    # handler set to `:run` and not defining the method.
     #
-    attr_reader :interrupt_handler
+    # @return [Proc] if the run handler is defined as a Proc
+    # @return [Symbol] if the run handler is defined as a method
+    # @return [nil] if the tool is explicitly made non-runnable
+    #
+    attr_reader :run_handler
 
     ##
     # The usage error handler.
     #
-    # @return [Proc] The usage error handler proc
-    # @return [Symbol] The name of a method to call
+    # This handler is called when at least one usage error is detected during
+    # argument parsing, and is called instead of the `run` method. It can be
+    # specified as a Proc, or a Symbol indicating a method to call. It
+    # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
+    # argument.
+    #
+    # @return [Proc] if the usage error handler is defined as a Proc
+    # @return [Symbol] if the user error handler is defined as a method
     # @return [nil] if there is no usage error handler
     #
     attr_reader :usage_error_handler
@@ -498,9 +513,37 @@ module Toys
       full_name.join(" ")
     end
 
+    ##
+    # Return the signal handler for the given signal.
+    #
+    # This handler is called when the given signal is received, immediately
+    # taking over the execution as if it were the new run handler. The signal
+    # handler can be specified as a Proc, or a Symbol indicating a method to
+    # call. It optionally takes the `SignalException` as the sole argument.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @return [Proc] if the signal handler is defined as a Proc
+    # @return [Symbol] if the signal handler is defined as a method
+    # @return [nil] if there is no handler for the given signal
+    #
+    def signal_handler(signal)
+      @signal_handlers[canonicalize_signal(signal)]
+    end
+
+    ##
+    # Return the interrupt handler. This is equivalent to `signal_handler(2)`.
+    #
+    # @return [Proc] if the interrupt signal handler is defined as a Proc
+    # @return [Symbol] if the interrupt signal handler is defined as a method
+    # @return [nil] if there is no handler for the interrupt signals
+    #
+    def interrupt_handler
+      signal_handler(2)
+    end
+
     ##
     # Returns true if this tool is a root tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def root?
       full_name.empty?
@@ -508,23 +551,38 @@ module Toys
 
     ##
     # Returns true if this tool is marked as runnable.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def runnable?
-      tool_class.public_instance_methods(false).include?(:run)
+      @run_handler.is_a?(::Symbol) &&
+        tool_class.public_instance_methods(false).include?(@run_handler) ||
+        @run_handler.is_a?(::Proc)
     end
 
     ##
-    # Returns true if this tool handles interrupts.
-    # @return [Boolean]
+    # Returns true if this tool handles interrupts. This is equivalent to
+    # `handles_signal?(2)`.
+    #
+    # @return [true,false]
     #
     def handles_interrupts?
-      !interrupt_handler.nil?
+      handles_signal?(2)
+    end
+
+    ##
+    # Returns true if this tool handles the given signal.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @return [true,false]
+    #
+    def handles_signal?(signal)
+      signal = canonicalize_signal(signal)
+      !@signal_handlers[signal].nil?
     end
 
     ##
     # Returns true if this tool handles usage errors.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def handles_usage_errors?
       !usage_error_handler.nil?
@@ -532,7 +590,7 @@ module Toys
 
     ##
     # Returns true if this tool has at least one included module.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_modules?
       @includes_modules
@@ -540,7 +598,7 @@ module Toys
 
     ##
     # Returns true if there is a specific description set for this tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_description?
       !long_desc.empty? || !desc.empty?
@@ -549,7 +607,7 @@ module Toys
     ##
     # Returns true if at least one flag or positional argument is defined
     # for this tool.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_arguments?
       !default_data.empty? || !flags.empty? ||
@@ -559,7 +617,7 @@ module Toys
 
     ##
     # Returns true if this tool has any definition information.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def includes_definition?
       includes_arguments? || runnable? || argument_parsing_disabled? ||
@@ -568,7 +626,7 @@ module Toys
 
     ##
     # Returns true if this tool's definition has been finished and is locked.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def definition_finished?
       @definition_finished
@@ -576,7 +634,7 @@ module Toys
 
     ##
     # Returns true if this tool has disabled argument parsing.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def argument_parsing_disabled?
       @disable_argument_parsing
@@ -584,7 +642,7 @@ module Toys
 
     ##
     # Returns true if this tool enforces flags before args.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def flags_before_args_enforced?
       @enforce_flags_before_args
@@ -592,7 +650,7 @@ module Toys
 
     ##
     # Returns true if this tool requires exact flag matches.
-    # @return [Boolean]
+    # @return [true,false]
     #
     def exact_flag_match_required?
       @require_exact_flag_match
@@ -867,7 +925,7 @@ module Toys
     # Enforce that flags must come before args for this tool.
     # You may disable enforcement by passoing `false` for the state.
     #
-    # @param state [Boolean]
+    # @param state [true,false]
     # @return [self]
     #
     def enforce_flags_before_args(state = true)
@@ -885,7 +943,7 @@ module Toys
     # Require that flags must match exactly. (If false, flags can match an
     # unambiguous substring.)
     #
-    # @param state [Boolean]
+    # @param state [true,false]
     # @return [self]
     #
     def require_exact_flag_match(state = true)
@@ -919,10 +977,10 @@ module Toys
     #     formats. Defaults to the empty array.
     # @param name [String,Symbol,nil] The name of the group, or nil for no
     #     name.
-    # @param report_collisions [Boolean] If `true`, raise an exception if a
+    # @param report_collisions [true,false] If `true`, raise an exception if a
     #     the given name is already taken. If `false`, ignore. Default is
     #     `true`.
-    # @param prepend [Boolean] If `true`, prepend rather than append the
+    # @param prepend [true,false] If `true`, prepend rather than append the
     #     group to the list. Default is `false`.
     # @return [self]
     #
@@ -977,7 +1035,7 @@ module Toys
     # @param complete_values [Object] A specifier for shell tab completion
     #     for flag values associated with this flag. Pass any spec
     #     recognized by {Toys::Completion.create}.
-    # @param report_collisions [Boolean] Raise an exception if a flag is
+    # @param report_collisions [true,false] Raise an exception if a flag is
     #     requested that is already in use or marked as disabled. Default is
     #     true.
     # @param group [Toys::FlagGroup,String,Symbol,nil] Group for
@@ -1147,33 +1205,65 @@ module Toys
     end
 
     ##
-    # Set the run handler block
+    # Set the run handler.
+    #
+    # This handler is called to run the tool. Normally it is a method name,
+    # represented by a symbol. (The default is `:run`.) It can be set to a
+    # different method name, or to a proc that will be called with `self` set
+    # to the tool context. Either way, it takes no arguments. The run handler
+    # can also be explicitly set to `nil` indicating a non-runnable tool;
+    # however, typically a tool is made non-runnable simply by leaving the run
+    # handler set to `:run` and not defining the method.
     #
-    # @param proc [Proc] The runnable block
+    # @param handler [Proc,Symbol,nil] the run handler
     #
-    def run_handler=(proc)
+    def run_handler=(handler)
       check_definition_state(is_method: true)
-      tool_class.class_eval do
-        define_method(:run, &proc)
+      if !handler.is_a?(::Proc) && !handler.is_a?(::Symbol) && !handler.nil?
+        raise ToolDefinitionError, "Run handler must be a proc or symbol"
       end
+      @run_handler = handler
     end
 
     ##
-    # Set the interrupt handler.
+    # Set the interrupt handler. This is equivalent to calling
+    # {#set_signal_handler} for the `SIGINT` signal.
     #
-    # @param handler [Proc,Symbol] The interrupt handler
+    # @param handler [Proc,Symbol] The interrupt signal handler
     #
     def interrupt_handler=(handler)
+      set_signal_handler(2, handler)
+    end
+
+    ##
+    # Set the handler for the given signal.
+    #
+    # This handler is called when the given signal is received, immediately
+    # taking over the execution as if it were the new `run` method. The signal
+    # handler can be specified as a Proc, or a Symbol indicating a method to
+    # call. It optionally takes the `SignalException` as the sole argument.
+    #
+    # @param signal [Integer,String,Symbol] The signal number or name
+    # @param handler [Proc,Symbol] The signal handler
+    #
+    def set_signal_handler(signal, handler)
       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"
+        raise ToolDefinitionError, "Signal handler must be a proc or symbol"
       end
-      @interrupt_handler = handler
+      signal = canonicalize_signal(signal)
+      @signal_handlers[signal] = handler
     end
 
     ##
     # Set the usage error handler.
     #
+    # This handler is called when at least one usage error is detected during
+    # argument parsing, and is called instead of the `run` method. It can be
+    # specified as a Proc, or a Symbol indicating a method to call. It
+    # optionally takes an array of {Toys::ArgParser::UsageError} as the sole
+    # argument.
+    #
     # @param handler [Proc,Symbol] The usage error handler
     #
     def usage_error_handler=(handler)
@@ -1374,14 +1464,14 @@ module Toys
           name = walk_context[::Toys::Context::Key::TOOL_NAME]
           path << name.join(" ").inspect
           if name == target
-            raise "Delegation loop: #{path.join(' <- ')}"
+            raise ToolDefinitionError, "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(' ')}\""
+          raise ToolDefinitionError, "Delegate target not found: \"#{target.join(' ')}\""
         end
         exit(cli.run(target + self[::Toys::Context::Key::ARGS], delegated_from: self))
       end
@@ -1400,5 +1490,18 @@ module Toys
       raise ToolDefinitionError, "Unknown completion: #{name.inspect}" if completion.nil?
       completion
     end
+
+    def canonicalize_signal(signal)
+      case signal
+      when ::String, ::Symbol
+        sigstr = signal.to_s
+        sigstr = sigstr[3..-1] if sigstr.start_with?("SIG")
+        signo = ::Signal.list[sigstr]
+        return signo if signo
+      when ::Integer
+        return signal if ::Signal.signame(signal)
+      end
+      raise ::ArgumentError, "Unknown signal: #{signal}"
+    end
   end
 end

data/lib/toys/utils/exec.rb

@@ -16,6 +16,27 @@ module Toys
     # This class is not loaded by default. Before using it directly, you should
     # `require "toys/utils/exec"`
     #
+    # ### The exec service
+    #
+    # The main entrypoint class is this one, {Toys::Utils::Exec}. It's a
+    # "service" object that provides functionality, primarily methods that
+    # spawn processes. Create it like any object:
+    #
+    #     require "toys/utils/exec"
+    #     exec_service = Toys::Utils::Exec.new
+    #
+    # There are two "primitive" functions: {#exec} and {#exec_proc}. The {#exec}
+    # method spawns an operating system process specified by an executable and
+    # a set of arguments. The {#exec_proc} method takes a `Proc` and forks a
+    # Ruby process. Both of these can be heavily configured with stream
+    # handling, result handling, and numerous other options described below.
+    # The class also provides convenience methods for common cases such as
+    # spawning a Ruby process, spawning a shell script, or capturing output.
+    #
+    # The exec service class also stores default configuration that it applies
+    # to processes it spawns. You can set these defaults when constructing the
+    # service class, or at any time by calling {#configure_defaults}.
+    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -24,7 +45,7 @@ module Toys
     # If you start a background process, its streams will be redirected to null
     # by default, and control will be returned to you immediately.
     #
-    # When a process is running, you can control it using a
+    # While a process is running, you can control it using a
     # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
     # the process's input and output streams, send it signals, or wait for it
     # to complete.

data/lib/toys/utils/gems.rb

@@ -304,6 +304,9 @@ module Toys
       end
 
       def setup_bundle(gemfile_path, groups: nil, retries: nil)
+        # Lock the bundler version, preventing bundler's SelfManager from
+        # installing a different bundler and taking over the process.
+        ::ENV["BUNDLER_VERSION"] = ::Bundler::VERSION
         check_gemfile_compatibility(gemfile_path)
         groups = Array(groups)
         modified_gemfile_path = create_modified_gemfile(gemfile_path)