toys-core 0.14.7 → 0.15.0

data/lib/toys/cli.rb

@@ -72,7 +72,7 @@ module Toys
     #      *  `preload_dir_name`: Name of preload directories in tool directories
     #      *  `data_dir_name`: Name of data directories in tool directories
     #
-    # @param logger [Logger] A global logger to use for all tools. This may be
+    # @param logger [Logger] A global logger to use for all tools. This can be
     #     set if the CLI will call at most one tool at a time. However, it will
     #     behave incorrectly if CLI might run multiple tools at the same time
     #     with different verbosity settings (since the logger cannot have
@@ -80,19 +80,21 @@ module Toys
     #     global logger, but use the `logger_factory` parameter instead.
     # @param logger_factory [Proc] A proc that takes a {Toys::ToolDefinition}
     #     as an argument, and returns a `Logger` to use when running that tool.
-    #     Optional. If not provided (and no global logger is set), CLI will use
-    #     a default factory that writes generates loggers writing formatted
-    #     output to `STDERR`, as defined by {Toys::CLI.default_logger_factory}.
+    #     Optional. If not provided (and no global logger is set),
+    #     {Toys::CLI.default_logger_factory} is called to get a basic default.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the current level of the
     #     logger (which is often `Logger::WARN`).
-    # @param error_handler [Proc,nil] A proc that is called when an error is
-    #     caught. The proc should take a {Toys::ContextualError} argument and
-    #     report the error. It should return an exit code (normally nonzero).
-    #     Optional. If not provided, defaults to an instance of
-    #     {Toys::CLI::DefaultErrorHandler}, which displays an error message to
-    #     `STDERR`.
+    # @param error_handler [Proc,nil] A proc that is called when an unhandled
+    #     exception (a normal exception subclassing `StandardError`, an error
+    #     loading a toys config file subclassing `SyntaxError`, or an unhandled
+    #     signal subclassing `SignalException`) is detected. The proc should
+    #     take a {Toys::ContextualError}, whose cause is the unhandled
+    #     exception, as the sole argument, and report the error. It should
+    #     return an exit code (normally nonzero) appropriate to the error.
+    #     Optional. If not provided, {Toys::CLI.default_error_handler} is
+    #     called to get a basic default handler.
     # @param executable_name [String] The executable name displayed in help
     #     text. Optional. Defaults to the ruby program name.
     #
@@ -101,9 +103,8 @@ module Toys
     #     characters are period, colon, and slash.
     # @param completion [Toys::Completion::Base] A specifier for shell tab
     #     completion for the CLI as a whole.
-    #     Optional. If not provided, defaults to an instance of
-    #     {Toys::CLI::DefaultCompletion}, which delegates completion to the
-    #     relevant tool.
+    #     Optional. If not provided, {Toys::CLI.default_completion} is called
+    #     to get a default completion that delegates to the tool.
     #
     # @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
     #     middleware that will be used by default for all tools.
@@ -198,8 +199,8 @@ module Toys
       @mixin_lookup = mixin_lookup || CLI.default_mixin_lookup
       @middleware_lookup = middleware_lookup || CLI.default_middleware_lookup
       @template_lookup = template_lookup || CLI.default_template_lookup
-      @error_handler = error_handler || DefaultErrorHandler.new
-      @completion = completion || DefaultCompletion.new
+      @error_handler = error_handler || CLI.default_error_handler
+      @completion = completion || CLI.default_completion
       @logger = logger
       @logger_factory = logger ? proc { logger } : logger_factory || CLI.default_logger_factory
       @base_level = base_level
@@ -461,9 +462,10 @@ module Toys
         context = build_context(tool, remaining,
                                 verbosity: verbosity,
                                 delegated_from: delegated_from)
-        execute_tool(tool, context, &:run)
+        run_handler = make_run_handler(tool)
+        execute_tool(tool, context, &run_handler)
       end
-    rescue ContextualError, ::Interrupt => e
+    rescue ContextualError => e
       @error_handler.call(e).to_i
     end
 
@@ -487,102 +489,6 @@ module Toys
       end
     end
 
