class Tput

• Tput
• Reference
• Object

Overview

Many Tput methods correspond to terminal sequences. Often times methods are named according to their purpose, and then aliased to the names of sequences used behind the scenes.

For example, method #delete_columns is directly implemented using sequence decdc. Therefore, it is also accessible under the alias #decdc.

Furthermore, for understanding the instructions on terminal sequences, the following names are important:

ESC - Sequence starting with ESC (\e)
CSI - Control Sequence Introducer: sequence starting with ESC [ (7bit) or CSI (\x9B, 8bit)
DCS - Device Control String: sequence starting with ESC P (7bit) or DCS (\x90, 8bit)
OSC - Operating System Command: sequence starting with ESC ] (7bit) or OSC (\x9D, 8bit)
C0: single byte command (7bit control codes, byte range \x00 .. \x1F, \x7F)
C1: single byte command (8bit control codes, byte range \x80 .. \x9F)

Some sequences accept arguments. Their naming and types correspond to those used in XTerm documentation:

Ps: A single (usually optional) numeric parameter, composed of one or more decimal digits.
Pm: A multiple numeric parameter composed of any number of single numeric parameters, separated by ";", e.g. ` Ps ; Ps ; … `.
Pt: A text parameter composed of printable characters.

In all of the examples above, spaces exist just for clarity and are not part of actual escape sequences. For example, in "ESC [" or " Ps ; Ps ;" there are no actual spaces.

Included Modules

• Crystallabs::Helpers::Logging
• JSON::Serializable
• Tput::ACSC
• Tput::Coordinates
• Tput::Input
• Tput::Keyboard
• Tput::Namespace
• Tput::Output
• Tput::Probe
• Tput::Response

Defined in:

Constant Summary

CSI7 = "\e["

CSI8 = "\x9B"

DCS7 = "\eP"

DCS8 = "\x90"

DEFAULT_SCREEN_SIZE = Size.new(80, 24)

ESC = "\e"

Log = ::Log.for((self.name.gsub("::", '.')).underscore)

OSC7 = "\e]"

OSC8 = "\x9D"

VERSION = "1.0.8"

Constructors

• .new(pull : JSON::PullParser)
• .new(terminfo : Nil | Unibilium = nil, input : IO = STDIN, output : IO = STDOUT, error : IO = STDERR, force_unicode = nil, use_buffer : Bool = Superconf.tput_use_buffer, screen_size = nil, probe = Superconf.tput_probe)

Class Method Summary

• .build_detections(pairs, sources : Hash(String, String)) : Hash(String, Detection)

  Builds a {name => Detection} map, pairing each stringified value with its recorded provenance from sources (or "unknown").

Instance Method Summary

• #_exiting=(_exiting : Bool)
• #_exiting? : Bool
• #_saved : Hash(String | Symbol | UInt64, Tput::Namespace::CursorState)

  Internal cursor-save state.

• #_saved=(_saved : Hash(String | Symbol | UInt64, Tput::Namespace::CursorState))

  Internal cursor-save state.

• #_title : String
• #aliases : Array(String)

  Terminfo aliases for #name (downcased), e.g.

• #attr_cache_limit : Int32

  Upper bound on @_attr_cache; once reached, the oldest-inserted entry is evicted before each new insert.

• #attr_cache_limit=(attr_cache_limit : Int32)

  Upper bound on @_attr_cache; once reached, the oldest-inserted entry is evicted before each new insert.

• #bracketed_paste_enabled? : Bool

  Whether bracketed paste (DEC 2004) is currently enabled.

• #capture(&) : String

  Captures the escape sequences emitted by the block and returns them as a String, instead of writing them to the terminal.

• #cursor : Point
• #cursor_hidden? : Bool
• #detections : Hash(String, Hash(String, Detection))

  All detected emulator + feature information, each value paired with a description of how it was determined.

