Class: Toys::Utils::StandardUI

Inherits:
Object
  • Object
show all
Defined in:
core-docs/toys/utils/standard_ui.rb

Overview

Defined in the toys-core gem

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.



30
31
32
 
# File 'core-docs/toys/utils/standard_ui.rb', line 30

def initialize(output: nil)
  # Source available in the toys-core gem
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>}) 


49
50
51
 
# File 'core-docs/toys/utils/standard_ui.rb', line 49

def log_header_severity_styles
  @log_header_severity_styles
end

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

The terminal underlying this UI

Returns:



39
40
41
 
# File 'core-docs/toys/utils/standard_ui.rb', line 39

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) 


58
59
60
 
# File 'core-docs/toys/utils/standard_ui.rb', line 58

def cli_args
  # Source available in the toys-core gem
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) 


117
118
119
 
# File 'core-docs/toys/utils/standard_ui.rb', line 117

def create_logger(_tool)
  # Source available in the toys-core gem
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:



161
162
163
 
# File 'core-docs/toys/utils/standard_ui.rb', line 161

def display_error_notice(error)
  # Source available in the toys-core gem
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) 


147
148
149
 
# File 'core-docs/toys/utils/standard_ui.rb', line 147

def display_signal_notice(error)
  # Source available in the toys-core gem
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) 


69
70
71
 
# File 'core-docs/toys/utils/standard_ui.rb', line 69

def error_handler_proc
  # Source available in the toys-core gem
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



135
136
137
 
# File 'core-docs/toys/utils/standard_ui.rb', line 135

def exit_code_for(error)
  # Source available in the toys-core gem
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) 


179
180
181
 
# File 'core-docs/toys/utils/standard_ui.rb', line 179

def format_log_entry(severity, time, _progname, msg)
  # Source available in the toys-core gem
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



99
100
101
 
# File 'core-docs/toys/utils/standard_ui.rb', line 99

def handle_error(error)
  # Source available in the toys-core gem
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) 


80
81
82
 
# File 'core-docs/toys/utils/standard_ui.rb', line 80

def logger_factory_proc
  # Source available in the toys-core gem
end