-    ##
-    # A basic error handler that prints out captured errors to a stream or
-    # a logger.
-    #
-    class DefaultErrorHandler
-      ##
-      # Create an error handler.
-      #
-      # @param output [IO,nil] Where to write errors. Default is `$stderr`.
-      #
-      def initialize(output: $stderr)
-        require "toys/utils/terminal"
-        @terminal = Utils::Terminal.new(output: output)
-      end
-
-      ##
-      # The error handler routine. Prints out the error message and backtrace,
-      # and returns the correct result code.
-      #
-      # @param error [Exception] The error that occurred.
-      # @return [Integer] The result code for the execution.
-      #
-      def call(error)
-        cause = error
-        case error
-        when ContextualError
-          cause = error.cause
-          @terminal.puts(cause_string(cause))
-          @terminal.puts(context_string(error), :bold)
-        when ::Interrupt
-          @terminal.puts
-          @terminal.puts("INTERRUPTED", :bold)
-        else
-          @terminal.puts(cause_string(error))
-        end
-        exit_code_for(cause)
-      end
-
-      private
-
-      def exit_code_for(error)
-        case error
-        when ArgParsingError
-          2
-        when NotRunnableError
-          126
-        when ::Interrupt
-          130
-        else
-          1
-        end
-      end
-
-      def cause_string(cause)
-        lines = ["#{cause.class}: #{cause.message}"]
-        cause.backtrace.each_with_index.reverse_each do |bt, i|
-          lines << "    #{(i + 1).to_s.rjust(3)}: #{bt}"
-        end
-        lines.join("\n")
-      end
-
-      def context_string(error)
-        lines = [
-          error.banner || "Unexpected error!",
-          "    #{error.cause.class}: #{error.cause.message}",
-        ]
-        if error.config_path
-          lines << "    in config file: #{error.config_path}:#{error.config_line}"
-        end
-        if error.tool_name
-          lines << "    while executing tool: #{error.tool_name.join(' ').inspect}"
-          if error.tool_args
-            lines << "    with arguments: #{error.tool_args.inspect}"
-          end
-        end
-        lines.join("\n")
-      end
-    end
-
-    ##
-    # A Completion that implements the default algorithm for a CLI. This
-    # algorithm simply determines the tool and uses its completion.
-    #
-    class DefaultCompletion < Completion::Base
-      ##
-      # Returns candidates for the current completion.
-      #
-      # @param context [Toys::Completion::Context] the current completion
-      #     context including the string fragment.
-      # @return [Array<Toys::Completion::Candidate>] an array of candidates
-      #
-      def call(context)
-        context.tool.completion.call(context)
-      end
-    end
-
     class << self
       ##
       # Returns a default set of middleware that may be used as a starting
@@ -637,56 +543,43 @@ module Toys
       end
 
       ##
-      # Returns a logger factory that generates loggers that write to stderr.
-      # All loggers generated by this factory share a single
-      # {Toys::Utils::Terminal}, so log entries may interleave but will not
-      # interrupt one another.
+      # Returns a bare-bones error handler that takes simply reraises the
+      # error. If the original error (the cause of the {Toys::ContextualError})
+      # was a `SignalException` (or a subclass such as `Interrupted`), that
+      # `SignalException` itself is reraised so that the Ruby VM has a chance
+      # to handle it. Otherwise, for any other error, the
+      # {Toys::ContextualError} is reraised.
+      #
+      # @return [Proc]
+      #
+      def default_error_handler
+        proc do |error|
+          cause = error.cause
+          raise cause.is_a?(::SignalException) ? cause : error
+        end
+      end
+
+      ##
+      # Returns a default logger factory that generates simple loggers that
+      # write to STDERR.
       #
       # @return [Proc]
       #
       def default_logger_factory
-        require "toys/utils/terminal"
-        shared_terminal = Utils::Terminal.new(output: $stderr)
         proc do
-          logger = ::Logger.new(shared_terminal)
-          logger.formatter = proc do |severity, time, _progname, msg|
-            msg_str =
-              case msg
-              when ::String
-                msg
-              when ::Exception
-                "#{msg.message} (#{msg.class})\n" << (msg.backtrace || []).join("\n")
-              else
-                msg.inspect
-              end
-            format_log(shared_terminal, time, severity, msg_str)
-          end
+          logger = ::Logger.new($stderr)
           logger.level = ::Logger::WARN
           logger
         end
       end
 
