Low-level component for building term/console applications in Crystal
  • v0.6.0 - January 17, 2021
  • v0.4.2 - April 12, 2020
  • v0.4.1 - February 24, 2020
  • v0.4.0 - December 16, 2019
  • v0.3.1 - December 14, 2019

Tput (akin to tput(1)) is a complete term/console output library for Crystal.

In general, when writing console apps, 4 layers can be identified:

  1. Low-level (terminal emulator & terminfo)
  2. Mid-level (console interface, memory state, cursor position, etc.)
  3. High-level (a framework or toolkit)
  4. End-user apps

Tput implements levels (1) and (2).

Is it any good? Yes, there are many, many functions supported. Check the API docs for a list.

It is a Crystal-native implementation (except for binding to a C Terminfo library called unibilium). Not even ncurses bindings are used; Tput is a standalone library that implements all the needed functions itself and provides a much nicer API.


  1. Add the dependency to your shard.yml:
    github: crystallabs/
    version: ~> 1.0
  1. Run shards install


If/when initialized with term name, terminfo data will be looked up. If no terminfo data is found (or one wishes not to use terminfo), Tput's built-in replacements will be used.

As part of initialization, Tput will also detect terminal features and the terminal emulator program in use.

There is zero configuration or considerations to have in mind when using this library. Everything is set up automatically.

For example:

require "unibilium"
require "tput"

terminfo = Unibilium::Terminfo.from_env
tput = terminfo

# Print detected features and environment
p tput.features.to_json
p tput.emulator.to_json

# Set terminal emulator's title, if possible
tput.title = "Test 123"

# Set cursor to red block:
tput.cursor_shape Tput::CursorShape::Block, blink: false
tput.cursor_color Tput::Color::Red

# Switch to "alternate buffer", print some text
tput.cursor_pos 10, 20
tput.echo "Text at position y=10, x=20"

tput.echo "Now displaying ACS chars:"
tput.echo "``aaffggiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz{{||}}~~"
tput.echo "Press any keys; q to exit."

# Listen for keypresses:
tput.listen do |char, key, sequence|
  # Char is a single typed character, or the first character
  # of a sequence which led to a particular key.

  # Key is a keyboard key, if any. Ordinary characters like
  # 'a' or '1' don't have a representation as Key. Special
  # keys like Enter, F1, Esc etc. do.

  # Sequence is the complete sequence of characters which
  # were consumed as part of identifying the key that was
  # pressed.
  if char == 'q'
    tput.echo "Char=#{char.inspect}, Key=#{key.inspect}, Sequence=#{sequence.inspect}"


Why no ncurses? Ncurses is an implementation sort-of specific to C. When not working in C, many of the ncurses methods make no sense. Also in general, the ncurses API is arcane.

API documentation

Run crystal docs as usual, then open file docs/index.html.


Run crystal spec as usual.


  • All the fine folks on Libera.Chat IRC channel #crystal-lang and on Crystal's Gitter channel

  • Blacksmoke16, Asterite, HertzDevil, Raz, Oprypin, Straight-shoota, Watzon, Naqvis, and others!

github statistic
  • 18
  • 0
  • 0
  • 0
  • 8 days ago
  • November 22, 2019

Synced at

Sat, 19 Jun 2021 08:37:29 GMT