toys-core 0.14.7 → 0.15.0

data/lib/toys/utils/standard_ui.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Toys
+  module Utils
+    ##
+    # An object that implements standard UI elements, such as error reports and
+    # logging, as provided by the `toys` command line. Specifically, it
+    # implements pretty formatting of log entries and stack traces, and renders
+    # using ANSI coloring where available via {Toys::Utils::Terminal}.
+    #
+    # This object can be used to implement `toys`-style behavior when creating
+    # a CLI object. For example:
+    #
+    #     require "toys/utils/standard_ui"
+    #     ui = Toys::Utils::StandardUI.new
+    #     cli = Toys::CLI.new(**ui.cli_args)
+    #
+    class StandardUI
+      ##
+      # Create a Standard UI.
+      #
+      # By default, all output is written to `$stderr`, and will share a single
+      # {Toys::Utils::Terminal} object, allowing multiple tools and/or threads
+      # to interleave messages without interrupting one another.
+      #
+      # @param output [IO,Toys::Utils::Terminal] Where to write output. You can
+      #     pass a terminal object, or an IO stream that will be wrapped in a
+      #     terminal output. Default is `$stderr`.
+      #
+      def initialize(output: nil)
+        @terminal = output || $stderr
+        require "toys/utils/terminal"
+        @terminal = Terminal.new(output: @terminal) unless @terminal.is_a?(Terminal)
+        @log_header_severity_styles = {
+          "FATAL" => [:bright_magenta, :bold, :underline],
+          "ERROR" => [:bright_red, :bold],
+          "WARN" => [:bright_yellow],
+          "INFO" => [:bright_cyan],
+          "DEBUG" => [:white],
+        }
+      end
+
+      ##
+      # The terminal underlying this UI
+      #
+      # @return [Toys::Utils::Terminal]
+      #
+      attr_reader :terminal
+
+      ##
+      # A hash that maps severities to styles recognized by
+      # {Toys::Utils::Terminal}. Used to style the header for each log entry.
+      # This hash can be modified in place to adjust the behavior of loggers
+      # created by this UI.
+      #
+      # @return [Hash{String => Array<Symbol>}]
+      #
+      attr_reader :log_header_severity_styles
+
+      ##
+      # Convenience method that returns a hash of arguments that can be passed
+      # to the {Toys::CLI} constructor. Includes the `:error_handler` and
+      # `:logger_factory` arguments.
+      #
+      # @return [Hash]
+      #
+      def cli_args
+        {
+          error_handler: error_handler,
+          logger_factory: logger_factory,
+        }
+      end
+
+      ##
+      # Returns an error handler conforming to the `:error_handler` argument to
+      # the {Toys::CLI} constructor. Specifically, it returns the
+      # {#error_handler_impl} method as a proc.
+      #
+      # @return [Proc]
+      #
+      def error_handler
+        @error_handler ||= method(:error_handler_impl).to_proc
+      end
+
+      ##
+      # Returns a logger factory conforming to the `:logger_factory` argument
+      # to the {Toys::CLI} constructor. Specifically, it returns the
+      # {#logger_factory_impl} method as a proc.
+      #
+      # @return [Proc]
+      #
+      def logger_factory
+        @logger_factory ||= method(:logger_factory_impl).to_proc
+      end
+
+      ##
+      # Implementation of the error handler. As dictated by the error handler
+      # specification in {Toys::CLI}, this must take a {Toys::ContextualError}
+      # as an argument, and return an exit code.
+      #
+      # The base implementation uses {#display_error_notice} and
+      # {#display_signal_notice} to print an appropriate message to the UI's
+      # terminal, and uses {#exit_code_for} to determine the correct exit code.
+      # Any of those methods can be overridden by a subclass to alter their
+      # behavior, or this main implementation method can be overridden to
+      # change the overall behavior.
+      #
+      # @param error [Toys::ContextualError] The error received
+      # @return [Integer] The exit code
+      #
+      def error_handler_impl(error)
+        cause = error.cause
+        if cause.is_a?(::SignalException)
+          display_signal_notice(cause)
+        else
+          display_error_notice(error)
+        end
+        exit_code_for(cause)
+      end
+
+      ##
+      # Implementation of the logger factory. As dictated by the logger factory
+      # specification in {Toys::CLI}, this must take a {Toys::ToolDefinition}
+      # as an argument, and return a `Logger`.
+      #
+      # The base implementation returns a logger that writes to the UI's
+      # terminal, using {#logger_formatter_impl} as the formatter. It sets the
+      # level to `Logger::WARN` by default. Either this method or the helper
+      # methods can be overridden to change this behavior.
+      #
+      # @param _tool {Toys::ToolDefinition} The tool definition of the tool to
+      #     be executed
+      # @return [Logger]
+      #
+      def logger_factory_impl(_tool)
+        logger = ::Logger.new(@terminal)
+        logger.formatter = method(:logger_formatter_impl).to_proc
+        logger.level = ::Logger::WARN
+        logger
+      end
+
+      ##
+      # Returns an exit code appropriate for the given exception. Currently,
+      # the logic interprets signals (returning the convention of 128 + signo),
+      # usage errors (returning the conventional value of 2), and tool not
+      # runnable errors (returning the conventional value of 126), and defaults
+      # to 1 for all other error types.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [Exception] The exception raised. This method expects the
+      #     original exception, rather than a ContextualError.
+      # @return [Integer] The appropriate exit code
+      #
+      def exit_code_for(error)
+        case error
+        when ArgParsingError
+          2
+        when NotRunnableError
+          126
+        when ::SignalException
+          error.signo + 128
+        else
+          1
+        end
+      end
+
+      ##
+      # Displays a default output for a signal received.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [SignalException]
+      #
+      def display_signal_notice(error)
+        @terminal.puts
+        if error.is_a?(::Interrupt)
+          @terminal.puts("INTERRUPTED", :bold)
+        else
+          @terminal.puts("SIGNAL RECEIVED: #{error.signm || error.signo}", :bold)
+        end
+      end
+
+      ##
+      # Displays a default output for an error. Displays the error, the
+      # backtrace, and contextual information regarding what tool was run and
+      # where in its code the error occurred.
+      #
+      # This method is used by {#error_handler_impl} and can be overridden to
+      # change its behavior.
+      #
+      # @param error [Toys::ContextualError]
+      #
+      def display_error_notice(error)
+        @terminal.puts
+        @terminal.puts(cause_string(error.cause))
+        @terminal.puts(context_string(error), :bold)
+      end
+
+      ##
+      # Implementation of the formatter used by loggers created by this UI's
+      # logger factory. This interface is defined by the standard `Logger`
+      # class.
+      #
+      # This method can be overridden to change the behavior of loggers created
+      # by this UI.
+      #
+      # @param severity [String]
+      # @param time [Time]
+      # @param _progname [String]
+      # @param msg [Object]
+      # @return [String]
+      #
+      def logger_formatter_impl(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
+        timestr = time.strftime("%Y-%m-%d %H:%M:%S")
+        header = format("[%<time>s %<sev>5s]", time: timestr, sev: severity)
+        styles = log_header_severity_styles[severity]
+        header = @terminal.apply_styles(header, *styles) if styles
+        "#{header}  #{msg_str}\n"
+      end
+
+      private
+
+      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
+  end
+end

data/lib/toys-core.rb

@@ -12,10 +12,51 @@
 # This module contains the command line framework underlying Toys. It can be
 # used to create command line executables using the Toys DSL and classes.
 #
+# ## Common starting points
+#
+# Some of the most commonly needed class documentation is listed below:
+#
+# * For information on the DSL used to write tools, start with
+#   {Toys::DSL::Tool}.
+# * The base class for tool runtime (i.e. that defines the basic methods
+#   available to a tool's implementation) is {Toys::Context}.
+# * For information on writing mixins, see {Toys::Mixin}.
+# * For information on writing templates, see {Toys::Template}.
+# * For information on writing acceptors, see {Toys::Acceptor}.
+# * For information on writing custom shell completions, see {Toys::Completion}.
+# * Standard mixins are defined under the {Toys::StandardMixins} module.
+# * Various utilities are defined under {Toys::Utils}. Some of these serve as
+#   the implementations of corresponding mixins.
+# * The main entrypoint for the command line framework is {Toys::CLI}.
+#
+# Other important internal classes are listed below.
+#
+# * The definition of a tool is represented by {Toys::ToolDefinition} along
+#   the helpers {Toys::Flag}, {Toys::PositionalArg}, and {Toys::FlagGroup}.
+# * Argument parsing is implemented by {Toys::ArgParser}.
+# * The process of finding and loading a tool definition given a tool name, is
+#   implemented by {Toys::Loader}.
+# * Text wrapping is handled by {Toys::WrappableString}.
+# * The settings system is implemented by {Toys::Settings}.
+#
 module Toys
   ##
   # Namespace for DSL classes. These classes provide the directives that can be
-  # used in configuration files. Most are defined in {Toys::DSL::Tool}.
+  # used in configuration files.
+  #
+  # DSL directives that can appear at the top level of Toys files and tool
+  # blocks are defined by the {Toys::DSL::Tool} module.
+  #
+  # Directives that can appear within a block passed to {Toys::DSL::Tool#flag}
+  # are defined by the {Toys::DSL::Flag} class.
+  #
+  # Directives that can appear within a {Toys::DSL::Tool#flag_group} block or
+  # any of its related directives, are defined by the {Toys::DSL::FlagGroup}
+  # class.
+  #
+  # Directives that can appear within a {Toys::DSL::Tool#required_arg},
+  # {Toys::DSL::Tool#optional_arg}, or {Toys::DSL::Tool#remaining_args} block,
+  # are defined by the {Toys::DSL::PositionalArg} class.
   #
   module DSL
   end
@@ -23,6 +64,9 @@ module Toys
   ##
   # Namespace for standard middleware classes.
   #
+  # These middleware are provided by Toys-Core and can be referenced by name
+  # when creating a {Toys::CLI}.
+  #
   module StandardMiddleware
     ##
     # @private
@@ -42,6 +86,9 @@ module Toys
   ##
   # Namespace for standard mixin classes.
   #
+  # These mixins are provided by Toys-Core and can be included by name by
+  # passing a symbol to {Toys::DSL::Tool#include}.
+  #
   module StandardMixins
   end
 
@@ -49,8 +96,9 @@ module Toys
   # Namespace for common utility classes.
   #
   # These classes are not loaded by default, and must be required explicitly.
-  # For example, before using {Toys::Utils::Exec}, you must
-  # `require "toys/utils/exec"`.
+  # For example, before using {Toys::Utils::Exec}, you must:
+  #
+  #     require "toys/utils/exec"
   #
   module Utils
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.14.7
+  version: 0.15.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-07-19 00:00:00.000000000 Z
+date: 2023-10-13 00:00:00.000000000 Z
 dependencies: []
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
@@ -71,6 +71,7 @@ files:
 - lib/toys/utils/git_cache.rb
 - lib/toys/utils/help_text.rb
 - lib/toys/utils/pager.rb
+- lib/toys/utils/standard_ui.rb
 - lib/toys/utils/terminal.rb
 - lib/toys/utils/xdg.rb
 - lib/toys/wrappable_string.rb
@@ -78,10 +79,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.14.7/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.14.7
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.15.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -97,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
 summary: Framework for creating command line executables