-      private
-
-      def format_log(terminal, time, severity, msg)
-        timestr = time.strftime("%Y-%m-%d %H:%M:%S")
-        header = format("[%<time>s %<sev>5s]", time: timestr, sev: severity)
-        styled_header =
-          case severity
-          when "FATAL"
-            terminal.apply_styles(header, :bright_magenta, :bold, :underline)
-          when "ERROR"
-            terminal.apply_styles(header, :bright_red, :bold)
-          when "WARN"
-            terminal.apply_styles(header, :bright_yellow)
-          when "INFO"
-            terminal.apply_styles(header, :bright_cyan)
-          when "DEBUG"
-            terminal.apply_styles(header, :white)
-          else
-            header
-          end
-        "#{styled_header}  #{msg}\n"
+      ##
+      # Returns a default Completion that simply uses the tool's completion.
+      #
+      def default_completion
+        proc do |context|
+          context.tool.completion.call(context)
+        end
       end
     end
 
@@ -704,7 +597,20 @@ module Toys
       tool.tool_class.new(arg_parser.data)
     end
 
-    def execute_tool(tool, context)
+    def make_run_handler(tool)
+      run_handler = tool.run_handler
+      if run_handler.is_a?(::Symbol)
+        proc do |context|
+          context.send(run_handler)
+        end
+      else
+        proc do |context|
+          context.instance_exec(&run_handler)
+        end
+      end
+    end
+
+    def execute_tool(tool, context, &block)
       tool.source_info&.apply_lib_paths
       tool.run_initializers(context)
       cur_logger = context[Context::Key::LOGGER]
@@ -713,9 +619,7 @@ module Toys
         cur_logger.level = (base_level || original_level) - context[Context::Key::VERBOSITY].to_i
       end
       begin
-        executor = build_executor(tool, context) do
-          yield context
-        end
+        executor = build_executor(tool, context, &block)
         catch(:result) do
           executor.call
           0
@@ -733,11 +637,10 @@ module Toys
           elsif !tool.runnable?
             raise NotRunnableError, "No implementation for tool #{tool.display_name.inspect}"
           else
-            yield
+            yield context
           end
-        rescue ::Interrupt => e
-          raise e unless tool.handles_interrupts?
-          handle_interrupt(context, tool.interrupt_handler, e)
+        rescue ::SignalException => e
+          handle_signal_by_tool(context, tool, e)
         end
       end
       tool.built_middleware.reverse_each do |middleware|
@@ -750,24 +653,25 @@ module Toys
       usage_errors = context[Context::Key::USAGE_ERRORS]
       handler = tool.usage_error_handler
       raise ArgParsingError, usage_errors if handler.nil?
-      handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
-      if handler.arity.zero?
-        context.instance_exec(&handler)
-      else
-        context.instance_exec(usage_errors, &handler)
-      end
+      call_handler(context, handler, usage_errors)
     end
 
-    def handle_interrupt(context, handler, exception)
+    def handle_signal_by_tool(context, tool, exception)
+      handler = tool.signal_handler(exception.signo)
+      raise exception unless handler
+      call_handler(context, handler, exception)
+    rescue ::SignalException => e
+      raise e if e.equal?(exception)
+      handle_signal_by_tool(context, tool, e)
+    end
+
+    def call_handler(context, handler, argument)
       handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
       if handler.arity.zero?
         context.instance_exec(&handler)
       else
-        context.instance_exec(exception, &handler)
+        context.instance_exec(argument, &handler)
       end
-    rescue ::Interrupt => e
-      raise e if e.equal?(exception)
-      handle_interrupt(context, handler, e)
     end
 
     def make_executor(middleware, context, next_executor)

data/lib/toys/compat.rb

@@ -12,37 +12,27 @@ module Toys
     parts = ::RUBY_VERSION.split(".")
     ruby_version = parts[0].to_i * 10000 + parts[1].to_i * 100 + parts[2].to_i
 
-    ##
     # @private
-    #
     def self.jruby?
       ::RUBY_ENGINE == "jruby"
     end
 
-    ##
     # @private
-    #
     def self.truffleruby?
       ::RUBY_ENGINE == "truffleruby"
     end
 
