Class: Toys::Utils::StandardUI

Inherits:
Object
  • Object
show all
Defined in:
core-docs/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)

Defined in the toys-core gem

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(output: nil, backtrace_omit_prefixes: nil, incomplete_backtrace_message: 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.

  • backtrace_omit_prefixes (Array<String>) (defaults to: nil) —

    An array of directories under which Ruby files should be elided from backtraces. Optional. To elide internal Toys framework files, you can pass Toys.framework_lib_paths.

  • incomplete_backtrace_message (String) (defaults to: nil) —

    A message to display when the backtrace has been elided. Optional.



36
37
38
 
# File 'core-docs/toys/utils/standard_ui.rb', line 36

def initialize(output: nil, backtrace_omit_prefixes: nil, incomplete_backtrace_message: 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>}) 


55
56
57
 
# File 'core-docs/toys/utils/standard_ui.rb', line 55

def log_header_severity_styles
  @log_header_severity_styles
end

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

The terminal underlying this UI

Returns:



45
46
47
 
# File 'core-docs/toys/utils/standard_ui.rb', line 45

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) 


64
65
66
 
# File 'core-docs/toys/utils/standard_ui.rb', line 64

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


126
127
128
 
# File 'core-docs/toys/utils/standard_ui.rb', line 126

def create_logger(_tool)
  # Source available in the toys-core gem
end

#display_error_notice(error) ⇒ Object

Displays a default output for an error.

The output format includes the error message itself, a backtrace (possibly with some entries omitted), and the stack of tool calls if available (i.e. if the error is a ContextualError).

This method is used by #handle_error and can be overridden to change the rendering.

Parameters:



174
175
176
 
# File 'core-docs/toys/utils/standard_ui.rb', line 174

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) 


156
157
158
 
# File 'core-docs/toys/utils/standard_ui.rb', line 156

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) 


75
76
77
 
# File 'core-docs/toys/utils/standard_ui.rb', line 75

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



144
145
146
 
# File 'core-docs/toys/utils/standard_ui.rb', line 144

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) 


192
193
194
 
# File 'core-docs/toys/utils/standard_ui.rb', line 192

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 Runner, this takes the error as its argument, and returns an exit code or raises 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:

  • error (Toys::ContextualError, SignalException, StandardError, ScriptError) —

    The error received. An unhandled signal arrives unwrapped. Any other error normally arrives as a ContextualError wrapper, but arrives unwrapped if the run disabled error wrapping.

Returns:

  • (Integer) —

    The exit code



108
109
110
 
# File 'core-docs/toys/utils/standard_ui.rb', line 108

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) 


86
87
88
 
# File 'core-docs/toys/utils/standard_ui.rb', line 86

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