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/input/key_event.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 (see Ansi.bbcode). It automagically detects whether your terminal supports ANSI features, like coloring (see Terminal.colors) or the CSIu protocol support (see Terminal.read_key_event, Terminal.on_key_event and Terminal.input_mode). It calculates the display width for Unicode chars (see Text.width) and help you to display text with word-wise line breaks (see Text.each_line).

Defined Under Namespace

Modules: Ansi, Text Classes: KeyEvent

Constant Summary collapse

VERSION = The version number of the gem.

'0.18.0'

Attributes collapse

.application ⇒ Symbol^? readonly
Terminal application identifier.
.input_mode ⇒ :csi_u, ... readonly
Supported input mode.
.output_mode ⇒ :ansi, ... readonly
Supported output mode.
.tui? ⇒ true, false readonly
Return true if the current terminal supports ANSI control codes for input and output.

Output attributes collapse

.ansi? ⇒ true, false readonly
Whether ANSI control codes are supported for output.
.colors ⇒ Integer readonly
Number of supported colors.
.columns ⇒ Integer
Screen column count.
.pos ⇒ [Integer, Integer]^?
Current cursor position.
.rows ⇒ Integer
Screen row count.
.size ⇒ [Integer, Integer]
Screen size as a tuple of Terminal.rows and Terminal.columns.
.true_color? ⇒ true, false readonly
Whether true colors are supported.

Tool methods collapse

.sh(*cmd, **options, &block) ⇒ Object
Execute a command and report command output line by line or capture the output.

Input methods collapse

.on_key_event(mouse: false, mouse_move: false, focus: false) {|event| ... } ⇒ true, ...
Event loop for key and mouse events.
.read_key_event ⇒ KeyEvent^?
Read next KeyEvent from standard input.

Output methods collapse

.<<(object) ⇒ Terminal
Writes the given object to the terminal.
.print(*objects, bbcode: true) ⇒ nil
Writes the given objects to the terminal.
.puts(*objects, bbcode: true) ⇒ nil
Writes the given objects to the terminal.

Output helper methods collapse

.hide_alt_screen ⇒ Terminal
Hide the alternate screen.
.hide_cursor ⇒ Terminal
Hide the cursor.
.show_alt_screen ⇒ Terminal
Show the alternate screen.
.show_cursor ⇒ Terminal
Show the cursor.

Class Attribute Details

.ansi? ⇒ `true`, `false` (readonly)

Returns whether ANSI control codes are supported for output.

Returns:

(true, false) —
whether ANSI control codes are supported for output

See Also:

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

.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, :docker, :fluent, :hpterm, :hyper, :iterm, :macos, :mintty, :ms_terminal, :ncr260, :nsterm, :terminator, :terminology, :termite, :vt100, :warp, :wezterm, :wyse, :xnuppc

Returns:

(Symbol, nil) —
the application identifier

34	# File 'lib/terminal.rb', line 34 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

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

.columns ⇒ `Integer`

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

Returns:

(Integer) —
number of available columns



79
80
81

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

def columns = size[1]
#
# @attribute [w] columns

.input_mode ⇒ `:csi_u`, ... (readonly)

Supported input mode.

Returns:

(:csi_u) —
when CSIu protocol supported
(:legacy) —
for standard terminal
(:dumb) —
for non-interactive input (pipes etc.)
(:error) —
when input device is not avail (closed)

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

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

Supported 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 22

.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

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

.rows ⇒ `Integer`

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

Returns:

(Integer) —
number of available rows



90
91
92

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

def rows = size[0]
#
# @attribute [w] rows

.size ⇒ `[Integer, Integer]`

Screen size as a tuple of rows and columns.

If the terminal does not support the report of it's dimension or ANSI is not supported in general then environment variables COLUMNS and LINES 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:

rows
columns

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

.true_color? ⇒ `true`, `false` (readonly)

Returns whether true colors are supported.

Returns:

(true, false) —
whether true colors are supported

See Also:

colors

70	# File 'lib/terminal/output.rb', line 70 def true_color? = (colors == 16_777_216)

.tui? ⇒ `true`, `false` (readonly)

Return true if the current terminal supports ANSI control codes for input and output. In this case not only all output methods (<<, print, puts) will forward ANSI control codes to the terminal and translate BBCode (see Terminal::Ansi.bbcode). But also the input methods read_key_event and on_key_event will support extended key codes, mouse and focus events.

Returns:

(true, false) —
whether ANSI control codes are supported for input and output

See Also:

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

Class Method Details

.<<(object) ⇒ `Terminal`

Writes the given object to the terminal. Interprets embedded BBCode (see Terminal::Ansi.bbcode).

Parameters:

