TTY is a toolbox for developing beautiful command line clients in Ruby. It provides a fluid interface for gathering input from the user, querying system and terminal and displaying information back. It is not another command line options parser, rather a plumbing library that helps in common tasks.

Motivation

All too often libraries that interact with command line create their own interface logic that gathers input from users and displays information back. Many times utility files are created that contain methods for reading system or terminal properties. Shouldn't we focus our energy on building the actual client?

Even more so, any command line application needs a clear way of communicating its results back to terminal whether in tabular form, column form or colorfully indented text. Our time and energy should be spent in creating the tools not the foundation.

Features

Fully modular, choose out of many components to suite your needs and jump-start development of your command line app:

• Terminal ASCII and Unicode tables. [status: ✔ ]
• Terminal output colorization. [status: ✔ ]
• Terminal output paging. [status: ✔ ]
• System detection utilities. [status: ✔ ]
• Command detection utilities. [status: ✔ ]
• Text manipulation(wrapping/truncation) [status: ✔ ]
• Terminal progress bars drawing. [status: ✔ ]
• Terminal spinners. [status: ✔ ]
• Interactive prompt for user input. [status: ✔ ]
• File diffs. [status: TODO]
• Configuration file management. [status: TODO]
• Logging [status: In Progress]
• Plugin ecosystem [status: TODO]
• Fully tested with major ruby interpreters.

Installation

Add this line to your application's Gemfile:

gem 'tty'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty

Contents

• 1. Overview
• 2. Prompting for input
• 3. Drawing tables
• 4. Drawing progress bars
• 5. Drawing spinners
• 6. Output coloring
• 7. Output paging
• 8. Detecting screen properties
• 9. Detecting platform
• 10. Detecting color capabilities
• 11. Searching executables
• 12. Moving cursor
• 13. Setting editor

1. Overview

TTY provides you with many tools to get the job done in terminal.

To ask for user input use TTY::Prompt:

prompt = TTY::Prompt.new
prompt.yes?('Do you like Ruby?')
# => Do you like Ruby? (Y/n)

# or ask to select from list

prompt.select("Choose your destiny?", %w(Scorpion Kano Jax))
# =>
# Choose your destiny? (Use arrow keys, press Enter to select)
# ‣ Scorpion
#   Kano
#   Jax

To print tabular output use TTY::Table:

table = TTY::Table[['a1', 'a2', 'a3'], ['b1', 'b2', 'b3']]
table.to_s
# => a1  a2  a3
     b1  b2  b3

To create a progress bar use TTY::ProgressBar:

bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
30.times { bar.advance }

To create a spinner use TTY::Spinner:

spinner = TTY::Spinner.new('Loading ... ', format: :spin_2)
30.times { spinner.spin }

To colorize your strings use Pastel:

pastel = Pastel.new
pastel.green.on_red.bold('Piotr')

To page very long input use TTY::Pager:

pager = TTY::Pager.new
pager.page('Very long text...')

To measure screen size use TTY::Screen:

screen = TTY::Screen.new
screen.size     # => [51, 280]
screen.width    # => 280
screen.height   # => 51

TTY::Color allows you to check if terminal supports color:

TTY::Color.supports?  # => true
TTY::Color.mode # => 64

To move cursor around the terminal use TTY::Cursor:

cursor = TTY::Cursor
print cursor.up(5) + cursor.forward(2)

2. Prompting for input

TTY relies on tty-prompt component for processing user input.

prompt.ask('What is your name?', default: ENV['USER'])
# => What is your name? (piotr)

Please refer to documentation for complete API.

2. Drawing tables

TTY uses the tty-table component in order to convert data into table and render as string output in tabular form. For example, to render data with ASCII border:

table = TTY::Table.new ['header1','header2'], [['a1','a2'], ['b1','b2']]
table.render(:ascii)
# =>
  +-------+-------+
  |header1|header2|
  +-------+-------+
  |a1     |a2     |
  |b1     |b2     |
  +-------+-------+

Please refer to documentation for complete API.

3. Drawing progress bars

In order to draw progress bars in terminal, TTY uses the tty-progressbar component.

For example, to render basic download bar do:

bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
30.times { bar.advance }

Please refer to documentation for complete API.

4. Drawing spinners

TTY uses the tty-spinner component to handle terminal spinning animation. For instance, to create a simple spinner do:

spinner = TTY::Spinner.new('Loading ... ', format: :spin_2)
30.times { spinner.spin }

Please refer to documentation for complete API.

6. Output coloring

In order to colorize strings, TTY uses the pastel component:

pastel = Pastel.new
pastel.red.on_green.bold 'text...'  # => red bold text on green background

Please refer to documentation for complete API.

7. Output paging

To page terminal output TTY relies on tty-pager component.

For example to page terminal output do (on non unix systems falls back to ruby implementation):

pager = TTY::Pager.new
pager.page('Very long text...')

Please refer to documentation for complete API.

8. Detecting screen properties

TTY uses the tty-screen component to measure the screen properties.

For example to get screen size do:

screen = TTY::Screen.new
screen.size     # => [51, 280]
screen.width    # => 280
screen.height   # => 51

Please refer to documentation for complete API.

9. Detecting platform

To check for platform properties TTY uses tty-platform component.

platform = TTY::Platform.new
platform.cpu     # => 'x86_64'
platform.os      # => 'darwin'
platform.version # => '10.6.1'

In addition, there are more generic utilities to check for type of operating system:

TTY::Platform.unix?    # => true
TTY::Platform.windows? # => false

Please refer to documentation for complete API.

10. Detecting color capabilities

tty-color component allows TTY detect color support and mode in terminal emulator:

TTY::Color.supports?  # => true
TTY::Color.mode # => 64

Please refer to documentation for complete API.

11. Searching executables

To find executable path TTY uses tty-which component.

For instance, to find out if less utility is actually supported by the system do:

TTY::Which.which('less')  # => '/usr/bin/less'

Please refer to documentation for complete API.

12. Moving cursor

To perform terminal cursor movements use tty-cursor component.

For example, to move cursor up by 5 rows and forward by 2 columns:

cursor = TTY::Cursor
print cursor.up(5) + cursor.forward(2)

Please refer to documentation for complete API.

13. Setting editor

TTY::System.editor.command('vim')

To open a file in your editor of choice do

TTY::System.editor.open('file path...')

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Copyright

Copyright (c) 2012-2016 Piotr Murach. See LICENSE for further details.