-    ##
     # @private
-    #
     def self.windows?
       ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
     end
 
-    ##
     # @private
-    #
     def self.allow_fork?
       !jruby? && !truffleruby? && !windows?
     end
 
-    ##
     # @private
-    #
     def self.supports_suggestions?
       unless defined?(@supports_suggestions)
         begin
@@ -60,9 +50,7 @@ module Toys
       @supports_suggestions
     end
 
-    ##
     # @private
-    #
     def self.suggestions(word, list)
       if supports_suggestions?
         ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
@@ -73,16 +61,12 @@ module Toys
 
     # The :base argument to Dir.glob requires Ruby 2.5 or later.
     if ruby_version >= 20500
-      ##
       # @private
-      #
       def self.glob_in_dir(glob, dir)
         ::Dir.glob(glob, base: dir)
       end
     else
-      ##
       # @private
-      #
       def self.glob_in_dir(glob, dir)
         ::Dir.chdir(dir) { ::Dir.glob(glob) }
       end
@@ -90,16 +74,12 @@ module Toys
 
     # Dir.children requires Ruby 2.5 or later.
     if ruby_version >= 20500
-      ##
       # @private
-      #
       def self.dir_children(dir)
         ::Dir.children(dir)
       end
     else
-      ##
       # @private
-      #
       def self.dir_children(dir)
         ::Dir.entries(dir) - [".", ".."]
       end
@@ -110,16 +90,12 @@ module Toys
     # This also hits TruffleRuby
     # (see https://github.com/oracle/truffleruby/issues/2567)
     if ruby_version >= 20700 && !truffleruby?
-      ##
       # @private
-      #
       def self.instantiate(klass, args, kwargs, block)
         klass.new(*args, **kwargs, &block)
       end
     else
-      ##
       # @private
-      #
       def self.instantiate(klass, args, kwargs, block)
         formals = klass.instance_method(:initialize).parameters
         if kwargs.empty? && formals.all? { |arg| arg.first != :key && arg.first != :keyrest }
@@ -133,26 +109,35 @@ module Toys
     # File.absolute_path? requires Ruby 2.7 or later. For earlier Rubies, use
     # an ad-hoc mechanism.
     if ruby_version >= 20700
-      ##
       # @private
-      #
       def self.absolute_path?(path)
         ::File.absolute_path?(path)
       end
     elsif ::Dir.getwd =~ /^[a-zA-Z]:/
-      ##
       # @private
-      #
       def self.absolute_path?(path)
         /^[a-zA-Z]:/.match?(path)
       end
     else
-      ##
       # @private
-      #
       def self.absolute_path?(path)
         path.start_with?("/")
       end
     end
+
+    # The second argument to method_defined? and private_method_defined?
+    # requires Ruby 2.6 or later.
+    if ruby_version >= 20600
+      # @private
+      def self.method_defined_without_ancestors?(klass, name)
+        klass.method_defined?(name, false) || klass.private_method_defined?(name, false)
+      end
+    else
+      # @private
+      def self.method_defined_without_ancestors?(klass, name)
+        klass.instance_methods(false).include?(name) ||
+          klass.private_instance_methods(false).include?(name)
+      end
+    end
   end
 end

data/lib/toys/context.rb

@@ -139,22 +139,30 @@ module Toys
     #
     # This is a convenience getter for {Toys::Context::Key::ARGS}.
     #
+    # If the `args` method is overridden by the tool, you can still access it
+    # using the name `__args`.
+    #
     # @return [Array<String>]
     #
     def args
       @__data[Key::ARGS]
     end
+    alias __args args
 
     ##
     # The currently running CLI.
     #
     # This is a convenience getter for {Toys::Context::Key::CLI}.
     #
+    # If the `cli` method is overridden by the tool, you can still access it
+    # using the name `__cli`.
+    #
     # @return [Toys::CLI]
     #
     def cli
       @__data[Key::CLI]
     end
+    alias __cli cli
 
     ##
     # Return the context directory for this tool. Generally, this defaults
@@ -164,71 +172,98 @@ module Toys
     #
     # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
     #
+    # If the `context_directory` method is overridden by the tool, you can
+    # still access it using the name `__context_directory`.
+    #
     # @return [String] Context directory path
     # @return [nil] if there is no context.
     #
     def context_directory
       @__data[Key::CONTEXT_DIRECTORY]
     end