object (#to_s) —
object to write

Returns:

(Terminal) —
itself

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

.hide_alt_screen ⇒ `Terminal`

Hide the alternate screen. Will not send the control code if the alternate screen is not used.

When you called show_alt_screen n-times you need to call hide_alt_screen n-times to show the default screen again.

Returns:

(Terminal) —
itself

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

.hide_cursor ⇒ `Terminal`

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

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

Returns:

(Terminal) —
itself

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

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

Event loop for key and mouse events.

Parameters:

mouse (true, false) (defaults to: false) —
whether mouse buttons should be reported
mouse_move (true, false) (defaults to: false) —
whether mouse movement should be reported
focus (true, false) (defaults to: false) —
whether focus/unfocus of terminal window should be reported

Yield Parameters:

event (KeyEvent) —
next event

Yield Returns:

(true, false) —
whether the loop should be continued

Returns:

(true) —
when the loop was started
(false) —
when the current input device is not available
(nil) —
when no block was given

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

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

Writes the given objects to the terminal. Optionally interprets embedded BBCode (see Terminal::Ansi.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)

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

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

Writes the given objects to the terminal. Writes a newline after each object 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 (see Terminal::Ansi.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)

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

.read_key_event ⇒ `KeyEvent`^?

.sh(*cmd, **options) ⇒ `[Process::Status, output, error]`^? .sh(*cmd, **options) {|line, type| ... } ⇒ `Process::Status`^?

Execute a command and report command output line by line or capture the output.

Examples:

Execute a command wih arguments

ret, out, = Terminal.sh('curl', '--version')
raise('command not found - curl') unless ret
puts out

Execute shell commands and print error

ret, _, err = Terminal.sh("mkdir '/test' && cd '/test'")
raise('unable to execute') unless ret
puts("error #{ret.exitstatus}: #{err.join}") unless ret.success?

Copy a file content to clipboard

command = ENV.fetch('CLIP_COPY', 'pbcopy')
File.open(__FILE__) do |file|
  ret, = Terminal.sh(*command, input: file)
  raise("command not found - #{command}") unless ret
end

Overloads:

.sh(*cmd, **options) ⇒ [Process::Status, output, error]^?
Returns:
- ([Process::Status, output, error]) —
  the status of the process successfully executed, the captured output, the captured error output,
- (nil) —
  when the command was not executable
.sh(*cmd, **options) {|line, type| ... } ⇒ Process::Status^?
Yield Parameters:
- line (String) —
  next received line from the process
- type (:output, :error) —
  whether the received line is standard output or error
Returns:
- (Process::Status) —
  the status of the process successfully executed
- (nil) —
  when the command was not executable

Parameters:

cmd (Array<#to_s>) —
command line or command with arguments
options (Hash) —
options how to execute the new process; see Process.spawn for default execution options provided by Ruby

Options Hash (**options):

:env (Hash<String,String>) —
key/value pairs added to the ENV of the process; with option :unsetenv_others set to true it replaces the ENV
:shell (true, false) —
whether to create a seperate shell or not
:input (#readpartial, #to_io, Array, #each, #to_a, #to_s) —
piped to the command as input

Raises:

(ArgumentError) —
when command is missing

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

def sh(*cmd, **options, &block)
  raise(ArgumentError, 'command expected') if cmd.empty?
  return Shell.exec(cmd, **options, &block) if block_given?
  out = []
  err = []
  [
    Shell.exec(cmd, **options) do |line, type|
      (type == :error ? err : out) << line
    end,
    out,
    err
  ]
end

.show_alt_screen ⇒ `Terminal`

Show the alternate screen. Will not send the control code if the alternate screen is already used.

When you called show_alt_screen n-times you need to call hide_alt_screen n-times to show the default screen again.

Returns:

(Terminal) —
itself

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

.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:

(Terminal) —
itself

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

Module: Terminal

Overview

Defined Under Namespace

Constant Summary collapse

Attributes collapse

Output attributes collapse

Tool methods collapse

Input methods collapse

Output methods collapse

Output helper methods collapse

Class Attribute Details

.ansi? ⇒ true, false (readonly)

.application ⇒ Symbol? (readonly)

.colors ⇒ Integer (readonly)

.columns ⇒ Integer

.input_mode ⇒ :csi_u, ... (readonly)

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

.pos ⇒ [Integer, Integer]?

.rows ⇒ Integer

.size ⇒ [Integer, Integer]

.true_color? ⇒ true, false (readonly)

.tui? ⇒ true, false (readonly)

Class Method Details

.<<(object) ⇒ Terminal

.hide_alt_screen ⇒ Terminal

.hide_cursor ⇒ Terminal

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

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

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

.read_key_event ⇒ KeyEvent?

.sh(*cmd, **options) ⇒ [Process::Status, output, error]? .sh(*cmd, **options) {|line, type| ... } ⇒ Process::Status?

Examples:

Execute a command wih arguments

Execute shell commands and print error

Copy a file content to clipboard

.show_alt_screen ⇒ Terminal

.show_cursor ⇒ Terminal

.ansi? ⇒ `true`, `false` (readonly)

.application ⇒ `Symbol`^? (readonly)

.colors ⇒ `Integer` (readonly)

.columns ⇒ `Integer`

.input_mode ⇒ `:csi_u`, ... (readonly)

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

.pos ⇒ `[Integer, Integer]`^?

.rows ⇒ `Integer`

.size ⇒ `[Integer, Integer]`

.true_color? ⇒ `true`, `false` (readonly)

.tui? ⇒ `true`, `false` (readonly)

.<<(object) ⇒ `Terminal`

.hide_alt_screen ⇒ `Terminal`

.hide_cursor ⇒ `Terminal`

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

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

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

.read_key_event ⇒ `KeyEvent`^?

.sh(*cmd, **options) ⇒ `[Process::Status, output, error]`^? .sh(*cmd, **options) {|line, type| ... } ⇒ `Process::Status`^?

.show_alt_screen ⇒ `Terminal`

.show_cursor ⇒ `Terminal`