toys-core 0.14.7 → 0.15.1

data/lib/toys/tool_definition.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "set"
-
 module Toys
   ##
   # A ToolDefinition describes a single command that can be invoked using Toys.
@@ -18,12 +16,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 +39,7 @@ module Toys
 
       ##
       # Whether to complete subtool names
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_subtools?
         @complete_subtools
@@ -49,7 +47,7 @@ module Toys
 
       ##
       # Whether to include hidden subtools
-      # @return [Boolean]
+      # @return [true,false]
       #
       def include_hidden_subtools?
         @include_hidden_subtools
@@ -57,7 +55,7 @@ module Toys
 
       ##
       # Whether to complete flags
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flags?
         @complete_flags
@@ -65,7 +63,7 @@ module Toys
 
       ##
       # Whether to complete positional args
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_args?
         @complete_args
@@ -73,7 +71,7 @@ module Toys
 
       ##
       # Whether to complete flag values
-      # @return [Boolean]
+      # @return [true,false]
       #
       def complete_flag_values?
         @complete_flag_values
@@ -205,7 +203,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 +271,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
 
@@ -283,7 +282,7 @@ module Toys
     ##
     # Settings for this tool
     #
-    # @return [Toys::Tool::Settings]
+    # @return [Toys::ToolDefinition::Settings]
     #
     attr_reader :settings
 
@@ -454,19 +453,33 @@ module Toys
     attr_reader :completion
 
     ##
-    # The interrupt handler.
+    # 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.
     #
-    # @return [Proc] The interrupt handler proc
-    # @return [Symbol] The name of a method to call
-    # @return [nil] if there is no 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 :interrupt_handler
+    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 +511,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 +549,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 +588,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 +596,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 +605,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 +615,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 +624,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 +632,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 +640,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 +648,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 +923,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 +941,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 +975,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 +1033,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 +1203,65 @@ module Toys
     end
 
     ##
-    # Set the run handler block
+    # Set the run handler.
     #
-    # @param proc [Proc] The runnable block
+    # 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.
     #
-    def run_handler=(proc)
+    # @param handler [Proc,Symbol,nil] the run handler
+    #
+    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 +1462,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 +1488,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/completion_engine.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "shellwords"
-
 module Toys
   module Utils
     ##
@@ -21,6 +19,7 @@ module Toys
         # @param cli [Toys::CLI] The CLI.
         #
         def initialize(cli)
+          require "shellwords"
           @cli = cli
         end
 

data/lib/toys/utils/exec.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require "rbconfig"
-require "logger"
-require "shellwords"
-
 module Toys
   module Utils
     ##
@@ -16,6 +12,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 +41,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.
@@ -245,6 +262,9 @@ module Toys
       #     for a description of the options.
       #
       def initialize(**opts, &block)
+        require "rbconfig"
+        require "logger"
+        require "stringio"
         @default_opts = Opts.new(&block).add(opts)
       end
 

data/lib/toys/utils/gems.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "monitor"
-require "rubygems"
 
 module Toys
   module Utils
@@ -123,6 +122,7 @@ module Toys
                      output: nil,
                      suppress_confirm: nil,
                      default_confirm: nil)
+        require "rubygems"
         @default_confirm = default_confirm || default_confirm.nil? ? true : false
         @on_missing = on_missing ||
                       if suppress_confirm
@@ -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)

data/lib/toys/utils/git_cache.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 
-require "digest"
-require "fileutils"
-require "json"
-require "toys/compat"
-require "toys/utils/exec"
-require "toys/utils/xdg"
-
 module Toys
   module Utils
     ##
@@ -288,6 +281,11 @@ module Toys
       #     a specific directory in the user's XDG cache.
       #
       def initialize(cache_dir: nil)
+        require "digest"
+        require "fileutils"
+        require "json"
+        require "toys/compat"
+        require "toys/utils/exec"
         @cache_dir = ::File.expand_path(cache_dir || default_cache_dir)
         @exec = Utils::Exec.new(out: :capture, err: :capture)
       end
@@ -485,6 +483,7 @@ module Toys
       end
 
       def default_cache_dir
+        require "toys/utils/xdg"
         ::File.join(XDG.new.cache_home, "toys", "git")
       end
 

data/lib/toys/utils/help_text.rb

@@ -351,6 +351,7 @@ module Toys
         def initialize(tool, executable_name, delegates, subtools, search_term,
                        show_source_path, separate_sources, indent, indent2, wrap_width, styled)
           require "toys/utils/terminal"
+          require "stringio"
           @tool = tool
           @executable_name = executable_name
           @delegates = delegates
@@ -667,6 +668,7 @@ module Toys
         def initialize(tool, subtools, recursive, search_term, separate_sources,
                        indent, wrap_width, styled)
           require "toys/utils/terminal"
+          require "stringio"
           @tool = tool
           @subtools = subtools
           @recursive = recursive

data/lib/toys/utils/pager.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "toys/utils/exec"
-
 module Toys
   module Utils
     ##
@@ -150,7 +148,10 @@ module Toys
         # @private
         #
         def default_exec_service
-          @default_exec_service ||= Exec.new
+          @default_exec_service ||= begin
+            require "toys/utils/exec"
+            Utils::Exec.new
+          end
         end
       end
     end