+    alias __context_directory context_directory
 
     ##
     # The logger for this execution.
     #
     # This is a convenience getter for {Toys::Context::Key::LOGGER}.
     #
+    # If the `logger` method is overridden by the tool, you can still access it
+    # using the name `__logger`.
+    #
     # @return [Logger]
     #
     def logger
       @__data[Key::LOGGER]
     end
+    alias __logger logger
 
     ##
     # The full name of the tool being executed, as an array of strings.
     #
     # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
     #
+    # If the `tool_name` method is overridden by the tool, you can still access
+    # it using the name `__tool_name`.
+    #
     # @return [Array<String>]
     #
     def tool_name
       @__data[Key::TOOL_NAME]
     end
+    alias __tool_name tool_name
 
     ##
     # The source of the tool being executed.
     #
     # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
     #
+    # If the `tool_source` method is overridden by the tool, you can still
+    # access it using the name `__tool_source`.
+    #
     # @return [Toys::SourceInfo]
     #
     def tool_source
       @__data[Key::TOOL_SOURCE]
     end
+    alias __tool_source tool_source
 
     ##
     # The (possibly empty) array of errors detected during argument parsing.
     #
     # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
     #
+    # If the `usage_errors` method is overridden by the tool, you can still
+    # access it using the name `__usage_errors`.
+    #
     # @return [Array<Toys::ArgParser::UsageError>]
     #
     def usage_errors
       @__data[Key::USAGE_ERRORS]
     end
+    alias __usage_errors usage_errors
 
     ##
     # The current verbosity setting as an integer.
     #
     # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
     #
+    # If the `verbosity` method is overridden by the tool, you can still access
+    # it using the name `__verbosity`.
+    #
     # @return [Integer]
     #
     def verbosity
       @__data[Key::VERBOSITY]
     end
+    alias __verbosity verbosity
 
     ##
     # Fetch an option or other piece of data by key.
     #
+    # If the `get` method is overridden by the tool, you can still access it
+    # using the name `__get` or the `[]` operator.
+    #
     # @param key [Symbol]
     # @return [Object]
     #
@@ -251,6 +286,9 @@ module Toys
     ##
     # Set one or more options or other context data by key.
     #
+    # If the `set` method is overridden by the tool, you can still access it
+    # using the name `__set`.
+    #
     # @return [self]
     #
     # @overload set(key, value)
@@ -272,6 +310,7 @@ module Toys
       end
       self
     end
+    alias __set set
 
     ##
     # The subset of the context that uses string or symbol keys. By convention,
@@ -279,6 +318,9 @@ module Toys
     # include well-known context values such as verbosity or private context
     # values used by middleware or mixins.
     #
+    # If the `options` method is overridden by the tool, you can still access
+    # it using the name `__options`.
+    #
     # @return [Hash]
     #
     def options
@@ -286,10 +328,14 @@ module Toys
         k.is_a?(::Symbol) || k.is_a?(::String)
       end
     end
+    alias __options options
 
     ##
     # Find the given data file or directory in this tool's search path.
     #
+    # If the `find_data` method is overridden by the tool, you can still access
+    # it using the name `__find_data`.
+    #
     # @param path [String] The path to find
     # @param type [nil,:file,:directory] Type of file system object to find,
     #     or nil to return any type.
@@ -300,10 +346,14 @@ module Toys
     def find_data(path, type: nil)
       @__data[Key::TOOL_SOURCE].find_data(path, type: type)
     end
+    alias __find_data find_data
 
     ##
     # Exit immediately with the given status code.
     #
+    # If the `exit` method is overridden by the tool, you can still access it
+    # using the name `__exit` or by calling {Context.exit}.
+    #
     # @param code [Integer] The status code, which should be 0 for no error,
     #     or nonzero for an error condition. Default is 0.
     # @return [void]
@@ -311,6 +361,7 @@ module Toys
     def exit(code = 0)
       Context.exit(code)
     end
+    alias __exit exit
 
     ##
     # Exit immediately with the given status code. This class method can be

data/lib/toys/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.14.7"
+    VERSION = "0.15.0"
   end
 
   ##