Module: Terminal

Defined in:
lib/terminal.rb,
lib/terminal/ansi.rb,
lib/terminal/text.rb,
lib/terminal/input.rb,
lib/terminal/shell.rb,
lib/terminal/detect.rb,
lib/terminal/output.rb,
lib/terminal/version.rb,
lib/terminal/input/ansi.rb,
lib/terminal/input/dumb.rb,
lib/terminal/output/ansi.rb,
lib/terminal/output/dumb.rb,
lib/terminal/text/formatter.rb,
lib/terminal/input/key_event.rb,
lib/terminal/text/char_width.rb,
lib/terminal/ansi/named_colors.rb,
lib/terminal/ansi/screen_viewer.rb

Overview

Terminal I/O with ANSI support, BBCode markup, Unicode display width, keyboard/mouse events, and text formatting.

The appropriate output and input modes are selected automatically at load time based on terminal capabilities. Use the class-level methods for all interaction.

Examples:

Formatted output with BBCode

Terminal.puts '[bold green]Success![/]'

Read a key event

event = Terminal.read_key_event
puts "You pressed: #{event.name}"

Execute a shell command

status, out, err = Terminal.sh('ls', '-la')

Defined Under Namespace

Modules: Ansi, Text Classes: KeyEvent

Constant Summary collapse

VERSION =

The version number of the gem.

'1.0.3'

Attributes collapse

Output Attributes collapse

Tool methods collapse

Input methods collapse

Output Methods collapse

Class Attribute Details

.ansi? ⇒ true, false (readonly)

Whether ANSI escape codes are supported.

Returns:

  • (true, false)

See Also:




# File 'lib/terminal/output.rb', line 39

.application ⇒ Symbol? (readonly)

Detect the terminal emulator application.

Known applications: +:alacritty+, +:amiga+, +:code_edit+, +:dg_unix+, +:docker+, +:fluent+, +:hpterm+, +:hyper+, +:iterm+, +:kitty+, +:macos+, +:mintty+, +:ms_terminal+, +:ncr260+, +:nsterm+, +:terminator+, +:terminology+, +:termite+, +:vscode+, +:vt100+, +:warp+, +:wyse+, +:xnuppc+

Any unrecognized +TERM_PROGRAM+ value is converted to a sanitized symbol. Returns +nil+ when no terminal can be identified.

Examples:

Terminal.application # => :kitty

Returns:

  • (Symbol, nil) —

    the detected application



65
 
# File 'lib/terminal.rb', line 65

def application = (@application ||= Detect.application)

.colors ⇒ Integer (readonly)

Number of colors supported by the terminal.

Returns:

  • (Integer) —

    one of 2, 8, 16, 256, or 16777216

See Also:




# File 'lib/terminal/output.rb', line 48

.columns ⇒ Integer

Terminal width in columns.

Returns:

  • (Integer)

See Also:



77
 
# File 'lib/terminal/output.rb', line 77

def columns = size[1]

.input_mode ⇒ Symbol (readonly)

Detect and return the current input mode.

Examples:

Terminal.input_mode # => :csi_u

Returns:

  • (Symbol) —

    +:csi_u+, +:legacy+, +:dumb+, or +:error+




# File 'lib/terminal/input.rb', line 10

.output_mode ⇒ :ansi, ... (readonly)

Current output mode.

Returns:

  • (:ansi) —

    All output methods (<<, print, puts) will forward ANSI control codes to the terminal and translate BBCode (see Terminal::Ansi.bbcode).

  • (:dumb) —

    All output methods will not forward ANSI control codes and BBCodes will be removed. The colors method will just return 2 (two).

  • (:error) —

    When the output device signaled an error or was closed, nothing will be written to the terminal.




# File 'lib/terminal/output.rb', line 9

.pos ⇒ Array<Integer, Integer>?

Current cursor position. This is only available when ANSI is supported (ansi? return true).

Returns:

  • (Array<Integer, Integer>, nil) —

    +[row, column]+ or +nil+ if unavailable




# File 'lib/terminal/output.rb', line 87

.resized? ⇒ true, false (readonly)

Whether the terminal has been resized since the last size query.

