Class: Toys::Utils::Terminal

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

Overview

Defined in the toys-core gem

A simple terminal class.

Styles

This class supports ANSI styled output where supported.

Styles may be specified in any of the following forms:

  • A symbol indicating the name of a well-known style, or the name of a defined style.
  • An rgb string in hex "rgb" or "rrggbb" form.
  • An ANSI code string in \e[XXm form.
  • An array of ANSI codes as integers.

Defined Under Namespace

Classes: TerminalError

Constant Summary collapse

CLEAR_CODE =

ANSI style code to clear styles

Returns:

  • (String) 
"\e[0m"
BUILTIN_STYLE_NAMES =

Standard ANSI style codes by name.

Returns:

  • (Hash{Symbol => Array<Integer>}) 
{
  clear: [0],
  reset: [0],
  bold: [1],
  faint: [2],
  italic: [3],
  underline: [4],
  blink: [5],
  reverse: [7],
  black: [30],
  red: [31],
  green: [32],
  yellow: [33],
  blue: [34],
  magenta: [35],
  cyan: [36],
  white: [37],
  on_black: [30],
  on_red: [31],
  on_green: [32],
  on_yellow: [33],
  on_blue: [34],
  on_magenta: [35],
  on_cyan: [36],
  on_white: [37],
  bright_black: [90],
  bright_red: [91],
  bright_green: [92],
  bright_yellow: [93],
  bright_blue: [94],
  bright_magenta: [95],
  bright_cyan: [96],
  bright_white: [97],
  on_bright_black: [100],
  on_bright_red: [101],
  on_bright_green: [102],
  on_bright_yellow: [103],
  on_bright_blue: [104],
  on_bright_magenta: [105],
  on_bright_cyan: [106],
  on_bright_white: [107],
}.freeze
DEFAULT_SPINNER_FRAME_LENGTH =

Default length of a single spinner frame, in seconds.

Returns:

  • (Float) 
0.1
DEFAULT_SPINNER_FRAMES =

Default set of spinner frames.

Returns:

  • (Array<String>) 
["-", "\\", "|", "/"].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(input: $stdin, output: $stdout, styled: nil) ⇒ Terminal

Create a terminal.

Parameters:

  • input (IO, nil) (defaults to: $stdin) —

    Input stream.

  • output (IO, Logger, nil) (defaults to: $stdout) —

    Output stream or logger.

  • styled (Boolean, nil) (defaults to: nil) —

    Whether to output ansi styles. If nil, the setting is inferred from whether the output has a tty.



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

def initialize(input: $stdin, output: $stdout, styled: nil)
  # Source available in the toys-core gem
end

Instance Attribute Details

#input ⇒ IO? (readonly)

Input stream

Returns:

  • (IO, nil) 


131
132
133
 
# File 'core-docs/toys/utils/terminal.rb', line 131

def input
  @input
end

#output ⇒ IO, ... (readonly)

Output stream or logger

Returns:

  • (IO, Logger, nil) 


125
126
127
 
# File 'core-docs/toys/utils/terminal.rb', line 125

def output
  @output
end

#styled ⇒ Boolean (readonly)

Whether output is styled

Returns:

  • (Boolean) 


137
138
139
 
# File 'core-docs/toys/utils/terminal.rb', line 137

def styled
  @styled
end

Class Method Details

.remove_style_escapes(str) ⇒ String

Returns a copy of the given string with all ANSI style codes removed.

Parameters:

  • str (String) —

    Input string

Returns:

  • (String) —

    String with styles removed



105
106
107
 
# File 'core-docs/toys/utils/terminal.rb', line 105

def self.remove_style_escapes(str)
  # Source available in the toys-core gem
end

Instance Method Details

#<<(str) ⇒ self

Write a line, appending a newline if one is not already present.

Parameters:

  • str (String) —

    The line to write

Returns:

  • (self) 


188
189
190
 
# File 'core-docs/toys/utils/terminal.rb', line 188

def <<(str)
  # Source available in the toys-core gem
end

#apply_styles(str, *styles) ⇒ String

Apply the given styles to the given string, returning the styled string. Honors the styled setting; if styling is disabled, does not add any ANSI style codes and in fact removes any existing codes. If styles were added, ensures that the string ends with a clear code.

Parameters:

  • str (String) —

    String to style

  • styles (Symbol, String, Array<Integer>...) —

    Styles to apply

Returns:

  • (String) —

    The styled string



305
306
307
 
# File 'core-docs/toys/utils/terminal.rb', line 305

def apply_styles(str, *styles)
  # Source available in the toys-core gem
end

#ask(prompt, *styles, default: nil, trailing_text: :default) ⇒ String

Ask a question and get a response.

Parameters:

  • prompt (String) —

    Required prompt string.

  • styles (Symbol, String, Array<Integer>...) —

    Styles to apply to the prompt.

  • default (String, nil) (defaults to: nil) —

    Default value, or nil for no default. Uses nil if not specified.

  • trailing_text (:default, String, nil) (defaults to: :default) —

    Trailing text appended to the prompt, nil for none, or :default to show the default.

Returns:

  • (String) 


212
213
214
 
# File 'core-docs/toys/utils/terminal.rb', line 212

def ask(prompt, *styles, default: nil, trailing_text: :default)
  # Source available in the toys-core gem
end

#close ⇒ Object

This method is defined so that ::Logger will recognize a terminal as a log device target, but it does not actually close anything.



165
166
167
 
# File 'core-docs/toys/utils/terminal.rb', line 165

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

#confirm(prompt = "Proceed? ", *styles, default: nil) ⇒ Boolean

Confirm with the user.

Parameters:

  • prompt (String) (defaults to: "Proceed? ") —

    Prompt string. Defaults to "Proceed?".

  • styles (Symbol, String, Array<Integer>...) —

    Styles to apply to the prompt.

  • default (Boolean, nil) (defaults to: nil) —

    Default value, or nil for no default. Uses nil if not specified.

Returns:

  • (Boolean) 


226
227
228
 
# File 'core-docs/toys/utils/terminal.rb', line 226

def confirm(prompt = "Proceed? ", *styles, default: nil)
  # Source available in the toys-core gem
end

#define_style(name, *styles) ⇒ self

Define a named style.

Style names must be symbols. The definition of a style may include any valid style specification, including the symbol names of existing defined styles.

Parameters:

  • name (Symbol) —

    The name for the style

  • styles (Symbol, String, Array<Integer>...)

Returns:

  • (self) 


291
292
293
 
# File 'core-docs/toys/utils/terminal.rb', line 291

def define_style(name, *styles)
  # Source available in the toys-core gem
end

#height ⇒ Integer

Return the terminal height

Returns:

  • (Integer) 


276
277
278
 
# File 'core-docs/toys/utils/terminal.rb', line 276

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

#newline ⇒ self

Write a newline and flush the current line.

Returns:

  • (self) 


196
197
198
 
# File 'core-docs/toys/utils/terminal.rb', line 196

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

#puts(str = "", *styles) ⇒ self Also known as: say

Write a line, appending a newline if one is not already present.

Parameters:

  • str (String) (defaults to: "") —

    The line to write

  • styles (Symbol, String, Array<Integer>...) —

    Styles to apply to the entire line.

Returns:

  • (self) 


177
178
179
 
# File 'core-docs/toys/utils/terminal.rb', line 177

def puts(str = "", *styles)
  # Source available in the toys-core gem
end

#readline ⇒ String?

Read a line, blocking until one is available.

Returns:

  • (String) —

    the entire string including the temrinating newline

  • (nil) —

    if the input is closed or at eof, or there is no input



157
158
159
 
# File 'core-docs/toys/utils/terminal.rb', line 157

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

#size ⇒ Array(Integer,Integer)

Return the terminal size as an array of width, height.

Returns:

  • (Array(Integer,Integer)) 


258
259
260
 
# File 'core-docs/toys/utils/terminal.rb', line 258

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

#spinner(leading_text: "", final_text: "", frame_length: nil, frames: nil, style: nil) ⇒ Object

Display a spinner during a task. You should provide a block that performs the long-running task. While the block is executing, a spinner will be displayed.

Parameters:

  • leading_text (String) (defaults to: "") —

    Optional leading string to display to the left of the spinner. Default is the empty string.

  • frame_length (Float) (defaults to: nil) —

    Length of a single frame, in seconds. Defaults to DEFAULT_SPINNER_FRAME_LENGTH.

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

    An array of frames. Defaults to DEFAULT_SPINNER_FRAMES.

  • style (Symbol, Array<Symbol>) (defaults to: nil) —

    A terminal style or array of styles to apply to all frames in the spinner. Defaults to empty,

  • final_text (String) (defaults to: "") —

    Optional final string to display when the spinner is complete. Default is the empty string. A common practice is to set this to newline.

Returns:

  • (Object) —

    The return value of the block.



248
249
250
251
 
# File 'core-docs/toys/utils/terminal.rb', line 248

def (leading_text: "", final_text: "",
            frame_length: nil, frames: nil, style: nil)
  # Source available in the toys-core gem
end

#width ⇒ Integer

Return the terminal width

Returns:

  • (Integer) 


267
268
269
 
# File 'core-docs/toys/utils/terminal.rb', line 267

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

#write(str = "", *styles) ⇒ self

Write a partial line without appending a newline.

Parameters:

  • str (String) (defaults to: "") —

    The line to write

  • styles (Symbol, String, Array<Integer>...) —

    Styles to apply to the partial line.

Returns:

  • (self) 


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

def write(str = "", *styles)
  # Source available in the toys-core gem
end