• #dump(io : IO = STDOUT) : Nil

  Dumps all detected emulator and feature information to io (STDOUT by default) in an aligned, human-readable report.

• #emulator : Emulator
• #emulator? : Emulator | Nil
• #error : IO
• #error=(error : IO)
• #features : Features
• #features? : Features | Nil
• #force_unicode? : Bool
• #has?(&)
• #in_band_resize_enabled? : Bool

  Whether in-band resize notifications (DEC 2048) are currently enabled.

• #input : IO
• #input=(input : IO)
• #is_alt : Bool
• #keyboard_protocol : KeyboardProtocol | Nil

  The enhanced keyboard protocol currently enabled (tracked by #enable_keyboard_protocol/#disable_keyboard_protocol), or nil when only the always-available Legacy baseline is active.

• #mouse_cell_pixels : Tuple(Int32, Int32) | Nil

  When SGR-Pixels (DEC private mode 1016) mouse reporting is active, the terminal's cell size in pixels ({cell_w, cell_h}) used to derive cell coordinates from the pixel coordinates the terminal now reports; nil (the default) means pixel mode is off and \e[<…M/m reports are decoded as ordinary SGR (1006) cell coordinates.

• #mouse_cell_pixels=(mouse_cell_pixels : Tuple(Int32, Int32) | Nil)

  When SGR-Pixels (DEC private mode 1016) mouse reporting is active, the terminal's cell size in pixels ({cell_w, cell_h}) used to derive cell coordinates from the pixel coordinates the terminal now reports; nil (the default) means pixel mode is off and \e[<…M/m reports are decoded as ordinary SGR (1006) cell coordinates.

• #mouse_enabled? : Bool

  Whether xterm mouse reporting is currently enabled (tracked by #enable_mouse/#disable_mouse).

• #mouse_focus_enabled? : Bool?

  Whether FocusIn/FocusOut reporting (DEC private mode 1004) is currently enabled (tracked by #enable_mouse/#disable_mouse).

• #name : String

  Resolved primary terminal name — from the loaded terminfo entry, else $TERM, else the "xterm" fallback — downcased.

• #name?(nam : String)
• #name?(*names)
• #output : IO
• #output=(output : IO)
• #pause(callback : Proc | Nil = nil) : Proc(Nil)

  Suspends the program's use of the terminal: saves the cursor, leaves the alternate buffer, shows the cursor, disables mouse reporting, and returns input to cooked mode, leaving the terminal usable by another program (a shell, $EDITOR, …).

• #put(&)

  Outputs a string capability to @output, if it exists.

• #put_extended(name : String, *args)

  Like #put, but resolves a user-defined (extended) string capability by name and runs it with the given arguments.

• #read_timeout : Time::Span

  Timeout when reading escape sequences: an ESC on input could be a lone ESC key or the start of an escape sequence, so we wait this long for more input before treating it as a key press (same approach Vi and others use).

• #restore_terminal : Nil

  Restores the terminal to the state it was in before the program took it over: shows the cursor, leaves the alternate buffer, disables mouse reporting, returns input to cooked mode.

• #resume
• #ret : IO | Nil
• #ret=(ret : IO | Nil)
• #saved_cursor : Point | Nil
• #screen : Size
• #scroll_bottom : Int32
• #scroll_top : Int32
• #shim : Unibilium::Terminfo::Shim | Nil
• #sigtstp(callback)
• #terminfo : Unibilium | Nil
• #use_buffer? : Bool

Constructor Detail

Class Method Detail

Instance Method Detail

seq = tput.capture &.cursor_pos(1, 2) # => "\e[2;3H"
# or:
seq = tput.capture { |t| t.cursor_pos 1, 2; t.bell }

tput = Tput.new terminfo
tput.probe! # optional: fills in the live-probed colors/width
tput.dump

put &.smcup?

put &.cursor_pos?(10, 20)

put_extended "Cr"          # reset cursor color, if the terminal defines Cr
put_extended "Cs", "white" # set cursor color