Class: Toys::Utils::StandardUI

Inherits:
Object
  • Object
show all
Defined in:
lib/toys/utils/standard_ui.rb

Overview

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 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)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(output: nil) ⇒ StandardUI

Create a Standard UI.

By default, all output is written to $stderr, and will share a single Terminal object, allowing multiple tools and/or threads to interleave messages without interrupting one another.

Parameters:

  • output (IO, Toys::Utils::Terminal) (defaults to: nil) —

    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.



32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/toys/utils/standard_ui.rb', line 32

def initialize(output: nil)
  require "toys/utils/terminal"
  @terminal = output || $stderr
  @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

Instance Attribute Details

#log_header_severity_styles ⇒ Hash{String => Array<Symbol>} (readonly)

A hash that maps severities to styles recognized by 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.

Returns:

  • (Hash{String => Array<Symbol>}) 


60
61
62
 
# File 'lib/toys/utils/standard_ui.rb', line 60

def log_header_severity_styles
  @log_header_severity_styles
end

#terminal ⇒ Toys::Utils::Terminal (readonly)

The terminal underlying this UI

Returns:



50
51
52
 
# File 'lib/toys/utils/standard_ui.rb', line 50

def terminal
  @terminal
end

Instance Method Details

#cli_args ⇒ Hash

Convenience method that returns a hash of arguments that can be passed to the CLI constructor. Includes the :error_handler and :logger_factory arguments.

Returns:

  • (Hash) 


69
70
71
72
73
74
 
# File 'lib/toys/utils/standard_ui.rb', line 69

def cli_args
  {
    error_handler: error_handler_proc,
    logger_factory: logger_factory_proc,
  }
end

#create_logger(_tool) ⇒ Logger

Implementation of a logger factory. As dictated by the logger factory specification in CLI, this must take a ToolDefinition as an argument, and return a Logger.

The base implementation returns a logger that writes to the UI's terminal, using #format_log_entry 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.

Parameters:

Returns:

  • (Logger) 


137
138
139
140
141
142
 
# File 'lib/toys/utils/standard_ui.rb', line 137

def create_logger(_tool)
  logger = ::Logger.new(@terminal)
  logger.formatter = method(:format_log_entry).to_proc
  logger.level = ::Logger::WARN
  logger
end

#display_error_notice(error) ⇒ Object

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 #handle_error and can be overridden to change its behavior.

Parameters:



198
199
200
201
202
 
# File 'lib/toys/utils/standard_ui.rb', line 198

def display_error_notice(error)
  @terminal.puts
  @terminal.puts(cause_string(error.cause))
  @terminal.puts(context_string(error), :bold)
end

#display_signal_notice(error) ⇒ Object

Displays a default output for a signal received.

This method is used by #handle_error and can be overridden to change its behavior.

Parameters:

  • error (SignalException) 


179
180
181
182
183
184
185
186
 
# File 'lib/toys/utils/standard_ui.rb', line 179

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

#error_handler_proc ⇒ Proc

Convenience method that returns the error handler proc implemented by this UI (in the #handle_error method). This proc can be passed to the :error_handler argument in the CLI constructor.

Returns:

  • (Proc) 


83
84
85
 
# File 'lib/toys/utils/standard_ui.rb', line 83

def error_handler_proc
  method(:handle_error).to_proc
end

#exit_code_for(error) ⇒ Integer

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 #handle_error and can be overridden to change its behavior.

Parameters:

  • error (Exception) —

    The exception raised. This method expects the original exception, rather than a ContextualError.

Returns:

  • (Integer) —

    The appropriate exit code



158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/toys/utils/standard_ui.rb', line 158

def exit_code_for(error)
  case error
  when ArgParsingError
    2
  when NotRunnableError
    126
  when ::SignalException
    error.signo + 128
  else
    1
  end
end

#format_log_entry(severity, time, _progname, msg) ⇒ String

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.

Parameters:

  • severity (String)
  • time (Time)
  • _progname (String)
  • msg (Object)

Returns:

  • (String) 


218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/toys/utils/standard_ui.rb', line 218

def format_log_entry(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

#handle_error(error) ⇒ Integer

Implementation of an error handler. As dictated by the error handler specification in CLI, this must take a ContextualError as an argument, and return an exit code or raise an exception.

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.

Parameters:

Returns:

  • (Integer) —

    The exit code



113
114
115
116
117
118
119
120
121
 
# File 'lib/toys/utils/standard_ui.rb', line 113

def handle_error(error)
  cause = error.cause
  if cause.is_a?(::SignalException)
    display_signal_notice(cause)
  else
    display_error_notice(error)
  end
  exit_code_for(cause)
end

#logger_factory_proc ⇒ Proc

Convenience method that returns the logger factory proc implemented by this UI (in the #create_logger method). This proc can be passed to the :logger_factory argument in the CLI constructor.

Returns:

  • (Proc) 


94
95
96
 
# File 'lib/toys/utils/standard_ui.rb', line 94

def logger_factory_proc
  method(:create_logger).to_proc
end