Returns:

  • (true, false)

See Also:



101
 
# File 'lib/terminal/output.rb', line 101

def resized? = @size.nil?

.rows ⇒ Integer

Terminal height in rows.

Returns:

  • (Integer)

See Also:



85
 
# File 'lib/terminal/output.rb', line 85

def rows = size[0]

.size ⇒ Array<Integer, Integer>

The terminal size.

Returns:

  • (Array<Integer, Integer>) —

    +[rows, columns]+




# File 'lib/terminal/output.rb', line 65

.true_color? ⇒ true, false (readonly)

Whether the terminal supports true color (24-bit, 16.7 million colors).

Returns:

  • (true, false)

See Also:



63
 
# File 'lib/terminal/output.rb', line 63

def true_color? = (colors == 16_777_216)

.tui? ⇒ true, false (readonly)

Whether the terminal supports full TUI interaction (ANSI output with CSI-u or legacy keyboard input).

Returns:

  • (true, false)

See Also:




# File 'lib/terminal/output.rb', line 30

Class Method Details

.<<(object) ⇒ self

Output an object with BBCode markup processing.

Examples:

Terminal << '[bold]Hello[/bold] World'

Parameters:

  • object (#to_s, nil) —

    the object to output; +nil+ is ignored

Returns:

  • (self) 



# File 'lib/terminal/output.rb', line 109

.fputs(*objects, bbcode: true, spaces: true, eol: true, align: nil, width: nil, height: nil, padding: nil, prefix: nil, suffix: nil) ⇒ nil

Formatted output with word-wrapping, alignment, and padding.

Examples:

Terminal.fputs('Hello World', align: :center, width: 40)

Parameters:

  • objects (Array<#to_s>) —

    text to process

  • bbcode (true, false) (defaults to: true) —

    process BBCode markup

  • spaces (true, false) (defaults to: true) —

    preserve whitespace; when +false+ leading/trailing spaces and multiple spaces are collapsed

  • eol (true, false) (defaults to: true) —

    preserve line endings; when +false+ newlines are treated as spaces

  • align (Symbol, nil) (defaults to: nil) —

    text alignment: +:left+, +:right+, +:center+, or +nil+ (no fill)

  • width (Integer, nil) (defaults to: nil) —

    output line width in columns

  • height (Integer, nil) (defaults to: nil) —

    number of output lines; negative values take lines from the end

  • padding (Integer, Array, nil) (defaults to: nil) —

    CSS-style padding

    • 1 value: all sides;
    • 2 values: [vertical, horizontal];
    • 3 values: [top, horizontal, bottom];
    • 4 values: [top, right, bottom, left]
  • prefix (#to_s, nil) (defaults to: nil) —

    string prepended to each line

  • suffix (#to_s, nil) (defaults to: nil) —

    string appended to each line

Returns:

  • (nil)

Raises:

  • (ArgumentError) —

    if +width+ is zero or negative

See Also:




# File 'lib/terminal/output.rb', line 142

.hide_alt_screen ⇒ self

Note:

Reference-counted; safe for nested use.

Switch back from the alternate screen buffer.

Returns:

  • (self)

See Also:




# File 'lib/terminal/output.rb', line 201

.hide_cursor ⇒ self

Note:

Reference-counted; safe for nested use.

Hide the cursor.

Calls are reference-counted — nested calls are safe; the cursor is only hidden on the first call and shown when the last matching show_cursor is called.

Returns:

  • (self)

See Also:




# File 'lib/terminal/output.rb', line 167

.on_key_event(mouse: false, mouse_move: false, focus: false) {|event| ... } ⇒ nil, false

Enter a key event loop, yielding each event to the block.

Enables optional mouse and focus event reporting. The block receives KeyEvent instances until input ends or the block breaks.

Examples:

Terminal.on_key_event(mouse: true) do |event|
  break if event.name == 'ESC'
  puts event.name
end

Parameters:

  • mouse (true, false) (defaults to: false) —

    enable mouse button events

  • mouse_move (true, false) (defaults to: false) —

    enable mouse move events

  • focus (true, false) (defaults to: false) —

    enable terminal focus/unfocus events

Yields:

  • (event) —

    called for each input event

Yield Parameters:

  • event (KeyEvent) —

    the parsed key event

Returns:

  • (nil, false) —

    +false+ on I/O error

Raises:

  • (RuntimeError) —

    if already inside a key event loop




# File 'lib/terminal/input.rb', line 26

.on_resize { ... } ⇒ self

Register a callback to be invoked when the terminal is resized.

Examples:

Terminal.on_resize { puts "New size: #{Terminal.size}" }

Yields:

  • called on terminal resize

Returns:

  • (self) 


218
219
220
221
 
# File 'lib/terminal/output.rb', line 218

def on_resize(&block)
  @on_resize = block
  self
end

.print(*objects, bbcode: true) ⇒ nil

Print objects to the terminal.

Examples:

Terminal.print('[green]OK[/]')
Terminal.print('press the [red] button', bbcode: false)

Parameters:

  • objects (Array<#to_s>) —

    objects to print

  • bbcode (true, false) (defaults to: true) —

    process BBCode markup

Returns:

  • (nil) 



# File 'lib/terminal/output.rb', line 119

.puts(*objects, bbcode: true) ⇒ nil

Print objects to the terminal followed by newlines.

Examples:

Terminal.puts('[bold]Hello[/bold]', '[italic]World[/italic]')

Parameters:

  • objects (Array<#to_s>) —

    objects to print

  • bbcode (true, false) (defaults to: true) —

    process BBCode markup

Returns:

  • (nil) 



# File 'lib/terminal/output.rb', line 131

.raw_write(object) ⇒ Integer?

Write raw bytes directly to the terminal without BBCode or ANSI processing.

Parameters:

  • object (#to_s) —

    object to write

Returns:

  • (Integer, nil) —

    bytes written, or +nil+ on error




# File 'lib/terminal/output.rb', line 159

.read_key_event ⇒ KeyEvent, false

Read a single key event (blocking).

Examples:

event = Terminal.read_key_event
puts "You pressed: #{event.name}"

Returns:

  • (KeyEvent, false) —

    the next key event, or +false+ on error




# File 'lib/terminal/input.rb', line 48

.sh(*cmd, **options) ⇒ Array<Process::Status, Array<String>, Array<String>> .sh(*cmd, **options) {|line, type| ... } ⇒ Process::Status

Execute a shell command.

Overloads:

  • .sh(*cmd, **options) ⇒ Array<Process::Status, Array<String>, Array<String>>

    Run a command and capture output.

    Examples:

    status, output, error = Terminal.sh('echo', 'hello')
output # => ["hello\n"]

    Parameters:

    • cmd (Array<String>) —

      command and arguments

    • options (Hash) —

      options passed to the shell runner

    Returns:

    • (Array<Process::Status, Array<String>, Array<String>>) —

      +[status, stdout_lines, stderr_lines]+

  • .sh(*cmd, **options) {|line, type| ... } ⇒ Process::Status

    Run a command and stream output to a block.

    Examples:

    Terminal.sh('make') do |line, type|
  Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
end

    Parameters:

    • cmd (Array<String>) —

      command and arguments

    • options (Hash) —

      options passed to the shell runner

    Yields:

    • (line, type) —

      called for each output line

    Yield Parameters:

    • line (String) —

      the output line

    • type (Symbol) —

      +:output+ or +:error+

    Returns:

    • (Process::Status) —

      the exit status

Raises:

  • (ArgumentError) —

    if no command is given



99
100
101
102
103
104
105
 
# File 'lib/terminal.rb', line 99

def sh(*cmd, **, &)
  raise(ArgumentError, 'command expected') if cmd.empty?
  return Shell.run(*cmd, **, &) if block_given?
  out = []
  err = []
  [Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }, out, err]
end

.show_alt_screen ⇒ self

Note:

Reference-counted; safe for nested use.

Switch to the alternate screen buffer.

Returns:

  • (self)

See Also:




# File 'lib/terminal/output.rb', line 191

.show_cursor ⇒ self

Note:

Reference-counted; safe for nested use.

Show the cursor.

Returns:

  • (self)

See Also:




# File 'lib/terminal/output.rb', line 181