Module: Terminal

Defined in:
lib/terminal.rb,
lib/terminal/ansi.rb,
lib/terminal/text.rb,
lib/terminal/input.rb,
lib/terminal/detect.rb,
lib/terminal/version.rb,
lib/terminal/ansi/attributes.rb,
lib/terminal/text/char_width.rb,
lib/terminal/ansi/named_colors.rb

Overview

Terminal access with support for ANSI control codes and BBCode-like embedded text attribute syntax.

It automagically detects whether your terminal supports ANSI features.

Defined Under Namespace

Modules: Ansi, Text

Constant Summary collapse

VERSION =

The version number of the gem.

'0.9.1'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.ansi? ⇒ Boolean (readonly)

Return true when the current terminal supports ANSI control codes. When the terminal does not support it, colors will return 2 as color count and all output methods (<<, print, puts) will not forward ANSI control codes to the terminal.

Returns:

  • (Boolean) —

    whether ANSI control codes are supported



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

def ansi? = (@mode == :ansi)

.application ⇒ Symbol? (readonly)

Terminal application identifier.

The detection supports a wide range of terminal emulators but may return nil if an unsupported terminal was found. These are the supported application IDs:

  • :alacritty,
  • :amiga,
  • :code_edit,
  • :dg_unix,
  • :fluent,
  • :ghostty,
  • :hpterm,
  • :hyper,
  • :iterm,
  • :macos,
  • :mintty,
  • :ms_terminal,
  • :ncr260,
  • :nsterm,
  • :rio,
  • :tabby,
  • :terminator,
  • :terminology,
  • :terminus,
  • :termite,
  • :tmux,
  • :vscode,
  • :vt100,
  • :warp,
  • :wezterm,
  • :wyse,
  • :xnuppc

Returns:

  • (Symbol, nil) —

    the application identifier



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

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

.colors ⇒ Integer (readonly)

Number of supported colors. The detection checks various conditions to find the correct value. The most common values are

  • 16_777_216 for 24-bit encoding (true_color? return true)
  • 256 for 8-Bit encoding
  • 52 for some Unix terminals with an extended color palette
  • 8 for 3-/4-bit encoding
  • 2 if ANSI is not supported in general (ansi? return false)

Returns:

  • (Integer) —

    number of supported colors



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

def colors = (@colors ||= ansi? ? Detect.colors : 2)

.columns ⇒ Integer

Screen column count. See size for support and detection details.

Returns:

  • (Integer) —

    number of available columns



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

def columns = size[1]

.pos ⇒ [Integer, Integer]?

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

Returns:

  • ([Integer, Integer]) —

    cursor position as rows and columns

  • (nil) —

    for incompatible terminals



94
95
96
97
98
 
# File 'lib/terminal.rb', line 94

def pos
  @con&.cursor
rescue IOError
  @con = nil
end

.rows ⇒ Integer

Screen row count. See size for support and detection details.

Returns:

  • (Integer) —

    number of available rows



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

def rows = size[0]

.size ⇒ [Integer, Integer]

Screen size as a tuple of rows and columns.

If the terminal does not support the report for it's dimension or ANSI is not supported in general then environment variables will be used. If this failed [25, 80] will be returned as default.

Setting the terminal size is not widely supported.

Returns:

  • ([Integer, Integer]) —

    available screen size as rows and columns

See Also:



132
133
134
135
136
137
 
# File 'lib/terminal.rb', line 132

def size
  @size ||= @inf&.winsize || _default_size
rescue IOError
  @inf = nil
  @size = _default_size
end

.true_color? ⇒ Boolean (readonly)

Returns whether true colors are supported.

Returns:

  • (Boolean) —

    whether true colors are supported

See Also:



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

def true_color? = (colors == 16_777_216)

Class Method Details

.<<(object) ⇒ Terminal

Writes the given object to the terminal. Interprets embedded BBCode.

Parameters:

  • object (#to_s) —

    object to write

Returns:



179
180
181
182
183
184
185
 
# File 'lib/terminal.rb', line 179

def <<(object)
  @out.write(@bbcode[object]) unless object.nil? || @out.nil?
  self
rescue IOError
  @out = nil
  self
end

.hide_cursor ⇒ Terminal

Hide the cursor. Will not send the control code if the cursor is already hidden.

To show the cursor again call show_cursor.

Returns:



157
158
159
160
 
# File 'lib/terminal.rb', line 157

def hide_cursor
  _write(Ansi::CURSOR_HIDE) if ansi? && (@cc += 1) == 1
  self
end

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

Writes the given objects to the terminal. Optionally interprets embedded BBCode.

Parameters:

  • objects (Array<#to_s>) —

    any number of objects to write

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

    whether to interpret embedded BBCode

Returns:

  • (nil) 


193
194
195
196
197
198
199
200
 
# File 'lib/terminal.rb', line 193

def print(*objects, bbcode: true)
  return unless @out
  bbcode = bbcode ? @bbcode : @nobbcode
  objects.flatten.each { @out.write(bbcode[_1]) unless _1.nil? }
  nil
rescue IOError
  @out = nil
end

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

Writes the given objects to the terminal. Writes a newline after each objects that does not already end with a newline sequence in it's String represenation. If called without any arguments, writes a newline only.

Optionally interprets embedded BBCode.

Parameters:

  • objects (Array<#to_s>) —

    any number of objects to write

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

    whether to interpret embedded BBCode

Returns:

  • (nil) 


211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/terminal.rb', line 211

def puts(*objects, bbcode: true)
  return unless @out
  objects.flatten!
  if objects.empty?
    @out.write("\n")
    return
  end
  bbcode = bbcode ? @bbcode : @nobbcode
  objects.each do |s|
    next @out.write("\n") if s.nil?
    @out.write(s = bbcode[s])
    @out.write("\n") if s[-1] != "\n"
  end
  nil
rescue IOError
  @out = nil
end

.read_key(mode: :named) ⇒ String, [String, String]

Read next keyboard input.

The input will be returned as named key codes like "Ctrl+C" by default. This can be changed by mode.

Parameters:

  • mode (:named, :raw, :both) (defaults to: :named) —

    modifies the result

Returns:

  • (String) —

    key code ("as is") in :raw mode

  • (String) —

    key name in :named mode

  • ([String, String]) —

    key code and key name in :both mode



16
17
18
19
20
 
# File 'lib/terminal/input.rb', line 16

def read_key(mode: :named)
  key = _raw_read_key or return
  return key if mode == :raw
  mode == :both ? [key, _key_name(key)] : _key_name(key) || key
end

.show_cursor ⇒ Terminal

Show the cursor. Will not send the control code if the cursor is not hidden.

When you called hide_cursor n-times you need to call show_cursor n-times to show the cursor again.

Returns:



169
170
171
172
 
# File 'lib/terminal.rb', line 169

def show_cursor
  _write(Ansi::CURSOR_SHOW) if @cc > 0 && (@cc -= 1).zero?
  self
end